js type hints for AI scripting

[wanjia1]

I turned the Markdown Document of JavaScript Scripting API into a .js file:
pylint.js
When you open both your AI script and pylint.js in IDE like vscode,
the type hinting will be enabled and you can see each function's document, type of arguments, type of return,
like it is TypeScript.
it also contains names of most constants,like DORDER_MOVE.

the pylint.js was generates from Markdown Document of API of 4.3.2.
you can run the z-jslist.py to re-generate the pylint.js

license:CC0

[wanjia1]

a fragment of the pylint.js reads as follow:

var object=class {
constructor() {
this.type=0,
this.id=0,
this.x=0,
this.y=0,
this.z=0,
this.player=0,
this.selected=false,
this.name="object",
this.health=100,
this.armour=1,
this.thermal=1,
this.born=0
}}
var object0=new object()

...

/**Returns an array of droid objects. If no parameters given, it will
return all of the droids for the current player. The second, optional parameter
is the name of the droid type. The third parameter can be used to filter by
visibility - the default is not to filter.*/
function enumDroid(player, droidType, playerFilter) {return [droid0]}

/**Returns an array of all features seen by player of given name, as defined in "features.json".
If player is ```ALL_PLAYERS```, it will return all features irrespective of visibility to any player. If
name is empty, it will return any feature.*/
function enumFeature(playerFilter, featureName) {return [object0]}

[wanjia1]

bugfix:
fix some type hints that hint a wrong type.
type hinting for global constants.

[wanjia1]

bugfix:
remove attribute names of classes from constant hints
now every function have type hinting for arguments, in jsdoc format.

[wanjia1]

a sample of jsdoc, in the pylint.js, reads as follow:

/** Start factory production of new droid with the given name, body, propulsion and turrets.
The reserved parameter should be passed **null** for now. The components can be
passed as ordinary strings, or as a list of strings. If passed as a list, the first available
component in the list will be used. The second reserved parameter used to be a droid type.
It is now unused and in 3.2+ should be passed "", while in 3.1 it should be the
droid type to be built. Returns a boolean that is true if production was started.
* @param {_struct} factory
* @param {String} templateName
* @param {String[]|String} body
* @param {String[]|String} propulsion
* @param {""} reserved
* @param {""} reserved
* @param {(String[]|String)[]} turrets
*/
function buildDroid(factory, templateName, body, propulsion, reserved, reserved, ...turrets) {return true}

[wanjia1]

bugfix:
fixed return type of special cases
fixed markdown document of eventSyncRequest:

at version 4.4.2, if player 0 calls syncRequest(1,2,3)
the expected event is eventSyncRequest(1,2,3,null,null)
but, in fact it is eventSyncRequest(0,1,256,384,null,null), different to document.
argument 0 is "from" player, other arguments is shifted right. x and y are multiplied by 128.

this now fixed by modifying markdown document that generates type hinting.

link of issue:
https://github.com/Warzone2100/warzone2100/issues/3193

[wanjia1]

bugfix:
fixed return type of more special cases

upgrade document to version 4.5.1
added jsdoc for map script
copy global variables from a T4 skirmish game ( for out-game references of weapon / structure statistics )

[wanjia1]

# Refactored JS API header

## Usage
1. Extract the zip file to project root directory
2. Open project root directory with latest VSCode
3. Hover mouse over a API function in editor, check if argument typing and comments show

## Includes
- WZAPI/
- constants.ts
- events.js (overwrites by user script, it considered as error in TypeScript)
- functions.js (too much work to reformat)
- functions2.ts (API that have overload, currently only getObject and hackMarkTiles)
- objects.ts (interface of objects used in API)
- jsconfig.json (project config file for VSCode)

## New features
- object attribute comment
- function overload (getObject, hackMarkTiles)
- type alias (rename some number as worldCoord, to distinct from mapCoord)
- volatile/variable constant (gameTime, alliancesType, baseType, ...)

## Extra
- bold comments not included in origin document