diff --git a/doc/js-campaign.md b/doc/js-campaign.md index b7816f4118e..6620a1cd7a7 100644 --- a/doc/js-campaign.md +++ b/doc/js-campaign.md @@ -26,6 +26,7 @@ Tell `libcampaign.js` to manage a certain set of artifacts. The argument is a JavaScript map from object labels to artifact description. If the label points to a game object, artifact will be placed when this object is destroyed; if the label is a position, the artifact will be placed instantly. +The label can point to a pre-existing feature artifact on the map too. Artifact description is a JavaScript object with the following fields: * `tech` The technology to grant when the artifact is recovered. Note that this can be made into an array to make artifacts give out @@ -39,12 +40,33 @@ Artifact description is a JavaScript object with the following fields: @param {Object} artifacts @returns {void} +## camAddArtifact(artiLabel, artiTech) + +Adds another artifact to be managed. Will override existing ones if the names match. + +@param {String} artiLabel +@param {String|Array} artiTech +@returns {void} + +## camDeleteArtifact(artiLabel) + +Deletes the artifact from the list of managed artifacts. + +@param {String} artiLabel +@returns {void} + ## camAllArtifactsPickedUp() Returns `true` if all artifacts managed by `libcampaign.js` were picked up. @returns {boolean} +## camGetArtifacts() + +Returns the labels of all existing artifacts. + +@returns {Object[]} + ## camSetEnemyBases([bases]) Tell `libcampaign.js` to manage a certain set of enemy bases. @@ -173,6 +195,12 @@ and traces entering the area in the TRACE log. @param {Function} callback @returns {void} +## camClassicMode() + +Returns `true` if classic balance mod is enabled. + +@returns {boolean} + ## camDef(something) Returns `false` if something is JavaScript-undefined, `true` otherwise. @@ -253,6 +281,16 @@ Mimics wzscript's `numStructsButNotWallsInArea()`. @param {number} [playerFilter] @returns {number} +## camCleanTileOfObstructions(x, y | pos) + +Obliterates player structures and features near the tile around certain coordinates. +Can be used for spawn locations or transport reinforcement spots. May not +delete very large objects like factories or skyscrapers. + +@param {number|Object} x +@param {number} [y] +@returns {void} + ## camChangeOnDiff(numericValue) Change a numeric value based on campaign difficulty. @@ -284,6 +322,63 @@ Break alliances between all players. @returns {void} +## camGenerateRandomMapEdgeCoordinate(reachPosition) + +Returns a random coordinate anywhere on the edge of the map that reachs a position. + +@param {Object} reachPosition +@returns {Object} + +## camGenerateRandomMapCoordinate(reachPosition) + +Returns a random coordinate anywhere on the map + +@param {Object} reachPosition +@returns {Object} + +## camDiscoverCampaign() + +Figures out what campaign we are in without reliance on the source at all. + +@returns {number} + +## camNexusLaugh() + +Play a random NEXUS laugh. + +@returns {void} + +## camAbsorbPlayer([who[, to]]) + +Completely give all of player `who` droids and structures to player `to`. +Will default to `CAM_HUMAN_PLAYER` and `CAM_NEXUS` respectively. + +@param {number} [who] +@param {number} [to] +@returns {void} + +## camHackIntoPlayer([player[, to]]) + +Steal a droid or structure from a player if the NEXUS hack state is active. +Will default to `CAM_HUMAN_PLAYER` and `CAM_NEXUS` respectively. + +@param {number} [player] +@param {number} [to] +@returns {void} + +## camSetNexusState(flag) + +Turn on/off the NEXUS hacking state feature. + +@param {boolean} flag +@returns {void} + +## camGetNexusState() + +Returns the activation state of the NEXUS hacking feature. + +@returns {boolean} + ## camSetFactories(factories) Tell `libcampaign.js` to manage a certain set of enemy factories. @@ -345,9 +440,8 @@ at the end of its production loop, first queued first served. ## camSetPropulsionTypeLimit([limit]) -On hard and insane the propulsion type can be limited with this. -For type II pass in `2`, and for type III pass in `3`. Hard defaults to type II and insane defaults to type III. -If nothing is passed in then the type limit will match what is in templates.json. +This function can automatically augment units to use Type I/II/III propulsions. +If nothing or zero is passed in then the type limit will match what is in templates.json. @param {number} [limit] @returns {void} @@ -419,6 +513,14 @@ Grants research from the given list to player and also researches the required r @param {number} playerId @returns {void} +## camClassicResearch(researchIds, playerId) + +Grants research from the given list to player based on the "classic balance" variant. + +@param {string[]} researchIds +@param {number} playerId +@returns {void} + ## camManageGroup(group, order, data) Tell `libcampaign.js` to manage a certain group. The group would @@ -491,6 +593,34 @@ Print campaign order as string, useful for debugging. @param {number} order @returns {string} +## camSecondsToMilliseconds(seconds) + +Returns the amount of milliseconds in `seconds`. + +@param {number} seconds +@returns {number} + +## camMinutesToMilliseconds(minutes) + +Returns the amount of milliseconds in `minutes`. + +@param {number} minutes +@returns {number} + +## camMinutesToSeconds(minutes) + +Returns the amount of seconds in `minutes`. + +@param {number} minutes +@returns {number} + +## camHoursToSeconds(hours) + +Returns the amount of seconds in `hours`. + +@param {number} hours +@returns {number} + ## camIsTransporter(gameObject) Determine if the object is a transporter. @@ -557,13 +687,13 @@ The following options are available: The following data parameter fields are available: * `area` The landing zone to return to. * `message` The "Return to LZ" message ID. Optional. + * `playLzReminder` Play and show the "Return to LZ" message. Optional, enabled by default. * `reinforcements` Reinforcements interval, in seconds. For standard and offworld victory, some extra data parameters can be defined: * `callback` A function callback to check for extra win/loss conditions. Return values are interpreted as follows: * `false` means instant defeat ("objective failed"), * `true` means victory as long as other standard victory conditions are met, * `undefined` means suppress other victory checks ("clearly not won yet"). -* `victoryVideo` Pass in the name of a video string here and it will be played before attempting to load the next level. For offworld victory, some more extra data parameters can be defined: * `retlz` Force the player to return to the LZ area: * `false` mission does not require a LZ return, @@ -580,6 +710,27 @@ For offworld victory, some more extra data parameters can be defined: @param {Object} data @returns {void} +## camCheckExtraObjective() + +Checks for extra win conditions defined in level scripts being met, if any. + +@returns {boolean|undefined} + +## camSetExtraObjectiveMessage(message) + +Message(s) the mission script can set to further explain specific victory conditions. +Allows a single string or an array of strings. + +@param {string|Object[]} message +@returns {void} + +## camClearConsoleOnVictoryMessage(clear) + +If the script wants to allow `__camSetupConsoleForVictoryConditions()` to clear the console. + +@param {boolean} clear +@returns {void} + ## camPlayVideos(data) Formats for parameter `data`: `{video: "video string", type: MISS_MSG/CAMP_MSG, immediate: true/false}` OR @@ -593,3 +744,44 @@ as a sound to play before a video. Of which is only supported when parameter `da @param {Object|Object[]} data @returns {void} +## camSetVtolData(player, startPos, exitPos, templates, timer, [obj[, extras]]) + +Setup hit and runner VTOLs. NOTE: Will almost immediately spawn VTOLs upon calling this function. +`Player`: What player number the VTOLs will belong to. +`StartPos`: Starting position object where VTOLs will spawn. Can be an array. Use undefined for random map edge location. +`ExitPos`: Exit position object where VTOLs will despawn at. +`Templates`: An array of templates that the spawn uses. +`Timer`: How much time in milliseconds the VTOLs will wait to spawn again. +`Obj`: A game object that will stop the spawn when it no longer exists. May be undefined for no explicit end condition. +`Extras`: An object with possible members: + `limit`: Numeric limit of a VTOL design in regards to the parameter Templates. May be an array paired to Templates. + `alternate`: A boolean to force the spawn to use one of the designs at a time in parameter Templates. + `altIdx`: Which design index the spawn will first cycle through the list of templates from. + `minVTOLs`: Minimum amount of VTOLs that will spawn. + `maxRandomVTOLs`: Random amount of VTOLs that will spawn in addition to minVTOLs. + +@param {number} player +@param {Object|Object[]|undefined} startPos +@param {Object} exitPos +@param {Object[]} templates +@param {number} timer +@param {Object} obj +@param {Object} extras +@returns {void} + +## camSetVtolSpawnState(state, identifier) + +Sets the active status of a VTOL spawn point. The identifier can either be the +the index number or the label of the object that stops the spawn naturally. + +@param {boolean} state +@param {number|string} identifier +@returns {void} + +## camSetVtolSpawnStateAll(state) + +Sets the active status of all VTOL spawns to `state`. + +@param {boolean} state +@returns {void} + diff --git a/doc/js-events.md b/doc/js-events.md index d415b668955..8a3ca089f14 100644 --- a/doc/js-events.md +++ b/doc/js-events.md @@ -1,8 +1,9 @@ # Events -This section describes event callbacks (or 'events' for short) that are called from the -game when something specific happens. Which scripts receive them is usually filtered -by player. Call ```receiveAllEvents(true)``` to start receiving all events unfiltered. +This section describes event callbacks (or 'events' for short) that are +called from the game when something specific happens. Which scripts +receive them is usually filtered by player. Call ```receiveAllEvents(true)``` +to start receiving all events unfiltered. ## eventGameInit() @@ -53,6 +54,14 @@ An event that is run when the mission transporter has no more reinforcements to An event that is run when the mission transporter has landed with reinforcements. +## eventTransporterEmbarked(transport) + +An event that is run when a unit embarks into a transporter. + +## eventTransporterDisembarked(transport) + +An event that is run when a unit disembarks from a transporter. + ## eventDeliveryPointMoving() An event that is run when the current player starts to move a delivery point. @@ -146,28 +155,34 @@ if the structure was built by a droid. It is not triggered for building theft ## eventStructureDemolish(structure[, droid]) -An event that is run every time a structure begins to be demolished. -This does not trigger again if the structure is partially demolished. +An event that is run every time a structure begins to be demolished. This does +not trigger again if the structure is partially demolished. ## eventStructureReady(structure) -An event that is run every time a structure is ready to perform some special ability. -It will only fire once, so if the time is not right, register your own timer to keep checking. +An event that is run every time a structure is ready to perform some +special ability. It will only fire once, so if the time is not right, +register your own timer to keep checking. ## eventStructureUpgradeStarted(structure) An event that is run every time a structure starts to be upgraded. +## eventDroidRankGained(droid, rankNum) + +An event that is run whenever a droid gains a rank. + ## eventAttacked(victim, attacker) -An event that is run when an object belonging to the script's controlling player is attacked. -The attacker parameter may be either a structure or a droid. +An event that is run when an object belonging to the script's controlling player is +attacked. The attacker parameter may be either a structure or a droid. ## eventResearched(research, structure, player) -An event that is run whenever a new research is available. The structure parameter is set if -the research comes from a research lab owned by the current player. If an ally does the research, -the structure parameter will be set to null. The player parameter gives the player it is called for. +An event that is run whenever a new research is available. The structure +parameter is set if the research comes from a research lab owned by the +current player. If an ally does the research, the structure parameter will +be set to null. The player parameter gives the player it is called for. ## eventDestroyed(object) @@ -176,7 +191,8 @@ the parameter object around, since it is about to vanish! ## eventPickup(feature, droid) -An event that is run whenever a feature is picked up. It is called for all players / scripts. +An event that is run whenever a feature is picked up. It is called for +all players / scripts. Careful passing the parameter object around, since it is about to vanish! (3.2+ only) ## eventObjectSeen(viewer, seen) @@ -184,19 +200,22 @@ Careful passing the parameter object around, since it is about to vanish! (3.2+ An event that is run sometimes when an object, which was marked by an object label, which was reset through resetLabel() to subscribe for events, goes from not seen to seen. An event that is run sometimes when an objectm goes from not seen to seen. -First parameter is **game object** doing the seeing, the next the game object being seen. +First parameter is **game object** doing the seeing, the next the game +object being seen. ## eventGroupSeen(viewer, group) An event that is run sometimes when a member of a group, which was marked by a group label, which was reset through resetLabel() to subscribe for events, goes from not seen to seen. -First parameter is **game object** doing the seeing, the next the id of the group being seen. +First parameter is **game object** doing the seeing, the next the id of the group +being seen. ## eventObjectTransfer(object, from) -An event that is run whenever an object is transferred between players, for example due -to a Nexus Link weapon. The event is called after the object has been transferred, -so the target player is in object.player. The event is called for both players. +An event that is run whenever an object is transferred between players, +for example due to a Nexus Link weapon. The event is called after the +object has been transferred, so the target player is in object.player. +The event is called for both players. ## eventChat(from, to, message) @@ -204,6 +223,14 @@ An event that is run whenever a chat message is received. The ```from``` paramet player sending the chat message. For the moment, the ```to``` parameter is always the script player. +## eventQuickChat(from, to, messageEnum) + +An event that is run whenever a quick chat message is received. The ```from``` parameter is the +player sending the chat message. For the moment, the ```to``` parameter is always the script +player. ```messageEnum``` is the WzQuickChatMessage value (see the WzQuickChatMessages global +object for constants to match with it). The ```teamSpecific``` parameter is true if this message +was sent only to teammates, false otherwise. + ## eventBeacon(x, y, from, to[, message]) An event that is run whenever a beacon message is received. The ```from``` parameter is the @@ -215,20 +242,21 @@ Message may be undefined. An event that is run whenever a beacon message is removed. The ```from``` parameter is the player sending the beacon. For the moment, the ```to``` parameter is always the script player. -## eventGroupLoss(object, groupId, newSize) +## eventGroupLoss(gameObject, groupId, newSize) An event that is run whenever a group becomes empty. Input parameter is the about to be killed object, the group's id, and the new group size. ## eventArea