4E Zone Extension

[lokiare]

How would you go about creating a 'zone' extension for the 4E rule set?

It would need to be able to tell where it is on the map, as well as be resizable and it would need to be able to tell which tokens are where on the map. Then it would need to tie into the combat tracker to be able to tell when a creature starts its turn inside it, enters it, exits it, or the creator has a turn. It would also need to be able to do things like deal damage to the characters.

I'm a programmer, but I'm new to LUA and FG programming.

[Trenloe]

I think something like this might be possible - but would take a lot of coding, especially to cater for the exceptions to the normal operation (e.g. "oops, I didn't mean to move there, can you heal me of the damage for that zone please?").

The extension would need to:

Allow the creation of a zone - top left corner x,y and bottom right corner x,y coordinates probably.
Have some way to display the zone - perhaps hide it from the players as well?
Have code to check at the beginning of a PC/NPC turn if the linked token is within the zone.
Have code linked into the token movement events to check entering/leaving the zone. Some info on token events, the onMove event would be handy as well as the getPosition function: https://www.fantasygrounds.com/refdoc/tokeninstance.xcp#onMove
The size of the token would have to be taken into account, not just the position of the token as larger tokens would spread out from the token position. People use different sizes of tokens - would it rely on the size of the token itself or the number of squares the creature would take up, how east would this be to do?

Most of this is possible (after a fashion), but I think it would be lot of work to get it working close to 100% and allow for: easy maintenance of the zone - and also allow for multiple zones, tokens moving in/out, creature size, map features getting in the way, effects that impact on the zone, etc..

[Zeus]

Hmm I agree a fair amount of work but doable. In my 4E games I simply created a set of area of effect tokens (scaled to 50px see attached) which can be used to represent zones or AoE. Coupled with 4E Enhanced Images you can use them very effectively to model zones as they can sit on a lower layer than the player tokens so no horrible token stacking side effects.

[lokiare]

I think something like this might be possible - but would take a lot of coding, especially to cater for the exceptions to the normal operation (e.g. "oops, I didn't mean to move there, can you heal me of the damage for that zone please?").

The extension would need to:

Allow the creation of a zone - top left corner x,y and bottom right corner x,y coordinates probably.
Have some way to display the zone - perhaps hide it from the players as well?
Have code to check at the beginning of a PC/NPC turn if the linked token is within the zone.
Have code linked into the token movement events to check entering/leaving the zone. Some info on token events, the onMove event would be handy as well as the getPosition function: https://www.fantasygrounds.com/refdoc/tokeninstance.xcp#onMove
The size of the token would have to be taken into account, not just the position of the token as larger tokens would spread out from the token position. People use different sizes of tokens - would it rely on the size of the token itself or the number of squares the creature would take up, how east would this be to do?

Most of this is possible (after a fashion), but I think it would be lot of work to get it working close to 100% and allow for: easy maintenance of the zone - and also allow for multiple zones, tokens moving in/out, creature size, map features getting in the way, effects that impact on the zone, etc..

That's interesting. Is there any good tutorials on getting started with LUA and FG Extension creation? I might try to hammer this out.

[lokiare]

Hmm I agree a fair amount of work but doable. In my 4E games I simply created a set of area of effect tokens (scaled to 50px see attached) which can be used to represent zones or AoE. Coupled with 4E Enhanced Images you can use them very effectively to model zones as they can sit on a lower layer than the player tokens so no horrible token stacking side effects.

That will definitely help out in the mean time while I work on an extension. Of course I have to learn LUA and FG Extension programming

[lokiare]

Ok, so looking at the functions. It seems like I would have to grab a list of the creatures in the combat tracker, then verify their position between each initiative round change. Then from there I can apply the effect to the creature that ended its turn or the creature that started its turn.

I would also have to use the onDrag token function to detect when a token is moved into or out of the zone. Is there any simple example Extensions that I can look at for FG 3.x? Something I could use as a base and then add onto. First I would like to see if I can just notify the chat window when a creature enters/exits, starts/ends its turn in a zone. If I can get that far then I can move onto the next step.

[lokiare]

Ok, I have a basic extension made. It loads up, and on a turn change it spits a message to the chat screen. I'll have to see how to tell who's turn it is and then check to see if they are in any zones.

[lokiare]

The secret I've found to finding out how to do this is to open up the core ruleset and 4E ruleset files and search through the Lua code for what you need

[lokiare]

Ok, now I have the x, and y values of the current characters token whose turn its is on the combat tracker. I'd like to tie it into the pointers so you could just draw a pointer and add the zone effect to that. How would I go about accessing the pointers and getting a list of pointers?

[dulux-oz]

From lokiare1 in a PM to me:


I'm working on making a Zone and Aura Extension for 4E and I can't find where the pointer data is located. I want to allow the player to create a pointer on the map and then designate it as a zone for automating the effects of a zone. Where can I access the pointer info so I can tie the zone to the pointer?

Thank you for the info.

Not quite sure I understand your query, but here goes:

Pointers are embedded into the FG engine, so cannot be accessed directly. There is an exposed function that allows for the drawing of Custom Pointers, which I explain how to use in this post (https://www.fantasygrounds.com/forums/showthread.php?19253-Custom-Pointers-Coding-Toolkit-Over-Several-Posts&p=153209#post153209), but this doesn't exposed the built-in pointers.

Reading through your 4E Zone Extension post it seems to me what you are trying to do is access the in-built Pointers - and I don't think there is a way to do that - Moon Wizard would know for sure, as he's one of the FG owners.

Dr Zeus and I have a discussion further down the Pointer Thread (listed above) about Line of Sight, etc - I don't know how far he's gotten on that but it seems to me that what you are trying to accomplish is somewhat similar.

Anyway, I'm posting this onto the 4E Zone Thread as others will more than likely be interested

Cheers

[Trenloe]

The secret I've found to finding out how to do this is to open up the core ruleset and 4E ruleset files and search through the Lua code for what you need
Yeah, the ruleset code is the best place to look for examples.... "Find in Files" is your friend! :)

I'm guessing that as you have got this far you already know of the documentation in the library?

In the outside chance that you don't, or for others reading this thread that aren't familiar with it, the FG API is defined in the library -> Ruleset Reference and details on extensions, XML, where to find more info on LUA, etc. are given in the Library -> Ruleset Modification Guide.

Find the library here: https://www.fantasygrounds.com/library/ (the link used to be included at the top of the forums page but is not there now).

[lokiare]

Yeah, the ruleset code is the best place to look for examples.... "Find in Files" is your friend! :)

I'm guessing that as you have got this far you already know of the documentation in the library?

In the outside chance that you don't, or for others reading this thread that aren't familiar with it, the FG API is defined in the library -> Ruleset Reference and details on extensions, XML, where to find more info on LUA, etc. are given in the Library -> Ruleset Modification Guide.

Find the library here: https://www.fantasygrounds.com/library/ (the link used to be included at the top of the forums page but is not there now).

Unfortunately those seem to be extremely out of date. Many functions have been changed, things have been migrated to different classes/packages etc...etc...

[Trenloe]

Unfortunately those seem to be extremely out of date. Many functions have been changed, things have been migrated to different classes/packages etc...etc...
Really? Which ones in particular?

The ruleset modification guide is pretty generic and scanning through that I'd say that 95% of it is still relevant now. https://www.fantasygrounds.com/modguide/ Most of the code in there is examples and not tied to a specific ruleset, but the information contained gives good background on how certain aspects of the FG architecture works: Resources, Windows and Controls, Data Base, Scripting, Templates and Extensions.

The Ruleset Reference has been updated to FG 3.0 - which functions etc. do you think are out of date? https://www.fantasygrounds.com/refdoc/

I use both of these guides extensively and very recently (I've used them today) and have been using them as references to update older extensions to FG 3.0 and in developing the FG 3.0 version of the Star Wars: Edge of the Empire ruleset. So, I'm a bit puzzled that you think these are extremely out of date.

Perhaps if you could point out the area that are out of date it would help to get them scheduled to be updated. Thanks. :)

[lokiare]

Really? Which ones in particular?

The ruleset modification guide is pretty generic and scanning through that I'd say that 95% of it is still relevant now. https://www.fantasygrounds.com/modguide/ Most of the code in there is examples and not tied to a specific ruleset, but the information contained gives good background on how certain aspects of the FG architecture works: Resources, Windows and Controls, Data Base, Scripting, Templates and Extensions.

The Ruleset Reference has been updated to FG 3.0 - which functions etc. do you think are out of date? https://www.fantasygrounds.com/refdoc/

I use both of these guides extensively and very recently (I've used them today) and have been using them as references to update older extensions to FG 3.0 and in developing the FG 3.0 version of the Star Wars: Edge of the Empire ruleset. So, I'm a bit puzzled that you think these are extremely out of date.

Perhaps if you could point out the area that are out of date it would help to get them scheduled to be updated. Thanks. :)


Well the anatomy of a ruleset is extremely out of date. Then there is no real information in the modguide about how to override a rulesets xml in an extension as far as I can tell. Like I'm trying to use the custom pointers coding tutorial, but I have no clue where to put the xml <imagecontrol> stuff.

[Trenloe]

Well the anatomy of a ruleset is extremely out of date.
Yeah, that is out of date - hence why I didn't reference it. :)


Then there is no real information in the modguide about how to override a rulesets xml in an extension as far as I can tell. Like I'm trying to use the custom pointers coding tutorial, but I have no clue where to put the xml <imagecontrol> stuff.
That is related to what I mentioned above - it is generic information as a lot of rulesets will do stuff differently. For example, the main map/image <imagecontrol> control could be in different files (and classes) for different rulesets, so giving specifics in these type of guides would only be relevant for a handful of rulesets. With FG 3.0 hopefully this will begin to change for rulesets layered on top of CoreRPG, but this will take a while for older rulesets to be updated (if they ever are). That's where either looking through the existing rulesets & extensions and/or asking the very helpful members of the community comes in! :)

I've answered your question on where to put the custom code in an <imagecontrol> specification for the CoreRPG ruleset in another thread.

I still maintain that the 2 links I provided will give you a lot of background information on various aspects of Fantasy Grounds and the vast majority of the information there (Ruleset Modification Guide and Ruleset Reference) is completely valid in FG 3.0. Yes, it won't contain information specific to a certain ruleset or exactly what you're trying to do (no document ever will) but it gives you a good background. The next step is then to look through the ruleset you are interested in (and extensions based off that ruleset) to see examples of how controls are defined in the base ruleset and how extensions override those. See the Enhanced Images extension as an example of an extension that modifies the \campaign\campaign_images.xml file: https://www.fantasygrounds.com/forums/showthread.php?20231-Enhanced-Images-%28layers%29-for-FG-3-0-CoreRPG-%28and-rulesets-based-on-CoreRPG%29

[lokiare]

Yeah, that is out of date - hence why I didn't reference it. :)


That is related to what I mentioned above - it is generic information as a lot of rulesets will do stuff differently. For example, the main map/image <imagecontrol> control could be in different files (and classes) for different rulesets, so giving specifics in these type of guides would only be relevant for a handful of rulesets. With FG 3.0 hopefully this will begin to change for rulesets layered on top of CoreRPG, but this will take a while for older rulesets to be updated (if they ever are). That's where either looking through the existing rulesets & extensions and/or asking the very helpful members of the community comes in! :)

I've answered your question on where to put the custom code in an <imagecontrol> specification for the CoreRPG ruleset in another thread.

I still maintain that the 2 links I provided will give you a lot of background information on various aspects of Fantasy Grounds and the vast majority of the information there (Ruleset Modification Guide and Ruleset Reference) is completely valid in FG 3.0. Yes, it won't contain information specific to a certain ruleset or exactly what you're trying to do (no document ever will) but it gives you a good background. The next step is then to look through the ruleset you are interested in (and extensions based off that ruleset) to see examples of how controls are defined in the base ruleset and how extensions override those. See the Enhanced Images extension as an example of an extension that modifies the \campaign\campaign_images.xml file: https://www.fantasygrounds.com/forums/showthread.php?20231-Enhanced-Images-%28layers%29-for-FG-3-0-CoreRPG-%28and-rulesets-based-on-CoreRPG%29

Sure.

I'm actually already looking at that, but its not helping much. I'm trying right now:

in my extension.xml:


<root version="3.0" release="1.0" logo="logo.png">
<properties>
<name>Zones (4E)</name>
<version>0.1</version>
<author>James (Lokiare) Holloway</author>
<description>A persistent area effect extension.</description>
</properties>
<windowclass name="imagewindow" merge="join">
<sheetdata>
<imagecontrol name="image">
<script file="pointer_toolkit.lua" />
<pointertypes>
<arrow>
<icon>pointer</icon>
<label>Draw Arrow</label>
</arrow>
<square>
<icon>pointer_square</icon>
<label>Draw Square</label>
</square>
<circle>
<icon>pointer_circle</icon>
<label>Draw Circle</label>
</circle>
<cone>
<icon>pointer_cone</icon>
<label>Draw Cone</label>
</cone>
<custom name="Zone">
<icon>pointer_square</icon>
<label>Draw a Zone that can have effects applied to it.</label>
</custom>
</pointertypes>
</imagecontrol>
</sheetdata>
</windowclass>
<base>
<script name="ZoneManager" file="scripts/zone_manager.lua" />
</base>
</root>


The 'custom' pointer doesn't show up when I load it.

[lokiare]

There is no reference for DesktopManager as well as other managers. I don't know, is DesktopManager specific to 4E because I would think it would be used by all the rulesets?

[lokiare]

Ok, found your post in the other thread and I got that part working, now to make it actually draw a square when I select that one. Thanks for the help. With a few more tweaks I can probably get this thing working. It would probably be useful for others since you can compare the x and y coordinates of anything in a pointer shape and then have the code select it with the hit of a button or something like that.

[lokiare]

I'll probably throw together a tutorial on how to make an extension for beginners after this as its sorely needed.

[lokiare]

Progress so far:
You can right click on a map and the pointers menu has an extra square shape called 'zone' that you can select. Once you create the zone, the rule set can tell whether a creature is in the zone or not on the start or end of its turn (and I have it echo that information to the chat window).

One thing I need to know how to do is persist the data. If you draw a zone and then close FG, then reopen it the shape of the zone is on the map, but the extension doesn't have the data from the zone available. So how do you save your global tables to the campaign table to make it persistent between sessions?

I also need to know specifically which functions in the 4E rule set are used to apply conditions and damage and if there is a way to send a text string to these functions along with a target list or something like that to apply the effect?

[Trenloe]

One thing I need to know how to do is persist the data. If you draw a zone and then close FG, then reopen it the shape of the zone is on the map, but the extension doesn't have the data from the zone available. So how do you save your global tables to the campaign table to make it persistent between sessions?
Use the campaign database to store your data that needs to be persisted. You'll probably need to add it within the <image> entry in the database that is specific to the image in question. Add a new tag/entry section to the image.id-XXXXX database entry for the image that contains the zone and store the data you need to maintain in that new section.

Use the DB package: https://www.fantasygrounds.com/refdoc/DB.xcp and/or the databasenode object: https://www.fantasygrounds.com/refdoc/databasenode.xcp to access the database.

[Zeus]

As Trenloe has pointed out you need to store the zone data at creation in campaign database. Then when your extension initialises have it check for the existence of the database nodes , if they exist then you load your zone information in from the database.

However, whereas Trenloe suggested storing this data inside the images database structure, I would suggest creating a sub node under the combattracker root node or perhaps under ctproperties. This, as the CT can only link entries to one image/map at anyone time so it makes sense to tie your zones to the CT as opposed to the images. This unless you want to be able to pre-create zones on maps before play (in which case Trenloe's suggestion would work better).

[Paladin's Pride]

Nothing helpful to say here except that I really hope this manages to be completed. Zones are a frequent "oops forgot to apply that" in my present campaign.

[lokiare]

Having to wade through long lists of code that I don't fully understand is getting in the way. I'll try to get it done, but if I give up I'll post the extension in this thread so someone else can complete it.