[Any Ruleset] Patrol Duty: Automated Token Pathing

[Saagael]

Forge Link: https://forge.fantasygrounds.com/shop/items/1811/view

Patrol Duty allows the GM to create paths for tokens. Tokens will then travel along the path at configurable intervals. Perfect for any scenario where many NPC tokens move independently of the party, and allows the GM to focus on running the game instead of moving tokens around.

Getting Started

See the extension in action on Youtube: https://www.youtube.com/watch?v=YH21EMqIGio. Laerun and I recorded a short session that goes over all the major features for this extension and how to use them.

To get started creating a path for a token, simply right-click the token and select the "Open Path Editor" option at the bottom of the radial menu. Alternatively, you can select the token and click the "Open Path Editor" button on the image toolbar. This will open the path editor for that token.

Paths for most tokens are saved with the token and image, and will be deleted if you delete the token. The exception for this is if the token is associated with a combat tracker entry, in which case the path will persist even if the token is delete and re-added.

When setting up paths for tokens that are part of an Encounter, the data for those paths is saved with the Encounter and is added to the token when the encounter is added to the combat tracker. This way you can pre-make your paths when designing your encounters and pre-placing tokens, and then have those paths activate as soon as you add the Encounter to the combat tracker.

Paths

Paths are assigned to tokens, and they are made up of a collection of waypoints. When a token moves along its path, it moves from waypoint to waypoint in sequential order. When it reaches the end, the token will either stop moving, loop back to the start of the path, or travel the path in reverse based on how the path is configured by the GM.

Tokens move at a set speed, and each path has a configured trigger that moves the token. These triggers are:


At the end of the round
Every turn
On the token's turn (only works for tokens of combat tracker entries)
In real time, on an interval of seconds


Paths also have the following settings:


Speed. This is the raw speed that the token moves per round. This is measure
Period. Sets how many trigger events must occur before the token moves. For example, a Period of 2 means the token will move only every second trigger. A Period of 3 means the token only moves every third trigger
Jitter. Sets how precise a token's movement is. A value of 0 means the token will most exactly on the most straight line between waypoints. The higher this value (up to a max of 100) means the token's movement will have a random deviation. The closer the token gets to its target waypoint the less this deviation gets.
Snap to Grid. If enable, tokens will snap to the grid of the image after it moves.


Waypoints

Waypoints are denoted with one of three map pin tokens. You can add them to a path by drag/dropping them from the path editor onto the image with the token whose path you are editing. A green waypoint marks the start of a path, a red waypoint marks the end, and yellow waypoints mark out points between the beginning and end.

Each waypoint in a path has a few options for it specifically.


Behavior when reached. When a token reaches a waypoint, the waypoint can be configured such that the token either pauses its movement until the next movement trigger, or stop for a number of movement triggers. Useful if you want a token to linger at a waypoint
Speed override. Modifies a token's speed between the current waypoint and its target waypoint. This can either override the base speed set in the Path, or it can act as a multiplier for the base speed. Useful when you want a token to move more slowly or quickly through an area
Warping. Instead of physically traveling from one waypoint to the next, this tells the system to instead instantly teleport the token from one waypoint to the next. Waypoints can be configured so that the token either teleports from the current waypoint to the next waypoint, teleports from the previous waypoint to the current waypoint, or both of these properties.


Change History
June 12th, 2024 - Initial release

https://ko-fi.com/saagael

[anstett]

HUZZAH!!!!

Thank you

[rhagelstrom]

This sounds like it might be really neat

[MrDDT]

This is really cool. I've been testing it out.

Love it. I did notice that it doesn't snap into the center of a grid square, is it possible to make this happen as an option?

Advice to people that the waypoints set are to show the pathing but not where exactly the tokens land, they are to set the path so the tokens don't go the wrong way, it can also jump LOS walls, so use the pathing to set it for that.

[Saagael]

This is really cool. I've been testing it out.

Love it. I did notice that it doesn't snap into the center of a grid square, is it possible to make this happen as an option?

Advice to people that the waypoints set are to show the pathing but not where exactly the tokens land, they are to set the path so the tokens don't go the wrong way, it can also jump LOS walls, so use the pathing to set it for that.

Unfortunately I couldn't find a way to tell FG to "snap to the center", and the only way I could figure to do it is to rewrite the token position math and I didn't feel like doing that. That or actually implement a pathfinding algorithm that worked on a per-square basis. I'll keep thinking on it, but for now it's not something I have the energy to do.

EDIT: I also justified it to myself that for things that are automatically moving on a patrol it's less important to know exactly what square they're in, so it's fine if they sit on the edges or vertices.

Regarding the second point, you are correct that the tokens are not "moving" in the technical sense, so they can go through line of sight. However they will always exactly hit a waypoint before moving to the next one.

[Moon Wizard]

@Saagael, there is an Image.snapToGrid API.
https://fantasygroundsunity.atlassian.net/wiki/spaces/FGCP/pages/2165473281/Image#snapToGrid

Regards,
JPG

[Saagael]

@Saagael, there is an Image.snapToGrid API.
https://fantasygroundsunity.atlassian.net/wiki/spaces/FGCP/pages/2165473281/Image#snapToGrid

Regards,
JPG

That's what I'm using, but it will snap to the nearest center, edge, or vertex. Based on the documentation, I can't tell it to only snap to a subset of those points.

[Moon Wizard]

That's correct; it snaps to the nearest snap point as if you were dragging.

Regards,
JPG

[rhagelstrom]

It'd be nice if it indicated if that snap point is an intersection, center or edge. That would be very useful for a number of reasons.

[Jiminimonka]

Nice one!

[claedawg]

This is awesome. When I run larger dungeons, I like to place all encounters at the beginning and have some of the npcs patrol (instead of running random encounters). With this was around a few years ago, lol.

[seycyrus]

This is pretty awesome, but a question came up when i was testing by myself with running two instances of FGU (one connecting as localhost). I tried to get a token to move every second, but it was stuck in place. Is this another sideeffect of the heartbeats or timers not really running unless another user connects in to FGU?

[MrDDT]

This is pretty awesome, but a question came up when i was testing by myself with running two instances of FGU (one connecting as localhost). I tried to get a token to move every second, but it was stuck in place. Is this another sideeffect of the heartbeats or timers not really running unless another user connects in to FGU?

I was able to get it going with no users on timer. Make sure to turn the timer on the map at the top.

[seycyrus]

I was able to get it going with no users on timer. Make sure to turn the timer on the map at the top.

Thanks, that was it!

My localhost connection is able to see the waypoints ... I assume that normal players won't?

[Giggles666]

Awesome, thanks for this, very much appreciated. I'm sure my PCs will love it. ;)

[Saagael]

Thanks, that was it!

My localhost connection is able to see the waypoints ... I assume that normal players won't?

That's a good question. I haven't tested it specifically but now that you mention it I think players will see the waypoints if you open up the path while they've got the map open. That's an oversight and I'll get it fixed shortly.

[Jiminimonka]

I did have FGU lockup twice with this - but not the 3rd time. Might be the URL timer related.

When I get time I will try to reproduce with steps.

[Lou Ciphor]

That's a good question. I haven't tested it specifically but now that you mention it I think players will see the waypoints if you open up the path while they've got the map open. That's an oversight and I'll get it fixed shortly.

Yes, players do see the waypoints.

I'm still not able to get this to work properly. Token warps to START, but then just sits there no matter what mode I set it to. Yes, the timer is on and the path is on.

Could you do a demo video? Maybe that'll help me and others. :D

[Saagael]

Yes, players do see the waypoints.

I'm still not able to get this to work properly. Token warps to START, but then just sits there no matter what mode I set it to. Yes, the timer is on and the path is on.

Could you do a demo video? Maybe that'll help me and others. :D

I'll see if I can put together a video. In the meantime, is the speed for the path set to a non-zero value? It defaults to 1, but if the game system has a default distance multiplier of 5 (like in 5e) and you have Snapping set to true, it could be moving 1/5th of a space and then snapping back to its original spot.

If that's not it, feel free to zip up the campaign and share it here. I'll take a look and see if I can find what's up.

[Morbid-Don]

Hi,

Once I click the stopwatch then an Open URL popup window shows (so the timer will work) - after clicking 'Yes to All' then the log becomes filled up with 'Detecting path with an infinite warp loop. Skipping that path'

How do I remedy this issue? My goal is to set my Buffalo token to walk around the map in a loop (basically animate the one token)

61099

[Saagael]

Hi,

Once I click the stopwatch then an Open URL popup window shows (so the timer will work) - after clicking 'Yes to All' then the log becomes filled up with 'Detecting path with an infinite warp loop. Skipping that path'

How do I remedy this issue? My goal is to set my Buffalo token to walk around the map in a loop (basically animate the one token)

61099

Interesting. That error is supposed to prevent paths that have an infinite loop, but it doesn't look like your path has that. Can you send me a zip of the campaign so I can debug it?

[Morbid-Don]

Hey - here is a zip of my campaign (wasnt sure what to submit) 61100

[Saagael]

Hey - here is a zip of my campaign (wasnt sure what to submit) 61100

So the images and tokens that are referenced in the campaign aren't actually in the campaign, so I can't look at or edit anything. I'll keep trying to reproduce this though.

When you were adding the waypoints, did you add them in the order they're supposed to be traversed, or did you add the start and end point before the middle waypoints?

EDIT: I've attached a version of the ext to this post that adds some logging. It will spam the chat even more, but if you could get me a screenshot of chat when it does that will also help.

[Morbid-Don]

Hi - two items - my clipboard from FG and a video capture 61102

Originally the sequence i did was

Drop token onto map from Assets
Right Click Token
Drop green, yellow, yellow, yellow, red (start, middle, middle, middle, end)

[Saagael]

Hi - two items - my clipboard from FG and a video capture 61102

Originally the sequence i did was

Drop token onto map from Assets
Right Click Token
Drop green, yellow, yellow, yellow, red (start, middle, middle, middle, end)

Thanks for that, I think I figured it out. There were a handful of paths that had no waypoints, and I had a bug that considered that an bad path when it shouldn't be. And based on your recording it looks like the token is moving just fine. I'll get this submitted to the Forge shortly

[Morbid-Don]

woohoo ~ thank you!

[nephranka]

This ext seems to remove the red helmet in the radial menu of B9's spell tokens ext. It appears that both are fighting for the 6'o clock space.

[Saagael]

This ext seems to remove the red helmet in the radial menu of B9's spell tokens ext. It appears that both are fighting for the 6'o clock space.

I was concerned this might happen; I'll try and get something working to fix that.

[Saagael]

Laerun and I recorded a video that walks through how to use the main features for this extension, which you can see on the FG Academy Youtube channel: https://www.youtube.com/watch?v=YH21EMqIGio

[Morbid-Don]

Hi - i saw the updated - here is my latest compile log - based on the timer error 61142

[Saagael]

Hi - i saw the updated - here is my latest compile log - based on the timer error 61142

Thanks for reporting. I uploaded a fix for this; let me know if you see any other errors.

[Morbid-Don]

Just tested - there is a script error = scripts/manager_pathing.lua attempt to index null value / new compile log attached61150

[Saagael]

Just tested - there is a script error = scripts/manager_pathing.lua attempt to index null value / new compile log attached61150

Hm, that's the same error at the same location. You updated and don't have an unzipped version of the extension, correct? I'll re-upload the build just in case though.

[Morbid-Don]

Hi Saagael,

Confirming now - all is working (what i did was a manual update to FG - which did the trick) - thank you, stay GAMING!

[nephranka]

Any luck resolving the conflict with B9's spell tokens?

[Saagael]

Any luck resolving the conflict with B9's spell tokens?

Yes, but apparently it didn't get merged into my release branch. I'll get it out by the end of the weekend.

[Saagael]

Any luck resolving the conflict with B9's spell tokens?

I just pushed the update to the Forge. This should mean that spell tokens' radial menu option is now visible, and you can still access the Path Editor window from the image control bar.

[nephranka]

I just pushed the update to the Forge. This should mean that spell tokens' radial menu option is now visible, and you can still access the Path Editor window from the image control bar.

Looks like version 1.0.2 still overwrites the 6 o'clock position on the radial.

[Saagael]

Looks like version 1.0.2 still overwrites the 6 o'clock position on the radial.

Dang. I've removed the option from the radial menu altogether. There's no way for me to make the compatible. The only solution is to remove the radial option and use the buttons in the image toolbar.

[nephranka]

Dang. I've removed the option from the radial menu altogether. There's no way for me to make the compatible. The only solution is to remove the radial option and use the buttons in the image toolbar.

Maybe you can put in a check for B9's ext and remove the radial, that way others who don't use the ext would be uneffected?

[Saagael]

Maybe you can put in a check for B9's ext and remove the radial, that way others who don't use the ext would be uneffected?

I could, but I'd have to find a way to get the unvaulted code for Spell Tokens. But in general radial menus are one of the hardest places to coordinate between extensions; there's absolutely no built-in way to avoid these kinds of collisions. So it's probably for the best that I don't use it and instead use the image toolbar, which does have a lot of support.

[nephranka]

I could, but I'd have to find a way to get the unvaulted code for Spell Tokens. But in general radial menus are one of the hardest places to coordinate between extensions; there's absolutely no built-in way to avoid these kinds of collisions. So it's probably for the best that I don't use it and instead use the image toolbar, which does have a lot of support.

I see. B9 is easy to work with if you wanted to go that route. I am sure you could discuss the code with him but I am good either way. I can't lose the radial for B9 given how much I use it so, any solution works for me.

[nephranka]

Looks fixed now. Thanks!

[Arnagus]

Hello Saagael,

I noticed that for "per second", you are leveraging mattekure's Timer (https://forge.fantasygrounds.com/shop/items/665/view). Unfortunately, there is no way to change the URL for the "delayed response" time server (I have mine hosted on localhost as his server sometimes... times out - thus stopping the timer).

Would it be possible to leverage his option (https://www.fantasygrounds.com/forums/showthread.php?73977-Timer&p=652131&viewfull=1#post652131) to point to the right server if his extension is loaded? Or alternatively add an option for this extension?

He is using:

-- Constants
DEFAULT_TIMER_URL = "https://mattekure.com/Timer/"
LOCALHOST_TIMER_URL = "http://localhost:1803"

function getTimerUrl()
if checkUrlOptionDefault() then
return DEFAULT_TIMER_URL
else
return LOCALHOST_TIMER_URL
end
end

function checkUrlOptionDefault()
return OptionsManager.isOption(TIMER_URL, DEFAULT_TIMER_URL)
end

I see that this is hardcoded in your scripts/manager_path_timer.lua:

Interface.openURL("https://mattekure.com/Timer/", onClock)

Many thanks for considering!

[Saagael]

Would it be possible to leverage his option (https://www.fantasygrounds.com/forums/showthread.php?73977-Timer&p=652131&viewfull=1#post652131) to point to the right server if his extension is loaded? Or alternatively add an option for this extension?

An excellent request! I just pushed an v1.0.4, which directs Patrol Duty to use Timer's configured url if it is loaded. If Timer is not loaded, it will still use the hardcoded one.

[Arnagus]

An excellent request! I just pushed an v1.0.4, which directs Patrol Duty to use Timer's configured url if it is loaded. If Timer is not loaded, it will still use the hardcoded one.

Perfect, many thanks. Will try out this evening.

[Arnagus]

Perfect, many thanks. Will try out this evening.

You introduced a spelling error :confused:
The function name misses the last letter: getTimerUr instead of getTimerUrl


[ERROR] Script execution error: [string "PatrolDuty:scripts/manager_path_time.lua"]:69: attempt to call a field 'getTimerUr' a nil value

However - even after fixing it, whatever starts second does not work: either the token does not move on seconds (if the timer started first), or the timer does not tick but the token is moving (if the token was started first).

Not sure what is causing the interference.

[Saagael]

You introduced a spelling error :confused:
However - even after fixing it, whatever starts second does not work: either the token does not move on seconds (if the timer started first), or the timer does not tick but the token is moving (if the token was started first).

Not sure what is causing the interference.

I'm not exactly sure what you mean here; things look like they're behaving on my end. Tokens are moving based on the timer, and I can disable the timer or disable token pathing and it stops/starts as expected. Were you seeing this behavior before the update?

If the token is moving then the timer must be running, there's not really any other way it could be moving.

What order are you adding and enabling things on the map that causes the incorrect behavior?

[Arnagus]

I'm not exactly sure what you mean here; things look like they're behaving on my end. Tokens are moving based on the timer, and I can disable the timer or disable token pathing and it stops/starts as expected. Were you seeing this behavior before the update?

If the token is moving then the timer must be running, there's not really any other way it could be moving.

What order are you adding and enabling things on the map that causes the incorrect behavior?

There are two timers: the small clock on the map starting the token movement (on seconds), and the time from Timer with its own window (button on sidebar).

You can start both independently, but only the first one started works.

Will try again with a fresh campaign.

[Saagael]

There are two timers: the small clock on the map starting the token movement (on seconds), and the time from Timer with its own window (button on sidebar).

You can start both independently, but only the first one started works.

Will try again with a fresh campaign.

Ah, got it. I haven't done anything with the built-in timer that the Timer extension adds except pull the URL from its settings. Patrol Duty will only use its own timer that's started from an image's toolbar.

I can look at syncing the two, but for now they'll run separately.

[legionariobr]

Hello, I would like to ask about the ext, maybe I am doing something wrong because I cannot see the waypoint markers.

Things I tried:
Disable all other extensions - doesn't work.
Create a new campaign – doesn’t work.
Delete ext folder and update everything, new campaign - doesn't work.
Try adding CT tokens – it doesn’t work.

63219
63220

[Saagael]

Hello, I would like to ask about the ext, maybe I am doing something wrong because I cannot see the waypoint markers.

Things I tried:
Disable all other extensions - doesn't work.
Create a new campaign – doesn’t work.
Delete ext folder and update everything, new campaign - doesn't work.
Try adding CT tokens – it doesn’t work.

63219
63220

There's a module called Patrol Duty Tokens that has the tokens the extension looks for. Can you try loading that mod and see if they show up for you then?

[legionariobr]

I don't think it loads properly.
63221

[Saagael]

That's very strange. Do you see any errors or warnings in the console log? You can open it by typing "/console" in the chat box.

[Saagael]

I don't think it loads properly.
63221

I think I found out what's wrong. Try updating one more time and see if it loads correctly.

[legionariobr]

That's very strange. Do you see any errors or warnings in the console log? You can open it by typing "/console" in the chat box.

true, I can't see any errors and it's a new install, new campaign, no other extensions loaded.

can find the module, but it doesn't appear.

i'll try another ruleset.

[legionariobr]

I think I found out what's wrong. Try updating one more time and see if it loads correctly.

It worked, after pressing 'update' 2 times, it downloaded and works.

Thank you very much for your help and sorry to bother you for something so simple.

[Saagael]

It worked, after pressing 'update' 2 times, it downloaded and works.

Thank you very much for your help and sorry to bother you for something so simple.

Not a problem at all! It was my mistake; the last update I submitted didn't have the module in it.

[madman]

Hello,
I am not sure what I am missing. There is no radial menu icon to open the settings.
New campaign. nothing else loaded. I also tried it in a PF2 campaign with the same results.
Any help would be appreciated.

Madman

[Saagael]

Hello,
I am not sure what I am missing. There is no radial menu icon to open the settings.
New campaign. nothing else loaded. I also tried it in a PF2 campaign with the same results.
Any help would be appreciated.

Madman

This menu was removed due to compatibility issues with other extensions. You can access the path menu using the buttons on the image's toolbar.

[madman]

Sweet! Thanks!

[Elrix]

Ok,

so the link to mattakure's isn't working. But I didn't need it for what I was doing, I got the pathing of the NPC's (5.5e) to work starting on turn..

I added the NPC's via an encounter, added them the combat tracker and set their paths, cycled through a bunch of turns and everything moved on it's own REALLY nice.

So, I remove them from the combat tracker... and then I added the back in from the combat tracker... and the pathing is gone.

Did I do something wrong?

[claedawg]

Can you set the time between waypoints to be hours, days, weeks or months?

Was wondering if this can be used for overland maps to track nomadic tribes and monsters.

[Saagael]

Can you set the time between waypoints to be hours, days, weeks or months?

Was wondering if this can be used for overland maps to track nomadic tribes and monsters.

Not natively, unfortunately. There would need to be some mechanism that tracks time on that large a time scale, and this extension doesn't add that.