Area events

[Per]

While working on porting the cam1a mission, I was happy to see that the existing API almost completely covered my needs.

Things that I've added in this process: .stattype field for features, hackAddMessage() and hackRemoveMessage() similar to wzscript addMessage and removeMessage (the 'hack' is to flag my disgust for this code, and that this interface may change suddenly), non-droids may now be group members, eventGroupEmpty is now eventGroupLoss, and addLabel() got added.

However, one task that I felt was much harder with the javascript API than it was with wzscript was doing something when a droid enters an area for the first time. An implementation with a function on a timer that continually checks the contents of the area is possible, but not somewhat ugly, slow and a bit much code for something that should probably be a very basic operation, given how frequently this is done in campaign code.

So I was thinking of adding a new event that is triggered the first time that a droid enters an area defined in labels.ini. We know in the c++ code when a droid changes tiles, and iterating over the area labels will not cause performance problems there. My first thought was 'eventArea(label, droid)', but this quickly becomes a huge catch-all function for this kind of stuff. Then I thought, why not call 'eventArea<label>(droid)' if it exists? This should make it slightly faster, since you don't need to be invoking the javascript engine on every area transition, only those with implemented event handlers. And it should make the scripting code neater. But making up events names dynamically is a new API mechanic, so I figured I'd air it here first.

In any case, the idea was that each area has a flag associated with it, so once a droid has entered it, that flag has to be cleared before it will trigger again. So we'd need a new function 'resetArea(label)' to tell the code that we want more events triggered on this area, eg if the wrong droid entered.

Opinions?

[aubergine]

I couldn't find where the add/remove message docs were -- any idea what those functions do?

Great to see non-droids being allowed in groups

Regarding droids entering an area...

First, who's droids will trigger the event? Eg. it would be useful to know when enemy or ally droids enter an area, not just my own.

Second, will the event fire each time a droid enters an area? Or just first time a droid from a given player enters the area?

Third, will the event only fire when the droid moves in to an area, and not when a droid that's already within the area moves within that area?

Fourth, will it trigger on any label of type AREA? -- If so, JS can automatically create the event listeners by doing enumLabels(), going through each of the labels to find AREA labels, and then creating global functions to listen for the event. So I don't see any issues from JS side of things.

I can already see lots of uses for this area feature in the AI I'm developing: I've split the map in to sectors of (usually) 20x20 tiles. I can addLabel() to define the area of each sector and then be told when droids enter it, rather than having to constantly enumArea

Will it be possible to get some indication of whether the droid that entered the area is visible to my script player (or allies)? That way I can start listening to the sector area events from the outset, but only act if the droid entering an area is visible to me/allies.

Other thoughts...

Having a general eventDroidMove() would be very useful in some scenarios. Currently my AI sets a timer and each time it fires it checks through all my droids to see if they've moved to a different tile. As you can imagine, it's not great from a performance perspective. I'm using this to a) detect log-jamming and b) monitor the paths of my droids.

If I was able to bind to specific droids to have an event fired when they enter a new tile, it would be massively useful.

Maybe the bind() function could be updated as follows:

Code: Select all

bind(object, event, eventHandler);

Where object would be any valid game object (droid, feature, structure); event would be the event to monitor (eg. move, destroyed, attacked, etc); eventHandler would be a string stating the function to call when the event occurs. The event handler function would be passed the same parameters as the bind() function.

[Per]

The idea is that a droid entering an area from outside the area will trigger the event, then deactivate the trigger. However, you can reset the trigger from inside the event, if that was not the droid you were looking for, or you just want to be notified each time. It will trigger on any label of type AREA. I do not recall if visibility information is currently exposed to the JS world, if not, it probably should be. On the c++ side, each game object has an array that says if if each other player can see it.

[Per]

Area events have been added. They are of the form eventArea<label>(droid).

Area labels can now have two new values (in labels.ini): player = N, where N is -1 by default, which is equal to JS constant ALL_PLAYERS; and triggered = M, where M is -1 by default, meaning it is active, or 1 which means it is currently inactive. For aesthetic reasons, area labels should now be capitalized...

Also added new js function resetArea(label[, filter]) which can re-activate a triggered area. Whenever an area is triggered, it is automatically deactivated, so it needs to be reset to trigger again. The optional filter argument can determine whose droids it should trigger for.

[aubergine]

I assume values of N and filter can be ALLIES, ENEMIES, ALL_PLAYERS or <playerID>?

[Per]

I assume values of N and filter can be ALLIES, ENEMIES, ALL_PLAYERS or <playerID>?

No. Just ALL_PLAYERS and <playerID>. (Areas are not owned by anyone, and hence cannot have allies or enemies...)