(info) This AI is still in early stages of development.

GO 3.1

Using GO, you can run Warzone 3.2 scripts on Warzone 3.1...

 

Overview

GO 3.1 upgrades the JS API to a state that is much closer to that in Warzone 3.2:

  • Implements several bug fixes
  • Adds many missing functions, events, constants, globals and properties
  • Updates existing JS API features to work like their 3.2 counterparts

All of this is transparent – you develop your script as if it were for Warzone 3.2, include a few files at the start of it, and GO takes care of the rest.

GO is ideal for AIs, scavfact.js, rules.js and 'extra' scripts. If you're scripting campaigns, GO can't help much - you need Warzone 3.2 for that.

There are obviously some things that can't be implemented, such as chat and beacons, however fake functions are created so your code remains simple and consistent across Warzone versions. The API allows you to determine the status of each part of the JS API, for example to work out if you're using a native JS API feature, or an upgraded/modified implementation.

Adding GO to your script

Two lines of code need to be inserted as close to the top (ideally the very top) of your script:

include("path/to/APIs/Util.js");
include("path/to/Defines/GO31.js");

This will cause a bunch of scripts and APIs to be loaded, including:

All the scripts are designed to minimise global object/scope pollution wherever possible. See linked documentation for more details.

In the documentation below, the following icons are used:

(tick) = Safe to use without worrying

(warning) = Use with caution / understanding of limitations

(error) = Don't use (not implemented or removed)

(info) = Minor note, nothing to worry about unless you are doing crazy stuff.

Groups

(tick) GO provides almost identical group implementation to that found in WZ 3.2, meaning you can group any game objects (including structures and stuff owned by other players). So use groups in exactly the same way you would in 3.2.

(info) The only limitation is groups defined by labels in labels.ini – however it's highly unlikely you'll be using those in AI scripts or rules.js, etc.

Objects

GO adds most missing properties to droid, structure and feature objects, and basically makes them look like their Warzone 3.2 counterparts.

It achieves this using a range of techniques:

  • Deducing values based on information available in the 3.1 JS API
  • Extrapolating values from game events (eg. working out attackers .range when they attack you)
  • Integration with your scripts

That last point is where you come in, especially for items marked (warning) in the table below. Your script will often have lots of additional data about the droids and structures it builds, custom research trees and so on. You can hook in to GO's decision making processes to increase the accuracy of results.

Compatibility Matrix

PropertiesDroid ObjectStructure ObjectFeature Object
born(tick)

Accurate values for all map-placed droids.

Accurate values for droids created by your script.

Approximate values for other players droids.

(tick)

Accurate values for all map-placed structures.

Accurate values for structures created by your script.

Approximate values for other players structures.

(tick)

Accurate values for all map-placed features.

Accurate values for features created by your script.

Approximate values for features created by other scripts.

group(tick)Fully 3.2 compatible grouping system.(tick)Fully 3.2 compatible grouping system.(tick)Fully 3.2 compatible grouping system.
armed(tick)Defaults to null for non-VTOLs.(tick)Defaults to null.  
isVTOL(tick)Full implementation, even works on droid objects that are no longer on the map.(info)To improve performance, .isVTOL property also appears on structure objects as a static false value.  
cost(warning)

Fairly accurate values for droids created by your script using buildDroid().

Inaccurate values for everything else.

(warning)

Fairly accurate values for structures created by your script using orderDroidBuild().

Inaccurate values for everything else.

  
isRadarDetector(tick)Generally accurate identification for all droids.(tick)Generally accurate identification for all structures.  
isCB(tick)Generally accurate identification for all droids.(tick)Generally accurate identification for all structures.  
isSensor(tick)Generally accurate identification for all droids.(tick)Generally accurate identification for all structures.  
range(warning)

Inaccurate values for all droids.

As you get attacked by other players' droids, their range value becomes more accurate.

(warning)

Inaccurate values for most structures.

As you get attacked by other players' droids, their range value becomes more accurate.

  
canHitAir(tick)

Fairly accurate for all droids, especially any that attack you.

(tick)Fairly accurate for all structures, especially any that attack you.  
canHitGround(tick)Fairly accurate for all droids, especially any that attack you.(tick)Fairly accurate for all structures, especially any that attack you.  
hasIndirect(warning)Not very accurate, although it checks for droids assigned to sensors and will sometimes guesstimate based on range.(tick)Generally accurate for defence structures, and obviously laser satellite.  
weapons[](warning)
  • id & name – Fully accurate for droids created by your script; inaccurate for all other players' droids (I need help to rectify this).
  • armed – Rough approximation for VTOLs; static 100% for all other droids.
  • lastFired – Rough approximation for enemies that attack you; inaccurate for all other droids.
(warning)
  • id & name – Currently inaccurate for all structures (I need help to rectify this).
  • armed – Rough approximation for your LASSAT; static 100% for all other structures.
  • lastFired – Accurate for your LASSAT; rough approximation for enemy structures that attack you; inaccurate for all other structures.
  
body(warning)

Very accurate for droids created by your script.

Usually accurate for human player droids, unless they choose custom droid names.

Often inaccurate for other AI players unless their droid names are recognisable.

    
propulsion(warning)

Very accurate for droids created by your script.

Usually accurate for human player droids, unless they choose custom droid names.

Often inaccurate for other AI players unless their droid names are recognisable.

    
bodySize(error)Not currently implemented (I need help to rectify this).    
cargoSize(error)Not currently implemented (I need help to rectify this).    
cargoCapacity(error)Not currently implemented (I need help to rectify this).    
cargoSpace(error)Not currently implemented (I need help to rectify this).    
cargoCount(error)Not currently implemented (I need help to rectify this).    
droidType(info)

Fixes some cyborg-related bugs.

    

API hooks

As mentioned earlier, your script can hook in to GO to help increase accuracy of the properties listed above:

  • go.guessSensor(gameObject, property) – called when GO is trying to work out whether a game object has a sensor, CB radar, or radar detector.
  • go.guessWeapon(gameObject, property) – called when GO is trying to work out information about a game objects' weapons.
  • go.guessBodyProp(droidObject, property) – called when GO is trying to work out body or propulsion of a droid object.
  • go.guessDroidType(droidObject) – called when GO is trying to determine droid type. Note: The droidObject is often a fake object so be careful how you interact with it.

<more docs on this bit at later date>

Constants

Pretty much all constants found in WZ 3.2 are backported. Also, constants removed in 3.2 are removed from 3.1 to ensure you don't use outdated constants. (wink)

In addition, many missing constants (even with respect to 3.2) are also added - such as those applicable to .action and .order.

Globals

The following globals are backported:

GlobalNotes
groupSizes[]Almost identical to Warzone 3.2 implementation, with the exception of groups defined in labels.ini (no way to get to them in 3.1).
scriptNameOptional – include <this script> at the top of your script if you want this backport.
... 

Events

As insane as it might sound, GO even backports some of the WZ 3.2 events to 3.1!

EventNotes
eventDestroyed()(tick)

Identical to WZ 3.2 in that it will be triggered when enemy objects and even features are destroyed.

Only triggers for your own objects, or objects your script has interacted with (eg. if you do an enumDroid() that's counted as an interaction for all droids listed, any objects in other events, etc).

Feature objects are a bit hit and miss, which can be fixed if required, just let me know..

eventGroupLoss()(tick)Full implementation, just like on WZ 3.2 – even triggers if a grouped enemy object gets destroyed!
eventPickup()(warning)

Full implementation, just like on WZ 3.2.

Will sometimes give a false positive (other player reached the item a split second before you did) and will sometimes report the wrong claiming droid (if you have two droids that are both close to the object).

eventTransporterLanded()(tick)Triggers whenever one of your transports lands. Not triggered for other players' transports.
eventTransporterLaunch()(tick)Triggers whenever one of your transports takes off. Not triggered for other players' transports.
...  

Functions

The following functions are implemented or modified by GO, and any function that returns a game object will return a WZ 3.2 style object unless specified otherwise:

FunctionNotes
addDroid()(tick)

Hooks to this function ensure that the droids' .born property is accurately set, as well as .propulsion, .body and (if applicable) .weapons, etc. Also, the function will attempt to return the newly created object like its WZ 3.2 equivalent.

Allows same parameter syntax as WZ 3.2, however it's recommended that you still provide droidType param to avoid problems (or provide go.guessDroidType() function).

buildDroid()(tick)

Hooks to this function ensure that the droids' .born property is accurately set, as well as .propulsion, .body and (if applicable) .weapons, etc. It will also estimate the droids .cost fairly accurately.

Allows same parameter syntax as WZ 3.2, however it's recommended that you still provide droidType param to avoid problems (or provide go.guessDroidType() function).

countDroid()(warning)

A close approximation to the Warzone 3.2 function that returns fairly accurate results without loss of performance. In cases where a decent approximation can't be obtained, the full accuracy approach will be used...

For full accuracy, at the expense of performance, set countDroid.enhanced = true. This will make the function use enumDroid() internally to get fully accurate results.

When in enhanced mode, caching can be applied – set countDroid.ttl = <milliseconds> (eg. 1000 = 1 second cache).

droidCanReach()(info)The results are recorded in an internal cache for use with propulsionCanReach().
enumCargo()(error)Not currently implemented.
enumDroid()(warning)

Conversion to WZ 3.2 style droid objects, while fast, may impair performance on big lists.

Optionally enable caching by setting enumDroid.ttl = <milliseconds>.

Use Native.enumDroid() for the standard version that returns WZ 3.1 style droid objects if you need max performance.

isVTOL()(tick)

Fixed a bug that would throw nasty errors if used on destroyed droid objects.

See also: <droidObj>.isVTOL

orderDroid()(tick)Full implementation of features, including DORDER_RECYCLE support.
orderDroidBuild()(info)Structures built with this function will have fairly accurate .cost properties auto-calculated.
orderDroidLoc()(info)Hooks to this function are used to generate transport events, and certain droid properties, etc.
orderDroidStatsLoc()(error)This long-deprecated function is removed to prevent accidental use. Use orderDroidLoc() instead.
orderDroidObj()(info)Hooks to this function are used to determine certain droid properties.
queue()(tick)

If you pass a game object to queue(), the queued function will receive a WZ 3.2 style version of that object transparently.

If problems arise, it's likely that you've made the queued function immutable – eg. defining it as a const, or using object.addConst() etc. If so, update your code to manually Hook the function before making it immutable.

setTimer()(tick)See notes for queue() above – same applies here.
addFeature()(tick)Hooks to this function ensure that the feature's .born property is accurately set. Also, the function will attempt to return the newly created object like its WZ 3.2 equivalent.
enumFeature()(tick)See notes for enumDroid() above – same applies here.
setDroidLimit()? 
getDroidLimit()? 
setStructureLimits()(info)

If this function is used by your script on WZ 3.1 RC3 or earlier, the data will be cached to allow getStructureLimit() to be used within your script.

The function is not modified on WZ 3.1.0 or above.

getStructureLimit()(info)

On Warzone 3.1 RC3 or earlier, this function will be backported but will only give accurate results in two scenarios:

  • If your script is rules.js and had used setStructureLimits() for the queried structure.
  • If the queried structure isn't available to build, but you have already built at least one such structure, the function will return the current number of that structure you have.

In all other cases, Math.max(currentCount, gameDefault) will be returned as a "best guess".

The function is not modified on WZ 3.1.0 or above.

enumGroup()(tick)

Fully functional including support for non-droid and non-owned objects.

(info) As mentioned earlier, can't handle labels.ini groups.

groupAdd()(tick)Updated to allow adding structures, features and non-owned objects, and supports auto-group creation if group specified doesn't exist.
groupAddArea()(tick)Updated to work the same way as the WZ 3.2 version.
groupAddDroid()(error)This long-deprecated function is removed from the API to prevent accidental use. Use groupAdd() instead.
groupSize()(tick)Updated to work with dynamically created groups.
newGroup()(tick)Updated to work with groupSizes[] array discussed earlier.
enumArea()(warning)

It has to list all matching game objects and then filter to those within the area, so on big lists performance may suffer.

Caching can be enabled by setting enumArea.ttl = <milliseconds>, if same parameters are used before cache expires the cached results will be returned.

Note, however, that if you use enumArea() filtered to your own droids it will be just as fast as WZ 3.2 even without caching (groupAddArea() to the rescue!).

enumRange()(warning)

See enumArea() above – same applies here.

If you enumRange() filtered to your own droids, it instead does an enumArea() to gain the same performance boost mentioned above.

propulsionCanReach()(warning)(warning)(warning)

Yes, 3 warning icons. Had lots of trouble backporting this one.

The function will always return accurate results for VTOL propulsion – it will always return true if the destination is within map bounds (let me know if this assumption is wrong).

It will return accurate results for land propulsion (wheels, half-tracks, tracks, legs) if there are confirmed land-propulsion droids (including ally/enemy droids) on the map. However, if there are no confirmed land propulsion droids, it will choose the oldest surviving non-VTOL droid and assume that's a land propulsion, which might not necessarily be the case.

Once there are confirmed hover droids on the map (including ally/enemy droids), the results for hover propulsion checks will be accurate.

However, if there are no hover droids, it will often return false even if hover propulsion could reach the location, rather than give a false positive.

Confirmed accurate results are cached for the duration of the game to help minimise inaccurate responses.

donateObject()(error)A dummy function is created so you don't need to adapt code for omission of the function, however it obviously won't do anything on WZ 3.1.
getObject()(warning)

Full implementation of the function as per WZ 3.2.

(info) One exception: Not possible to retrieve group objects via labels, which probably won't be used outside of campaign scripts.

(warning) Getting structure/feature at a specific tile can be quite slow because the enumArea() implementation (as described above) has to be used.

Oil resource locations are cached to boost performance (assuming more scripts will start using getObject() in conjunction with derrickPositions[]).

hackGetObj()

objFromId()

droidFromId()

(error)

All these long-deprecated functions are removed from the JS API to prevent accidental use – use getObject() instead.

You can use Native.<function> if you still need access to them, eg. Native.droidFromId()

label()(error)

This deprecated function is removed from JS API to prevent accidental use – use getObject() instead.

As with the other deprecated functions, you can still get to it via Native.labels()

removeObject()(warning)

Uses hacky DORDER_DESTRUCT when attempting to remove droids – may be hit and miss.

Unable to remove features in 3.1.

removeStruct()(error)

This deprecated function is removed from the JS API to prevent accidental use – use removeObject() instead.

If needed, you can still access it via Native.removeStruct()

activateStructure()(tick)Hooks to this function are used to set accurate .lastFired time on the associated structure object.
addStructure()(tick)Like WZ 3.2 equivalent, it attempts to return the newly created object if successful.
countStruct()(tick)See notes on countDroid() earlier – same applies here.
enumStruct()(tick)Returns WZ 3.2 style structure objects.
enumStructOffWorld()

(warning)(warning)

Not that anyone uses this yet, but it will return WZ 3.1 style objects, not enhanced 3.2 style objects.
getDroidProduction()(warning)

Works as expected for your own factories.

Does not work for other players' factories.

setAssemblyPoint()? 
structureIdle()? 
enumSelected()(warning)Works as expected but slow as it has to enumDroid() and filter results.
Contents

Jump to: