Undocumented lua functions and how c#->lua is exposed in general.

[bratch9]

Hi,
While looking at code a while back. ( In the 4.3.3 release period, and waited to see if it would get documented.. ) I noticed the death markers were added and they expose new lua api that I can not find the documentation for. ( Or see in the release notes that they were added.. )

addLayer, deleteLayer, getLayerByName, addLayerPaintStamp ( In 'Image' )


I pick up documentation from Developer Guide Ruleset API Reference Is this the correct valid location ?

Also noticed in the <layer><token> sections a new entry for <prototype3Dflat />, and not sure what this is going to be for etc.. ( I'm sure its for some new fun stuff at some point !! )

I'm again seeing an issue with how SW adds to the lua api, in that it seems only the minimum required gets added. So if the death markers had not been written in lua, I'd guess we would not have seen these new api exposed.. ( If the death markers had been added via c# etc.. )

I'm sure the likes of 'addLayer' could be used for 'add fx layer', but then not having a lua function for 'addLayerFxStamp', or what ever the function would be to add a <layer><fx> type item, causes questions to what we could do with an extension with access to more lua api would give us ? ( And the other things like 'lights' 'walls' etc.. )

Obviously we are also missing things like, getLayerItem(path,layerID) to get a list of the items in that layer. ( <stroke> list for death markers eg.. <fx> or <light> or <shortcut> or <occluders> etc.... ) Or the ability to edit/delete any 'one' item in that list.

This is because most of the 'image editor' is on c# and not in lua... So I guess the person who added 'death markers' decided it was simper to do the bulk of the work in lua and expose a few new c#=>lua api functions.

Would it be possible to get a shift in the way SW exposed c# to lua, and try and get a more 'full' way to allow more things to be done in pure 'lua' ?

For example, getting more of the image layer function, would allow an extension to code up a 'pure lighting' only edit GUI tool or a more specific focused 'wall edit' GUI tool. But to do this we would need api access to add/get/delete/edit the different types of items that can be added to layers..

I'd love to see 'per player' level visibility to a layer, and lua api to control this. Thinking along the lines of a map with these 'layers'
1. image roof layer.
2. token upper layer.
3. image upper layer.
4. token ground layer.
5. image ground layer.

So an extension could enable, layer 1+4+5 when outside a building and show it with its roof on... and then when inside the building ground level enable just 4+5... and then go upstairs to enable 2+3 etc... to create a more interactive map as a player walks around. ( Instead of the Dm having to move the token to a new area of the map or into a new image depending on how the levels are set up etc.. )

But this would require control of 'Token' onto a layer level... Sort of like creating the 'death marker' layer... create a 'addLayer(path,"paint", {name = "token"}) type thing and then use the layer api to get tokens on the layer and edit/move them around etc.. ( Which I know is a far change from the current 'Token' system... but would 'unify' the 'Token' system into the layer system for these sorts of new features.. )

I also find it odd that the 'death markers' causes an 'addLayer' which add it to the top of the layer system... so the death markers end up on top of a map eg 'snow fx layer'.. along with the 'Tokens' that are also on top of said layer... Been able to map edit and pre-add the 'Death Markers' layer in the map setup, would allow the map creator to put them under such effects as 'snow/rain' fx layer. And if the system was extended to allow 'Tokens' to be move to a layer the map creator could pre-add a 'Token Layer' layer in the map.

But pre-adding layers to the map dont work because the 'clearMarkers' for death markers deletes the 'layer' from the map, instead of deleting each 'death marker' from the layer. ( Because the item level delete was not exposed... only the item level create was exposed. ) So this destroys and concept of map maker pre-adding layer 'Death Markers' to assign them to a sensible layer of the map.

I know the standard responses to these are 'we are a small team and can not do everything', but I'm sure with some increased, more extension friendly, work on adding c#->lua api then extension coders would take up the challenge to add things. ( Think, add a few c#->lua api and maybe some of those 'wish list' items become possible for us to write instead of SW having to do all the work.. ) Since we already had an extension doing death markers with 'Tokens', I'm sure given the c#->lua api for layers the extension coder would have swapped over to using those instead of Tokens. Since it would help with draw order of Tokens and other things we currently 'stuff' into the 'Token' system because we dont have 'layer' access api functions. [Also like my spell tokens, these been added to a custom 'layer' would help a lot with 'Token' draw order. ]

I feel that SW picking 'minimal' c#->lua api, and only adding them when SW happens to add to the ruleset lua that would need access causes serious restrictions to what we could add from an extension point of view. If we can get a change of working practice to expose more of the c# api and allow SW and extension coders to write more code that the development of the product would get even more momentum of new features/custom automations.. And indirectly this extends the 'small team at SW into a larger team of people wanting to improve FGU' ( I'm thinking more like minecraft, and the improvements that mods did to make minecraft the massive hit it turned into... lets face it the root minecraft game was very basic for a lot of its early (pre Microsoft) development days... mods made the game what it is.. )

Getting events for say, 'pre-game-tick' and 'post-game-tick' event would allow the new set of 'clock' extensions that are bouncing 'messages' around the network to create a 'per game tick' level of lua update to work. ( Or getting a 'ping' message added from the server to clients with a clock stamp that goes off every few seconds to clock sync the host/clients along with a per-game-tick lua api call etc... to minimise network but allow host->client time sync items. ) To allow for these new generations of 'hacks' to the system to try and make things that should just be available to work.

Getting things like 'get/setPrototype' for 'Token' so we can change the token image, think animated tokens... Or maybe the 'prototype3Dflat' is for isometric and its going to allow directional images to be added to Tokens to allow for isometric character/npc facing images of front/side/back views of the token. ( Or maybe even a proper 3D mesh for a token that can rotate and has incidental animations and/or set movement animation events... like swing weapon or standing animation so the map is not so 'static', which get nice c#->lua api access to control animation events to play.. )

Getting 'get/setTintColor' for 'Token', so the like of moving into a color light can tint the token as it moves around the map. [ Or allow my spell tokens to allow uses to 'down alpha/tint' a graphics they are using as a spell token.. ]

I mainly want SW to consider extensions as the product improvement they are but could be greater if the focus was on getting more of the c# api exposed into lua and getting more of the 'cpu intensive' code in c# but controlled by the lua side. ( Minimising the c# code as much as possible and allow a greater lua flexibility for the ruleset/extensions. )


-pete

[bratch9]

Well a month on, and I do not see any update to the documentation to reflect the new functions from the even earlier 4.3.3 release that introduced these new functions.

4.3.3 also introduced the token set/getHeight functions, control with alt+wheel to adjust the concept of the token height which also adjusts the distance measure to reflect this. But not sure what use this is in real terms, normally higher levels are on a different map or different area of map making the distance between token on different levels incorrect. I guess if the team make more maps multi-layer layouts so the higher location is now on the same x,y location on the map with the height been the different layers for z and allow enable/disable of layers at a player situation. Then it would make more sense.

Anyway, I think the lack of basic documentation updates of the new functions goes to show that the 'api' is not developed for extensions but for internal ruleset... We developers of extensions just get to use it as a by-product, which I think is a shame. A few extra functions exposed to align consistency across some of the graphics access, and a few extra functions for the newer layers/los/lighting would go a long way.

I do think these will come with time, just not quick.

-pete

[Moon Wizard]

As I have mentioned in other threads, a lot of the capabilities in the ruleset/APIs that we are developing are not finalized yet. By including them in small parts of the core code, it allows us to refine them to make sure that they work as we intended and to get some real world mileage before adding to API documentation for everyone. In some cases, I don't want community developers using and relying on them yet, because I expect they will be changing soon. I have an internal list, and look over every couple months to see what I think should be moved into the documentation.

The height capability is to simply mirror what was already being done by the community, but allowing the distance measurements to be automated by the client and to have a visual display of the token height. This is mainly for same map height differences (think flying in outdoor maps; or swimming in water maps).

Regards,
JPG

[bratch9]

As I have mentioned in other threads, a lot of the capabilities in the ruleset/APIs that we are developing are not finalized yet. By including them in small parts of the core code, it allows us to refine them to make sure that they work as we intended and to get some real world mileage before adding to API documentation for everyone. In some cases, I don't want community developers using and relying on them yet, because I expect they will be changing soon. I have an internal list, and look over every couple months to see what I think should be moved into the documentation.

The height capability is to simply mirror what was already being done by the community, but allowing the distance measurements to be automated by the client and to have a visual display of the token height. This is mainly for same map height differences (think flying in outdoor maps; or swimming in water maps).

Regards,
JPG

Can I suggest these 'in flight' function we are not supposed to be relying on are marked some way... like say using an '_' marker on the name until they become finalised. So we can have an understanding that they are still very much in development and should not be used without the expectation of change, and then we can also make informed feedback and suggestions against these developing api and influence the final design ?

[ Since in the last 3 months, FG has had about 70 ruleset changes, and 5 exe releases, and zero changes to these functions. Hence why I was not considering them as still in development. I had waited a couple months before making comment on the undocumented status having not seen any changes to them. ]

Realistically 'how long' will these functions be considered not finalised ? ( Are we expected to just wait until they are documented ? )

Thanks,
Pete

[Moon Wizard]

Yes, you should wait until they are documented. While I understand that you would like more structure around these changes, these updates are only a small part of what I need to cover with the limited time I have.

Regards,
JPG