Javascript API documentation

[Per]

I'd like to have DORDER_OBSERVE, so that i could use mobile sensors to pick targets for long-range artillery. Neither DORDER_ATTACK nor DORDER_SCOUT seem to do the job.

Ok, done.

[Per]

My short term scripting plans:
* Add function link(object1, object2) -- links two game objects. this is visible only in current scripting context. If either object is destroyed, the link is removed.
* Add function enumLinks(object) -- returns list of game objects that we have linked to this game object. These two functions can be used to eg easily keep track of which droids you have sent where
* Add function annotate(object, key, value) -- add permanent custom field to a game object, available under a ".custom" object that is added whenever the game object is returned from a scripting function; this is visible only to current scripting context.
* Add global object sessionStorage -- this variable is shared between all script contexts, and is kept intact when changing levels; it can be used to implement a communication channel between scripts, or as a campaign memory
* Add global object gameStorage -- this variable is shared between all script contexts, and is also kept intact when changing games; this can be used to implement permanent experience, AI learning, high scores, and so on
* Add function enumEnemies(x, y, range) -- returns a list of visible enemy objects within range of given position. Maybe also add a similar enumAllies(x, y, range) function as well. (This won't add any functionality that is not already possible, but is much more convenient and will use high performance code for searching.)

Comments / opinions?

[Emdek]

Per, sessionStorage and gameStorage - these will be accessed using getters and setters similar to that of QSettings, right?
annotate(), permanent as of session (single game) context?

[NoQ]

* Add function link(object1, object2) -- links two game objects. this is visible only in current scripting context. If either object is destroyed, the link is removed.
* Add function enumLinks(object) -- returns list of game objects that we have linked to this game object. These two functions can be used to eg easily keep track of which droids you have sent where

We could also use a linkedTo(object) function that returns an array of all objects its argument is linked to, in case it will be more productive than enumerating all links.

[Per]

sessionStorage and gameStorage is planned as a simple object, where you can just add whatever you want, eg sessionStorage.semperfi.attackTarget.x = pos.x

Not sure whether annotate() should be current level scope only or session scope.

Links are intended as mere relations, there is not intended to be any distinction between to and from.

[Emdek]

Per, so in this case what do you think about saving those objects in more readable way (that offtopic in beta4 announcement)?

For annotate() we can have additional boolean parameter to decide if it should be preserved or not.

[aubergine]

Instead of enumAllies() and enumEnemies() would it be better to have an enumMapObjects(x,y,range[,lookingPlayer]) which returns a list of all objects (structures, features, droids) within range of x,y, optionally filtered to a lookingPlayer's visibility of that area of the map?

[aubergine]

would it be worth renaming the storage objects:

levelStoage = persists for current level (I have no idea what levels are yet!)

gameStorage = persists for the current game (including save/load cycle)

permStorage = persists indefinitely

I'm not convinced that they should be available to all contexts, will that not lead to one context overwriting the data of another context? In terms of sharing data between AIs, I think the in game chat system would be a better approach, otherwise you're going to need to track changes in deep-nested object structures and fire events when things change.

For example, let's say I have a few AIs that want to share map data. They could all bung information in to a central object, but how would they know if they are overwriting valid data from one of the other players or not? How would they know when data has been changed? What happens if one of them gets kicked from the alliance it's in but still has access to all the same data (and the other AIs still have access to it's data)?

[aubergine]

An unlinkObjects(obj1,obj2) would be useful - otherwise there is no way to remove a link from script.

enumLinks() renamed to enumLink() -- ie. singular form, for consistency with other enum functions (enumDroid, enumFeature, etc).

[Per]

Added new global 'scavengerPlayer', which is the index of the scavenger player. It won't be found in the playerData or startPositions arrays, since it is not a proper player, but at least know you can know what index it has for use in functions that need it.

Also added new function enumRange(x, y, range[, filter]) for searching the map for objects that the player the script is running as can see. Filter can be one of player index, ALL_PLAYERS, ALLIES or ENEMIES.

[aubergine]

Would it be worth namespacing the new chat/enumRange constants a bit before they start getting used in scripts:

* PLAYERS_ALL
* PLAYERS_ALLY
* PLAYERS_ENEMY

Maybe even a:

* PLAYERS_SCAVS

Also, for linking, why not make it automatic (but keep the link() and unlink() functions so scripts can still add/remove links themselves).

For exmaple, if I orderDroidObj() or orderDroidBuild() then those functions would automatically link the droid to what it's doing.

[aubergine]

For annotations, it would be better if there was an enumAnnotation(obj) to get them for a specific object. In most cases, if I'm cycling through big lists of enumDroid() or enumStruct() results I won't want annotations for all of them so it seems wasteful if those functions were having to expose annotations for every single object they return regardless of whether I need them or not.

[aubergine]

How is the transition from global vars persistence to storage object persistence going to be made?

[Per]

I have no intention of removing global vars persistence for the time being. The new persistence stuff proposed is for a different purpose (cross-game or cross-level persistence, or AI comms).

Your comments on linking and annotations are interesting. I have to think about them.

Concerning the namespace... I am not sure. I think I like it the way it is...

[aubergine]

With the namespacing, I was just thinking that as we get more and more constants, it's just going to be a bit tidier if they have a prefix. For me the namespace tells me what category of constant it is, it just feels a bit more orderly if it's there.

In particular, it groups related constants together when alphabetically sorted, and it makes searching for constants easier too:

https://warzone.atlassian.net/wiki/disp ... /Constants

Notice how BUILT and BUILD are next to each other, yet are completely different things (BUILT is a structure status constant, BUILD is a reticule button). And note how NO_ALLIANCES is split away from the ALLIANCES and ALLIANCES_TEAMS constants.

Also, when searching it's easier to find what you're looking for - eg. type "camp" in to the search box on the top-right of that URL above and you'll see it instantly lists all the CAMP_* constants which all relate to the base type selected for the game.