Page 1 of 1

IB2: Guide for setting up moving props

PostPosted: Thu Aug 25, 2016 5:47 am
by youngneil1
IceBlink Engine and Toolset 2: Implementing moving props in your adventure

Essential: Movers require a square shaped area map for now

One of the many new built in functionalities of IceBlink Engine and Toolset 2 is to have props (i.e. graphical tokens that can represent NPC, creatures, objects...) that can change their location, moving around the map in alternating turns with party movement. This allows for lots of new gameplay and world immersion opportunities, ranging from NPC living a full blown daily schedule (e.g. rising early in the morning, working in the fields and then having a drink in their favourite tavern late night), to caravan traders and soldiers commuting on the roads between cities to creatures stalking in the woods and chasing the party across the map should the adventurers dare to get too close to the creatures.

Additionally, while not the primary subejct of this guide, props carry a plethora of settings - in addtion to mobile conversations and encounters, see below - to make them work as premade blocks of gameplay logic (eg traps, climbable walls, pushable objects, locked chests or doors, jumbable chasms, hidden information...), often tied to optional trait checks to determine whether an interaction (bump into or press space key/investigate nearby, depending on the type of prop) is successful or not.

All this can be setup directly in the toolset itself without any further scripting (scripting can provide additional functionalities, but a very, very comprehensive level of functionality - like all the examples above - works completely without scripting).

Finally, just a reminder concerning the "Avoid conversation" and "Show interaction state" toggles in the palyer interface ingame (button left corner of the screen, toggles row). These can used by the player to avoid optional conversations as well well as to show with indicators whether props carry encounters / have optional or mandatory conversations attached to them. Both toggles make navigation eg in crowded cities much easier for the player (eg avoiding unwanted small talk).

Getting started
You will want to start by opening the "Tutorial Module" (this is WIP though) in the toolset and then navigate to the props blueprints section in the toolset. Choose a mover blueprint and place an instance of this prop onto the adventure area map for testing. Select that creature instance on the area map and have a look at its properties.

Logic events called directly from the prop
First thing to note - before we go into the movement details - is that props can carry with them their own mobile conversation ("conversationWhenOnPartySquar") and mobile encounter ("EncounterWhenOnPartySquare"). This is extremely helpful and replaces a large chunk of trigger functionality. Encounters and conversations just start when the party bumps into the prop (or the prop bumps into the party actually). Furthermore, it can be setup that the prop itself is removed when the attached encounter is won by the party, i.e. the prop (or the group of creatures it represents) is slain ("DeletePropWhenThisEncounterIsWon"). Also, please note in this context that encounters themselves can be set to be repeatable (under Area properties of the encounter, properties tab) and props can be set to respawn (prop properties).

Properties determining the state of a prop
Please note that props can be set to isActive (prop can be interacted with, e.g. cause encounter or conversation), isShown (turn prop invisible) and isMover (use one of the mover types explained below). Additionally, the HasCollision property defines whether the party can move through the prop or not (movers have their collision always set to false, so they can move through each other, see below). Moving props themselves also react to HasCollision correctly and will therefore will not move through or onto static props that have collision set to true. They will also never end their move on squares occupied by other moving props (despite all movers having HasCollision set to false).

Move speed
Furthermore, you can set the movementSpeed property of a prop here. This is compared to the movement speed of the party (which is determined by the trait you set under edit/module properties/tagOfMovementSpeedTrait (defaults to "traveller", using zero if trait does not exist). If prop speed and party speed are vaguely matching (-2 to +2 difference) , a prop as a 10% chance to skip a move and 10% to have a double speed move. So, even at the same speed the outcome of a race bewteen party and prop is a bit uncertain. Here are the details for all levels of relative speed:

//prop is lightning fast (<= -13); Double:75% , None:0%
//prop is very fast (-8 til -12); Double:50% , None:5%
//prop is fast (-3 til -7); Double:30% , None:10%
//prop at default (-2 til +2); Double:10% , None:10%
//prop is slow (+3 til +7); Double:5% , None:15%
//prop is very slow (+8 til +12); Double:0% , None:20%
//prop is extremely slow (>= +13); Double:0% , None:30%

If you set prop movementSpeed to -1, the prop will not move relative to sparty speed. Instead, it will never do a double move and has a 15% chance to delay its move. The party will catch up such movers eventually, even if the party is very slow. Depending on AI workload and number of moving props nearby, props also skip moves occassionaly to maintain game perfomance (note that chasing props never skip a move for performance reasons though). Another reason for props coming to a halt is when they have a wait duration set at their current waypoint (for patrolling props) or if the departure time of the current waypoint has not been reached yet (for time driven props). Finally, random moving props might need some turns to find a new, reachable random destination after having reached their last random destination.

Via the gaTogglePartyToken script you can also set an absolute party speed (not affected by traits, attributes, items) or an additional speed modifier adding on top of the party speed.

Collision and pathfinding
Please note that all movers by default should have their collision turned to off. This allows them to move through each other and enhances their pathfinding greatly, i.e. it means less prop queues in crowded places and less props stuck without valid path. The engine makes sure that props do not end their moves in each others squares anyhow (exception: cross area waypoints on area borders for time driven movers that are in the process of switching areas -> on such waypoints props are allowed to stack, see also below), granting double (or more) moves to hop over other mobile props in the way or making props temporarily wait until the path is free again. These double, tripple, etc. moves make a prop move very quickly at times from the player's perspective. The more crowded an area is, the more very swift moves you will see. In extreme cases a prop will move 5 or 6 squares in a swipe overtaking all the other props lined up before it.

The different types of movers
All that being said, I suggest to have a look at the different types of movement that are available from the drop down menu ("MoverType"):

Upfront it's important to note that props of the types post, patrol and random can never leave the area map they are initially placed on (if the party already entered a nearby neighbouring area they continue to move though as long as they are on screen or a even bit outside visible screen). On the other hand, time driven props (daily, weekly, monthly, yearly) will work across any number of area maps and will always be moved/shown (with a bit of teleporting/synchronizing trickery running in the background): they can leave or enter into the area map the party is currently on. And when the party enters a new area, the location of time driven props will be set to the most fitting waypoint on this area map (see details below). When time driven props (see below) leave the current area towards a non-neigbouring area, they will vanish. When moving to a neighbouring area they just smoothly move across the border (assuming you set their waypoints correctly back-to-back at the area border, see below). To distinguish vanishing props from a bug, the engine displays a floaty text ("Heading off...") with the name of the target area, using the inGameAreaName property of class area (you can define this ingame areaname in the toolset, under area properties). Similarly, props entering the visible screen space, coming from non-neighbouring othwr areas, will pop in with a "Just arrived here..." message. Performancewise, time driven props a bit more ressource intensive (but the engine can handle quite a lot of them, at least from my recent testing with 20 of them on a single map).

The following explanations refer to setting waypoints manually via the properties tab (and waypoints subentry) of a prop. In the next section after this one I will go into details how to do this more quickly via the waypoint interface of the toolset (WPButton).

Post: The prop is stationary at the post and will not move in default mode. There's a mode available for all mover types here that is called "isChaser" though (see below for details). When this kicks in e.g. our prop of moverType here will move up to to a certain distance around the post ("PostLocationX","PostLocationY") specified here (and then give up chasing, returning to the post). Could be used e.g. for a stationary guardman.

Random: A random mover will randomly pick its next move target within a distance ("randomMoverRadius") around the central post location("PostLocationX","PostLocationY") and will then move towards that target. Once having reached the current target location, the random moving prop will pick the next random target location within the radius and so forth. Also, after 20 turns a random will switch its target in any event, so they wont get stuck permanently by unluckily picked targets. Random movers are extremely quickly setup: choose the post location and the allowed radius in which the random mover has to stay and you are done. Locally roaming monsters and ambience creatures can be dropped on the map very effectively this way. Like all other mover types, random movers can make use of the isChaser property (see below).

Patrol: The first mover type that makes use of the waypoints ("wayPointList") of a prop. A patrol mover starts at the first in list waypoint (index 0 in the waypoint list) and from there on moves from waypoint to waypoint in order of the waypoint list. After having reached the end of the list, the patrol mover starts with first waypoint again. A never ending circle.
The waypoints themselves are found in prop properties window, too. You can add and delete them from the props waypointlist. Each waypoint has an x and y location. When you move your mouse pointer over the area in the toolset's area main window you can see the location of each square as x,y coordinates. This way you can easily plan your props patrol route. Additionally waypoints have departureTime and areaName properties - both are only relevant for time driven props (daily, weekly, monthly, yearly), so you can ignore them patrol movers.
Furthermore, waypoints allow to set barkstrings for them (BarkStringsAtWayPoint, BarkStringsOnTheWayToNextWaypoints), short floating texts that will appear with a modifiable chance of 10% (checked for every barkstring entry, but a max. of one barkstring is shown per turn) above the prop on the main area map itself. An author can set two different lists of barkstrings for each waypoint, one at the waypoint itself (BarkStringsAtWayPoint) and one for travelling to the next waypoint (BarkStringsOnTheWayToNextWaypoints). Then, there's also a wait duration property: it makes props of mover type "patrol" wait for x rounds on the waypoint before moving on.

Daily: These movers will follow the cycle of their waypoints, too, but they will also adhere to the departureTime property of each waypoint. A reached waypoint will not be left until departure time of that waypoint has come. Also, once the departure time of the waypoint that the prop is headed to has come (even prior to stepping on that waypoint), the prop will change its movement target to the next in line waypoint. This way a long delayed prop might even skip a few waypoints, catching up with its time schedule.

The second important property for determining the course of a time driven prop is the areaName property of a waypoint. It shows on which area the waypoint it belongs to is located. This is used for signaling an area change of the prop. If the next in line waypoint shows a different area name than the one the prop is currently on and the departure time of the current waypoint has come, the prop is automatically transitioned to the new area, right on top of the next in line waypoint. This means that moving props across a number of different maps is as simple as typing different names in the areaName properties of their waypoints. For auch an area transition between neighbouring maps to look smoothly, you have to set the waypoint on current map and the waypoint on next map directly adjacent (back to back) to each other, like x16,y16 and x0,y16 for a transition towards the eastern neighbour.

The departure time expects the following format in its property field: days:hours:minutes. So the three time unit categories are separated by ":". For days any entry between zero and 336 will be accepted (the engine assumes a 12 month, 28 days a month, grouped into four weeks of seven days each, time format). Day 0 and day 1 both mean day 1 actually (ie using 0 or1 in the first place is the same). A daily mover requires the author to enter either 0 or 1 here. Hours range from 0 to 23 and minutes from 0 to 59. Some examples:
0:7:1 means on day one, seven hours in the morning and one minute
1:16:48 means on day one, 16 hours in the afternoon and 48 minutes
For our daily mover here only use 1 or 0 as entry for day. Weekly movers accept 0 to 7 for days, monthly movers will take 0 to 28 and yearly ones 0 to 336.

The type (daily, weekly, monthly, yearly) determines when the mover will start its movement pattern anew, beginning on waypoint 0 in its waypoint list again. Please note that the engine will automatically assign departure time values to first (index 0) and last waypoint (highest index number), overriding anything you entered here: the first waypoint has a departure time that is near the beginning of the interval, i.e. near 0:0:0, the last will have departure time near the end of the interval, i.e. in case of a daily mover near 0:23:59. I use "near" because the exact value depends on the time one step on the current area takes (timePerSquare). Also, please note right now every waypoint of a time driven mover (including first and last) waypoint needs a valid entry in the time format shown above for now. I will eventually add some convenience and error catch functionality here. All this considered I think it's a good practice if you grant the first and last waypoint time values near the beginning and end of the relevant interval (daily: 1:0:1 and 1:23:59, weekly: 1:0:1 and 7:23:59, monthly: 1:0:1 and 28:23:59, yearly: 1:0:1 and 336:23:59).

Also please make departure times increase all the time from waypoint to waypoint and never exceed the length of the interval. I think you will do so intuitively, but I mention it just in case.

Furthermore, time driven props will aways leave cross area waypoints (those waypoints on map borders, back to back, allowing smooth and seamless transitions of time driven props from area to area) as soon as they again, regardless of whether the departure time of that waypoint has been reached. This is coded to help props avoid bottleneck situations like eg when many props try to wiggle through a city gate in the morning on the way to the fields.

Finally, as the first and last waypoint mark the beginning and end of the time interval there is not much sense in placing them apart from each other. It is a good practice to have them on the very same square, like closing a circle.

The WP interface of the toolset described below already does adhere to these rules automatically (autosetting times of first and last waypoint, always placing them on the same square).

Weekly, Monthly and Yearly: These work just like daily above except that their respective intervals before the reset are longer. These can be used for e.g. merchant caravans who need weeks or months to travel from city to city. A market might take place once a week or some bizarre ritual in the woods nearby the remote village is conducted every full moon ;) ...

All moving props (post, random, patrol, time driven) can be set to be chasers (isChaser).

A chaser will try to get on the same square that the party is on (temporarily overriding his normal movement plans) but only once it has detected the party. Party detection happens when the party enters the "chaserDetectRangeRadius" around the chaser prop. A party with a good shadow trait (you can reroute this to any trait you like under edit/module properties in the toolset) can avoid detection by chasers. On the other hand, a chaser with a good spot spotEnemy value (under prop/properties) will detect a stealthing party more likely. This skill value comparison (party shadow trait vs. prop spotEnemy trait) is also influenced by light level (by +4 stealth in the night and by +12 stealth in utter darkness, both assuming no light on the current party square) and distance between party and prop (each square of distance between chaser and party gives party the a +2 stealth bonus). Finally, tiles themselves can grant a stealth bonus to the party (stealthModifier property of a tile), so the party can use eg undergrowth for cover. If you set the stealthSkipsPropTriggers property of a prop to true (found under prop properties section 08- Project Living World), the party can even sneak right through a prop on successful check (DC increased by 5), bypassing any attached encounters or convos.

Chasers (and actually all props) can be hidden in shadows (ie invisible) from the party, too, though. This is determined by a roll of the parties spot enemy trait (again, you can reroute this to any trait you like under edit/module properties in the toolset) vs a DC using the props stealth value (light level and distance figrued in again, see above).

The described stealth and detection mechanics also influence who might get a surprise round in a combat. They also emphasize active use of the party torch in darkness/night time, for either easier detection or better stealth chances.

The chaser prop will then try to catch the party, but only until it reaches its "chaserChaseDuration". It will also stop chasing when the party manages to get a certain distance between itself and the chaser. This distance is called "chaserGiveUpChasingRangeRadius". A chaser that manages to catch the party will trigger its "conversationWhenOnPartySquare" or "encounterWhenOnPartySquare" (should those be setup). When giving up chasing on the other hand, the prop will resume its normal routine again (walk to next waypoint for patrol and time driven movers, go to post and thwn resume for post and random movers).

Chasers will not cross map borders though, so best design chase situations more towards the middle of a map.

Using the new waypoint mode of the toolset (WP button)

The new WP button (next to the Info button) will let you enter waypoint editing mode.

It will allow you to set up, edit or delete waypoints for the currently selected prop (you can also change/select a prop after entering wp mode; reminder: right click on a square, then choose the prop from the dropdown menu with entities on that square).

The basics are - all require the WP toggle/button to be on:
1. Placing, left mouse click places a new waypoint, always one higher in order number than the currently focused waypoint (highlighted in blue, see also below). The way points are counted (like 3/8): first number is current order number, second number (behind the slash) is the number of currently existing waypoints for this prop.
2. Selecting, right mouse click opens the dropdown menu on a square, eg allowing you to choose an existing waypoint for focusing/editing or to choose a different mover prop to set up; the properties of the currently selected waypoint are shown in the properties tab (right hand side, like for props or other objects)
3. Deleting, escape key deletes the currently selected waypoint
4. Quickly rotating through, A/D key or W/S key allow you to change focus quickly on the next/prior waypoint of the selected prop. The currently selected waypoint is always highlighted in blue (rest is yellow). Using the keys to go through the waypoints is especially handy as - for time driven movers - this will also open so far closed areas if these contain waypoints of this prop. In other words: You can trace the whole path of a prop through the gameworld by going back and forth with A/D or W/S keys.
5. Copy & Paste: c key pressed with a waypoint selected copies this waypoint; v key and then left click on target square places the copied waypoint. This works also on other areas than the one the mover is placed on (if the mover is time driven). Copying waypoints is mainly useful for re-using the floaty lines/bark strings already set up for the copied waypoint.

Furthermore, there are some specifics to note, depending on the nature of the mover (time driven, patrol, random, post):

1. Post: Only one waypoint allowed (additional left clicks move this single waypoint), always on current map. Described with "post". The prop will return to this waypoint after a chase.

2. Random: Only one waypoint allowed (additional left clicks move this single waypoint), always on current map. Described with "random". This waypoint is the center of the radius that the random prop is allowed to choose new random targets within (see above for details). The prop will set a new random waypoint after each chase (not using post waypoint as return target after chases).

3. Patrol: Unlimited number of waypoints allowed (additional left clicks add waypoint after currently selected waypoint, see above), all waypoints always on current map. The wait duration in turns is displayed right after the way point number. After a chase, the prop will resume its patrol. Post waypoint is not used.

4. Daily: Unlimited number of waypoints allowed (additional left clicks add waypoint after currently selected waypoint, see above). Waypoints can be on as many different areas as you like. A "D" indicates that the interval is daily. The time in interval when the prop is supposed to leave this waypoint is shown right behind the "D". When the departure time is missing, the whole waypoint is shown in red and "Enter time" is written into the waypoint text. The waypoints of time driven movers are auto sorted in order of departure time. For this to kick in correctly, all waypoints need to have a departure time set up though. The first and last waypoint of time driven movers are always automatically set on the same square (the square of the first waypoint) and alway use the beginning and very end of the intervall. To set up waypoints correctly that are the last on an area and the next on a new area (croos area waypoints), plaase place them back to back right on the border of the respective areas. These will always just be move through waypoints for the movers, regardless of the departure times you set. In other words: Props will leave them as quickly as possible to prevent bottleneck situations on area change spots. After a chase, the prop will resume its scheduled route. Post waypoint is not used.

5.Weekly, Monthly and Yearly: These work just like the daily type, except that the letters "W", "M" and "Y" respectively flag which length of interval is used for the mover (see above for format and details on the time intervals).

I hope this is a helpful introduction to the world of movers. Setting up a living world of movers seems a bit intimidating at first (for me, too), but the new interface speeds the process up big time and also provides much more overview within the toolset than just manually edting waypoints list with no visual hints.

Two last things: Do not forget about the bark strings on the way to or at each waypoint - having the props utter situational one liners as floaties goes a long way in explaining the player what currently goes on onscreen. Finally, keep in mind that you can copy whole props (outside wp mode) just like single waypoints or whole triggers (select prop, press c key, press v key, left click to place the copied prop). This allows you to make clones of movers you have set up, for which you then can slightly adjust their waypoints/barkstrings. The cloning process is very helpful for setting up crowds of props quickly, like villagers, who adhere to certain samey movement patterns (eg leave village in the morning, return in the evening, etc).

Re: IB2: Guide for setting up moving props

PostPosted: Tue May 16, 2017 12:59 pm
by youngneil1
Updated guide above with:

"Essential: Movers require a square shaped area map for now".

Re: IB2: Guide for setting up moving props

PostPosted: Tue Oct 01, 2019 6:11 am
by youngneil1
Starting to update this guide now for the new WP interface in the toolset.. WIP for the time being...

Re: IB2: Guide for setting up moving props

PostPosted: Mon Dec 09, 2019 7:32 am
by youngneil1
Finally completed this guide, including the usage of the new waypoint interface in the toolset :D !