BattleScripts

Overview

This is a new game entity, representing a special command that is processing in the battlescape layer after the end of each player's turn. In its design it is close to mapScripts and missionScripts. Currently, it supports only two command types and used to introduce the reinforcement mechanic to the game - spawnUnit and showMessage.

General script properties

These properties apply to all command types:

Property	Data type	Description	Default
type	string	String ID for battlescript	Required
executionChances	integer	The probability (0-100%) that this command will be executed (or fails)	100
executions	integer	How many times this command repeats in one turn	1
maxRuns	integer	How many times this command repeats in battlescape game session (controlled with variable).	-1 (unlimited)
variable	string	Variable name to track executions of the battlescripts.	battleScriptVariable
label	integer	A numeric label that can be used for conditional execution of commands. Please make sure that you use positive and unique labels (unique within the command). If you try using negative labels, engine will convert them to positive (abs. value) anyway. If you try using non-unique labels, you'll get undefined behavior	0
conditionals	integer	Defines the pre-conditions for the execution of this command. For example [1, -4] means it will be executed if command with label 1 was a success and command with label 4 failed. Note: commands that are not yet executed are always in failed state.	0
unitSet	string	A list of units to spawn
packSize	integer	How many units can be spawned with one command (on a single map block)	1
randomPackSize	bool	Should number in packSize treated as maximum possible to generate random number	false
minLevel	integer	The min Z level for command.	0
maxLevel	integer	The max Z level for command.	0
unitSide	integer	Side for spawned units, 0 = FACTION_PLAYER, 1 = FACTION_HOSTILE, 2 = FACTION_NEUTRAL	1
startTurn	integer	Turn number to start running this command	0
endTurn	integer	Turn number to start running this command. If set to -1 then command would run forever until battle would end	-1
minDifficulty	integer	This command only applies to difficulty levels of this or above	0
maxDifficulty	integer	This command only applies to difficulty levels of this or below	4
minAlarmLevel	integer	This command will run when alert level is above specified number	1
maxAlarmLevel	integer	This command will run only when alert level is below specified number	infinite
messages	message (see below)	Custom battle message	0

spawnUnit command type

Here is an example of the ruleset:

battleScripts:
  - type: TEST_SCRIPT
    commands:
    - type: spawnUnit
      executions: 2
      executionChances: 90
      startTurn: 4
      endTurn: 6
      packSize: 3
      randomPackSize: true
      unitSide: 1
      minDifficulty: 1
      maxDifficulty: 3
      groups: [3, 4]
      spawnBlocks: ["N", W, S, E, NW, NE, SW, SE]
      unitSet: [STR_XCOM_EX_COMMANDER]

This command would summon 1-3 hostile STR_XCOM_EX_COMMANDER, 2 times with 90% probability, from turn 4 to 6 if the difficulty is not the lowest or the highest.

showMessage command type

This command produce CustomBattleMessageState to the player in battlescape. All specific properties are described inside message property after number (used if you want to randomize output):

Property	Data type	Description	Default
title	string	A title of the message
content	string	A text to display inside the body of the message
answer	string	A label on "OK" button	"STR_OK"
background	string	String ID to the background message	"TAC00.SCR"