3.2 JS API Wishlist :)

For AI and campaign script related discussions and questions
Post Reply
User avatar
aubergine
Professional
Professional
Posts: 3459
Joined: 10 Oct 2010, 00:58
Contact:

3.2 JS API Wishlist :)

Post by aubergine »

Maybe a tad early to start requesting things for 3.2, but wanted to jot down before I forget...

Ability to dump short strings to log file

I always imagined debug() would do this, but it seems not. I'd like the ability to do something like log("short string") and have it go directly to the log file.

Use case:

* Logging decisions made by an AI, without having to worry about time stamping, so I can later review to get a clearer picture of what happened inside my AI with a view to improving it.

Ability to dump text to a file

There are scenarios where I want to dump a large chunk of text (maybe up to a thousand lines) in to a text file.

Something like: dumpToFile("filename", "large chunk of text");

File created would be named: filename + ".dump" (to prevent misuse of the function)

The file would always be created in the logs folder, and if the file of given name already exists it gets overwritten. (I can easily put a timestamp in filename using JS Date object if I want to avoid that happening).

Use case:

* Dumping JSON representation of some objects within a script, for later analysis
* Placing structures on a map, then dumping JSONified results of enumStruct() to file. The AI could later include the file as a template for where to build stuff on a specific map.

Beacons API

IMPLEMENTED SO FAR: addBeacon(), removeBeacon(), eventBeacon(), eventBeaconRemoved()

To do:

* enumBeacons(visibility, color) colour defaults to COLOUR_ALL, visibility defaults to me

Beacon objects would have properties such as:

* type - BEACON
* player - who created it
* x, y - where is it
* born - game tick at which the beacon was created
* ttl - how many game ticks after born before disappears (-1 = don't disappear)
* colour - what colour is it
* to - who can see it (player ID or ALLIES or ALL_PLAYERS)
* name - optional string (eg. if I want to give a beacon a custom ID, much in the same way I'd name droid templates)

More than one beacon could be on the map at a time.

Would be super nice if beacon colours available were same as the available player colours. Thus, a player's default beacon colour could be their own colour, making it visually obvious who placed a beacon.

The ability to choose a different beacon colour would be mainly for challenges, enhanced sit rep, custom campaigns, training bots, etc. Eg. defining mission objectives in one colour and waypoints/dangers in another, etc.

Beacons placed by the game engine, eg. to highlight location of an attacked building/droid, would have a suitable .name applied to them so I can distinguish between game created beacons and my own.
Last edited by aubergine on 12 Jan 2013, 18:36, edited 9 times in total.
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
Posts: 3459
Joined: 10 Oct 2010, 00:58
Contact:

Re: 3.2 JS API Wishlist :)

Post by aubergine »

getMousePos(player) function

Get x,y map coords of the mouse pointer for a given player (defaults to me).

Camera functions

Moved to separate topic: viewtopic.php?f=35&t=10427
Last edited by aubergine on 12 Jan 2013, 18:34, edited 1 time in total.
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
Posts: 3459
Joined: 10 Oct 2010, 00:58
Contact:

Re: 3.2 JS API Wishlist :)

Post by aubergine »

eventSelected(objects)

IMPLEMENTED: eventSelectionChange()

eventOrdered(objects,dorder,target)

Triggered when player issues a command to the selected droids/structure.

Where target can be:
* a POSITION object - eg. when ordering a droid to move somewhere
* a DROID/STRUCTURE/FEATURE object - eg. when ordering to attack
* an AREA object - eg. when setting droids to patrol between x1,y1 and x2,y2
* Null if no target specified

getRallyPoint(struct) and setRallyPoint(struct,x,y)

Allow scripts to interact with rally points.

PARTIAL IMPLEMENTATION: setAssemblyPoint()

setFactoryDefaults(factory,range,repair,fire,circle)

Ability to set factory defaults.

getFactoryDefaults(factory)

Returns an object containing the factory defaults.

* type = FACTORY_SETTINGS
* range
* repair
* fire
* circle

setDroidSettings(droid,range,repair,fire,stance)

Config settings for a specific droid.

range: RANGE_OPTIMAL, RANGE_SHORT, RANGE_LONG

repair: REPAIR_NONE ("Do or Die"), REPAIR_MEDIUM, REPAIR_LIGHT

fire: FIRE_AT_WILL, RETURN_FIRE, HOLD_FIRE

stance: STANCE_PURSUE, STANCE_GUARD, STANCE_HOLD

getDroidSettings(droid)

Returns an object containing the droid settings. Alternatively they could be exposed via new properties on DROID objects, but I worry about the amount of bits being flung around as a result of enumDroid() - the droid's settings are only required in certain circumstances.
Last edited by aubergine on 12 Jan 2013, 18:46, edited 4 times in total.
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
Duha
Trained
Trained
Posts: 287
Joined: 25 Mar 2012, 20:05
Location: SPb, Russia

Re: 3.2 JS API Wishlist :)

Post by Duha »

1. Interactive console. (like in firebug plugin or development tool in chromium/chrome (hit F12 in you browser) ) It will speedup development. (you can execute some code in runtime, check variables, see debug log.)

2. Object Oriented API

Code: Select all

var dist =  distBetweenTwoPoints(droid1.x, droid1.y, droid2.x, droid2.y)
// vs
var dist = droid1.getDistance(droid2)
Only one thing prevent to do it: saving system does not support classes with methods.
If saving feature will be solved, this API can be created as mod tools.
http://addons.wz2100.net/ developer
User avatar
aubergine
Professional
Professional
Posts: 3459
Joined: 10 Oct 2010, 00:58
Contact:

Re: 3.2 JS API Wishlist :)

Post by aubergine »

The OO API can be implemented first as a JS library, which would be best initial approach to find out what "feels nice" to work with, prior to considering moving the JS API in that direction.

It's fairly easy to override objects, etc. Eg. on enumDroids() it would be relatively easy to wrap that function in another function that runs through all the droids and changes their prototype chain so they get a bunch of new functions such as droid.getDistance(target) etc.
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
Duha
Trained
Trained
Posts: 287
Joined: 25 Mar 2012, 20:05
Location: SPb, Russia

Re: 3.2 JS API Wishlist :)

Post by Duha »

aubergine wrote:The OO API can be implemented first as a JS library, which would be best initial approach to find out what "feels nice" to work with, prior to considering moving the JS API in that direction.

It's fairly easy to override objects, etc. Eg. on enumDroids() it would be relatively easy to wrap that function in another function that runs through all the droids and changes their prototype chain so they get a bunch of new functions such as droid.getDistance(target) etc.
It works untill save. (I checked it long time ago on 3.1 betta)
http://addons.wz2100.net/ developer
User avatar
aubergine
Professional
Professional
Posts: 3459
Joined: 10 Oct 2010, 00:58
Contact:

Re: 3.2 JS API Wishlist :)

Post by aubergine »

Yes, but I was meaning from perspective of just getting a better idea of what shape the OO API would take. For the 3.x branch, I'd much rather see more WZ functionality exposed via the JS API than worry about trying to make a nice OO API. A basic API can result in slightly more obtuse code than an OO API, but an API with missing features completely roadblocks many avenues for developers. I want the roadblocks removed first.
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
Posts: 3459
Joined: 10 Oct 2010, 00:58
Contact:

Re: 3.2 JS API Wishlist :)

Post by aubergine »

These functions will allow the AI to "see" the map more like a human does...

enumContinents()

Return a series of CONTINENT objects, each object has:

* id - continent number
* type - CONTINENT
* links - array of CONTINENT_LINK objects, one for each continent that links directly to this continent

If a continent has no links, that indicates something that's only accessible by air, such as a mountain.

A CONTINENT_LINK object could be something like:

* type - CONTINENT_LINK
* continents - an array containing the two continents that the link joins
* access - ACCESS_LAND or ACCESS_HOVER (and maybe ACCESS_NAVAL at later date?)
* tiles - an array of POSITION objects defining where the link is

enumContinentTiles(continent)

Returns an array of POSITION objects, one for each tile in the continent.

getTile(x,y)

Returns a TILE object for the tile at x,y:

* x, y - coords of the tile
* z - height of the tile
* type - TILE
* landAccess - could a land unit be placed here currently (eg. false if there's a tree or structure on the tile)
* hoverAccess - could a hovercraft be placed here currently
(* seaAccess - maybe when naval units exist we'll need this also?)
* tileType - LAND, WATER, CLIFF
* continent - id of the continent the tile belongs to
* visibility - FOG, EXPLORED, SENSOR

FOG = dark tile, not yet explored, no idea what's there
EXPLORED = explored, but no current sensor coverage
SENSOR = actively monitored by sensor

enumContinentPaths(continentA, continentB)

Return a nested array of each path from continent A to continent B. The first level of the array would be the paths, then the second level of the array would be the CONTINENT_LINK objects along that path.

An example of where this could be used is if the AI realises it's default route is resulting in epic fail, it could get a list of alternate paths and then try those. It might see that there's a path that requires hovercraft and change it's research to get hover more quickly in order to see if that path yields better results. Or it might see that there's a longer path that it wouldn't normally take, but decide to give it a try (effectively setting waypoints for it's droids) in the hope the path will circumvent enemy defences.

It might also use the info to work out which paths the enemy is using - if it knows where the enemy factories are, it can get paths from those factories to its base, then find the choke points (CONTINENT_LINK objects give a good indication, but it can investigate tiles over a number of game ticks to do more detailed analysis if desired) and set up some defences or sensors, etc., to make it harder for the enemy to reach the base.

getShortestRoute(x1,y1, x2,y2, propulsion, via)

Works out the shortest route from A to B (optionally via a specific continent) for a given propulsion type, returns an array of objects for that route. If no route, returns empty array.

* type - ROUTE
* from - POSITION object
* to - POSITION object
* via - CONTINENT object, or null
* propulsion - constant defining propulsion type
* tiles - array of TILEs along the path

The AI might have found what looks like a short path from one continent to another, but wants to check if it really is shorter. It might be that a path which goes through 20 continents is actually shorter than a path that goes through 5.
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
Posts: 3459
Joined: 10 Oct 2010, 00:58
Contact:

Re: 3.2 JS API Wishlist :)

Post by aubergine »

(deleted)
Last edited by aubergine on 12 Nov 2012, 00:50, edited 2 times in total.
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
Posts: 3459
Joined: 10 Oct 2010, 00:58
Contact:

Re: 3.2 JS API Wishlist :)

Post by aubergine »

powerTransfer(to, amount)

IMPLEMENTED: donatePower()

eventPowerTransfer(from,to,amount)

Triggered whenever there is a power transfer, useful for letting scripts know they just gained or lost some power so they can update their plans accordingly. Also useful for situation reporting.

Specifically it will be triggered when:

* Player gets power from an oil drum (although eventPickUp() could be used?)
* Player loses power due to donation to an ally
* Player gains power due to donation from an ally

count*() siblings for enum*()

IMPLEMENTED: countStruct(), countDroid()
Last edited by aubergine on 12 Jan 2013, 18:52, edited 5 times in total.
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
Posts: 3459
Joined: 10 Oct 2010, 00:58
Contact:

Re: 3.2 JS API Wishlist :)

Post by aubergine »

unitTransfer(droid, to)

IMPLEMENTED: donateObject()
Last edited by aubergine on 12 Jan 2013, 18:31, edited 2 times in total.
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
Posts: 3459
Joined: 10 Oct 2010, 00:58
Contact:

Re: 3.2 JS API Wishlist :)

Post by aubergine »

eventLaserSatelliteStrike(from, warning, x, y)

Triggered when there is an incoming laser satellite strike, an when the strike occurs.

* from = player sending the strike
* warning = true (pending strike warning) or false (lassat strike confirmation = lassat fired)
* x,y = only provided when warning==false (ie. location of strike now known)

Useful for Situation Reporting (to move all sitrep out of core game and in to rules.js) and also would allow experimentation with making AI droid groups "scatter" to minimise chances of a lassat strike killing whole group.

The player issuing the strike would also get notifications, so they could build a list of expected victims when issuing the strike, update that list when warning occurs, and review the list after the laser fires. This would be useful to see if opponent scatters its units.
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
Posts: 3459
Joined: 10 Oct 2010, 00:58
Contact:

Re: 3.2 JS API Wishlist :)

Post by aubergine »

eventAllianceChange(playerA, playerB, allied)

When alliance state changes between two players, all players have this event triggered to let them know whether players A and B are now allied or not.
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
aubergine
Professional
Professional
Posts: 3459
Joined: 10 Oct 2010, 00:58
Contact:

Re: 3.2 JS API Wishlist :)

Post by aubergine »

IMPLEMENTED: eventGameSaving(), eventGameSaved(), eventGameLoaded()
Last edited by aubergine on 12 Nov 2012, 00:50, edited 2 times in total.
"Dedicated to discovering Warzone artefacts, and sharing them freely for the benefit of the community."
-- https://warzone.atlassian.net/wiki/display/GO
User avatar
Duha
Trained
Trained
Posts: 287
Joined: 25 Mar 2012, 20:05
Location: SPb, Russia

Re: 3.2 JS API Wishlist :)

Post by Duha »

aubergine wrote:eventGameSave(before)

Triggered twice - before game save (before == true) and after game is saved (before == false).

Primarily for dumping some internal script data to savegame-friendly global vars before game saved, then clearing up after saved. But I also have some scenarios where I want to stop timers to prevent them from kicking in unexpectedly when the game is loaded at a later date.
I like style:
eventPreSave
eventPostSave

And may be you need:
eventLoad


API:
may be it will be good to have some nonSaveArray. It will be array of strings. global attributes with names from list will not be saved. It can be implemented in javascript using save events.
http://addons.wz2100.net/ developer
Post Reply