Difference between revisions of "Ruleset Reference Nightly (OpenXcom)"

From UFOpaedia
Jump to navigation Jump to search
(487 intermediate revisions by 17 users not shown)
Line 1: Line 1:
−
A reference of all the customizable values of everything in a [[Rulesets (OpenXcom)|ruleset]], according to the latest nightly. This page should be updated as new versions become available in order to explain the changes from [[Ruleset Reference (OpenXcom)|version 1.0]].  
+
<div style="background:#ffdddd;">
 +
'''DID YOU KNOW?'''
 +
 
 +
OpenXcom (and also OpenXcom Extended) have a ruleset syntax validation and auto-completion tool (a plugin for VSCode), which automatically finds and highlights all your syntax errors.
 +
 
 +
'''More info''': https://openxcom.org/forum/index.php/topic,6552.0.html
 +
 
 +
'''Give it a try!'''
 +
</div>
 +
 
 +
A reference of the customizable values of everything in a [[Rulesets (OpenXcom)|ruleset]], according to the latest OpenXcom nightly.
 +
* '''Last full review''': 19th May 2020, by Meridian
 +
* '''Synchronized with''': OpenXcom v1.0 (2020-05-04 nightly build) <span style="background:#ddffdd;">and OpenXcom Extended v6.5.1 (2020-05-21)</span>
 +
 
 +
<div style="background:#ddffdd;">
 +
'''IMPORTANT''': The OpenXcom Extended (OXCE) ruleset is highlighted using '''light green background''', just like the one used in this disclaimer. Anything marked green does not work with OpenXcom (OXC).
 +
</div>
  
 
Some guidelines:
 
Some guidelines:
Line 9: Line 25:
 
* Money amounts (prices, costs, etc.) are represented in dollars.
 
* Money amounts (prices, costs, etc.) are represented in dollars.
 
* All file paths are case insensitive, but IDs (such as string IDs, music names, or cutscene names) are case sensitive.  In general, though, if it works on one operating system, it will work on all operating systems.
 
* All file paths are case insensitive, but IDs (such as string IDs, music names, or cutscene names) are case sensitive.  In general, though, if it works on one operating system, it will work on all operating systems.
 +
* Items are ordered as they come in the ruleset. To override this, you can specify a '''listOrder''' attribute. You can find the default listOrders in [[Ruleset List Order (OpenXcom)|Ruleset List Order]].
 +
* <span style="background:#ddffdd;"> OXCE allows inheritance for almost all types of rulesets, via the '''refNode''' attribute. You can use this to create copies of weapons, armors, facilities, etc. that inherit everything from another existing object and just modify a few attributes to save space, prevent copy/paste mistakes and have automatic update/synch when the original item changes. Below is an example for creating a new Laser Sniper Rifle item from an existing Laser Rifle item:</span>
  
−
Items are ordered as they come in the ruleset. To override this, you can specify a ''listOrder''. You can find the default listOrders in [[Ruleset List Order (OpenXcom)|Ruleset List Order]].
+
  items:
 +
    - &STR_LASER_RIFLE          # Let's mark laser rifle info with an anchor
 +
      type: STR_LASER_RIFLE
 +
      size: 0.2
 +
      costSell: 36900
 +
      weight: 8
 +
  #
 +
  # a million other attributes...
 +
  #
 +
    - type: STR_LASER_SNIPER_RIFLE
 +
      refNode: *STR_LASER_RIFLE  # First, let's inherit everything from the STR_LASER_RIFLE anchor.
 +
      bigSprite: xxx            # And now let's give it a new sprite,
 +
      accuracyAimed: 160        # increase aimed shot accuracy
 +
      tuAuto: 0                  # and disable auto shot.
  
  
−
=== Globe ===
+
=== Starting Base ===
 +
 
 +
Defines the content of the base at the start of game.
 +
 
 +
<div style="background:#ddffdd;">In OXCE, you can optionally define different starting bases for each game difficulty using the following top-level names:
 +
* startingBaseBeginner
 +
* startingBaseExperienced
 +
* startingBaseVeteran
 +
* startingBaseGenius
 +
* startingBaseSuperhuman
 +
 
 +
If you don't define some of them, the default starting base will be used instead of the missing ones.
  
−
Defines the drawing of landmasses and borders on the globe.
+
The default starting base will also be used for New Battle screen.
 +
</div>
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 22: Line 65:
 
! width="80" | Default
 
! width="80" | Default
 
|-
 
|-
−
| '''data'''
+
| '''randomSoldiers'''
−
| Path name of file which contains polygon and texture information. (For example WORLD.DAT).
+
| Determines number and type of starting X-Com soldiers.
−
| -
+
If a mod contains more than one type of soldiers, this can also be specified with:
 +
  randomSoldiers:
 +
    STR_SOLDIER: 3
 +
    STR_ANOTHER_SOLDIER: 7
 +
| 0
 +
|-
 +
| '''scientists'''
 +
| Determines number of starting scientists.  
 +
| 0
 +
|-
 +
| '''engineers'''
 +
| Determines number of starting engineers.
 +
| 0
 
|-
 
|-
−
| '''polygons'''
+
| '''facilities'''
−
| List of polygons drawn on the globe surface. A triangle consist of seven values: the first number defines the texture, followed by three pairs of (x,y) globe coordinates. Only polygons with 3 or 4 vertices are reliable shown on the globe = 7 or 9 values per entry.  
+
| List of starting base facilities and their position (x and y coordinates being 0-5).
 
| -
 
| -
 
|-
 
|-
−
| '''polylines'''
+
| '''items'''
−
| List of border lines. Each list entry consist of a list of (x,y) globe coordinates.
+
| List of starting items in the base, excluding items on crafts.
 
| -
 
| -
 
|-
 
|-
−
| '''textures'''
+
| '''crafts'''
−
| List of terrains that correspond to each [[TEXTURE.DAT|Geoscape texture]]. Terrains can be restricted to certain areas on the globe with '''area: (''[lon1, lat1, lon2, lat2]'')''' and '''weight: NUMBER''' gives their chance of appearance.  
+
| List of starting crafts in the base and items on board.
 
| -
 
| -
 
|}
 
|}
  
−
=== Countries ===
+
OpenXcom uses the same format to define a starting base as for saving/loading a real base (except for '''randomSoldiers''' attribute).
 +
That means you can also define various other parameters in your mod, for example:
 +
* predefined soldiers (if you don't like to start with randomly generated ones, but like it a bit more RPG)
 +
* transfers that arrive at specified times (you could control various game events/progression with these items)
 +
* base detected by aliens flag (which would allow you for example to start the campaign with an early scripted base defense mission)
 +
* and so on...
  
−
Defines one of the [[Country Funding (EU)|funding nations]], listed in ''"countries:"''. They're used for activity graphs and player scoring.
+
The easiest way to create this ruleset, is to copy it from an existing saved game, correct the indentation and manually change the actual content.
 +
The following table completes the list of highest-level attributes you can use.
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 48: Line 109:
 
! width="80" | Default
 
! width="80" | Default
 
|-
 
|-
−
| '''type'''
+
| '''soldiers'''
−
| String ID of the country name.
+
| List of starting base soldiers, their names, stats and everything else.
−
| ''required''
+
| -
 
|-
 
|-
−
| '''fundingBase'''
+
| '''transfers'''
−
| Country's base funding, in thousands. The starting funding can be anywhere between 1x and 2x the base funding.
+
| List of items, soldiers, engineers and/or scientists inbound to the starting base with a specified time lag.
−
| 0
+
| -
 
|-
 
|-
−
| '''fundingCap'''
+
| '''research'''
−
| Country's funding cap, in thousands. Once a country reaches this maximum, it will no longer increase its funding.
+
| List of ongoing research projects in the starting base.
−
| 0
+
| -
 
|-
 
|-
−
| '''labelLon'''
+
| '''productions'''
−
'''labelLat'''
+
| List of ongoing manufacturing projects in the starting base.
−
| Longitude and latitude coordinates of the country's label on the globe. This label is only shown when the globe is zoomed in and "detail" is turned on.
+
| -
−
| 0.0
 
−
0.0
 
 
|-
 
|-
−
| '''areas'''
+
| '''retaliationTarget'''
−
| List of "rectangles" on the globe defined as [''lon1'' ''lat1'' ''lon2'' ''lat2'']. Any activity within these areas counts towards the country's graph activity and affects their opinion of the player.
+
| Flag saying whether the aliens know about your starting base or not.
−
| -
+
| false
 
|}
 
|}
  
−
=== Regions ===
+
=== Globe ===
  
−
Defines one of the [[Geoscape (EU)#World Regions/Countries|world regions]], listed in ''"regions:"''. They're used for base placement, activity graphs and mission spawning.
+
Defines the drawing of landmasses and borders on the globe. Also defines mapping between geoscape textures and battlescape appearance.
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 80: Line 139:
 
! width="80" | Default
 
! width="80" | Default
 
|-
 
|-
−
| '''type'''
+
| '''data'''
−
| String ID of the region name.
+
| Path to a file, which contains polygon and texture information. (For example WORLD.DAT).
−
| ''required''
+
| -
 
|-
 
|-
−
| '''cost'''
+
| '''polygons'''
−
| Amount of money spent building an X-COM base in this region (first base is free).
+
| List of polygons drawn on the globe surface. A triangle consist of seven values: the first number defines the texture, followed by three pairs of (x,y) globe coordinates. Only polygons with 3 or 4 vertices are reliably shown on the globe, i.e. 7 or 9 values per entry.
−
| 0
+
 
 +
Note that:
 +
* '''data''' and '''polygons''' define the same thing... use one or another, not both
 +
* each time you define data or polygons, their previous definition is completely deleted (i.e. globe can be defined only as a whole, not incrementally)
 +
| -
 
|-
 
|-
−
| '''areas'''
+
| '''polylines'''
−
| List of "rectangles" on the globe defined as ''[lon1, lat1, lon2, lat2]''. Any activity within these areas counts towards the region's graph activity.
+
| List of border lines. Each list entry consist of a list of (x,y) globe coordinates.
 +
 
 +
Note that:
 +
* each time you define polylines, their previous definition is completely deleted (i.e. they can be defined only as a whole, not incrementally)
 
| -
 
| -
 
|-
 
|-
−
| '''regionWeight'''
+
| '''textures'''
−
| Weight of this region when selecting regions for alien missions.
+
| List of globe textures that determine the battlescape appearance of a certain place on the globe.
−
| 0
+
| -
 
|-
 
|-
−
| '''missionWeights'''
+
| '''countryColor'''
−
| Weighted list of the different mission types for this region (eg. ''STR_ALIEN_RESEARCH: 14'').
+
| Color of the country labels (0-255).
−
| -
+
| 239
 +
|-
 +
| '''cityColor'''
 +
| Color of the city labels (0-255).
 +
| 138
 +
|-
 +
| '''baseColor'''
 +
| Color of the xcom base labels (0-255).
 +
| 133
 +
|-
 +
| '''lineColor'''
 +
| Border line color (0-255).
 +
| 162
 
|-
 
|-
−
| '''missionZones'''
+
| '''oceanPalette'''
−
| List of "rectangles" (''[lon1, lat1, lon2, lat2]'') defining the mission zones for this region. Mission zones are waypoints for UFO trajectories.
+
| Color range (defined as palette offset) of the "oceans", or better said of the "globe sections not covered by polygons" (0-15).
−
Mission zone 3 defines cities belonging to a region (''[lon1, lat1, lon2, lat2, -1, STR_CITY_NAME]''). They will be displayed on the globe and used for terror site missions. Cities can also have a '''zoom''' setting which determines the appearance of its name label according to the specified zoom level.  
+
| 12
−
| -
 
 
|-
 
|-
−
| '''missionRegion'''
+
| '''oceanShading'''
−
| Spawn mission in this region instead (used for regions without land).
+
| Whether ocean shading (32-color) should be used or not.
−
| -
+
 
 +
Notes:
 +
* normally land uses 16-color shading and ocean uses 32-color shading... where "ocean" is defined as "lack of texture", i.e. for UFO lack of land and for TFTD lack of water
 +
* for hybrids (i.e. mods that combine UFO and TFTD textures together), there is no "ocean" anymore, because the globe is fully covered by textures (land and water textures)
 +
* thus the original 32 colors used for ocean shading can be:
 +
** re-used to provide more colors for the textures (2 distinct color ranges, 16 colors each)
 +
** ignored for ocean shading purposes, and used for texture shading purposes instead
 +
| true
 
|}
 
|}
  
−
=== Base Facilities ===
+
==== (Globe) Textures ====
−
 
 
−
Defines one of the [[Base Facilities (EU)|facilities]] that can be built in an X-COM base, listed in ''"facilities:"''.
 
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 119: Line 201:
 
! width="80" | Default
 
! width="80" | Default
 
|-
 
|-
−
| '''type'''
+
| '''id'''
−
| String ID of the facility name.
+
| ID of the texture.
−
| ''required''
+
 
 +
* Terrain-based textures have positive IDs (0, 1, 2, ...) and are used for drawing globe polygons
 +
* AlienDeployment-based textures have negative IDs (-1, -2, -3, ...) and are '''not''' used for drawing globe polygons
 +
| required
 
|-
 
|-
−
| '''requires'''
+
| '''terrain'''
−
| List of [[#Research|topics]] (string IDs) that must be researched to unlock this facility. If none are specified, this facility is unlocked from the start.
+
| List of terrains (can be more than one) that correspond to each [[TEXTURE.DAT|Geoscape texture]].
 +
 
 +
Terrains can be restricted to certain areas on the globe with '''area: (''[lon1, lon2, lat1, lat2]'')''' and '''weight: NUMBER''' that gives their chance of appearance.
 +
 
 +
These textures are primarily used for UFO landing/crash sites.
 +
 
 +
Example 1:
 +
globe:
 +
  textures:
 +
    - id: 0
 +
      terrain:
 +
        - name: FOREST
 +
          area: [0, 360, -90, 0]
 +
        - name: JUNGLE
 +
          area: [0, 360, 0, 90]
 +
 
 +
Example 2:
 +
globe:
 +
  textures:
 +
    - id: 11
 +
      terrain:
 +
        - name: PIPES
 +
          weight: 50
 +
        - name: SEABED
 +
          weight: 25
 +
        - name: CORAL
 +
          weight: 25
 
| -
 
| -
 
|-
 
|-
−
| '''spriteShape'''
+
| '''deployments'''
−
| Sprite ID from [[BASEBITS.PCK]] used to draw the facility's outer shape in the Basescape and UFOpaedia.
+
| Defined by weighted alien deployments (can be more than one), which determine appearance for mission sites (e.g. terror sites, artifact sites, shipping lanes, etc.).
−
| -1
+
 
−
|-
+
Example:
−
| '''spriteFacility'''
+
globe:
−
| Sprite ID from [[BASEBITS.PCK]] used to draw the facility's contents in the Basescape and UFOpaedia. Drawn on top of '''spriteShape'''.
+
  textures:
−
| -1
+
    - id: -4
−
|-
+
      deployments:
−
| '''lift'''
+
        STR_CARGO_SHIP_P1: 50
−
| Is this facility an [[Access Lift]]? All base facilities must be connected to the lift.
+
        STR_CRUISE_SHIP_P1: 50
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''baseTerrain'''
 +
| In OXCE, the terrain-based textures can additionally have separate terrain defined for base defense missions.
 +
 
 +
This terrain can be used in map scripting to replace the generic "dirt" blocks with something more fitting (e.g. snow in the arctic or jungle near the equator).
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,5108.0.html
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''startingCondition'''
 +
| In OXCE, the textures can have their own starting conditions (with lower priority than deployment starting conditions).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''fakeUnderwater'''
 +
| In OXCE, the (land) textures can also be flagged as fake underwater textures using this boolean attribute.
 +
 
 +
Such terrain can support underwater missions, underwater bases/facilities and have separate starting conditions.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7374.msg116684.html#msg116684
 
| false
 
| false
 +
|}
 +
 +
=== Countries ===
 +
 +
Defines one of the [[Country Funding (EU)|funding nations]], listed in ''"countries:"''. They're used for activity graphs and player scoring.
 +
 +
<div style="background:#ddffdd;">In OXCE, the same kind of ruleset can be used to define "extra globe labels" so that you can label continents, or anything else on non-Earth globes (e.g. Moon, Mars, Dune, etc.). Of course, nothing is stopping you from using this on the Earth globe too. Listed under its own top-level category ''"extraGlobeLabels:"''.
 +
</div>
 +
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 
|-
 
|-
−
| '''hyper'''
+
| '''type'''
−
| Is this facility a [[Hyperwave Decoder]]? Displays extra information for detected UFOs. Only valid for radar facilities. If "true", the radar detection chance will be set to 100% regardless of '''radarChance''' value.
+
| String ID of the country name.
−
| false
+
| ''required''
 
|-
 
|-
−
| '''mind'''
+
| '''fundingBase'''
−
| Is this facility a [[Mind Shield]]? Reduces the chance of UFOs finding your base. Does not stack.
+
| Country's base funding, in thousands. The starting funding can be anywhere between 1x and 2x the base funding.
−
| false
+
| 0
 
|-
 
|-
−
| '''grav'''
+
| '''fundingCap'''
−
| Is this facility a [[Grav Shield]]? Doubles the power of your base defenses. Does not stack.
+
| Country's funding cap, in thousands. Once a country reaches this maximum, it will no longer increase its funding.
−
| false
+
| 0
 
|-
 
|-
−
| '''size'''
+
| '''labelLon'''
−
| Size of the facility, in grid units. Every facility is square, so a size of 1 means 1x1, 2 means 2x2, etc. Bigger facilities are made up of multiple sprites, for example a 2x2 facility will use 4 sprites for '''spriteShape''' and 4 sprites for '''spriteFacility''' (top-left, top-right, bottom-left, bottom-right).
+
'''labelLat'''
−
| 1
+
| Longitude and latitude coordinates of the country's label on the globe. This label is only shown when the globe is zoomed in and "detail" is turned on.
 +
| 0.0
 +
0.0
 +
|- style="background-color:#ddffdd;"
 +
| '''labelColor'''
 +
| Color (0-255) of the country label.
 +
| 0 (not used)
 
|-
 
|-
−
| '''buildCost'''
+
| '''areas'''
−
| Amount of money spent to build this facility in the base.
+
| List of "rectangles" on the globe defined as [''lon1'' ''lon2'' ''lat1'' ''lat2'']. Any activity within these areas counts towards the country's graph activity and affects their opinion of the player.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''zoomLevel'''
 +
| Minimum globe zoom level at which this extra globe label becomes visible.
 +
 
 +
Note: doesn't work for countries. Only for extra globe labels.
 
| 0
 
| 0
 +
|}
 +
 +
=== Regions ===
 +
 +
Defines one of the [[Geoscape (EU)#World Regions/Countries|world regions]], listed in ''"regions:"''. They're used for base placement, activity graphs and mission spawning.
 +
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 
|-
 
|-
−
| '''buildTime'''
+
| '''type'''
−
| Amount of days it takes for this facility to be built.
+
| String ID of the region name.
−
| 0
+
| ''required''
 
|-
 
|-
−
| '''monthlyCost'''
+
| '''cost'''
−
| Amount of money spent monthly for the maintenance of this facility.
+
| Amount of money spent building an X-COM base in this region (first base is free).
 
| 0
 
| 0
 
|-
 
|-
−
| '''storage'''
+
| '''areas'''
−
| Amount of storage space (for items) this facility provides. See [[Base Stores]].
+
| List of "rectangles" on the globe defined as ''[lon1, lon2, lat1, lat2]''. Any activity within these areas counts towards the region's graph activity.
−
| 0
+
 
 +
Example:
 +
  regions:
 +
    - type: STR_EUROPE
 +
      areas:
 +
        - [335, 60, -70, -35]
 +
| -
 
|-
 
|-
−
| '''personnel'''
+
| '''regionWeight'''
−
| Amount of personnel (soldiers, scientsts, engineers) these quarters can contain.
+
| Weight of this region when selecting regions for alien missions.
 
| 0
 
| 0
 
|-
 
|-
−
| '''aliens'''
+
| '''missionWeights'''
−
| Amount of live aliens this facility can contain. Only checked if the ''alienContainmentLimitEnforced'' option is enabled.
+
| Weighted list of the different mission types for this region (eg. ''STR_ALIEN_RESEARCH: 14'').
−
| 0
+
| -
 
|-
 
|-
−
| '''crafts'''
+
| '''missionZones'''
−
| Amount of X-COM craft this facility can contain.
+
| List of mission zones. Mission zones are used for generating waypoints for UFO trajectories, and also for spawning mission sites and alien bases. Each mission zone itself is a list of "mission areas", where each mission area is defined by:
−
| 0
+
* a "rectangle" (''[lon1, lon2, lat1, lat2]'') defining a relevant section of the globe (does not need to be within the region itself); or a single point (a city) on the globe
 +
Zones used for mission site spawning additionally have:
 +
* a texture ID (from globe ruleset, this should be the alienDeployment-based texture, usually the ID is a negative number)
 +
* and optionally a city string ID (will be displayed on the globe if defined)
 +
Example: (''[lon1, lon2, lat1, lat2, textureID, STR_CITY_NAME]'').
 +
 
 +
'''Important:''' Crossing the prime meridian in '''missionZones''' requires a different syntax! (''lon2'' cannot be smaller than ''lon1'')
 +
 
 +
Wrong example:
 +
  [350,  8, 20, 30]
 +
Correct example:
 +
  [350, 368, 20, 30]  # 368 (=8+360) also represents 8 degrees, and satisfies the ''lon2 >= lon1'' condition
 +
 
 +
PS: This syntax exception does not apply to '''areas'''.
 +
| -
 
|-
 
|-
−
| '''labs'''
+
| '''missionRegion'''
−
| Amount of lab space this facility provides for research projects.
+
| Spawn mission in this region instead (used for regions without land).
−
| 0
+
| -
 +
|}
 +
 
 +
=== Base Facilities ===
 +
 
 +
Defines one of the [[Base Facilities (EU)|facilities]] that can be built in an X-COM base, listed in ''"facilities:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 
|-
 
|-
−
| '''workshops'''
+
| '''type'''
−
| Amount of workshop space this facility provides for manufacture projects.
+
| String ID of the facility name.
−
| 0
+
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''fakeUnderwater'''
 +
| Defines whether the facility can be built in a standard base, fake underwater base (used by hybrid mods), or both.
 +
 
 +
Possible options:
 +
* -1 = both (default)
 +
* 0 = only standard base
 +
* 1 = only fake underwater base
 +
| -1
 
|-
 
|-
−
| '''psiLabs'''
+
| '''requires'''
−
| Amount of soldier space this facility provides for psionic training.
+
| List of [[#Research|topics]] (string IDs) that must be researched to unlock this facility. If none are specified, this facility is unlocked from the start.
−
| 0
+
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''requiresBaseFunc'''
 +
| A list of services required to build this facility.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''provideBaseFunc'''
 +
| A list of services this facility provides after being built.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''forbiddenBaseFunc'''
 +
| A list of services that cannot be used anymore after this facility is built.
 +
| -
 
|-
 
|-
−
| '''radarRange'''
+
| '''spriteShape'''
−
| Maximum radar detection range of this facility, in nautical miles.
+
| Sprite ID from [[BASEBITS.PCK]] used to draw the facility's outer shape in the Basescape and UFOpaedia.
−
| 0
+
| -1
 
|-
 
|-
−
| '''radarChance'''
+
| '''spriteFacility'''
−
| Chance (0-100%) of this radar detecting a UFO that enters its range.
+
| Sprite ID from [[BASEBITS.PCK]] used to draw the facility's contents in the Basescape and UFOpaedia. Drawn on top of '''spriteShape'''. Not required for buildings size 2 or larger.
−
| 0
+
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''missileAttraction'''
 +
| A weight (i.e. not a percentage) of how likely will alien missiles/bombardments hit this type of facility.
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''destroyedFacility'''
 +
| String ID of the destroyed version of this facility (must have the same size).
 +
 
 +
Note: destruction can happen either in Base Defense mission or via Alien missiles/bombardment.
 +
| -
 
|-
 
|-
−
| '''defense'''
+
| '''lift'''
−
| Offensive power provided by this base defense against attacking UFOs.
+
| Is this facility an [[Access Lift]]? All base facilities must be connected to the lift.
−
| 0
+
| false
 
|-
 
|-
−
| '''hitRatio'''
+
| '''hyper'''
−
| Chance (0-100) of the base defense hitting an attacking UFO.
+
| Is this facility a [[Hyperwave Decoder]]? Displays extra information for detected UFOs. Only valid for radar facilities. If "true", the radar detection chance will be taken from '''radarChance''' value.
−
| 0
+
| false
 
|-
 
|-
−
| '''fireSound'''
+
| '''mind'''
−
| Sound ID from [[#Extra_Sounds|GEO.CAT]] played when the base defense fires.
+
| Is this facility a [[Mind Shield]]? Reduces the chance of UFOs finding your base. Does stack (detection chance is inversely proportional to the number of mind shields).
−
| -1
+
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''mindPower'''
 +
| The power of the mind shield provided by this facility.
 +
| 1
 
|-
 
|-
−
| '''hitSound'''
+
| '''grav'''
−
| Sound ID from [[#Extra_Sounds|GEO.CAT]] played when the base defense hits a target.
+
| Is this facility a [[Grav Shield]]? Doubles the power of your base defenses. Does not stack.
−
| -1
+
| false
 
|-
 
|-
−
| '''mapName'''
+
| '''size'''
−
| [[MAPS|Map]] associated to this facility in Battlescape base defenses.
+
| Size of the facility, in grid units. Every facility is square, so a size of 1 means 1x1, 2 means 2x2, etc. Bigger facilities are made up of multiple sprites, for example a 2x2 facility will use 4 sprites for '''spriteShape''' and 4 sprites for '''spriteFacility''' (top-left, top-right, bottom-left, bottom-right).
−
| -
+
| 1
 
|-
 
|-
−
|}
+
| '''buildCost'''
 +
| Amount of money spent to build this facility in the base.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''refundValue'''
 +
| Amount of money refunded when the facility is dismantled.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''buildCostItems'''
 +
| Items needed to build a facility and items "refunded" when the facility is dismantled.
  
−
=== Crafts ===
+
  - type: STR_MY_FACILITY
 +
    buildCostItems:
 +
      STR_ALIEN_ALLOYS:
 +
        build: 100
 +
        refund: 75
 +
      STR_ALIEN_ENTERTAINMENT:
 +
        build: 1
 +
        refund: 1
  
−
Defines one of the [[Craft|X-COM crafts]] that go on interception missions, listed in ''"crafts:"''.
 
−
 
−
{| class="wikitable" width="100%"
 
−
! width="150"| Value
 
−
! width="*"  | Description
 
−
! width="80" | Default
 
−
|-
 
−
| '''type'''
 
−
| String ID of the craft name.
 
−
| ''required''
 
−
|-
 
−
| '''requires'''
 
−
| List of [[#Research|topics]] (string IDs) that must be researched to unlock this craft. If none are specified, this craft is unlocked from the start.
 
 
| -
 
| -
 
|-
 
|-
−
| '''sprite'''
+
| '''buildTime'''
−
| Sprite ID from [[BASEBITS.PCK]] used to draw this craft in the Basescape and from [[INTICON.PCK]] used to draw the damage indicator in dogfights.
+
| Amount of days it takes for this facility to be built.
−
modders: the corresponding extrasprite file id for BASEBITS.PCK is sprite+33 INTICON.PCK contains a minimized icon id=sprite the file id for the dogfight image is sprite+11
 
−
| -1
 
−
|-
 
−
| '''fuelMax'''
 
−
| Maximum amount of fuel this craft can carry. Crafts use up fuel based on their speed while travelling.
 
 
| 0
 
| 0
 
|-
 
|-
−
| '''damageMax'''
+
| '''monthlyCost'''
−
| Maximum amount of damage this craft can take. If this amount is exceeded, the craft is destroyed.
+
| Amount of money spent monthly for the maintenance of this facility.
 
| 0
 
| 0
 
|-
 
|-
−
| '''speedMax'''
+
| '''storage'''
−
| Maximum speed in nautical miles. Crafts travel at max speed when flying and half speed when patrolling.
+
| Amount of storage space (for items) this facility provides. See [[Base Stores]].
 
| 0
 
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''storageTiles'''
 +
| A list of tile positions where to place items in this facility's storage. If empty, vanilla checkerboard pattern will be used.
 +
| -
 
|-
 
|-
−
| '''accel'''
+
| '''personnel'''
−
| Aceeleration value shown in the UFOpaedia.
+
| Amount of personnel (soldiers, scientsts, engineers) these quarters can contain.
 
| 0
 
| 0
 
|-
 
|-
−
| '''weapons'''
+
| '''aliens'''
−
| Amount of craft weapons this craft can equip. The UI can only display a max of 2 weapons.
+
| Amount of live aliens this facility can contain. Only checked if the ''storageLimitsEnforced'' option is enabled.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''prisonType'''
 +
| What type of prisoners (aliens) can be held in this facility.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,4830.msg69933.html#msg69933
 
| 0
 
| 0
 
|-
 
|-
−
| '''soldiers'''
+
| '''crafts'''
−
| Amount of soldiers this craft can carry.
+
| Amount of X-COM craft this facility can contain.
 
| 0
 
| 0
 
|-
 
|-
−
| '''maxItems'''
+
| '''labs'''
−
| Amount of items this craft can carry.
+
| Amount of lab space this facility provides for research projects.
−
| 80
+
| 0
 
|-
 
|-
−
| '''vehicles'''
+
| '''workshops'''
−
| Amount of vehicles this craft can carry.
+
| Amount of workshop space this facility provides for manufacture projects.
 
| 0
 
| 0
 
|-
 
|-
−
| '''costBuy'''
+
| '''psiLabs'''
−
| Amount of money spent for purchasing this craft. If set to 0, the craft will not be available in the Purchase/Recruit screen.
+
| Amount of soldier space this facility provides for psionic training.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''trainingRooms'''
 +
| Amount of soldier space this facility provides for combat/martial training.
 
| 0
 
| 0
 
|-
 
|-
−
| '''costRent'''
+
| '''radarRange'''
−
| Amount of money spent monthly for renting this craft. If set to 0, the craft is not on rental and won't count towards base maintenance.
+
| Maximum radar detection range of this facility, in nautical miles.
 
| 0
 
| 0
 
|-
 
|-
−
| '''costSell'''
+
| '''radarChance'''
−
| Amount of money gained for selling this craft.
+
| Chance (0-100%) of this radar detecting a UFO that enters its range.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''sightRange'''
 +
| Range at which the facility can detect alien bases in nautical miles.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''sightChance'''
 +
| Chance (0-100%) of this facility detecting an alien base that enters its sight range. More info: https://openxcom.org/forum/index.php/topic,8119.0.html
 
| 0
 
| 0
 
|-
 
|-
−
| '''refuelItem'''
+
| '''defense'''
−
| Item required for refuelling this craft. If no item is specified, the craft uses human fuel.
+
| Offensive power provided by this base defense against attacking UFOs.
 
| 0
 
| 0
 
|-
 
|-
−
| '''repairRate'''
+
| '''hitRatio'''
−
| Amount of damage restored every hour while [[Repairs|Repairing]] in base.
+
| Chance (0-100) of the base defense hitting an attacking UFO.
−
| 1
+
| 0
 
|-
 
|-
−
| '''refuelRate'''
+
| '''fireSound'''
−
| Amount of fuel restored every 30 mins while [[Refueling]] in base. If specified, a '''refuelItem''' is spent each time.
+
| Sound ID from [[#Extra_Sounds|GEO.CAT]] played when the base defense fires.
−
| 1
 
−
|-
 
−
| '''radarRange'''
 
−
| Detection range of the craft's radar in nautical miles. Every craft radar has a 100% detection chance.
 
−
| 600
 
−
|-
 
−
| '''transferTime'''
 
−
| Number of hours it takes to purchase/transfer this craft to a base.
 
 
| 0
 
| 0
 
|-
 
|-
−
| '''score'''
+
| '''hitSound'''
−
| [[Score]] lost when this craft is destroyed.
+
| Sound ID from [[#Extra_Sounds|GEO.CAT]] played when the base defense hits a target.
 
| 0
 
| 0
 
|-
 
|-
−
| '''spacecraft'''
+
| '''mapName'''
−
| Can this craft go to [[Cydonia]]?
+
| [[MAPS|Map]] associated to this facility in Battlescape base defenses.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''verticalLevels'''
 +
| Can be used instead of '''mapName'''. Allows generating a base facility map as if it were an ''addBlock'' map script command.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,5316.0.html
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''maxAllowedPerBase'''
 +
| Maximum number of facilities of this type allowed to be built per base.
 +
| 0 (not used)
 +
|- style="background-color:#ddffdd;"
 +
| '''manaRecoveryPerDay'''
 +
| How much mana does the facility recover per day. The facility setting is NOT cumulative, more facilities don't provide more regen. If there are multiple facilities of different type with different regen rate, the best (highest) regen rate is used.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''healthRecoveryPerDay'''
 +
| How much health/HP does the facility recover per day. The facility setting is NOT cumulative, more facilities don't provide more regen. If there are multiple facilities of different type with different regen rate, the best (highest) regen rate is used.
 +
 
 +
FIXME: add a link to more detailed description of this feature!
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''sickBayAbsoluteBonus'''<br/>'''sickBayRelativeBonus'''
 +
| How much additional HP is healed per day.
 +
 
 +
  - type: STR_FIELD_HOSPITAL
 +
    sickBayAbsoluteBonus: 0.75
 +
    sickBayRelativeBonus: 0.0
 +
  - type: STR_SURGERY_ROOM
 +
    sickBayAbsoluteBonus: 0.25
 +
    sickBayRelativeBonus: 1.0
 +
  - type: STR_REGENERATION_ROOM
 +
    sickBayAbsoluteBonus: 0.0
 +
    sickBayRelativeBonus: 10.0
 +
  - type: STR_GOAULD_SARCOPHAGUS
 +
    sickBayAbsoluteBonus: 90.0
 +
    sickBayRelativeBonus: 0.0
 +
 
 +
Examples, considering the ruleset above:
 +
* with no facilities: 1 hp healed per day
 +
* with one field hospital: 1.75 hp per day
 +
* with one surgery room: 1.25 hp per day + 1% of soldier's max hp
 +
* with 2 field hospitals and 2 surgery rooms: 3 hp per day + 2% of soldier's max hp
 +
* with regeneration room: 10% of soldier's max hp... i.e. fully recovered in 10 days or less
 +
* with Goa'uld sarcophagus: 90 hp per day... i.e. fully healed overnight
 +
| 0.0<br/>0.0
 +
|- style="background-color:#ddffdd;"
 +
| '''leavesBehindOnSell'''
 +
| A facility to leave behind a dismantled facility (must be of the same size); or a list of 1x1 facilities to fill in the old facility's place.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''removalTime'''
 +
| How long facilities left behind when this one is sold should take to build.
 +
 
 +
Possible options:
 +
* -1 = take '''buildTime''' from the other facilities' rulesets
 +
* 0 = instant
 +
* 1+ = that many days
 +
 
 +
Note: doesn't do anything without '''leavesBehindOnSell'''
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''canBeBuiltOver'''
 +
| Can this facility be built over?
 
| false
 
| false
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''battlescapeTerrainData'''
+
| '''buildOverFacilities'''
−
| [[#Terrains|Terrain]] associated to this craft in Battlescape missions.
+
| A list of other base facilities this one can be built over. If empty, it can be built over anything with ''canBeBuiltOver: true''.
−
| -
 
−
|-
 
−
| '''deployment'''
 
−
| Custom positions for the unit deployment in the craft, listed as: ''[x, y, z, facing]''
 
−
If not specified, units are placed on empty spots from top-left to bottom-right facing top-right.
 
 
| -
 
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''rightClickActionType'''
 +
| Which screen should open when R-clicking on this facility in the base view?
 +
 +
Possible options:
 +
* 0 = OpenXcom default
 +
* 1 = Prison (Alien Containment)
 +
* 2 = Manufacturing
 +
* 3 = Research
 +
* 4 = Martial Training
 +
* 5 = Psi Training
 +
* 6 = Barracks
 +
* 7 = Market (Sell)
 +
* other = go to Geoscape
 +
| 0
 
|}
 
|}
  
−
=== Craft Weapons ===
+
=== Crafts ===
  
−
Defines one of the [[Craft Armaments|weapons]] equipped by X-COM craft for shooting down UFOs, listed in ''"craftWeapons:"''.
+
Defines one of the [[Craft|X-COM crafts]] that go on interception missions, listed in ''"crafts:"''.
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 339: Line 656:
 
|-
 
|-
 
| '''type'''
 
| '''type'''
−
| String ID of the weapon name.
+
| String ID of the craft name.
 
| ''required''
 
| ''required''
 +
|-
 +
| '''requires'''
 +
| List of [[#Research|topics]] (string IDs) that must be researched to unlock this craft. If none are specified, this craft is unlocked from the start.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''requiresBuyBaseFunc'''
 +
| A list of services required to buy this craft.
 +
| -
 
|-
 
|-
 
| '''sprite'''
 
| '''sprite'''
−
| Sprite ID from [[BASEBITS.PCK]] used to draw the weapon in the Basescape and from [[INTICON.PCK]] used to draw the weapon in dogfights.
+
| Sprite ID from [[BASEBITS.PCK]] used to draw this craft in the Basescape and from [[INTICON.PCK]] used to draw the damage indicator in dogfights.
−
modders: the corresponding extrasprites file id for INTICON.PCK is sprite+5 and sprite+48 for BASEBITS.PCK
+
 
 +
Note that:
 +
* the corresponding id for INTICON.PCK for the minimized craft icon is sprite+0
 +
* the corresponding id for INTICON.PCK for the dogfight image is sprite+11
 +
* the corresponding id for BASEBITS.PCK is sprite+33
 
| -1
 
| -1
 
|-
 
|-
−
| '''sound'''
+
| '''marker'''
−
| Sound ID from [[#Extra_Sounds|GEO.CAT]] played when this weapon fires.
+
| Sprite ID from GlobeMarkers spritesheet, used for drawing craft icon on the globe. Usually 3x3 pixels, but can be modded to be bigger.
 +
 
 +
Note: if not modded, sprite id 1 is used (=vanilla craft marker)
 
| -1
 
| -1
 
|-
 
|-
−
| '''damage'''
+
| '''weapons'''
−
| Amount of damage this weapon does to enemy UFOs.
+
| Amount of craft weapons this craft can equip. The UI can only display a max of 2 weapons.
 +
 
 +
<span style="background:#ddffdd;">In OXCE, you can have up to '''4 weapons''' (or other accessories)</span>
 
| 0
 
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''weaponTypes'''
 +
| A list defining compatible weapon types for this craft type. Up to 4 slots, and each slot can have up to 4 compatible weapon types.
 +
 +
Example: [0, [0, 1], [2,3], [0,2,4]]
 +
| [0, 0, 0, 0]
 +
|- style="background-color:#ddffdd;"
 +
| '''weaponStrings'''
 +
| A list describing the craft's weapon slots (up to 4 slots).
 +
| [STR_WEAPON_ONE, STR_WEAPON_TWO]
 
|-
 
|-
−
| '''range'''
+
| '''soldiers'''
−
| Maximum range of this weapon in dogfights (in meters).
+
| Amount of soldiers this craft can carry.
 
| 0
 
| 0
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''accuracy'''
+
| '''pilots'''
−
| Chance (0-100%) of each shot hitting the enemy UFO.
+
| How many pilots are required to pilot this craft.
 +
 
 +
Notes:
 +
* pilots are also soldiers and will be fighting in the Battlescape
 +
* pilots give bonuses/penalties to the craft performance in the Dogfights (based on their skills)
 +
* pilots gain experience via Dogfights
 +
* you can manually assign pilots to the craft; if you don't want to, they can be assigned automatically
 
| 0
 
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''allowLanding'''
 +
| Should this craft be able to start a Battlescape mission?
 +
 +
Note: you may want to set ''false'' to your manned/piloted interceptors.
 +
| true
 
|-
 
|-
−
| '''reloadCautious'''
+
| '''vehicles'''
−
| Time this weapon takes to fire between each shot in ''Cautious Mode''.
+
| Amount of vehicles this craft can carry.
 
| 0
 
| 0
 
|-
 
|-
−
| '''reloadStandard'''
+
| '''costBuy'''
−
| Time this weapon takes to fire between each shot in ''Standard Mode''.
+
| Amount of money spent for purchasing this craft. If set to 0, the craft will not be available in the Purchase/Recruit screen.
 
| 0
 
| 0
 
|-
 
|-
−
| '''reloadAggressive'''
+
| '''costRent'''
−
| Time this weapon takes to fire between each shot in ''Aggressive Mode''.
+
| Amount of money spent monthly for renting this craft. If set to 0, the craft is not on rental and won't count towards base maintenance.
 
| 0
 
| 0
 
|-
 
|-
−
| '''ammoMax'''
+
| '''costSell'''
−
| Maximum amount of ammo this weapon can carry.
+
| Amount of money gained for selling this craft.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''forceShowInMonthlyCosts'''
 +
| Forces this craft type to appear in Monthly Costs breakdown, even if not present at the base.
 +
 
 +
Note: Skyranger, Interceptor, Triton and Barracuda have this turned on (for backwards-compatibility).
 +
| false
 +
|-
 +
| '''refuelItem'''
 +
| Item required for refueling this craft. If no item is specified, the craft uses human fuel.
 
| 0
 
| 0
 
|-
 
|-
−
| '''rearmRate'''
+
| '''repairRate'''
−
| Amount of ammo restored every 30 mins while the craft is [[Rearming]] in base. If specified, '''clip'''s are spent depending on their '''clipSize'''. If the '''clipSize''' of the specified ammo is 0, no '''clip'''s are spent.  
+
| Amount of damage restored every hour while [[Repairs|Repairing]] in base.
 
| 1
 
| 1
 
|-
 
|-
−
| '''projectileType'''
+
| '''refuelRate'''
−
| Type of the weapon projectile, used for the projectile sprite in dogfights:
+
| Amount of fuel restored every 30 mins while [[Refueling]] in base. If specified, a '''refuelItem''' is spent each time.
−
* 0 - [[Stingray]]
+
| 1
−
* 1 - [[Avalanche]]
 
−
* 2 - [[Cannon]]
 
−
* 3 - [[Fusion Ball]]
 
−
* 4 - [[Laser Cannon]]
 
−
* 5 - [[Plasma Beam]]
 
−
| 2
 
 
|-
 
|-
−
| '''projectileSpeed'''
+
| '''transferTime'''
−
| Speed of the weapon projectile in dogfights.
+
| Number of hours it takes to purchase/transfer this craft to a base.
 
| 0
 
| 0
 
|-
 
|-
−
| '''launcher'''
+
| '''score'''
−
| String ID of the [[#Items|item]] required to equip this weapon.
+
| [[Score]] lost when this craft is destroyed.
−
| -
+
| 0
 
|-
 
|-
−
| '''clip'''
+
| '''battlescapeTerrainData'''
−
| String ID of the [[#Items|item]] required to rearm this weapon.
+
| [[#Terrains|Terrain]] associated to this craft in Battlescape missions.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''craftInventoryTile'''
 +
| Coordinates [x, y, z] of the craft inventory tile (weapon's pile) in the craft. If not specified, tile occupied by the first soldier is used.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''mapVisible'''
 +
| Should the craft map be visible at the beginning of the battle? Used for some funky effects (see W40k mod for examples).
 +
| true
 +
|-
 +
| '''deployment'''
 +
| Custom positions for the unit deployment in the craft, listed as: ''[x, y, z, facing]''
 +
If not specified, units are placed on empty spots from top-left to bottom-right facing top-right.
 
| -
 
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''keepCraftAfterFailedMission'''
 +
| Defines whether the craft should be lost after a failed mission or not. Useful for example to implement paratroopers; or any kind of troop deployment without a craft physically being on the map.
 +
| false
 +
|-
 +
| '''spacecraft'''
 +
| Can this craft go to [[Cydonia]]?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''notifyWhenRefueled'''
 +
| Should a pop up window inform the player once this craft is fully refueled?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''autoPatrol'''
 +
| Should this craft automatically return to its patrol destination after refueling?
 +
| false
 +
|-
 +
| '''maxAltitude'''
 +
| Maximum altitude (0-4) this craft can dogfight to.
 +
| -1
 +
|-
 +
| '''maxItems'''
 +
| Amount of items this craft can carry.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''shieldRechargedAtBase'''
 +
| How many shield points are recharged when landed at base per hour.
 +
| 1000
 
|}
 
|}
  
−
=== Items ===
+
==== Craft Stats ====
 +
 
 +
The following attributes define so called "craft stats". They are listed in a separate table, just for convenience... but are still part of the Craft ruleset.
  
−
Defines the Geoscape and Battlescape properties of an [[Equipment (EU)|item]] that can be stored in X-COM bases, listed in ''"items:"''.
+
<span style="background:#ddffdd;">'''Note:''' In OXCE, all these stats are dynamic, i.e. can be modified by equipping craft weapons/accessories.</span>
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 415: Line 817:
 
! width="80" | Default
 
! width="80" | Default
 
|-
 
|-
−
| '''type'''
+
| '''fuelMax'''
−
| String ID of the internal item name.
+
| Maximum amount of fuel this craft can carry. Crafts use up fuel based on their speed while traveling.
−
| ''required''
+
| 0
 
|-
 
|-
−
| '''name'''
+
| '''damageMax'''
−
| String ID of the displayed item name, for cases where it's different from the internal name. If omitted, '''type''' is used.
+
| Maximum amount of damage this craft can take. If this amount is exceeded, the craft is destroyed.
−
| -
+
| 0
 
|-
 
|-
−
| '''requires'''
+
| '''speedMax'''
−
| List of [[#Research|topics]] (string IDs) that must be researched to unlock this item. If none are specified, this item is unlocked from the start. Soldiers can only use unlocked items in the Battlescape.
+
| Maximum speed in nautical miles. Crafts travel at max speed when flying and half speed when patrolling.
−
| -
 
−
|-
 
−
| '''size'''
 
−
| Space occupied by this item in [[Base Stores]]. Can be a decimal value.
 
−
| 0.0
 
−
|-
 
−
| '''costBuy'''
 
−
| Amount of money spent for purchasing this item. If set to 0, this item will not be available in the Purchase/Recruit screen.
 
 
| 0
 
| 0
 
|-
 
|-
−
| '''costSell'''
+
| '''accel'''
−
| Amount of money gained for selling this item.
+
| Acceleration value shown in the UFOpaedia.
 
| 0
 
| 0
 
|-
 
|-
−
| '''transferTime'''
+
| '''radarRange'''
−
| Number of hours it takes to purchase/transfer this item to a base.
+
| Detection range of the craft's radar in nautical miles. Every craft radar has a detection chance dependent on its '''radarChance'''.
−
| 24
+
| 672
 
|-
 
|-
−
| '''weight'''
+
| '''radarChance'''
−
| [[Item_Weight|Weight]] occupied by this item in a soldier's inventory.
+
| Chance (0-100%) of this craft radar detecting a UFO that enters its range.
−
| 999
+
| 100
 
|-
 
|-
−
| '''bigSprite'''
+
| '''sightRange'''
−
| Sprite ID from [[BIGOBS.PCK]] used to draw this item in a soldier's inventory and UFOpaedia.
+
| Range at which the craft can detect alien bases in nautical miles.
−
| -1
+
| 1696
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''floorSprite'''
+
| '''hitBonus'''
−
| Sprite ID from [[FLOOROB.PCK]] used to draw this item on the floor of a Battlescape tile.
+
| Flat bonus percentage to hit chances of all equipped weapons.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''avoidBonus'''
 +
| Flat bonus percentage to dodge chances against enemy fire.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''powerBonus'''
 +
| Multiplier for the power of craft weapons, e.g. 20 = weapons' power increased to 120% of their original power, -20 = decreased to 80%.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''armor'''
 +
| Amount of blocked damage per hit.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''shieldCapacity'''
 +
| Craft's maximum shield capacity.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''shieldRecharge'''
 +
| Defines the percent chance of recharging a point of shielding per game second (GS) during a Dogfight. Values under 100 are the percent chance, for over 100, every +100 means an automatic +1 to shields per GS. Thus ''shieldRecharge: 250'' means +2 shields/GS, with a 50% chance of +1 more.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''shieldRechargeInGeoscape'''
 +
| Similar to '''shieldRecharge''', but acts every 5 seconds in the Geoscape. Giving it a value of -1 means instant recharge as soon as 5 seconds pass!
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''shieldBleedThrough'''
 +
| Defines the percent of damage that passes the shield when it goes down.  A value of 0 means that with even just 1 shield point, any single hit will be blocked, while 100 means 100% of the damage left after the shield blocks it will go on to damage the craft.
 +
| 0
 +
|}
 +
 
 +
=== Craft Weapons ===
 +
 
 +
Defines one of the [[Craft Armaments|weapons]] equipped by X-COM craft for shooting down UFOs, listed in ''"craftWeapons:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| String ID of the weapon name.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''weaponType'''
 +
| A weapon's type/category. Used to limit certain weapons/accessories to certain craft weapon slots.
 +
| 0
 +
|-
 +
| '''sprite'''
 +
| Sprite ID from [[BASEBITS.PCK]] used to draw the weapon in the Basescape and from [[INTICON.PCK]] used to draw the weapon in dogfights.
 +
 
 +
Note that:
 +
* the corresponding id for INTICON.PCK is sprite+5
 +
* the corresponding id for BASEBITS.PCK is sprite+48
 
| -1
 
| -1
 
|-
 
|-
−
| '''handSprite'''
+
| '''sound'''
−
| Sprite ID from [[HANDOB.PCK]] used to draw this item on a soldier's hand in the Battlescape.
+
| Sound ID from [[#Extra_Sounds|GEO.CAT]] played when this weapon fires.
−
modders: each handobject needs 8 images (8 directions) define the extrasprites accordingly
 
−
| 120
 
−
|-
 
−
| '''bulletSprite'''
 
−
| Sprite ID from ''BulletSprites.png'' used to draw this weapon's projectile on the Battlescape:
 
−
* 0 - [[Rocket Launcher]]
 
−
* 1 - [[Pistol]]
 
−
* 2 - [[Rifle]]
 
−
* 3 - [[Auto Cannon]]
 
−
* 4 - [[Heavy Cannon]]
 
−
* 5 - [[Laser Pistol]]
 
−
* 6 - [[Laser Rifle]]
 
−
* 7 - [[Heavy Laser]]
 
−
* 8 - [[Plasma Rifle|Plasma]]
 
−
* 9 - [[Small Launcher]]
 
−
* 10 - [[Blaster Launcher]]
 
−
for modders: the bulletsprite needs to be put into the extraSprites type "Projectiles" the bulletsprite can contain up to 35 3x3 images. The corresponding file id is 35*[bulletSprite]
 
 
| -1
 
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''stats'''
 +
| Contains the same set of attributes as [[#Craft Stats|Craft Stats]]. These dynamically increase/decrease the stats of a craft, when equipped.
 +
 +
Examples:
 +
* you can increase the craft's range by equipping an extra fuel tank
 +
* you can increase the craft's hit chance by equipping advanced targeters
 +
* you can increase the craft's radar range/chance by equipping an extra radar
 +
* and so on...
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''hidePediaInfo'''
 +
| Allows hiding the weapon's stats in the Ufopedia.
 +
 +
Note: this can be used for example when the craft weapon is not really a weapon, but only an equipment/booster (e.g. radar booster, extra fuel tank, etc.).
 +
| false
 
|-
 
|-
−
| '''fireSound'''
+
| '''damage'''
−
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon fires.
+
| Amount of damage this weapon does to enemy UFOs.
−
| -1
+
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''shieldDamageModifier'''
 +
| Defines the percent of power that a weapon does to shields.
 +
| 100
 
|-
 
|-
−
| '''hitSound'''
+
| '''range'''
−
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon hits a target.
+
| Maximum range of this weapon in dogfights (in kilometers).
−
| -1
+
| 0
 
|-
 
|-
−
| '''hitAnimation'''
+
| '''accuracy'''
−
| Sprite ID from [[SMOKE.PCK]] used to draw the weapon's "hit explosion".
+
| Chance (0-100%) of each shot hitting the enemy UFO.
−
'''NOTE''': Do not define this value for melee/psi weapons, they use [[HIT.PCK]] and therefore meleeAnimation instead.
 
−
'''NOTE''': Explosive style weapons (Damage type: smoke, incendiary, stun, & High Explosive) use [[X1.PCK]] and should always be set to 0.
 
 
| 0
 
| 0
 
|-
 
|-
−
| '''power'''
+
| '''reloadCautious'''
−
| Average damage of the weapon, in most cases it will be +-50% this value.
+
| Time this weapon takes to fire between each shot in ''Cautious Mode''.
 
| 0
 
| 0
 
|-
 
|-
−
| '''strengthApplied'''
+
| '''reloadStandard'''
−
| Add the attacking unit's strength to this weapon's damage.
+
| Time this weapon takes to fire between each shot in ''Standard Mode''.
−
| false
 
−
|-
 
−
| '''compatibleAmmo'''
 
−
| List of string IDs of the ammo items that can be loaded on this weapon. If none are specified, the weapon doesn't need ammo.
 
−
| -
 
−
|-
 
−
| '''damageType'''
 
−
| What type of [[damage]] does this weapon do:
 
−
* 0 - None
 
−
* 1 - Armor Piercing
 
−
* 2 - Incendiary
 
−
* 3 - High Explosive
 
−
* 4 - Laser
 
−
* 5 - Plasma
 
−
* 6 - Stun
 
−
* 7 - Melee
 
−
* 8 - Acid
 
−
* 9 - Smoke
 
−
'''NOTE:''' A damage type other than 0-9 will do nothing.
 
 
| 0
 
| 0
 
|-
 
|-
−
| '''tuAuto'''
+
| '''reloadAggressive'''
−
'''accuracyAuto'''
+
| Time this weapon takes to fire between each shot in ''Aggressive Mode''.
−
| The percentage (0-100%) of [[Time Units]] (from the soldier's total) required to fire an Auto Shot. If 0, the weapon does not have an Auto Shot.
 
−
The base accuracy (0-100%) applied to a soldier's [[Firing Accuracy]] when firing an Auto Shot.
 
 
| 0
 
| 0
−
0
 
 
|-
 
|-
−
| '''tuSnap'''
+
| '''ammoMax'''
−
'''accuracySnap'''
+
| Maximum amount of ammo this weapon can carry.
−
| The percentage (0-100%) of [[Time Units]] (from the soldier's total) required to fire a Snap Shot. If 0, the weapon does not have a Snap Shot.
 
−
The base accuracy (0-100%) applied to a soldier's [[Firing Accuracy]] when firing a Snap Shot.
 
 
| 0
 
| 0
−
0
 
 
|-
 
|-
−
| '''tuAimed'''
+
| '''rearmRate'''
−
'''accuracyAimed'''
+
| Amount of ammo restored every hour while the craft is [[Rearming]] in base. If specified, '''clip'''s are spent depending on their '''clipSize''', and '''reamRate''' should be a multiple of '''clipSize'''. If the '''clipSize''' of the specified ammo is 0, no '''clip'''s are spent.  
−
| The percentage (0-100%) of [[Time Units]] (from the soldier's total) required to fire an Aimed Shot. If 0, the weapon does not have an Aimed Shot.
+
| 1
−
The base accuracy (0-100%) applied to a soldier's [[Firing Accuracy]] when firing an Aimed Shot.
 
−
| 0
 
−
0
 
 
|-
 
|-
 +
| '''projectileType'''
 +
| Type of the weapon projectile, used for the projectile sprite in dogfights:
 +
* 0 - [[Stingray]]
 +
* 1 - [[Avalanche]]
 +
* 2 - [[Cannon]]
 +
* 3 - [[Fusion Ball]]
 +
* 4 - [[Laser Cannon]]
 +
* 5 - [[Plasma Beam]]
 +
| 2
 
|-
 
|-
−
| '''tuMelee'''
+
| '''projectileSpeed'''
−
'''accuracyMelee'''
+
| Speed of the weapon projectile in dogfights.
−
| The percentage (0-100%) of [[Time Units]] (from the soldier's total) required to do a melee attack (Hit). If 0, the weapon does not have a melee attack.
 
−
The base accuracy (0-100%) applied to a soldier's [[Melee Accuracy]] when doing a melee attack.
 
−
| 0
 
−
0
 
−
|-
 
−
| '''clipSize'''
 
−
| The amount of ammo stored in each weapon clip. If -1 is specified, this weapon has infinite ammo.
 
 
| 0
 
| 0
 
|-
 
|-
−
| '''battleType'''
+
| '''launcher'''
−
| Defines the weapon's behavior in the Battlescape:
+
| String ID of the [[#Items|item]] required to equip this weapon.
−
* 0 - None (Geoscape-only item)
+
| -
−
* 1 - [[Weapons|Firearm]]
 
−
* 2 - Ammo
 
−
* 3 - Melee
 
−
* 4 - [[Grenade]]
 
−
* 5 - [[Proximity Grenade]]
 
−
* 6 - [[Medi-Kit (EU)|Medi-Kit]]
 
−
* 7 - [[Motion Scanner]]
 
−
* 8 - [[Mind Probe]]
 
−
* 9 - [[Psi-Amp]]
 
−
* 10 - [[Electro-flare]]
 
−
* 11 - Corpse
 
−
| 0
 
 
|-
 
|-
−
| '''twoHanded'''
+
| '''clip'''
−
| Is this weapon two-handed? If true, incurs an accuracy penalty if used with both hands occupied. Note that the handsprite of a twoHanded item is also drawn at a slightly different position than a one handed item.
+
| String ID of the [[#Items|item]] required to rearm this weapon.
−
| false
+
| -
 
|-
 
|-
−
| '''waypoint'''
+
| '''underwaterOnly'''
−
| Does this weapon use waypoints? (eg. [[Blaster Launcher]]). Can also be used to make ammo items use the waypoint system.
+
| Is this craft weapon restricted to underwater use only?
 
| false
 
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''tractorBeamPower'''
 +
| How much the weapon slows down the maximum speed of a UFO when it's in range and the weapon is active.
 +
 +
Note: Tractor beams allow you to effectively decrease the maximum speed of a UFO during interception, preventing their escape.  If you have powerful enough beams targeting the UFO, you can even cause it to land or splash down in the water!
 +
| 0
 +
|}
 +
 +
=== Items ===
 +
 +
Defines the Geoscape and Battlescape properties of an [[Equipment (EU)|item]] that can be stored in X-COM bases, listed in ''"items:"''.
 +
 +
==== Naming, Categorization and Storage ====
 +
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 
|-
 
|-
−
| '''fixedWeapon'''
+
| '''type'''
−
| Is this weapon fixed? (it's part of a unit, eg. tanks and terrorist units)
+
| String ID of the internal item name.
−
| false
+
| ''required''
 
|-
 
|-
−
| '''invWidth'''
+
| '''name'''
−
| Item width in a soldier's inventory (in grid units).
+
| String ID of the displayed item name, for cases where it's different from the internal name. If omitted, '''type''' is used. Only affects inventory screens and battlescape internals. Does not change the name of items in geoscape lists.
−
| 1
+
| =type
 +
|- style="background-color:#ddffdd;"
 +
| '''nameAsAmmo'''
 +
| Extension for the name of weapons loaded with this item as ammo.
 +
| -
 
|-
 
|-
−
| '''invHeight'''
+
| '''battleType'''
−
| Item height in a soldier's inventory (in grid units).
+
| Defines the weapon's behavior in the Battlescape:
−
| 1
+
* 0 - None (Geoscape-only item)
−
|-
+
* 1 - [[Weapons|Firearm]]
−
| '''painKiller'''
+
* 2 - Ammo
−
| Amount of painkillers contained in a [[Medi-Kit (EU)|Medi-Kit]].
+
* 3 - Melee
 +
* 4 - [[Grenade]]
 +
* 5 - [[Proximity Grenade]]
 +
* 6 - [[Medi-Kit (EU)|Medi-Kit]]
 +
* 7 - [[Motion Scanner]]
 +
* 8 - [[Mind Probe]]
 +
* 9 - [[Psi-Amp]]
 +
* 10 - [[Electro-flare]]
 +
* 11 - Corpse
 
| 0
 
| 0
 
|-
 
|-
−
| '''heal'''
+
| '''requires'''
−
| Amount of heal's contained in a [[Medi-Kit (EU)|Medi-Kit]].
+
| List of [[#Research|topics]] (string IDs) that must be researched to unlock this item. If none are specified, this item is unlocked from the start. Soldiers can only use unlocked items in the Battlescape.
−
| 0
+
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''requiresBuy'''
 +
| A list of research topics required to be able to buy this item.
 +
 
 +
Note: you ''can'' use the item even if the requirements are not met... you just can't buy it.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''requiresBuyBaseFunc'''
 +
| A list of services (for a given base) required to be able to buy this item.
 +
| -
 
|-
 
|-
−
| '''stimulant'''
+
| '''size'''
−
| Amount of stimulants contained in a [[Medi-Kit (EU)|Medi-Kit]].
+
| Space occupied by this item in [[Base Stores]]. Can be a decimal value.
−
| 0
+
| 0.0
 
|-
 
|-
−
| '''woundRecovery'''
+
| '''costBuy'''
−
| Amount of [[Fatal Wounds]] treated by each heal of a [[Medi-Kit (EU)|Medi-Kit]].
+
| Amount of money spent for purchasing this item. If set to 0, this item will not be available in the Purchase/Recruit screen.
 
| 0
 
| 0
 
|-
 
|-
−
| '''healthRecovery'''
+
| '''costSell'''
−
| Amount of [[Health]] recovered by each heal of a [[Medi-Kit (EU)|Medi-Kit]].
+
| Amount of money gained for selling this item.
 
| 0
 
| 0
 
|-
 
|-
−
| '''stunRecovery'''
+
| '''transferTime'''
−
| Amount of [[Stun]] removed by each stimulant of a [[Medi-Kit (EU)|Medi-Kit]].
+
| Number of hours it takes to purchase/transfer this item to a base.
 +
| 24
 +
|- style="background-color:#ddffdd;"
 +
| '''categories'''
 +
| A list of [[#Item Categories|categories]] this item belongs to.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''monthlyMaintenance'''
 +
| Monthly maintenance cost of items in Stores. For example your tanks could have a small monthly maintenance cost.
 
| 0
 
| 0
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''energyRecovery'''
+
| '''monthlySalary'''
−
| Amount of [[Energy]] recovered by each stimulant of a [[Medi-Kit (EU)|Medi-Kit]].
+
| Monthly salary of "other employees" (represented as items in Stores). This is practically identical to monthlyMaintenance, it just shows on a different place in the [Monthly costs] screen.
 +
 
 +
Note: the "other employees" can't do much (yet), but you could use them for example to increase your Stores capacity (by giving them negative '''size''')... representing increased storage effectiveness by hiring specialized logistics personnel (or outsourcing storage completely).
 
| 0
 
| 0
 +
|}
 +
 +
==== Sprites and Particles ====
 +
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''customItemPreviewIndex'''
 +
| Allows to have different icons for different types of Vehicles (HWP/SWS) on the [Craft Info] screen. Defined either as a single index into the CustomItemPreviews spritesheet, or as a list of indices (for bigger icons).
 +
| -
 
|-
 
|-
−
| '''tuUse'''
+
| '''bigSprite'''
−
| Amount of [[Time Units]] required to use this item (for non-offensive items). It's a flat rate if '''flatRate''' is true, otherwise it's a percentage (0-100%).
+
| Sprite ID from [[BIGOBS.PCK]] used to draw this item in a soldier's inventory and UFOpaedia.
−
| 0
+
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''specialIconSprite'''
 +
| Sprite ID from [[SPICONS.DAT]] used to draw this item when used as '''specialWeapon''' (in Armor definition).
 +
| -1
 
|-
 
|-
−
| '''recoveryPoints'''
+
| '''floorSprite'''
−
| [[Score]] gained for recovering this alien artifact.
+
| Sprite ID from [[FLOOROB.PCK]] used to draw this item on the floor of a Battlescape tile.
−
| 0
+
| -1
 
|-
 
|-
−
| '''armor'''
+
| '''handSprite'''
−
| How much damage is needed to destroy this item on the ground.
+
| Sprite ID from [[HANDOB.PCK]] used to draw this item on a soldier's hand in the Battlescape.
−
| 20
+
modders: each handobject needs 8 images (8 directions) define the extrasprites accordingly
 +
| 120
 +
|-
 +
| '''bulletSprite'''
 +
| Sprite ID from ''BulletSprites.png'' used to draw this weapon's projectile on the Battlescape:
 +
* 0 - [[Rocket Launcher]]
 +
* 1 - [[Pistol]]
 +
* 2 - [[Rifle]]
 +
* 3 - [[Auto Cannon]]
 +
* 4 - [[Heavy Cannon]]
 +
* 5 - [[Laser Pistol]]
 +
* 6 - [[Laser Rifle]]
 +
* 7 - [[Heavy Laser]]
 +
* 8 - [[Plasma Rifle|Plasma]]
 +
* 9 - [[Small Launcher]]
 +
* 10 - [[Blaster Launcher]]
 +
for modders: the bulletsprite needs to be put into the extraSprites type "Projectiles" the bulletsprite can contain up to 35 3x3 images. The corresponding file id is 35*[bulletSprite]
 +
| -1
 +
|-
 +
| '''bulletSpeed'''
 +
| How much faster (or slower, if you use a negative number) is a projectile fired from this weapon compared to the average.
 +
| 0
 
|-
 
|-
−
| '''recover'''
+
| '''explosionSpeed'''
−
| Is this item recoverable? (gets transported to the X-COM base on mission success)
+
| How much faster (or slower, if you use a negative number) is an explosion animated compared to the average.
−
| true
+
| 0
 
|-
 
|-
 
| '''turretType'''
 
| '''turretType'''
Line 639: Line 1,137:
 
| -1
 
| -1
 
|-
 
|-
−
| '''liveAlien'''
+
| '''vaporColor'''
−
| Does this item represent a live alien? (counts towards [[Alien Containment]])
+
| The color offset (0-3 in TFTD) to use for the vapor trail.
−
| false
 
−
|-
 
−
| '''blastRadius'''
 
−
| Size of the projectile explosions. 0 for no explosion. -1 to automatically calculate based on weapon power and damage type (actual '''blastRadius''' currently is capped due [[Explosions#Playing_With_Fire|Explosion calculations]]).
 
 
| -1
 
| -1
 
|-
 
|-
−
| '''flatRate'''
+
| '''vaporDensity'''
−
| If true, then TU costs for this weapon are a flat rate (instead of a percentage of unit TUs).
+
| The vapor cloud density (number of particles) for the vapor trail.
−
| false
+
| 0
 
|-
 
|-
−
| '''arcingShot'''
+
| '''vaporProbability'''
−
| Does this weapon fire in an arc?
+
| The vapor cloud probability (0-100%) for the vapor trail.
−
| false
+
| 15
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''attraction'''
+
| '''vaporColorSurface'''
−
| Represents how likely an alien is to pick up this item. Values below 5 will be ignored (by design).
+
| The color offset (0-3 in TFTD) to use for the vapor trail (for surface deployments, i.e. non-underwater).
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''vaporDensitySurface'''
 +
| The vapor cloud density (number of particles) for the vapor trail (for surface deployments, i.e. non-underwater).
 
| 0
 
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''vaporProbabilitySurface'''
 +
| The vapor cloud probability (0-100%) for the vapor trail (for surface deployments, i.e. non-underwater).
 +
| 15
 +
|}
 +
 +
==== Sounds and Animations ====
 +
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''explosionHitSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when explosion happens. Can be a list with multiple options. If not specified, default explosion sound is used.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''reloadSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon is reloaded. Can be a list with multiple options. If not specified, default reload sound is used.
 +
| -
 
|-
 
|-
−
| '''maxRange'''
+
| '''fireSound'''
−
| Maximum range at which this weapon can operate.
+
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon fires. <span style="background:#ddffdd;">In OXCE, can be a list with multiple options.</span>
−
| 200
+
| -1
 
|-
 
|-
−
| '''aimRange'''
+
| '''hitSound'''
−
| Maximum effective range with this weapon before which range-based dropoff occurs.
+
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon hits a target. <span style="background:#ddffdd;">In OXCE, can be a list with multiple options.</span>
−
| 200
+
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''psiSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon performs a psi attack (only Panic/MindControl). Can be a list with multiple options.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''hitMissSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon misses a psi attack (Use/Panic/MindControl). Can be a list with multiple options.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''psiMissSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon misses a psi attack (only Panic/MindControl). Can be a list with multiple options.
 +
| -
 
|-
 
|-
−
| '''snapRange'''
+
| '''meleeSound'''
−
| Maximum effective range with snap shot before which range-based dropoff occurs. (ufoextender accuracy only)
+
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon attacks a target with melee. <span style="background:#ddffdd;">In OXCE, can be a list with multiple options.</span>
−
| 15
+
| 39
 +
|-
 +
| '''meleeHitSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon hits a target with melee. <span style="background:#ddffdd;">In OXCE, can be a list with multiple options.</span>
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''meleeMissSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon misses a target with melee. Can be a list with multiple options.
 +
| -
 
|-
 
|-
−
| '''autoRange'''
+
| '''hitAnimation'''
−
| Maximum effective range with auto shot before which range-based dropoff occurs. (ufoextender accuracy only)
+
| Sprite ID from [[SMOKE.PCK]] used to draw the weapon's "hit explosion". <span style="background:#ddffdd;">In OXCE, it applies also to Use action of psi weapons.</span>
−
| 7
+
'''NOTE''': Do not define this value for melee/psi weapons, they use [[HIT.PCK]] and therefore meleeAnimation instead.
 +
 
 +
'''NOTE''': Explosive style weapons (Damage type: smoke, incendiary, stun, & High Explosive) use [[X1.PCK]] and should always be set to the first ''above water'' sprite (spriteID for UFO, spriteID + 8 for TFTD). TFTD spritesheet should start with 8 underwater images, followed by 8 above water images.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''hitMissAnimation'''
 +
| Sprite ID from [[SMOKE.PCK]] used to draw the weapon's "miss explosion". Applies only to Use action of psi weapons.
 +
| -1
 
|-
 
|-
−
| '''minRange'''
+
| '''meleeAnimation'''
−
| Range-based dropoff will work in reverse for ranges below this.
+
| Sprite ID from HIT.PCK played when this weapon hits a target with melee.
 
| 0
 
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''meleeMissAnimation'''
 +
| Sprite ID from HIT.PCK played when this weapon misses a target with melee.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''psiAnimation'''
 +
| Sprite ID from HIT.PCK played when this weapon hits a target with psi attack (only Panic/MindControl). For Use action on psi weapons, define hitAnimation.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''psiMissAnimation'''
 +
| Sprite ID from HIT.PCK played when this weapon misses a target with psi attack (only Panic/MindControl). For Use action on psi weapons, define hitMissAnimation.
 +
| -1
 +
|}
 +
 +
<div style="background:#ddffdd;">It can be pretty confusing, which sound/animation is played when... so here's an attempt to illustrate what happens. For each combination of "event" and "type of attack", there are multiple variables... the first variable that is not empty is used.
 +
</div>
 +
 +
{| class="wikitable"
 +
!  !! Bullets (non-explosive) !! Melee weapon (or gun-butt) !! Psi weapon (panic/MC) !! Psi weapon (Use)
 
|-
 
|-
−
| '''dropoff'''
+
! Hit sound
−
| The value by which the accuracy lowers for each tile after (or before) the thresholds above.
+
| hitSound || meleeSound+meleeHitSound || psiSound > hitSound || hitSound
−
| 2
 
 
|-
 
|-
−
| '''bulletSpeed'''
+
! Miss sound
−
| How much faster (or slower, if you use a negative number) is a projectile fired from this weapon compared to the average.
+
| - || meleeMissSound > meleeSound || psiMissSound > hitMissSound > psiSound > hitSound || hitMissSound > hitSound
−
| 0
 
 
|-
 
|-
−
| '''autoShots'''
+
! Hit animation
−
| How many auto shots does this weapon fire.
+
| hitAnimation || meleeAnimation || psiAnimation > meleeAnimation || hitAnimation
−
| 3
 
−
|-
 
−
| '''shotgunPellets'''
 
−
| Number of projectiles fired per unit of ammunition. (note: due to engine limitations it is currently impossible to draw multiple projectiles in flight.)
 
−
| 0
 
−
|-
 
−
| '''zombieUnit'''
 
−
| String ID of the unit used for zombification (eg. [[Chrysallid]]s turn units into [[Zombie]]s).
 
−
| none
 
−
|-
 
−
| '''meleeSound'''
 
−
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon attacks a target with melee.
 
−
| 39
 
−
|-
 
−
| '''meleeHitSound'''
 
−
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this weapon HITS a target with melee.
 
−
| -1
 
−
|-
 
−
| '''meleeAnimation'''
 
−
| Sprite ID from HIT.PCK played when this weapon attacks a target with melee.
 
−
| 0
 
−
|-
 
−
| '''meleePower'''
 
−
| Damage this weapon will do when using melee. This only applies to Firearms, and is only available as stun damage. For normal melee weapons, use regular power and damage types.
 
−
| 0
 
−
|-
 
−
| '''LOSRequired'''
 
−
| Does this item require line of sight? (only applies to mind probes and psi-amps)
 
−
| false
 
−
|-
 
−
| '''skillApplied'''
 
−
| Is melee skill applied to the accuracy of an attack made with this object?
 
−
| true
 
 
|-
 
|-
 +
! Miss animation
 +
| - || meleeMissAnimation > meleeAnimation || psiMissAnimation > meleeMissAnimation > psiAnimation > meleeAnimation || hitMissAnimation > hitAnimation
 
|}
 
|}
  
−
=== UFOs ===
+
==== Power and Damage types  ====
−
 
 
−
Defines one of the [[UFOs]] that invade Earth, listed in ''"ufos:"''.
 
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 734: Line 1,263:
 
! width="80" | Default
 
! width="80" | Default
 
|-
 
|-
−
| '''type'''
+
| '''power'''
−
| String ID of the UFO name.
+
| Weapon power. Usually corresponds to weapon's average damage. For some weapons/items, it determines the range (e.g. for incendiary or smoke).
−
| ''required''
+
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''hidePower'''
 +
| Allows hiding the weapon's power (and the entire ammo section) in the Ufopedia.
 +
 
 +
Note: this can be used for example when the weapon is mostly scripted and the damage info is more confusing than helpful.
 +
| false
 
|-
 
|-
−
| '''size'''
+
| '''damageType'''
−
| String ID of the UFO size.
+
| What type of [[damage]] does this weapon do:
−
| STR_VERY_SMALL
+
* 0 - None
 +
* 1 - Armor Piercing
 +
* 2 - Incendiary
 +
* 3 - High Explosive
 +
* 4 - Laser
 +
* 5 - Plasma
 +
* 6 - Stun
 +
* 7 - Melee
 +
* 8 - Acid
 +
* 9 - Smoke
 +
Notes:
 +
* A damage type other than 0-9 will do nothing in OpenXcom.
 +
* <span style="background:#ddffdd;">In OXCE, there are '''10 more damage types''' (10-19), which have same default settings as AP/Laser/Plasma/Acid damage types in OpenXcom.</span>
 +
| 0
 
|-
 
|-
−
| '''sprite'''
+
| '''blastRadius'''
−
| Sprite ID from [[INTERWIN.DAT]] used to draw this UFO in the dogfight view and UFOpaedia.
+
| Size of the projectile explosions. 0 for no explosion. -1 to automatically calculate based on weapon power and damage type (actual '''blastRadius''' currently is capped due [[Explosions#Playing_With_Fire|Explosion calculations]]).
−
don't try to add more images if you don't want to punch yourself in the face - use modsprite
+
 
 +
<span style="background:#ddffdd;">Note: blastRadius is deprecated in OXCE. Use '''damageAlter.FixRadius''' instead. If both are specified, FixRadius is taken.</span>
 
| -1
 
| -1
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''modSprite'''
+
| '''damageAlter'''
−
| Filename used to draw this UFO in the dogfight view and UFOpaedia.
+
| OpenXcom has 10 damage types and the mechanics of all 10 of them are completely hardcoded. In OXCE, you can use one of these hardcoded damage types as a starting point, but still be able to override all damage aspects for every item. To do this, you always use a pair of attributes for default and override:
 +
* for normal/primary damage: default is in '''damageType''' and overrides in '''damageAlter'''
 +
* for secondary melee damage: default is in '''meleeType''' and overrides in '''meleeAlter'''
 +
Damage override has many attributes, which are all described in [[#Item Damage Types|Item Damage Types]].
 +
 
 +
Small example:
 +
 
 +
  - type: STR_HWP_DISC_PLASMA_CANNON
 +
    damageType: 5
 +
    damageAlter:
 +
      RandomType: 6
 +
      IgnoreOverKill: false
 +
      ToArmorPre: 0.05
 +
      ToStun: 0.75
 +
      RandomWound: false
 +
      ToWound: 0.12
 +
      FireThreshold: 25.0
 +
 
 
| -
 
| -
 
|-
 
|-
−
| '''damageMax'''
+
| '''meleePower'''
−
| Maximum amount of damage this UFO can take. If the UFO takes 50% damage, it crash lands. If it takes 100% damage, it is destroyed.
+
| Damage this weapon will do when using melee. This only applies to Firearms, and is only available as stun damage. For normal melee weapons, use regular power and damage types.
 
| 0
 
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''meleeType'''
 +
| Default damage type for secondary melee attack. Automatically set to damage type 7 (melee) for items with '''battleType''' = 3 (melee weapon).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''meleeAlter'''
 +
| Damage type details for '''meleeType'''.
 +
 +
Damage override has many attributes, which are all described in [[#Item Damage Types|Item Damage Types]].
 +
| -
 
|-
 
|-
−
| '''speedMax'''
+
| '''strengthApplied'''
−
| Maximum speed in nautical miles.
+
| Add the attacking unit's strength to this weapon's damage.
−
| 0
+
 
 +
<span style="background:#ddffdd;">Note: strengthApplied is deprecated in OXCE. Use '''damageBonus''' instead, which is also more configurable. If both are specified, damageBonus is taken.</span>
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''damageBonus'''
 +
| Formulae for additional weapon power bonus (not damage bonus!). Defined as a sum of polynomials of up to third degree with various unit stats as parameters :) If you didn't understand the previous sentence, don't be sad, just look at an example. '''FIXME''': add more description and examples later.
 +
 
 +
Example:
 +
 
 +
  - type: STR_EXAMPLE_1
 +
    damageBonus:
 +
      bravery: 2.5
 +
      flatHundred: -1.25
 +
  - type: STR_EXAMPLE_2
 +
    damageBonus:
 +
      firing: [0.0, 0.01]
 +
 
 +
In the first example the power bonus is "250% of soldier's bravery minus 125".
 +
 
 +
In the second example the power bonus is "0% of firing accuracy plus 1% of firing accuracy squared".
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''meleeBonus'''
 +
| Same as '''damageBonus''', but applies to secondary melee attacks.
 +
| -
 +
|}
 +
 
 +
==== Accuracy  ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''noLOSAccuracyPenalty'''
 +
| The penalty (in percent) to accuracy applied when attacking a unit or a tile outside of LOS. Overrides global setting.
 +
| -1
 
|-
 
|-
−
| '''accel'''
+
| '''accuracyAimed'''<br/>'''accuracySnap'''<br/>'''accuracyAuto'''<br/>'''accuracyMelee'''
−
| Aceeleration value shown in the UFOpaedia.
+
| The base accuracy (in percent) applied to a soldier's [[Firing Accuracy]] when firing an Aimed/Snap/Auto shot or doing a Melee attack.
−
| 0
+
 
 +
<span style="background:#ddffdd;">Note: in OXCE, it doesn't need to be applied only to firing accuracy, a combination of many other attributes can be used instead, see '''accuracyMultiplier''' and '''meleeMultiplier'''.</span>
 +
| 0<br/>0<br/>0<br/>0
 +
|- style="background-color:#ddffdd;"
 +
| '''accuracyPanic'''<br/>'''accuracyMindControl'''<br/>'''accuracyUse'''
 +
| The accuracy bonus (in flat percent) applied during psi attacks (Panic/MindControl/Use). '''accuracyMultiplier''' is also used in the calculations.
 +
| 20<br/>0<br/>0
 +
|- style="background-color:#ddffdd;"
 +
| '''accuracyThrow'''
 +
| The base accuracy (in percent) applied when throwing items. See also '''throwMultiplier'''.
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''accuracyCloseQuarters'''
 +
| The base accuracy (in percent) applied when checking CQC (close quarters combat) score. Overrides global setting. See also '''closeQuartersMultiplier'''.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''blockBothHands'''
 +
| Does this weapon block both hands? If true, you '''cannot''' use this weapon while holding anything in the offhand.
 +
| false
 
|-
 
|-
−
| '''power'''
+
| '''twoHanded'''
−
| Damage power of this UFO's weapon in dogfights.
+
| Is this weapon two-handed? If true, incurs an accuracy penalty if used with both hands occupied. Note that the handsprite of a twoHanded item is also drawn at a slightly different position than a one handed item.
−
| 0
+
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''oneHandedPenalty'''
 +
| Override for the global one-handed penalty (which applies only to weapons marked as '''twoHanded'''). 20% penalty would be encoded as "80" (i.e. 100 minus 20), meaning you will use the weapon at 80% of its usual accuracy.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''kneelBonus'''
 +
| Override for the global kneel bonus (which applies to all weapons). 15% bonus would be encoded as "115" (i.e. 100 + 15), meaning you will use the weapon at 115% of its usual accuracy.
 +
| -1
 
|-
 
|-
−
| '''range'''
+
| '''skillApplied'''
−
| Maximum range of this UFO's weapon in dogfights (in meters).
+
| Is melee accuracy skill applied to the accuracy of an attack made with this item? Only affects melee attacks.
−
| 0
+
 
 +
<span style="background:#ddffdd;">Note: skillApplied is deprecated in OXCE. Use '''meleeMultiplier''' instead, which is also more configurable. If both are specified, meleeMultiplier is taken.</span>
 +
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''accuracyMultiplier'''
 +
| Formulae defining the skills (i.e. various units stats) affecting the unit's accuracy when using this item in Aimed/Snap/Auto shots and in Psi attacks (Panic/MindControl/Use).
 +
 
 +
Example:
 +
 
 +
  - type: STR_EXAMPLE
 +
    accuracyMultiplier:
 +
      firing: 0.0
 +
      throwing: 0.5
 +
      melee: 0.5
 +
 
 +
In this example, the accuracy is based on 50% of unit's throwing skill and 50% of unit's melee skill... and 0% of unit's firing skill.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''meleeMultiplier'''
 +
| Same as '''accuracyMultiplier''', but used for Melee attacks (primary and secondary).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''throwMultiplier'''
 +
| Same as '''accuracyMultiplier''', but used for Throwing.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''closeQuartersMultiplier'''
 +
| Same as '''accuracyMultiplier''', but used for CQC scoring.
 +
| -
 +
|}
 +
 
 +
==== Waypoints, Shotguns, Range Limits and Accuracy/Power Dropoff  ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 
|-
 
|-
−
| '''score'''
+
| '''waypoints'''
−
| [[Score]] gained when this UFO is destroyed, or half this score if it crash lands.
+
| Gives the integer number of waypoints the weapon can use. (eg. [[Blaster Launcher]]). Can also be used to make ammo items use the waypoint system. "-1" means unlimited waypoints.
 
| 0
 
| 0
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''reload'''
+
| '''sprayWaypoints'''
−
| Time the UFO's weapon takes to fire between each shot.
+
| Waypoints for "spray shots", i.e. autoshots in multiple directions.
 +
 
 +
More info here: https://openxcom.org/forum/index.php/topic,6423.0.html
 
| 0
 
| 0
 
|-
 
|-
−
| '''breakOffTime'''
+
| '''shotgunPellets'''
−
| Minimum amount of time for the UFO to be able to break off of a dogfight.
+
| Number of projectiles fired per unit of ammunition. (note: due to engine limitations it is currently impossible to draw multiple projectiles in flight.)
 
| 0
 
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''shotgunBehavior'''<br/>'''shotgunSpread'''<br/>'''shotgunChoke'''
 +
| Attributes affecting how shotguns work.
 +
 +
More info: https://openxcom.org/forum/index.php/topic,4834.0.html
 +
| 0<br/>100<br/>100
 +
|-
 +
| '''maxRange'''
 +
| Maximum range at which this weapon can operate.
 +
| 200
 +
|-
 +
| '''aimRange'''
 +
| Maximum effective range with this weapon before which range-based dropoff occurs.
 +
| 200
 +
|-
 +
| '''snapRange'''
 +
| Maximum effective range with snap shot before which range-based dropoff occurs. (ufoextender accuracy only)
 +
| 15
 +
|-
 +
| '''autoRange'''
 +
| Maximum effective range with auto shot before which range-based dropoff occurs. (ufoextender accuracy only)
 +
| 7
 
|-
 
|-
−
| '''battlescapeTerrainData'''
+
| '''minRange'''
−
| [[#Terrains|Terrain]] associated to this UFO in Battlescape missions.
+
| Range-based dropoff will work in reverse for ranges below this.
−
| ''required''
+
| 0
 
|-
 
|-
 +
| '''dropoff'''
 +
| The value by which the accuracy lowers for each tile after (or before) the thresholds above.
 +
| 2
 +
|- style="background-color:#ddffdd;"
 +
| '''powerRangeThreshold'''
 +
| Number of tiles defining the effective range (i.e. range with no power reduction). Beyond this range power reduction is applied.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''powerRangeReduction'''
 +
| Weapon's power dropoff per tile beyond effective range.
 +
| 0
 
|}
 
|}
  
−
=== Inventory Sections ===
+
==== Compatible ammo and Action Mapping  ====
−
 
 
−
Defines one of the sections of the [[Inventory TU Table|Battlescape inventory]] (eg. Backpack), listed in ''"invs:"''.
 
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 798: Line 1,505:
 
! width="80" | Default
 
! width="80" | Default
 
|-
 
|-
−
| '''type'''
+
| '''clipSize'''
−
| String ID of the inventory name.
+
| The amount of ammo stored in each weapon clip. If -1 is specified, this weapon has infinite ammo. If specified for a HWP, clipSize determines the maximum amount of shots which can be loaded into the HWP weapon. Use clipsize -1 for melee weapons.
−
| ''required''
 
−
|-
 
−
| '''x'''
 
−
'''y'''
 
−
| Pixel coordinates of this section on the inventory screen.
 
 
| 0
 
| 0
−
0
 
 
|-
 
|-
−
| '''type'''
+
| '''compatibleAmmo'''
−
| Type of this section:
+
| List of string IDs of the ammo items that can be loaded on this weapon. If none are specified, the weapon doesn't need ammo.
−
* 0 = Slot section, can contain as many items as will fit on the slots.
 
−
* 1 = Hand section, can only contain one item regardless of size.
 
−
* 2 = Ground section, can contain infinite items.
 
−
| 0
 
−
|-
 
−
| '''slots'''
 
−
| List of the grid slots (''[x, y]'') that this section is composed of. For example, to make a 2x2 section, you would have ''[0, 0] [0, 1] [1, 0] [1, 1]''.
 
 
| -
 
| -
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''costs'''
+
| '''tuLoad'''<br/>'''tuUnload'''
−
| List of [[Time Units]] costs to move an item from this section to another one (eg. ''STR_BACKPACK: 16'' means it will cost 16 TUs to move an item from this section to the Backpack).
+
| Amount of [[Time Units]] required to load/unload this item.
−
| -
+
 
−
|-
+
'''Note''': in OXCE, when loading a weapon, you need to '''additionally''' pay the cost of moving the ammo from its current inventory slot into a hand slot! Consider that when balancing reload costs.
−
|}
+
 
 +
'''Update''': since OXCE v6.2, the OXCE behavior is now turned off by default. It can be enabled using the '''extendedItemReloadCost''' setting.
 +
| 15<br/>8
 +
|- style="background-color:#ddffdd;"
 +
| '''ammo'''
 +
| In OXCE, you can load multiple '''different''' types of ammo into one gun at the same time. This allows you to create, for example, a rifle with a built-in grenade launcher. There are up to 4 ammo slots, which can be assigned to Aimed/Snap/Auto actions. Going back to the rifle with a grenade launcher example, you could have the rifle with Aimed and Snap and sacrifice the Auto action for implementing let's say a Snap shot for the grenade launcher.
  
−
=== Terrains ===
+
Example:
  
−
Defines one of the [[TERRAIN|terrains]] used to generate a Battlescape map, listed in "terrains:".
+
  - type: STR_WEAPON_WITH_4_AMMO_SLOTS
 +
    ammo:
 +
      0:
 +
        compatibleAmmo: [ STR_AMMO_1, STR_AMMO_2 ]
 +
        tuLoad: 5
 +
        tuUnload: 2
 +
      1:
 +
        compatibleAmmo: [ STR_AMMO_3 ]
 +
        tuLoad: 10
 +
        tuUnload: 4
 +
      2:
 +
        compatibleAmmo: [ STR_AMMO_4, STR_AMMO_5 ]
 +
        tuLoad: 10
 +
        tuUnload: 4
 +
      3:
 +
        compatibleAmmo: [ STR_GRENADE_AMMO ]
 +
        tuLoad: 20
 +
        tuUnload: 8
  
−
{| class="wikitable" width="100%"
+
| -
−
! width="150"| Value
 
−
! width="*"  | Description
 
−
! width="80" | Default
 
 
|-
 
|-
−
| '''name'''
+
| '''autoShots'''
−
| String ID of the terrain name.
+
| How many auto shots does this weapon fire.
−
| ''required''
+
| 3
 
|-
 
|-
−
| '''mapDataSets'''
+
| '''arcingShot'''
−
| List of filenames (each with matching [[MCD]]/[[Image Formats#PCK|PCK/TAB]] files) that contain the tiles of this terrain.
+
| Does this weapon fire in an arc?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''confAimed'''<br/>'''confSnap'''<br/>'''confAuto'''<br/>'''confMelee'''
 +
| A mapping between actions and ammo slots (see above).
 +
 
 +
Example:
 +
 
 +
  - type: STR_RIFLE_WITH_A_GRENADE_LAUNCHER
 +
    confAimed:
 +
      shots: 1
 +
      followProjectiles: true    # default
 +
      name: STR_AIMED_SHOT
 +
      ammoSlot: 0
 +
      arcing: false
 +
    confSnap:
 +
      shots: 2
 +
      followProjectiles: false  # the camera stays still while shooting (prevents minigun seizures)
 +
      name: STR_DOUBLE_SNAP_SHOT
 +
      ammoSlot: 0
 +
      arcing: false
 +
    confAuto:
 +
      shots: 1
 +
      name: STR_LAUNCH_GRENADE
 +
      ammoSlot: 3
 +
      arcing: true
 +
    confMelee:
 +
      name: STR_PUNCH_IN_THE_FACE
 +
 
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''psiAttackName'''
 +
| Besides panic attack and mind control, weapons of psi-amp type can have also a third type of attack, bound to "use" attributes (for example '''costUse'''). This attribute defines what should be the name of such attack in the action menu (e.g. Seduce, VooDoo spell, etc.).
 
| -
 
| -
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''mapBlocks'''
+
| '''primeActionName'''
−
| List of map blocks (see below) that are used for generating a map.
+
| Name of the prime action in the action menu. Default is STR_PRIME_GRENADE.
 +
 
 +
Tip: in OXCE more item battleTypes can be primed than in OpenXcom, for example also battleType 10 (Electro-flares).
 +
| <=
 +
|- style="background-color:#ddffdd;"
 +
| '''primeActionMessage'''
 +
| Message for the player informing about the priming of an item. Default is STR_GRENADE_IS_ACTIVATED.
 +
| <=
 +
|- style="background-color:#ddffdd;"
 +
| '''unprimeActionName'''
 +
| Name of the un-prime action in the action menu.
 
| -
 
| -
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''civilianTypes'''
+
| '''unprimeActionMessage'''
−
| List of units to use as civilians for this mission.
+
| Message for the player informing about the un-priming of an item. Default is STR_GRENADE_IS_DEACTIVATED.
−
| [MALE_CIVILIAN, FEMALE_CIVILIAN]
+
| <=
−
|-
 
 
|}
 
|}
  
−
==== Map Blocks ====
+
==== Cost of use  ====
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 859: Line 1,613:
 
! width="80" | Default
 
! width="80" | Default
 
|-
 
|-
−
| '''name'''
+
| '''tuAimed'''<br/>'''tuSnap'''<br/>'''tuAuto'''<br/>'''tuMelee'''
−
| Filename of the [[MAPS|map]].
+
| The percentage (0-100%) of [[Time Units]] (from the soldier's total) required to fire an Aimed/Snap/Auto Shot or doing a Melee attack. If 0, the weapon does not have the corresponding attack.
−
| ''required''
+
| 0<br/>0<br/>0<br/>0
 
|-
 
|-
−
| '''width'''
+
| '''tuUse'''
−
| Width of this map block in Battlescape grid units.
+
| Amount of [[Time Units]] required to use this item (for non-offensive items). It's a flat rate if '''flatRate''' is true, otherwise it's a percentage (0-100%).
 
| 0
 
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''tuMindControl'''<br/>'''tuPanic'''
 +
| Amount of [[Time Units]] required to use this item. If not specified, defaults to '''tuUse'''.
 +
| -1<br/>-1
 +
|- style="background-color:#ddffdd;"
 +
| '''tuThrow'''<br/>'''tuPrime'''<br/>'''tuUnprime'''
 +
| Amount of [[Time Units]] required to throw/prime/unprime this item.
 +
| 25<br/>50<br/>25
 +
|- style="background-color:#ddffdd;"
 +
| '''costAimed'''<br/>'''costSnap'''<br/>'''costAuto'''<br/>'''costMelee'''<br/>'''costUse'''<br/>'''costMindControl'''<br/>'''costPanic'''<br/>'''costThrow'''<br/>'''costPrime'''<br/>'''costUnprime'''
 +
| Extended way of defining the cost of item use. Instead of spending only time units, you can also define to spend energy, morale, HP, mana and stun. All costXXX settings override tuXXX settings, for example costAimed overrides tuAimed, etc.
 +
 +
Example:
 +
 +
  - type: STR_FUNNY_WEAPON
 +
    costAimed:
 +
      time: 90
 +
      energy: 20
 +
      morale: 65
 +
      mana: 5
 +
 +
| -
 
|-
 
|-
−
| '''length'''
+
| '''flatRate'''
−
| Length of this map block in Battlescape grid units.
+
| If true, then TU costs for this weapon are a flat rate (instead of a percentage of unit TUs).
−
| 0
+
| false
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''height'''
+
| '''flatAimed'''<br/>'''flatSnap'''<br/>'''flatAuto'''<br/>'''flatMelee'''<br/>'''flatUse'''<br/>'''flatThrow'''<br/>'''flatPrime'''<br/>'''flatUnprime'''
−
| Height of this map block in Battlescape grid units.
+
| Extended way of defining if the cost of item use is flat or in percentage. You can now define it for various actions separately. If defined, the more specific setting (e.g. flatAimed) overrides the less specific setting (flatRate).
−
| 1
 
−
|-
 
−
| '''groups'''
 
−
| List (or single number) of groups this mapblock belongs to (used in mapscripts)
 
−
default usage:
 
−
* 0 - Default
 
−
* 1 - Landing Zone (for placing X-COM / alien craft) (used in addcraft/ufo command)
 
−
* 2 - E-W Road (for city maps) (used in addline command)
 
−
* 3 - N-S Road (for city maps) (used in addline command)
 
−
* 4 - Road Crossing (for city maps) (used in addline command)
 
−
| 0
 
−
|-
 
−
|'''revealedFloors'''
 
−
| Map block floor to be revealed from the very beginning; use a list "[0, 1, ..]" to reveal multiple floors
 
−
|-
 
−
| '''items'''
 
−
| An array of items to add to this mapblock, an the positions to place them at.
 
−
| -1
 
−
|}
 
  
−
* '''hemisphere''' only applies to UFO missions, not Terror ones.
+
Example:
−
*'''width/length''' defines the size of the map
 
−
** be aware that the mapview "width"-label is the openxcom ruleset length parameter
 
−
** be aware that the mapview "length"-label is the openxcom ruleset width parameter
 
  
−
==== Guidelines/Tips ====
+
  - type: STR_FUNNY_WEAPON
−
* All maps with an XCOM/Alien craft require at least one map block assigned to Group 1. This map block can only contain ground tiles (no walls or objects), otherwise the game will crash or the walls/objects will be removed.
+
    costAimed:
−
* All Terror terrains (listed under STR_TERROR_MISSION) require the Groups of '''Types''' 2, 3 and 4 (for a total of 3 maps, which are required to place roads).
+
      time: 90
 +
      energy: 20
 +
      mana: 5
 +
    flatAimed:
 +
      time: false  # 90% of TU
 +
      energy: true  # 20 energy (flat)
 +
      mana: true    # 5 mana (flat)
  
−
=== Map Scripts ===
+
| -
 +
|}
 +
 
 +
==== Debriefing/Recovery  ====
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 908: Line 1,671:
 
! width="*"  | Description
 
! width="*"  | Description
 
! width="80" | Default
 
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''experienceTrainingMode'''
 +
| Defines which skill(s) should improve when the soldiers gain experience by hitting enemy units (or healing fatal wounds of any units).
 +
 +
More info: https://openxcom.org/forum/index.php/topic,4230.0.html
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''manaExperience'''
 +
| How much mana experience points does the weapon provide.
 +
 +
  manaExperience: 250    # this means 2 points + 50% chance for a 3rd point (on every hit on hostile unit)
 +
| 0
 
|-
 
|-
−
| '''type'''
+
| '''recover'''
−
| name of the script
+
| Is this item recoverable? (gets transported to the X-COM base on mission success)
−
| ''required''
+
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''recoverCorpse'''
 +
| Since the '''recover''' flag applies to both live body (prisoner capture) and dead body (corpse recovery) in OpenXcom, OXCE adds this new flag to allow recovery of a live body, but disable recovery of the corpse (used in mods mostly to ignore dead bodies of killed humans).
 +
| true
 +
|-
 +
| '''recoveryPoints'''
 +
| [[Score]] gained for recovering this alien artifact.
 +
| 0
 +
|-
 +
| '''liveAlien'''
 +
| Does this item represent a live alien? (counts towards [[Alien Containment]])
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''prisonType'''
 +
| What type of prison (alien containment) facility can accommodate a unit (marked as '''liveAlien''') represented by this item.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,4830.msg69933.html#msg69933
 +
| 0
 
|-
 
|-
−
| '''commands'''
+
| '''specialType'''
−
| List of MapCommands
+
| MCD value in map files to which this item corresponds for mission recovery.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''recoveryDividers'''
 +
| Definition how special items (with '''specialType''' > 1) should be recovered from the mission.
 +
 
 +
More info here: https://openxcom.org/forum/index.php/topic,6616.0.html
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''recoveryTransformations'''
 +
| Allows recovering items as other items (for example alien weapons as alien weapon fragments).
 +
 
 +
More info here: https://openxcom.org/forum/index.php/topic,6868.0.html
 
| -
 
| -
 
|}
 
|}
  
−
==== Map Command ====
+
==== Medikits  ====
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 924: Line 1,729:
 
! width="*"  | Description
 
! width="*"  | Description
 
! width="80" | Default
 
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''medikitActionName'''
 +
| Name of the use action in the action menu. Default is STR_USE_MEDI_KIT.
 +
| <=
 +
|- style="background-color:#ddffdd;"
 +
| '''medikitType'''
 +
| Defines, which functions can this medikit perform. Possible options:
 +
* 0 = All functions
 +
* 1 = Heal only
 +
* 2 = Stimulant only
 +
* 3 = Painkiller only
 +
| 0
 +
|- style="background-color:#ddffdd; color:#666666;"
 +
| '''allowSelfHeal'''
 +
| Deprecated. Use '''medikitTargetSelf''' instead.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''medikitTargetSelf'''
 +
| Is it possible to use the medikit on oneself (true)? Or only on other units (false)? Ignores other settings.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''medikitTargetImmune'''
 +
| Is it possible to use the medikit on units that cannot bleed (true)? Or only on other units (false)?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''medikitTargetMatrix'''
 +
| Says what targets are allowed for a medikit item. It is a composite attribute (a bit map), individual parts:
 +
* 1 = friendly on the ground
 +
* 2 = friendly standing
 +
* 4 = neutral on the ground
 +
* 8 = neutral standing
 +
* 16 = hostile on the ground
 +
* 32 = hostile standing
 +
 +
So, for example:
 +
* 0 = cannot use on anyone
 +
* 3 (1+2) = can use only on friendlies
 +
* 31 (1+2+4+8+16) =  can use on everyone except on standing hostiles/enemies
 +
* 63 = can use on everyone
 +
* etc.
 +
| 63
 +
|- style="background-color:#ddffdd;"
 +
| '''isConsumable'''
 +
| Will this medikit be automatically refilled at the base (false)? Or will it disappear after the mission, if used at least once (true)?
 +
 +
Note: If you use multiple medikits, they will use the same "combination" algorithm as the guns use for bullet recovery in OpenXcom. Using two medikits let's say just once will not make both of them disappear, because there will be enough "stuff" left to fully recover one of them.
 +
| false
 
|-
 
|-
−
| '''type'''
+
| '''painKiller'''
−
| Currently these commands are implemented:
+
| Amount of painkillers contained in a [[Medi-Kit (EU)|Medi-Kit]].
−
* addBlock
 
−
* addLine
 
−
* addCraft
 
−
* addUFO
 
−
* digTunnel
 
−
* fillArea
 
−
* checkBlock
 
−
* removeBlock
 
−
* resize
 
−
depending on the command type some of the following parameters are needed
 
−
| ''required''
 
−
|-
 
−
| '''label'''
 
−
| A numeric label that can be used for conditional execution of commands.
 
−
Each label should be unique within the command list (0=default no need for uniqueness).
 
 
| 0
 
| 0
 
|-
 
|-
−
| '''conditionals'''
+
| '''heal'''
−
| Defines the conditions that allows the execution of this command.
+
| Amount of heals contained in a [[Medi-Kit (EU)|Medi-Kit]].
−
eg. [1, -4] means it will be executed if command with label 1 was a success and command with label 4 failed.
 
−
commands that are not yet executed are always in failed state.
 
 
| 0
 
| 0
 
|-
 
|-
−
| '''executionChances'''
+
| '''stimulant'''
−
| the chance that this command will be executed (or fails)
+
| Amount of stimulants contained in a [[Medi-Kit (EU)|Medi-Kit]].
−
| 100
+
| 0
 
|-
 
|-
−
| '''executions'''
+
| '''woundRecovery'''
−
| this command will be executed multiple times with a value > 1
+
| Amount of [[Fatal Wounds]] treated by each heal of a [[Medi-Kit (EU)|Medi-Kit]].
−
| 1
+
| 0
 
|-
 
|-
−
| '''groups'''
+
| '''healthRecovery'''
−
| Defines the what mapblock are used within this command. Can be list of goups or a single number.
+
| Amount of [[Health]] recovered by each heal of a [[Medi-Kit (EU)|Medi-Kit]].
 
| 0
 
| 0
 
|-
 
|-
−
| '''blocks'''
+
| '''stunRecovery'''
−
| Alternative to groups. Here we define a list of mapblocks that are used within this command.
+
| Amount of [[Stun]] removed by each stimulant of a [[Medi-Kit (EU)|Medi-Kit]].
 
| 0
 
| 0
 
|-
 
|-
−
| '''rects'''
+
| '''energyRecovery'''
−
| A list of possible ranges where (random) placement/checks/removal can happen in a map.
+
| Amount of [[Energy]] recovered by each stimulant of a [[Medi-Kit (EU)|Medi-Kit]].
−
Is a list of a list of four integers.
+
| 0
−
| ?
+
|- style="background-color:#ddffdd;"
−
|-
+
| '''manaRecovery'''
−
| '''size'''
+
| Amount of Mana recovered by each stimulant of a [[Medi-Kit (EU)|Medi-Kit]].
−
| size of mapblocks that can be placed/checked/removed within rects. Also used for resize command type.
+
| 0
−
| ?
+
|- style="background-color:#ddffdd;"
−
|-
+
| '''painKillerRecovery'''
−
| '''freqs'''
+
| Strength of the pain killers (1.0 = 100%). Linear factor affecting vanilla morale recovery (based on lost health).
−
| For a list of mapblocks (defined by blocks?) we can define distribution frequency here.
+
| 1.0
−
| 1
+
|- style="background-color:#ddffdd;"
−
|-
+
| '''moraleRecovery'''
−
| '''maxUses'''
+
| Additional points of morale to restore when pain killers are used. Does not depend on lost health (or anything else).
−
| For a list of mapblocks (defined by blocks?) we can define the maximal amount a mapblock can be used here.
 
−
| -1
 
−
|-
 
−
| '''direction'''
 
−
| used for addLine command type. Values are both, horizontal or vertical. Typically defines the road type distribution.
 
−
| -1
 
−
|-
 
−
| '''tunnelData'''
 
−
| Parameter for digTunnel command type. Contains level (default: 0) and a list of MCD replacement rules (MCDReplacements)
 
 
| 0
 
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''medikitBackground'''
 +
| Sprite ID of the medikit background.
 +
 +
Tip: size and position of buttons can also be adjusted using Interface ruleset (but only globally for all medikit items).
 +
| -
 
|}
 
|}
  
−
==== Guidelines/Tips ====
+
==== Inventory  ====
−
* The Mapscript is still somewhat in development
 
−
 
 
−
 
 
−
 
 
−
 
 
−
=== Armor ===
 
−
 
 
−
Defines a Battlescape unit's [[armor]] as well as visual representation (so every unit has an armor), listed in ''"armors:"''.
 
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 1,007: Line 1,831:
 
! width="80" | Default
 
! width="80" | Default
 
|-
 
|-
−
| '''type'''
+
| '''weight'''
−
| String ID of the armor name.
+
| [[Item_Weight|Weight]] occupied by this item in a soldier's inventory.
−
| ''required''
+
| 3
 
|-
 
|-
−
| '''spriteSheet'''
+
| '''invWidth'''
−
| Sprite sheet from [[UNITS]] used to draw a unit wearing this armor.
+
| Item width in a soldier's inventory (in grid units).
−
| -
+
| 1
 
|-
 
|-
−
| '''spriteInv'''
+
| '''invHeight'''
−
| Sprite used for the [[Inventory Backgrounds]] of a unit wearing this armor.
+
| Item height in a soldier's inventory (in grid units).
−
| -
+
| 1
 
|-
 
|-
−
| '''spriteFaceGroup'''
+
| '''fixedWeapon'''
−
| Pixel color group in [[PALETTES.DAT#Color Indexes|palette]] that will be replace in unit graphic by new color, range form 1-15 (its skip first group). Used by face recoloring based on nationality.
+
| Is this weapon fixed (cannot be dropped from the Inventory)? (it's part of a unit, e.g. tanks and terrorist units)
−
| ''example:'' <br> 6
+
| false
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''spriteFaceColor'''
+
| '''fixedWeaponShow'''
−
| New colors index for face pixels. 8 values ordered by:
+
| Should the fixed weapon be drawn on the unit in the Battlescape or not? Normally, the weapon is not drawn (for example Reaper or Cyberdisc weapon... because it's a part of the unit itself), but in mods you may have for example fixed weapons on certain armors, which you want to display as normal "carried" weapons.
−
* Male Blond
+
| false
−
* Female Blond
+
|- style="background-color:#ddffdd;"
−
* Male Brown
+
| '''defaultInventorySlot'''
−
* Female Brown
+
| An inventory slot where a '''fixedWeapon''' should be placed when it is created.
−
* Male Asian
 
−
* Female Asian
 
−
* Male African
 
−
* Female African
 
−
Other units use random position form table.
 
−
Value 0 mean original value.
 
−
| ''example:''
 
−
  - 96
 
−
  - 96
 
−
  - 96
 
−
  - 96
 
−
  - 160
 
−
  - 160
 
−
  - 163
 
−
  - 163
 
−
|-
 
−
| '''spriteHairGroup'''
 
−
| Pixel color group in [[PALETTES.DAT#Color Indexes|palette]] that will be replace in unit graphic by new color, range form 1-15 (its skip first group). Used by hair recoloring based on nationality.
 
−
| ''example:'' <br> 9
 
−
|-
 
−
| '''spriteHairColor'''
 
−
| New colors index for hair pixels. 8 values ordered by:
 
−
* Male Blond
 
−
* Female Blond
 
−
* Male Brown
 
−
* Female Brown
 
−
* Male Asian
 
−
* Female Asian
 
−
* Male African
 
−
* Female African
 
−
Other units use random position form table.
 
−
Value 0 mean original value.
 
−
| ''example:''
 
−
  - 144
 
−
  - 144
 
−
  - 164
 
−
  - 164
 
−
  - 245
 
−
  - 245
 
−
  - 166
 
−
  - 166
 
−
|-
 
−
| '''spriteUtileGroup'''
 
−
| Pixel color group in [[PALETTES.DAT#Color Indexes|palette]] that will be replace in unit graphic by new color, range form 1-15 (its skip first group).
 
 
| -
 
| -
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''spriteUtileColor'''
+
| '''defaultInvSlotX'''
−
| New colors index for pixels. 8 values ordered by:
+
| A position within the inventory slot where a '''fixedWeapon''' should be placed when it is created.
−
* Male Blond
+
| 0
−
* Female Blond
+
|- style="background-color:#ddffdd;"
−
* Male Brown
+
| '''defaultInvSlotY'''
−
* Female Brown
+
| A position within the inventory slot where a '''fixedWeapon''' should be placed when it is created.
−
* Male Asian
+
| 0
−
* Female Asian
+
|- style="background-color:#ddffdd;"
−
* Male African
+
| '''supportedInventorySections'''
−
* Female African
+
| A list of inventory slots, where this item can be (manually) placed. If empty, all slots are OK.
−
Other units use random position form table.
 
−
Value 0 mean original value.
 
 
| -
 
| -
 
|-
 
|-
−
| '''spriteRankGroup'''
+
| '''ignoreInBaseDefense'''
−
| Pixel color group in [[PALETTES.DAT#Color Indexes|palette]] that will be replace in unit graphic by new color, range form 1-15 (its skip first group).
+
| Items marked with this flag will not appear in the Base Defense mission.
−
| -
+
 
−
|-
+
Note: mods, which have items used mostly in Geoscape (e.g. random resources used for manufacturing), but still recoverable from Battlescape should use this flag so that the ground inventory is not spammed by useless junk slowing the game down (significantly! if there are thousands of such items).
−
| '''spriteRankColor'''
+
| false
−
| New colors index for pixels. For solders 6 values ordered by:
+
|- style="background-color:#ddffdd;"
−
* STR_ROOKIE
+
| '''ignoreInCraftEquip'''
−
* STR_SQUADDIE
+
| Items marked with this flag will not appear in Craft Inventory Equipment screen.
−
* STR_SERGEANT
+
Defaults:
−
* STR_CAPTAIN
+
* true for corpses (battleType=11) and geoscape-only items (battleType=0)
−
* STR_COLONEL
+
* false for all other items
−
* STR_COMMANDER
+
| <=
−
For aliens 7 values ordered by (alien unit rank property):
+
|- style="background-color:#ddffdd;"
−
* STR_LIVE_SOLDIER
+
| '''specialUseEmptyHand'''
−
* STR_LIVE_ENGINEER
+
| Whether this '''specialWeapon''' is used when clicking on the empty hand slot in soldier's inventory. Used for punching/kicking with bare hands :)
−
* STR_LIVE_MEDIC
+
| false
−
* STR_LIVE_NAVIGATOR
+
|}
−
* STR_LIVE_LEADER
+
 
−
* STR_LIVE_COMMANDER
+
==== Things that go BOOM  ====
−
* STR_LIVE_TERRORIST
+
 
−
Civilians uses random position form 8 element table.
+
{| class="wikitable" width="100%"
−
Value 0 mean original value.
+
! width="150"| Value
−
| -
+
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''fuseType'''
 +
| Defines how item priming works.
 +
 
 +
Possible options:
 +
* -3 No priming. Flares always glow if '''defaultBehavior''' is true.
 +
* -2 Can be primed (without timer). Proxies work normally. Grenades explode instantly after throwing. Flares glow only after priming.
 +
* -1 Can be primed (for manually specified amount of turns). Grenades explode after set time. Proxies and flares disappear after set time.
 +
* 0-23 Can be primed (for fixed amount of turns).
 +
 
 +
Defaults:
 +
* -2 for proximity grenades
 +
* -1 for grenades
 +
* -3 for everything else
 +
| <=
 +
|- style="background-color:#ddffdd;"
 +
| '''fuseTriggerEvents'''
 +
| Defines how fuse triggers work. Contains 5 sub-attributes:
 +
 
 +
* '''defaultBehavior''': everything works as in vanilla
 +
* '''throwTrigger''': timer starts only after throwing
 +
* '''throwExplode''': items explode (grenades) or are removed (other) on throw; affected by '''specialChance'''
 +
* '''proximityTrigger''': timer starts only after moving into item's proximity
 +
* '''proximityExplode''': item explode (grenades, proxies) or are removed (other) after moving into item's proximity; affected by '''specialChance'''
 +
 
 +
Example/Defaults:
 +
 
 +
  fuseTriggerEvents:
 +
    defaultBehavior: true
 +
    throwTrigger: false
 +
    throwExplode: false
 +
    proximityTrigger: false
 +
    proximityExplode: false
 +
 
 +
| <=
 +
|- style="background-color:#ddffdd;"
 +
| '''specialChance'''
 +
| The chance (0-100%) of special effects happening, including:
 +
* mine triggering (see above)
 +
* corpse explosion (e.g. of a bio-drone corpse)
 +
* zombification (e.g. by a chryssalid weapon)
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''isExplodingInHands'''
 +
| Does the item explode also when still in a unit's inventory?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''hiddenOnMinimap'''
 +
| Is the item visible on the minimap?
 +
 
 +
Tip: use for example for mines hidden underground
 +
| false
 +
|}
 +
 
 +
==== Miscellaneous  ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''isFireExtinguisher'''
 +
| Can this item be used to extinguish fire on units?
 +
| false
 
|-
 
|-
−
| '''corpseBattle'''
+
| '''armor'''
−
| List of string IDs of the corpse [[#Items|items]] generated when a unit wearing this armor is killed (one per unit tile) on the Battlescape.
+
| How much damage is needed to destroy this item on the ground.
−
| -
+
| 20
 
|-
 
|-
−
| '''corpseGeo'''
+
| '''attraction'''
−
| String ID of the corpse [[#Items|item]] associated with this unit on the Geoscape.
+
| Represents how likely an alien is to pick up this item. Values below 5 will be ignored (by design).
−
| -
+
| 0
 
|-
 
|-
−
| '''storeItem'''
+
| '''LOSRequired'''
−
| String ID of the [[#Items|item]] that represents this armor in [[Base Stores]] for equipping.
+
| Does this item require line of sight? (only applies to mind probes and psi-amps)
−
| -
+
| false
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''weight'''
+
| '''psiRequired'''
−
| Physical weight of the armor when worn
+
| Does using this item require psi skill > 0 ? Items of battleType=9 (psi-amps) have this flag set to ''true'' by default.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''psiTargetMatrix'''
 +
| Says what targets are allowed for a psiamp item. It is a composite attribute (a bit map), individual parts:
 +
* 1 = friendly
 +
* 2 = hostile
 +
* 4 = neutral
 +
 
 +
So, for example:
 +
* 0 = cannot use on anyone
 +
* 1 = can use only on friendlies
 +
* 6 (2+4) = can use only on hostiles and neutrals
 +
* etc.
 +
 
 +
Note: Mind-controlling friendlies is never possible, hardcoded. Panicking friendlies is possible.
 
| 6
 
| 6
 +
|- style="background-color:#ddffdd;"
 +
| '''manaRequired'''
 +
| Does using this item require mana research unlocked?
 +
| false
 
|-
 
|-
−
| '''stats'''
+
| '''underwaterOnly'''
−
| like soldier stats (see below) but these are treated as stat bonuses for wearing the specific armor.
+
| Can this item only be used underwater?
−
| -
+
| false
 
|-
 
|-
−
| '''frontArmor'''
+
| '''landOnly'''
−
| Protection provided on the front of the unit.
+
| Can this item only be used on land?
−
| 0
+
| false
 
|-
 
|-
−
| '''sideArmor'''
+
| '''zombieUnit'''
−
| Protection provided on the sides of the unit.
+
| String ID of the unit used for zombification (eg. [[Chrysallid]]s turn units into [[Zombie]]s).
−
| 0
+
| -
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''rearArmor'''
+
| '''zombieUnitByArmorMale'''
−
| Protection provided on the rear of the unit.
+
| Overrides '''zombieUnit'''. Based on armor worn by the victim. A list of String ID pairs.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''zombieUnitByArmorFemale'''
 +
| Overrides '''zombieUnit'''. Based on armor worn by the victim. A list of String ID pairs.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''zombieUnitByType'''
 +
| Overrides '''zombieUnit'''. Based on the victim soldier/unit type. A list of String ID pairs.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''spawnUnit'''<br/>'''spawnUnitFaction'''
 +
| Used for spawning units from items.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,6535.0.html
 +
| -<br/>-1
 +
|- style="background-color:#ddffdd;"
 +
| '''ai.useDelay'''<br/>'''ai.meleeHitCount'''
 +
| 1/ Used to override AI delay defined by global settings.
 +
 
 +
2/ How many times should an AI unit try to perform a melee attack (in the single go)? In vanilla, the unit used the melee attack until the target was neutralized or until it ran out of TUs. This attribute gives you the option to perform "hit and run".
 +
 
 +
  ai:
 +
    useDelay: 1
 +
    meleeHitCount: 15
 +
 
 +
| -1<br/>25
 +
|}
 +
 
 +
=== Item Categories ===
 +
 
 +
<span style="background:#ddffdd;">Defines some extra behavior (and list order) of item categories, listed in ''"itemCategories:"''.</span>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''type'''
 +
| String ID of the item category name.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''hidden'''
 +
| Defines whether this category should be hidden in the filter on the [Craft Equipment] screen.
 +
 
 +
Note: categories not shown to the player are still useful for the modder sometimes.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''replaceBy'''
 +
| Defines mapping between item categories.
 +
 
 +
Note: this is useful when you are still experimenting with the item categorization. If you defined too many categories for example, you can group them together easily here, instead of having to redefine all the items. And if you change your mind later, you can easily ungroup them again.
 +
| -
 +
|}
 +
 
 +
=== Item Damage Types ===
 +
 
 +
<span style="background:#ddffdd;">These are the sub-attributes you can use within attributes '''damageAlter''' and '''meleeAlter'''. Listed separately for convenience.</span>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''FixRadius'''
 +
| A blast radius.
 +
* -1 = dynamic blast radius
 +
* 0 = no blast radius
 +
* 1+ = fixed blast radius
 
| 0
 
| 0
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''underArmor'''
+
| '''RandomType'''
−
| Protection provided under the unit (eg. from explosions).
+
| Defines how will be dice be rolled to determine damage based on power (primary damage calculation). Possible options:
−
| 0
+
* 0 = default vanilla behavior dependent on damageType
−
|-
+
* 1 = 0-200% spread
−
| '''drawingRoutine'''
+
* 2 = 50-150% spread
−
| Drawing routine used to put together the body parts in the unit's '''spriteSheet''':
+
* 3 = flat damage equal to power
−
* 0 = [[Soldier]], [[Sectoid]]
+
* 4 = random damage in range defined by '''fireDamageRange'''
−
* 1 = [[Floater]]
+
* 5 = no damage
−
* 2 = [[HWP]]
+
* 6 = 0-200% spread (2 dice roll), i.e. 0-100% + 0-100%
−
* 3 = [[Cyberdisk]]
+
* 7 = 50-200% spread
−
* 4 = [[Civilian]], [[Ethereal]]
+
| 0
−
* 5 = [[Sectopod]], [[Reaper]]
+
|- style="background-color:#ddffdd;"
−
* 6 = [[Snakeman]]
+
| '''ResistType'''
−
* 7 = [[Chryssalid]]
+
| A damage type, i.e. what resistance of the target unit's armor is applied. Same values like '''damageType'''.
−
* 8 = [[Silacoid]]
 
−
* 9 = [[Celatid]]
 
−
* 10 = [[Muton]]
 
−
* 11 = [[Submersible Weapons Systems]]
 
−
* 12 = [[Hallucinoid]]
 
−
* 13 = [[Aquanauts]]
 
−
* 14 = [[Calcinite]], [[Deep One]], [[Gillman]], [[Lobster Man]], [[Tasoth]]
 
−
* 15 = [[Aquatoid]]
 
−
* 16 = [[Bio-Drone]]
 
−
* 17 = TFTD Civilians type A and [[Zombie_(TFTD)]]
 
−
* 18 = TFTD Civilians type B
 
−
* 19 = [[Tentaculat]]
 
−
* 20 = [[Triscene]]
 
−
* 21 = [[Xarquid]]
 
 
| 0
 
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''FireBlastCalc'''
 +
| Vanilla fire/incendiary blast radius has a special formula. This option turns it on/off.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''IgnoreDirection'''
 +
| Should the damage calculation ignore from which direction the projectile came? Used for example for smoke or fire.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''IgnoreSelfDestruct'''
 +
| Killing using this damage prevents self-destruct (e.g. of Cyberdisc). Used for example on HE, Stun or Melee damage.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''IgnorePainImmunity'''
 +
| Some units are immune to pain/stun (see '''painImmune''' on Armor). This allows you to ignore such immunity. Used for example on Stun damage.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''IgnoreNormalMoraleLose'''
 +
| When units are hit, they lose morale. This option allows you to turn this effect on/off.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''IgnoreOverKill'''
 +
| Disables overkill damage, i.e. units won't get vaporized/disintegrated when killed (by a hit doing a lot more damage than necessary to kill).
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''ArmorEffectiveness'''
 +
| How effective is a unit's front/side/rear/bottom armor against this damage. 1.0 is 100%.
 +
| 1.0
 +
|- style="background-color:#ddffdd;"
 +
| '''RadiusEffectiveness'''
 +
| If FixRadius = -1, the blast radius is not fixed, but dynamically calculated from Power (incl. Power bonus). This is a factor for such calculation.
 +
| 0.0
 +
|- style="background-color:#ddffdd;"
 +
| '''RadiusReduction'''
 +
| How much explosion Power decreases with distance from the center.
 +
| 10.0
 +
|- style="background-color:#ddffdd;"
 +
| '''FireThreshold'''
 +
| How much damage is needed to set a unit or a tile on fire.
 +
| 1000
 +
|- style="background-color:#ddffdd;"
 +
| '''SmokeThreshold'''
 +
| How much damage is needed to create smoke on a tile.
 +
| 1000
 +
|- style="background-color:#ddffdd;"
 +
| '''ToArmorPre'''
 +
| How much of the primary damage (Power x RandomType) is applied to the unit's armor ''before'' armor is considered.
 +
| 0.0
 +
|- style="background-color:#ddffdd;"
 +
| '''RandomArmorPre'''
 +
| Should the calculation above be randomized?
 +
 +
Example 1: Power = 100. Primary damage rolled = for example 140. ToArmorPre = 0.1. RandomArmorPre = '''false'''. Damage applied to a unit's armor will be 14.
 +
 +
Example 2: Power = 100. Primary damage rolled = for example 140. ToArmorPre = 0.1. RandomArmorPre = '''true'''. Damage applied to a unit's armor will be a random value between 0 and 14.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''ToArmor'''
 +
| How much of the primary damage is applied to the unit's armor ''after'' armor is considered.
 +
| 0.1
 +
|- style="background-color:#ddffdd;"
 +
| '''RandomArmor'''
 +
| Should the calculation above be randomized?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''ToHealth'''
 +
| How much of the primary damage is applied to the unit's health.
 +
| 1.0
 +
|- style="background-color:#ddffdd;"
 +
| '''RandomHealth'''
 +
| Should the calculation above be randomized?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''ToStun'''
 +
| How much of the primary damage is applied to the unit's stun level.
 +
| 0.25
 +
|- style="background-color:#ddffdd;"
 +
| '''RandomStun'''
 +
| Should the calculation above be randomized?
 +
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''ToWound'''<br/>'''RandomWound'''
 +
| Determines how many fatal wounds should be inflicted. Default settings equal to vanilla calculations. Formula is quite hard to describe in words, so here's the code:
 +
 +
  if (damage > 0) {
 +
    if (RandomWound) {
 +
      if (RNG::generate(0, 10) < int(damage * ToWound)) {
 +
        return RNG::generate(1,3);
 +
      }
 +
    } else {
 +
      return (int)std::round(damage * ToWound);
 +
    }
 +
  }
 +
 +
| 1.0<br/>true
 +
|- style="background-color:#ddffdd;"
 +
| '''ToTime'''
 +
| How much of the primary damage is applied to the unit's TUs.
 +
| 0.0
 +
|- style="background-color:#ddffdd;"
 +
| '''RandomTime'''
 +
| Should the calculation above be randomized?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''ToEnergy'''
 +
| How much of the primary damage is applied to the unit's energy.
 +
| 0.0
 +
|- style="background-color:#ddffdd;"
 +
| '''RandomEnergy'''
 +
| Should the calculation above be randomized?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''ToMana'''
 +
| How much of the primary damage is applied to the unit's mana burn.
 +
| 0.0
 +
|- style="background-color:#ddffdd;"
 +
| '''RandomMana'''
 +
| Should the calculation above be randomized?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''ToMorale'''
 +
| How much of the primary damage is applied to the unit's morale.
 +
| 0.0
 +
|- style="background-color:#ddffdd;"
 +
| '''RandomMorale'''
 +
| Should the calculation above be randomized?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''ToItem'''
 +
| How much of the primary damage is applied to items.
 +
| 0.0
 +
|- style="background-color:#ddffdd;"
 +
| '''RandomItem'''
 +
| Should the calculation above be randomized?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''ToTile'''
 +
| How much of the primary damage is applied to the terrain.
 +
| 0.5
 +
|- style="background-color:#ddffdd;"
 +
| '''RandomTile'''
 +
| Should the calculation above be randomized?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''TileDamageMethod'''
 +
|  Which tile damage method should be used?
 +
* For AOE (area-of-effect) weapons:
 +
** TileDamageMethod==1: (50%-150% * power * ToTile)
 +
** TileDamageMethod==2: ((power x RandomTile) * ToTile), which defaults to vanilla 50% damage for HE and 0% for stun, smoke and incendiary
 +
* For non-AOE (projectile) weapons:
 +
** TileDamageMethod==1: (50%-150% * power * ToTile), which defaults to vanilla 25%-75% damage for AP/laser/plasma/etc.
 +
** TileDamageMethod==2: ((damage x RandomTile) * ToTile)
 +
| 1
 +
|}
 +
 +
<div style="background:#ddffdd;">'''IMPORTANT''': The defaults above are the generic defaults. For each damage type, there are also specific defaults that emulate the vanilla hardcoded damage types. For modding purposes, the specific defaults are relevant (they override the generic ones). Below is the summary of the specific defaults.</div>
 +
 +
{| class="wikitable" width="100%"
 +
!  !! DT_NONE !! DT_AP !! DT_IN !! DT_HE !! DT_LASER !! DT_PLASMA !! DT_STUN !! DT_MELEE !! DT_ACID !! DT_SMOKE !! DT_10 ... DT_19
 +
|- style="background-color:#ddffdd;"
 +
| ResistType ||  || 1 || 2 || 3 || 4 || 5 || 6 || 7 || 8 || 9 || 10 ... 19
 +
|- style="background-color:#ddffdd;"
 +
| FireBlastCalc ||  ||  || true ||  ||  ||  ||  ||  ||  ||  ||
 +
|- style="background-color:#ddffdd;"
 +
| IgnoreOverKill ||  || true || true || true || true || true || true || true || true || true || true
 +
|- style="background-color:#ddffdd;"
 +
| IgnoreSelfDestruct ||  ||  || true || true ||  ||  || true || true ||  ||  ||
 +
|- style="background-color:#ddffdd;"
 +
| IgnorePainImmunity ||  ||  ||  ||  ||  ||  || true ||  ||  ||  ||
 +
|- style="background-color:#ddffdd;"
 +
| IgnoreDirection ||  ||  || true ||  ||  ||  ||  ||  ||  || true ||
 +
|- style="background-color:#ddffdd;"
 +
| FixRadius ||  ||  || -1 || -1 ||  ||  || -1 ||  ||  || -1 ||
 +
|- style="background-color:#ddffdd;"
 +
| RadiusEffectiveness ||  ||  || 0.03 || 0.05 ||  ||  || 0.05 ||  ||  || 0.05 ||
 +
|- style="background-color:#ddffdd;"
 +
| ArmorEffectiveness ||  ||  || 0.0 ||  ||  ||  ||  ||  ||  || 0.0 ||
 +
|- style="background-color:#ddffdd;"
 +
| FireThreshold ||  ||  || 0 ||  ||  ||  ||  ||  ||  ||  ||
 +
|- style="background-color:#ddffdd;"
 +
| SmokeThreshold ||  ||  ||  ||  ||  ||  ||  ||  ||  || 0 ||
 +
|- style="background-color:#ddffdd;"
 +
| ToHealth ||  ||  || 1.0 ||  ||  ||  || 0.0 ||  ||  || 0.0 ||
 +
|- style="background-color:#ddffdd;"
 +
| ToArmor ||  ||  || 0.0 ||  ||  ||  || 0.0 ||  ||  || 0.0 ||
 +
|- style="background-color:#ddffdd;"
 +
| ToWound ||  ||  || 0.0 ||  ||  ||  || 0.0 ||  ||  || 0.0 ||
 +
|- style="background-color:#ddffdd;"
 +
| ToItem ||  ||  || 0.0 || 1.0 ||  ||  || 0.0 ||  ||  || 0.0 ||
 +
|- style="background-color:#ddffdd;"
 +
| ToTile ||  ||  || 0.0 ||  ||  ||  || 0.0 ||  ||  || 0.0 ||
 +
|- style="background-color:#ddffdd;"
 +
| ToStun ||  ||  || 0.0 ||  ||  ||  || 1.0 ||  ||  || 1.0 ||
 +
|- style="background-color:#ddffdd;"
 +
| RandomStun ||  ||  ||  ||  ||  ||  || false ||  ||  ||  ||
 +
|- style="background-color:#ddffdd;"
 +
| TileDamageMethod ||  ||  || 2 || 2 ||  ||  || 2 ||  ||  || 2 ||
 +
|}
 +
 +
=== UFOs ===
 +
 +
Defines one of the [[UFOs]] that invade Earth, listed in ''"ufos:"''.
 +
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| String ID of the UFO name.
 +
| ''required''
 
|-
 
|-
−
| '''movementType'''
+
| '''size'''
−
| Type of movement provided by this armor:
+
| String ID of the UFO size.
−
* 0 = Walking
+
| STR_VERY_SMALL
−
* 1 = Flying
+
|-
−
* 2 = Sliding (no walking animation)
+
| '''sprite'''
−
it also defines the body of an tank (32-images) in your spriteSheet or the change in sprites while flying using a flying armour see: [[TANKS.PCK]], [[XCOM_2.PCK]]
+
| Sprite ID from [[INTERWIN.DAT]] used to draw this UFO in the dogfight view and UFOpaedia.
 +
 
 +
Note: don't try to add more images if you don't want to punch yourself in the face - use '''modSprite''' instead.
 +
| -1
 +
|-
 +
| '''modSprite'''
 +
| Filename used to draw this UFO in the dogfight view and UFOpaedia.
 +
| -
 +
|-
 +
| '''marker'''
 +
| Sprite ID from GlobeMarkers spritesheet, used for drawing flying UFO icon on the globe. Usually 3x3 pixels, but can be modded to be bigger.
 +
 
 +
Note: if not modded, sprite id 2 is used (=vanilla flying UFO marker).
 +
| -1
 +
|-
 +
| '''markerLand'''
 +
| Sprite ID from GlobeMarkers spritesheet, used for drawing landed UFO icon on the globe. Usually 3x3 pixels, but can be modded to be bigger.
 +
 
 +
Note: if not modded, sprite id 3 is used (=vanilla landed UFO marker).
 +
| -1
 +
|-
 +
| '''markerCrash'''
 +
| Sprite ID from GlobeMarkers spritesheet, used for drawing crashed UFO icon on the globe. Usually 3x3 pixels, but can be modded to be bigger.
 +
 
 +
Note: if not modded, sprite id 4 is used (=vanilla crashed UFO marker).
 +
| -1
 +
|-
 +
| '''power'''
 +
| Damage power of this UFO's weapon in dogfights.
 
| 0
 
| 0
 
|-
 
|-
−
| '''damageModifier'''
+
| '''range'''
−
| List of decimal damage modifiers (1.0 = 100%) this armor applies to each damage type (see [[#Items|Items section]]) received. Modifiers must be specified for all damage types, in this order:
+
| Maximum range of this UFO's weapon in dogfights (in kilometers).
−
* None
+
| 0
−
* Armor Piercing
 
−
* Incendiary
 
−
* High Explosive
 
−
* Laser
 
−
* Plasma
 
−
* Stun
 
−
* Melee
 
−
* Acid
 
−
* Smoke
 
−
|  
 
−
- 1.0<br>
 
−
- 1.0<br>
 
−
- 1.0<br>
 
−
- 1.0<br>
 
−
- 1.0<br>
 
−
- 1.0<br>
 
−
- 1.0<br>
 
−
- 1.0<br>
 
−
- 1.0<br>
 
−
- 1.0
 
 
|-
 
|-
−
| '''size'''
+
| '''score'''
−
| Size of the unit wearing this armor, in Battlescape grid units. Every unit is square, so a size of 2 means 2x2.
+
| [[Score]] gained when this UFO is destroyed, or half this score if it crash lands.
−
| 1
+
| 0
 
|-
 
|-
−
| '''loftempsSet'''
+
| '''reload'''
−
| List of [[LOFTEMPS]] IDs (one per unit tile, so a 1x1 unit has 1, a 2x2 unit has 4, etc.) used to represent a unit wearing this armor in 3D space.
+
| Time the UFO's weapon takes to fire between each shot.
−
| -
+
| 0
 
|-
 
|-
−
| '''loftemps'''
+
| '''breakOffTime'''
−
| loftemps is a deprecated option that only works for 1x1 sized units.  
+
| Minimum amount of time for the UFO to be able to break off of a dogfight.
−
| -
+
| 0
 
|-
 
|-
−
| '''forcedTorso'''
+
| '''missionScore'''
−
| soldier sprites have female and male torsos. some armours reuse these sprites for flying/non flying torso without difference between genders. This can be controlled by the parameter: 0 = use genderrelated torso, 1 = use male torso, 2 = use female torso
+
| Negative points awarded each half hour the UFO is airborne, and twice this value when landed
 +
| 1
 +
|-
 +
| '''battlescapeTerrainData'''
 +
| [[#Terrains|Terrain]] associated to this UFO in Battlescape missions.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''hunterKillerPercentage'''
 +
| The chance (0-100%) to become a hunter-killer UFO upon spawning (unless overridden by mission wave).
 +
 
 +
Possible options:
 +
*  0 = not a hunter-killer
 +
*  1-99 = percentage chance to be flagged as hunter-killer upon spawn
 +
*  100 = always a hunter-killer
 
| 0
 
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''huntMode'''
 +
| Algorithm to use when prioritizing xcom targets (unless overridden by mission wave).
  
−
|}
+
Possible options:
 +
* 0 = prefer hunting xcom interceptors
 +
* 1 = prefer hunting xcom transports
 +
* 2 = random preference (0 or 1) determined at spawn
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''huntBehavior'''
 +
| Algorithm to use when considering retreating from the dogfight (unless overridden by mission wave).
 +
 
 +
Possible options:
 +
* 0 = flee if you're losing
 +
* 1 = never flee, never crash (since OXCE v6.5, they fight until 0% HP, not 50% HP)
 +
* 2 = random preference (0 or 1) determined at spawn
 +
| 2
 +
|- style="background-color:#ddffdd;"
 +
| '''huntSpeed'''
 +
| When hunter-killer finds a target, it will change speed to a percentage of its maximum speed.
 +
 
 +
Possible options:
 +
* 0 = don't change speed, i.e. keep current speed
 +
* 1-99 = set speed to a percentage of maximum speed
 +
* 100 = speed up to maximum
 +
* 100+ = yes, you can go beyond maximum speed... but only during the chase, when intercepted, the maximum speed will be correctly considered for all relevant calculations and game mechanics
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''missilePower'''
 +
| Only relevant for retaliation UFOs. If not shot down during the base defense, it will destroy some base facilities or even the whole base (without ground mission!).
 +
 
 +
Possible options:
 +
* -1 = destroy everything
 +
* 0 = disabled (i.e. not a missile)
 +
* N = destroy N 1x1 buildings or equivalent
  
−
=== Player Units (Soldiers) ===
+
More info: https://openxcom.org/forum/index.php/topic,6668.0.html
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''unmanned'''
 +
| Unmanned UFOs (e.g. missiles, drones, etc.) cannot crash land after dogfight and cannot be forced to land by a tractor beam. They fight until 0% HP (not 50% HP).
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''splashdownSurvivalChance'''
 +
| Chance (in percent) for a UFO to survive a crash landing on "fake underwater" globe texture.
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''fakeWaterLandingChance'''
 +
| Chance (in percent) for a UFO to land on "fake underwater" globe texture.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''fireSound'''
 +
| UFO's fire sound in the Dogfight, from GEO.CAT.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''alertSound'''
 +
| Sound played when this type of UFO is detected, from GEO.CAT.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''huntAlertSound'''
 +
| Sound played when this type of UFO starts hunting an XCOM craft, from GEO.CAT.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''raceBonus'''
 +
| Modifies or overrides the UFO Stats per alien race.
  
−
Defines a [[soldier]] recruited by X-COM, listed in ''"soldiers:"''. Currently only one soldier unit type (''XCOM'') is supported.
+
You can use this to make the same type of UFO have different [[#UFO Stats|stats]] depending on the alien race.
  
−
Unit stats are represented as follows:
+
  - type: STR_TERROR_SHIP
−
* [[Time Units|tu]]
+
    raceBonus:
−
* [[Energy|stamina]]
+
      STR_MUTON:
−
* [[Health|health]]
+
        hitBonus: 20
−
* [[Bravery|bravery]] (always a multiple of 10)
+
        craftCustomDeploy: STR_MORE_SCARY_WEAPONS
−
* [[Reactions|reactions]]
+
        missionCustomDeploy: STR_TERROR_SITE_MUTONS
−
* [[Firing Accuracy|firing]]
+
      STR_ETHEREAL:
−
* [[Throwing Accuracy|throwing]]
+
        missionCustomDeploy: STR_END_OF_THE_WORLD
−
* [[Strength|strength]]
 
−
* [[Psi Strength|psiStrength]]
 
−
* [[Psi Skill|psiSkill]]
 
−
* [[Melee Accuracy|melee]]
 
  
−
{| class="wikitable" width="100%"
+
| -
 +
|}
 +
 
 +
==== UFO Stats ====
 +
 
 +
The following attributes define so called "ufo stats". They are listed in a separate table, just for convenience... but are still part of the UFO ruleset.
 +
 
 +
<span style="background:#ddffdd;">'''Note:''' In OXCE, all these stats are dynamic, i.e. can depend on the alien race piloting the UFOs.</span>
 +
 
 +
{| class="wikitable" width="100%"
 
! width="150"| Value
 
! width="150"| Value
 
! width="*"  | Description
 
! width="*"  | Description
 
! width="80" | Default
 
! width="80" | Default
 
|-
 
|-
−
| '''type'''
+
| '''damageMax'''
−
| String ID of the soldier name.
+
| Maximum amount of damage this UFO can take. If the UFO takes 50% damage, it crash lands. If it takes 100% damage, it is destroyed.
−
| ''required''
+
| 0
 
|-
 
|-
−
| '''minStats'''
+
| '''speedMax'''
−
| Minimum values used to generate the soldier's [[Starting Stats]]. In this case, ''psiSkill'' is treated as the initial stat (not generated).
+
| Maximum speed in nautical miles.
−
| -
+
| 0
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''maxStats'''
+
| '''radarRange'''
−
| Maximum values used to generate the soldier's [[Starting Stats]]. In this case, ''psiSkill'' is treated as the minimum value for the first month of psi training (actual value is 100%-150%).
+
| Detection range of the UFO's radar in nautical miles. Relevant for hunter-killer UFOs.
−
| -
+
| 672
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''statCaps'''
+
| '''radarChance'''
−
| Maximum stats this soldier can gain through [[Experience]]. '''NOTE:''' A stat will still go over the limit once, and then will no longer increase (see [[Experience#Regarding Caps|Regarding Caps]]).
+
| Chance (0-100%) of this UFO radar detecting a craft that enters its range.
−
| -
+
| 100
 
|-
 
|-
 +
| '''sightRange'''
 +
| UFO's sight range (for detecting X-COM bases) in nautical miles.
 +
| 268
 +
|- style="background-color:#ddffdd;"
 +
| '''hitBonus'''
 +
| Flat bonus percentage to hit chance.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''avoidBonus'''
 +
| Flat bonus percentage to dodge chances against enemy fire.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''powerBonus'''
 +
| Multiplier for the weapon power, e.g. 20 = weapon power increased to 120%, -20 = decreased to 80%.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 
| '''armor'''
 
| '''armor'''
−
| String ID of the [[#Armor|armor]] this soldier uses by default.
+
| Amount of blocked damage per hit.
−
| -
+
| 0
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''standHeight'''
+
| '''shieldCapacity'''
−
| Height of this soldier when standing.
+
| UFO's maximum shield capacity.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''shieldRecharge'''
 +
| Defines the percent chance of recharging a point of shielding per game second (GS) during a Dogfight. Values under 100 are the percent chance, for over 100, every +100 means an automatic +1 to shields per GS. Thus ''shieldRecharge: 250'' means +2 shields/GS, with a 50% chance of +1 more.
 
| 0
 
| 0
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''kneelHeight'''
+
| '''shieldRechargeInGeoscape'''
−
| Height of this soldier when kneeling.
+
| Similar to '''shieldRecharge''', but acts every 5 seconds in the Geoscape. Giving it a value of -1 means instant recharge as soon as 5 seconds pass!
 
| 0
 
| 0
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''floatHeight'''
+
| '''shieldBleedThrough'''
−
| Distance between the bottom of this unit and the ground.
+
| Defines the percent of damage that passes the shield when it goes down.  A value of 0 means that with even just 1 shield point, any single hit will be blocked, while 100 means 100% of the damage left after the shield blocks it will go on to damage the UFO.
 
| 0
 
| 0
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''femaleFrequency'''
+
| '''craftCustomDeploy'''
−
| The probability that a female soldier is hired.
+
| Overrides the [[#Deployment Data|deployment data]] used during the Battlescape generation, when the UFO crashes or lands.
−
| 50
+
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''missionCustomDeploy'''
 +
| Overrides the [[#Deployment Data|deployment data]] used during the Battlescape generation, when the UFO spawns a mission site.
 +
| -
 
|}
 
|}
  
−
=== AI Units (Aliens/Civilians) ===
+
=== Inventory Sections ===
  
−
Defines an [[Alien Life Forms|alien]] (enemy) or [[civilian]] (neutral) unit, listed in ''"units:"''. Every different alien rank is a different unit, since they have completely different stats. Unit stats are represented as follows:
+
Defines one of the sections of the [[Inventory TU Table|Battlescape inventory]] (eg. Backpack), listed in ''"invs:"''.
−
* [[Time Units|tu]]
 
−
* [[Energy|stamina]]
 
−
* [[Health|health]]
 
−
* [[Bravery|bravery]] (always a multiple of 10)
 
−
* [[Reactions|reactions]]
 
−
* [[Firing Accuracy|firing]]
 
−
* [[Throwing Accuracy|throwing]]
 
−
* [[Strength|strength]]
 
−
* [[Psi Strength|psiStrength]]
 
−
* [[Psi Skill|psiSkill]]
 
−
* [[Melee Accuracy|melee]]
 
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 1,304: Line 2,532:
 
! width="80" | Default
 
! width="80" | Default
 
|-
 
|-
−
| '''type'''
+
| '''id'''
−
| String ID of the unit name.
+
| String ID of the inventory name.
 
| ''required''
 
| ''required''
 
|-
 
|-
−
| '''race'''
+
| '''x'''
−
| String ID of the unit race (for alien units).
+
'''y'''
−
| -
+
| Pixel coordinates of this section on the inventory screen.
 +
| 0
 +
0
 
|-
 
|-
−
| '''rank'''
+
| '''type'''
−
| String ID of the unit rank (for alien units).
+
| Type of this section:
−
| -
+
* 0 = Slot section, can contain as many items as will fit on the slots.
 +
* 1 = Hand section, can only contain one item regardless of size.
 +
* 2 = Ground section, can contain infinite items.
 +
| 0
 
|-
 
|-
−
| '''stats'''
+
| '''slots'''
−
| Battlescape stats of this unit.
+
| List of the grid slots (''[x, y]'') that this section is composed of. For example, to make a 2x2 section, you would have ''[0, 0] [0, 1] [1, 0] [1, 1]''.
 
| -
 
| -
 
|-
 
|-
−
| '''armor'''
+
| '''costs'''
−
| String ID of the [[#Armor|armor]] this unit uses by default.
+
| List of [[Time Units]] costs to move an item from this section to another one (eg. ''STR_BACKPACK: 16'' means it will cost 16 TUs to move an item from this section to the Backpack).
 
| -
 
| -
 
|-
 
|-
−
| '''standHeight'''
+
|}
−
| Height of this unit when standing.
+
 
−
| 0
+
=== Terrains ===
 +
 
 +
Defines one of the [[TERRAIN|terrains]] used to generate a Battlescape map, listed in "terrains:".
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 
|-
 
|-
−
| '''floatHeight'''
+
| '''name'''
−
| Distance between the bottom of this unit and the ground.
+
| String ID of the terrain name.
−
| 0
+
| ''required''
 +
|-
 +
| '''mapDataSets'''
 +
| List of filenames (each with matching [[MCD]]/[[Image Formats#PCK|PCK/TAB]] files) that contain the tiles of this terrain.
 +
| -
 
|-
 
|-
−
| '''value'''
+
| '''mapBlocks'''
−
| [[Score]] this unit is worth.
+
| List of map blocks (see below) that are used for generating a map.
−
| 0
+
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''addOnly'''
 +
| Normally, when loading '''mapBlocks''', any map blocks loaded previously (e.g. from other mods) are deleted first and then new map blocks are added. If this attribute is true, the existing map blocks are not deleted and the new ones are added at the end of the list.
 +
Note: does not apply to '''mapDataSets''' or anything else
 +
| false
 
|-
 
|-
−
| '''deathSound'''
+
| '''civilianTypes'''
−
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this unit dies.
+
| List of units to use as civilians for this mission.
−
| -1
+
| [MALE_CIVILIAN, FEMALE_CIVILIAN]
 
|-
 
|-
−
| '''aggroSound'''
+
| '''music'''
−
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this unit aggros.
+
| The list of musics this terrain can choose from (unless overridden by alienDeployment).
−
| -1
+
| -
 
|-
 
|-
−
| '''moveSound'''
+
| '''depth'''
−
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this unit moves.
+
| Minimum and maximum possible depth, format is [minDepth, maxDepth]. Sets the battlescape depth (randomly, unless overridden by alienDeployment).
 +
| [0, 0]
 +
|-
 +
| '''ambience'''
 +
| The ambient sound effect. Sound ID from [[#Extra_Sounds|BATTLE.CAT]].
 
| -1
 
| -1
 
|-
 
|-
−
| '''intelligence'''
+
| '''ambientVolume'''
−
| Intelligence of this unit's AI. The higher the value, the longer this unit remembers player troops between turns.
+
| The volume of the ambient sound effect.
−
| 0
+
| 0.5
 +
|- style="background-color:#ddffdd;"
 +
| '''ambienceRandom'''
 +
| A list of ambient sound effects (IDs from BATTLE.CAT). Doesn't work when '''ambience''' is defined. Uses '''ambientVolume'''. A random sound effect is chosen each time a sound is played.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''ambienceRandomDelay'''
 +
| The delay between random ambient sound effects in seconds. Chosen randomly between the defined min and max (after each sound played).
 +
 
 +
Note: the time passes only when the game is not "busy" (= when you see the map tiles animate). When the tiles don't animate, the timer for ambient sounds doesn't tick.
 +
| [20, 60]
 
|-
 
|-
−
| '''aggression'''
+
| '''script'''
−
| Aggression of this unit's AI. The higher the value, the more ruthless the unit, the more likely to make a frontal assault. Less aggressive units tend to set up ambushes.
+
| The map generation script name.
−
Vanilla values are:
+
| DEFAULT
−
* 0 = mostly passive
+
|- style="background-color:#ddffdd;"
−
* 1 = balanced
+
| '''enviroEffects'''
−
* 2 = mostly aggresive
+
| String ID of enviro effects for missions using this terrain.
−
| 0
+
 
−
|-
+
Note: if enviro effects are defined both on terrain and on alien deployment, the deployment's enviro effects are used.
−
| '''energyRecovery'''
 
−
| Energy recovered by the unit each turn (needs verification)
 
−
| 40 (?)
 
−
|-
 
−
| '''specab'''
 
−
| Special ability of this unit:
 
−
* 0 = None
 
−
* 1 = [[Cyberdisc|Explodes on Death]] (Requires '''power''' and '''blastRadius''' properties to be set on the corpse)
 
−
* 2 = [[Silacoid|Burns Floor]]
 
−
* 3 = [[Bio-Drone|Burns Floor and explodes on Death]]
 
−
| 0
 
−
|-
 
−
| '''spawnUnit'''
 
−
| String ID of the unit used to respawn on death (eg. [[Zombie]]s respawn as [[Chrysallid]]s).
 
 
| -
 
| -
−
|-
 
−
| '''livingWeapon'''
 
−
| Is this unit a living weapon? (only attacks with a '''fixedWeapon''')
 
−
| false
 
−
|-
 
−
| '''female'''
 
−
| Is this unit a female? (used for TFTD civilian types)
 
−
| false
 
−
|-
 
 
|}
 
|}
  
−
=== Alien Races ===
+
==== Map Blocks ====
−
 
 
−
Defines a [[Alien Life Forms|race]] used in [[Alien Missions]], listed in ''"alienRaces:"''. Heavily tied with deployment data.
 
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 1,395: Line 2,633:
 
! width="80" | Default
 
! width="80" | Default
 
|-
 
|-
−
| '''id'''
+
| '''name'''
−
| String ID of the alien race name.
+
| Filename of the [[MAPS|map]].
 
| ''required''
 
| ''required''
 
|-
 
|-
−
| '''members'''
+
| '''width'''
−
| Alien crew associated with this alien race (eg. race units + terrorist units), defined by a list of unit string IDs. Order here will define rank in terms of deployment. generally speaking the order is:
+
| Width of this map block in Battlescape grid units.
−
* 0 - Commander
+
 
−
* 1 - Leader
+
Note: in '''MapView''' tool (tested on version 1.6.0.0), this is called ''length''. MapView's dimensions [w, l, h] correspond to OpenXcom's dimensions [l,w,h].
−
* 2 - Engineer
+
| 10
−
* 3 - Medic
+
|-
−
* 4 - Navigator
+
| '''length'''
−
* 5 - Soldier
+
| Length of this map block in Battlescape grid units.
−
* 6 - Terrorist 1
+
 
−
* 7 - Terrorist 2
+
Note: in '''MapView''' tool (tested on version 1.6.0.0), this is called ''width''. MapView's dimensions [w, l, h] correspond to OpenXcom's dimensions [l,w,h].
−
but of course, not all races have all ranks, so the "fill in" rank would be listed multiple times (see ethereals).
+
| 10
−
| -
 
 
|-
 
|-
−
| '''retaliation'''
+
| '''height'''
−
| retaliation enables/disables the race for retaliation missions.
+
| Height of this map block in Battlescape grid units.
−
| ''True''
+
| 4
 
|-
 
|-
−
|}
+
| '''groups'''
−
 
+
| List (or single number) of groups this mapblock belongs to (used in mapscripts)
−
=== Alien Deployments ===
+
default usage:
−
 
+
* 0 - Default
−
Defines a Battlescape deployment data used in [[Alien Missions]] (such as alien and map configurations), listed in ''"alienDeployments:"''.
+
* 1 - Landing Zone (for placing X-COM / alien craft) (used in addCraft/addUFO mapscript commands)
 +
* 2 - E-W Road (for city maps) (used in addLine mapscript command)
 +
* 3 - N-S Road (for city maps) (used in addLine mapscript command)
 +
* 4 - Road Crossing (for city maps) (used in addLine mapscript command)
 +
 
 +
Hint: all maps with an XCOM/Alien craft require at least one map block assigned to Group 1. This map block can only contain ground tiles (no walls or objects).
 +
| 0
 +
|-
 +
|'''revealedFloors'''
 +
| Map block floor to be revealed from the very beginning; use a list "[0, 1, ..]" to reveal multiple floors
 +
| -
 +
|-
 +
| '''items'''
 +
| An array of items to add to this mapblock, and the positions to place them at.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''fuseTimers'''
 +
| This attribute allows you to pre-prime the items placed on the map using the '''items''' attribute. It's a list of items and information about minimum and maximum fuse timer.
 +
 
 +
Example:
 +
 
 +
  items:
 +
    STR_ELERIUM:
 +
      - [0, 0, 0]
 +
    STR_TIMEBOMB:
 +
      - [2, 1, 0]
 +
      - [6, 2, 0]
 +
  fuseTimers:
 +
    STR_TIMEBOMB: [0, 30]
 +
 
 +
In this example 3 items are placed on the map block: 1 Elerium item and 2 Timebomb items. Both Timebomb items will be pre-primed with a random delay between 0 and 30 (each item will have a different delay). Elerium item will not be pre-primed :)
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''randomizedItems'''
 +
| A list of additional items to add to this mapblock, using a more randomized approach. Does not support pre-priming of items.
 +
 
 +
Example:
 +
 
 +
  randomizedItems:
 +
    - position: [12, 15, 2]
 +
      amount: 3
 +
      mixed: true
 +
      itemList: [STR_ITEM_1, STR_ITEM_2, STR_ITEM_3, STR_ITEM_3]
 +
 
 +
In this example:
 +
* 3 items will be placed on the tile at coordinates [x,y,z] = [12, 15, 2]
 +
* all 3 items can be different (''mixed: true''); if you wanted 3 items of the same type use ''mixed: false''
 +
* items are selected from the ''itemList'' randomly; to increase odds for a certain item type, you can add it to the list multiple times
 +
** in our example STR_ITEM_1 has 25% chance, STR_ITEM_2 also 25% chance and STR_ITEM_3 a 50% chance
 +
| -
 +
|}
 +
 
 +
==== MCD Patches ====
 +
 
 +
'''FIXME''' Someone please document this...
 +
 
 +
=== Map Scripts ===
 +
 
 +
Defines how the battlescape maps are generated from the available map blocks.
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
Line 1,428: Line 2,723:
 
|-
 
|-
 
| '''type'''
 
| '''type'''
−
| String ID of the deployment name.
+
| name of the script
 
| ''required''
 
| ''required''
 
|-
 
|-
−
| '''width'''
+
| '''commands'''
−
| Width of the Battlescape map in grid units.
+
| List of MapCommands
−
| 0
+
| -
 +
|}
 +
 
 +
==== Map Command ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| Currently these commands are implemented:
 +
* addBlock - adds a mapblock can be combined with size, group, executions and blocks (for a weighted list)
 +
* addLine - adds a line of mapblocks from groups (roads for example)
 +
* addCraft - adds X-Com craft towards map
 +
* addUFO - can also be used to place 'UFO' maps (or any other single map) on missionSite (objective 3) missions.
 +
* digTunnel
 +
* fillArea
 +
* checkBlock
 +
* removeBlock
 +
* resize
 +
| ''required''
 +
|-
 +
| '''rects'''
 +
| A list of possible areas on the map where (random) placement/checks/removal can happen. If not specified, entire map is considered.
 +
Each item in the list is a group of four integers [x, y, width, height].
 +
| -
 
|-
 
|-
−
| '''length'''
+
| '''label'''
−
| Length of the Battlescape map in grid units.
+
| 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, OpenXcom will convert them to positive (abs. value) anyway. If you try using non-unique labels, you'll get undefined behavior.
 
| 0
 
| 0
 
|-
 
|-
−
| '''height'''
+
| '''conditionals'''
−
| Vertical height of the Battlescape map in grid units.
+
| 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
 
| 0
 
|-
 
|-
−
| '''terrains'''
+
| '''size'''
−
| list of string IDs of the [[#Terrains|terrain]] to choose from to generate this map. This is not used for UFO sites where the terrain comes from the Geoscape.
+
| Size of map blocks that can be placed/checked/removed within '''rects'''. Only width (sizeX) and length (sizeY) are relevant. Can be specified as a single value, which is then used as both width and length; or as group of up to three values [x, y, z].
−
| -
+
 
 +
Also used for resize command type, which can use also the height value (sizeZ).
 +
| [1, 1, 0]
 
|-
 
|-
−
| '''shade'''
+
| '''groups'''
−
| Shade of the map (0-15, where 0 is full daytime and 15 is full nighttime). This is not used for UFO sites where the shade comes from the Geoscape.
+
| Defines what types of map blocks can be used within this command. Can be defined as a list or as a single value.
 
| 0
 
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''horizontalGroup'''
 +
| Allows to override group used in addLine command.
 +
| 2
 +
|- style="background-color:#ddffdd;"
 +
| '''verticalGroup'''
 +
| Allows to override group used in addLine command.
 +
| 3
 +
|- style="background-color:#ddffdd;"
 +
| '''crossingGroup'''
 +
| Allows to override group used in addLine command.
 +
| 4
 
|-
 
|-
−
| '''nextStage'''
+
| '''blocks'''
−
| String ID of the next deployment stage to use after this one, for multi-stage missions.
+
| Alternative to '''groups'''. Here we define an explicit list of map blocks that can be used within this command.
−
| -
+
 
 +
Important: The list is defined by map block sequential IDs (not by name!), where first map block has sequential ID = 0 (not 1).
 +
| 0
 +
|-
 +
| '''freqs'''
 +
| Defines the distribution frequency for the '''groups''' or '''blocks''' (see above). If not used, all groups/blocks have frequency 1.
 +
| 1
 
|-
 
|-
−
| '''race'''
+
| '''maxUses'''
−
| Sets the race to use in the next stage.
+
| Defines the maximum number of uses for the '''groups''' or '''blocks''' (see above). If not used, all groups/blocks have frequency -1 (=unlimited).
−
| ""
+
| -1
 
|-
 
|-
−
| '''finalDestination'''
+
| '''tunnelData'''
−
| Sets whether this mission is where you send your "uber-craft" to win the game.
+
| Parameter for digTunnel command type. Contains a '''level''' (default: 0) and a list of MCD replacement rules ('''MCDReplacements''')
−
| "false"
+
| -
 
|-
 
|-
−
| '''winCutscene'''
+
| '''direction'''
−
| Sets the cutscene to play when you win the mission. If set to "wingame" or "losegame", the player will be returned to the main menu after the cutscene plays.
+
| Parameter for digTunnel and addLine command types. Values are: both, horizontal or vertical.
−
| ""
+
| -
 
|-
 
|-
−
| '''loseCutscene'''
+
| '''executionChances'''
−
| Sets the cutscene to play when you lose the mission. If set to "wingame" or "losegame", the player will be returned to the main menu after the cutscene plays.
+
| The probability (0-100%) that this command will be executed (or fails).
−
| ""
+
| 100
 
|-
 
|-
−
| '''script'''
+
| '''executions'''
−
| Reference to a mapScript.
+
| This command will be executed multiple times with a value > 1.
−
| ""
+
| 1
 
|-
 
|-
−
| '''data'''
+
| '''UFOName'''
−
| List of deployment data for each alien rank on this mission (see below).
+
| String ID of the UFO to be placed.
 
| -
 
| -
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''briefing'''
+
| '''canBeSkipped'''
−
| Information about the mission briefing (see below).
+
| Only relevant for ''addUFO'' command with no '''label''' defined. Determines, whether an unsuccessful ''addUFO'' command can be skipped (and logged into the log file) or whether the game should crash.
 +
 
 +
Note: this attribute is more or less deprecated. Maybe useful for testing/debugging?
 +
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''craftName'''
 +
| String ID of the craft to be placed.
 +
 
 +
Note: this can be used to replace the craft you arrived with (e.g. Skyranger) with a new vehicle you used to make the last section of your journey. For example a small submarine for an underwater mission or an APC for a mission, where you couldn't land or didn't want to make too much noise :)
 
| -
 
| -
−
|}
+
|- style="background-color:#ddffdd;"
 +
| '''terrain'''
 +
| String ID of an alternate terrain to be used for this command only. Used for example when you want to sneak in a few blocks from FOREST terrain into a map made predominantly using FARM terrain.
  
−
Notes:
+
There is a special constant '''globeTerrain''', which takes a random terrain corresponding to the globe texture, where the mission takes place. More info here: https://openxcom.org/forum/index.php/topic,7536.0.html
−
* '''terrains''' can also be used with UFOs, with the game using instead the listed terrain rather than the location of the UFO on Geoscape.  
 
−
==== Deployment Data ====
 
  
−
{| class="wikitable" width="100%"
+
There is also a special constant '''baseTerrain''' for base defense missions, which takes the terrain from the globe definition (see also '''baseDefenseMapFromLocation'''). More info: https://openxcom.org/forum/index.php/topic,5108.0.html
−
! width="150"| Value
+
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''randomTerrain'''
 +
| Alternative to '''terrain'''. A list of string IDs, one of them is chosen randomly.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7758.0.html
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''verticalLevels'''
 +
| Allows using a set of map blocks (of various vertical sizes) stacked on top of each other... instead of just a single map block.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,5316.0.html
 +
| -
 +
|}
 +
 
 +
==== Guidelines/Tips ====
 +
* There are 3 main 'types' of map generation in UFO/TFTD:
 +
** Random, where any map block (including XCom craft and/or UFOs/USOs) can be placed anywhere in the [[Battlescape]];
 +
** Procedurally generated, where placement of certain maps is defined by rules (i.e. the roads on the Urban terrain used in terror sites in Enemy Unknown/UFO Defense);
 +
** Static, where only 1 or more maps are used (i.e. Cargo and Liner Ships in TFTD).
 +
* Map scripting in OpenXcom allows also for a mixture of 2 or even all the 3 described above, where some parts of the map will be static, others will be filled according to certain rules and the remainer filled randomly.
 +
* Every script requires at least 1 map block used for spawning XCom units. Usually that role is taken by XCom craft, except on the XCom Base, Alien Base and the 2nd part of the Cydonia mission. If the script can't place this map then OpenXcom will display a message saying that it couldn't place XCom units on the map.
 +
* Every space on the Battlescape needs to be filled, so the script should have enough mapblocks available for use. In the case of the vanilla terrains, the maxUses settings were designed mostly for 50x50 dimensions so any increases to those dimensions will require adjusting the maxUses settings. Otherwise the game will crash and display an error message that it couldn't generate the map.
 +
* The "addLine" command relies on groups 2, 3 and 4 as its vertical road, horizontal road and crossroad pieces.
 +
* The "addCraft" and "addUFO" commands will place blocks from group 1 as well, by default, if any are defined.
 +
 
 +
=== Armor ===
 +
 
 +
Defines a Battlescape unit's [[armor]] as well as visual representation (so every unit has an armor), listed in ''"armors:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 
! width="*"  | Description
 
! width="*"  | Description
−
! width="80" | Default
+
! width="100" | Default
 
|-
 
|-
−
| '''alienRank'''
+
| '''type'''
−
| [[Alien Rank|Rank]] associated with this deployment data, as defined by the order of the race in question (see above)
+
| String ID of the armor name.
 
| ''required''
 
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''requires'''
 +
| The research required to equip this armor.
 +
 +
Modding hint: it is possible to equip one "store item" as several different armors, e.g. as armor with or without a helmet. This option allows you to limit some of those options by a research topic. You could use this also for example to define different armor variants for each game difficulty level, e.g. make armor stronger for beginners and weaker for veterans.
 +
| -
 
|-
 
|-
−
| '''lowQty'''
+
| '''spriteSheet'''
−
| Minimum quantity of aliens to spawn on beginner/experienced.
+
| Sprite sheet from [[UNITS]] used to draw a unit wearing this armor.
−
| 0
+
| -
 
|-
 
|-
−
| '''highQty'''
+
| '''spriteInv'''
−
| Minimum quantity of aliens to spawn on superhuman. (minimum quantity for veteran/genius is the median of this and the previous value)
+
| Sprite used for the [[Inventory Backgrounds]] of a unit wearing this armor.
−
| 0
+
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''layersDefaultPrefix''' '''layersSpecificPrefix''' '''layersDefinition'''
 +
| Alternative way of defining/creating inventory sprites (a.k.a. paperdolls), in layers.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,6290.msg104464.html#msg104464
 +
| -<br/>-<br/>-
 
|-
 
|-
−
| '''dQty'''
+
| '''allowInv'''
−
| Delta in Quantity. ie: random number of aliens to spawn on top of the minimum (all difficulties).
+
| Can the inventory of this armor be accessed or not?
−
| 0
+
| true
 +
|- style="color:#666666;"
 +
| '''corpseItem'''
 +
| ''Deprecated:'' use '''corpseGeo''' and '''corpseBattle''' instead.
 +
| -
 
|-
 
|-
−
| '''extraQty'''
+
| '''corpseBattle'''
−
| functionally identical to dQty, spawns a random number of additional aliens.
+
| List of string IDs of the corpse [[#Items|items]] generated when a unit wearing this armor is killed/stunned (1 for 1x1 unit, 4 for 2x2 unit) on the Battlescape.
−
| 0
+
| -
 
|-
 
|-
−
| '''percentageOutsideUfo'''
+
| '''corpseGeo'''
−
| Percentage (0-100%) of aliens to spawn outside in UFO sites.
+
| String ID of the corpse [[#Items|item]] recovered in Debriefing. Defaults to '''corpseBattle''' if omitted.
−
| 0
+
 
 +
Tip for modders: useful for example when you want to recover a "damaged" version of a soldier's armor.
 +
| -
 
|-
 
|-
−
| '''itemSets'''
+
| '''storeItem'''
−
| Three lists (one for each alien technology level) of [[#Items|items]] (string IDs) for the aliens to equip.
+
| String ID of the [[#Items|item]] that represents this armor in [[Base Stores]] for equipping. Set to ''STR_NONE'' to not require an item (eg. [[coveralls]]).
−
| ''required''
+
| -
 
|-
 
|-
−
|}
+
| '''specialWeapon'''
 +
| Alternative method of defining a melee/psi weapon for aliens (and civilians); instead of defining it on the unit itself.
  
−
==== Briefing Data ====
+
<span style="background:#ddffdd;">Note: in OXCE, this can be used also for Soldiers. It can be any type of weapon (not only melee/psi) and does not block the inventory. Instead it is accessed via a special icon.</span>
−
 
+
| -
−
{| class="wikitable" width="100%"
+
|- style="background-color:#ddffdd;"
−
! width="150"| Value
+
| '''builtInWeapons'''
−
! width="*"  | Description
+
| Alternative method of defining built-in weapons for aliens (and civilians); instead of defining them on the unit itself. Can be used also for Soldiers.
−
! width="80" | Default
+
| -
 
|-
 
|-
−
| '''palette'''
+
| '''frontArmor'''
−
| The color index to start at in the "PAL_GEOSCAPE" palette.
+
| Protection provided on the front of the unit.
 
| 0
 
| 0
 
|-
 
|-
−
| '''textOffset'''
+
| '''sideArmor'''
−
| Number of pixels to vertically offset the briefing text. Larger values move the text further down the screen.
+
| Protection provided on the sides of the unit.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''leftArmorDiff'''
 +
| Used to define different armor values on the sides (left/right). If specified, left side armor = '''sideArmor''' + '''leftArmorDiff'''.
 
| 0
 
| 0
 
|-
 
|-
−
| '''music'''
+
| '''rearArmor'''
−
| The ID of the music to play.
+
| Protection provided on the rear of the unit.
−
| "GMDEFEND"
+
| 0
 
|-
 
|-
−
| '''background'''
+
| '''underArmor'''
−
| The background screen to show.
+
| Protection provided under the unit (e.g. from explosions).
−
| "BACK16.SCR"
+
| 0
 
|-
 
|-
−
| '''showCraft'''
+
| '''drawingRoutine'''
−
| Whether to show the name of craft that arrived at the mission site.
+
| Drawing routine used to put together the body parts in the unit's '''spriteSheet''':
−
| true
+
* 0 = [[Soldier]], [[Sectoid]]
−
|-
+
* 1 = [[Floater]]
−
| '''showTarget'''
+
* 2 = [[HWP]]
−
| Whether to display the mission target name.
+
* 3 = [[Cyberdisk]]
−
| true
+
* 4 = [[Civilian]], [[Ethereal]]
−
|-
+
* 5 = [[Sectopod]], [[Reaper]]
−
|}
+
* 6 = [[Snakeman]]
−
 
+
* 7 = [[Chryssalid]]
−
=== Research ===
+
* 8 = [[Silacoid]]
 +
* 9 = [[Celatid]]
 +
* 10 = [[Muton]] (identical to routine 0 except for the placement of a single arm frame while walking in a specific direction, use routine 0 instead)
 +
* 11 = [[Submersible Weapons Systems]]
 +
* 12 = [[Hallucinoid]]
 +
* 13 = [[Aquanauts]]
 +
* 14 = [[Calcinite]], [[Deep One]], [[Gillman]], [[Lobster Man]], [[Tasoth]]
 +
* 15 = [[Aquatoid]]
 +
* 16 = [[Bio-Drone]]
 +
* 17 = TFTD Civilians type A and [[Zombie_(TFTD)]]
 +
* 18 = TFTD Civilians type B
 +
* 19 = [[Tentaculat]]
 +
* 20 = [[Triscene]]
 +
* 21 = [[Xarquid]]
 +
* 22 = Inverted [[Cyberdisc]] (propulsion animation on top)
 +
| 0
 +
|-
 +
| '''drawBubbles'''
 +
| Set to true for units that breathe underwater, e.g. humans and humanoid aliens.
  
−
Defines a [[Research|research topic]] that X-COM scientists can investigate, listed in ''"research:"''.
+
Note: in vanilla this is set to true for all units using '''drawingRoutine''' 13 and 14.
−
 
+
| false
−
{| class="wikitable" width="100%"
 
−
! width="150"| Value
 
−
! width="*"  | Description
 
−
! width="80" | Default
 
 
|-
 
|-
−
| '''name'''
+
| '''movementType'''
−
| String ID of the research project's name (or item, if a '''lookup''' is defined).
+
| Type of movement provided by this armor:
−
| ''required''
+
* 0 = Walking
−
|-
+
* 1 = Flying
−
| '''lookup'''
+
* 2 = Sliding (no walking animation)
−
| String ID of the research project's display name and UFOPaedia article reference.
+
* 3 = Floating (fly underwater, walk on the surface)
−
| -
+
* 4 = Sinking (walk underwater, fly on the surface)
 +
it also defines the body of a tank (32-images) in your spriteSheet or the change in sprites while flying using a flying armor see: [[TANKS.PCK]], [[XCOM_2.PCK]]
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''moveSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when a unit wearing this armor moves (overrides unit's moveSound).
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''deathMale/deathFemale'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when a unit wearing this armor dies. A list of sound IDs can be used too.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''selectUnitMale/selectUnitFemale'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when a unit wearing this armor is manually selected. A list of sound IDs can be used too.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''startMovingMale/startMovingFemale'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when a unit wearing this armor starts moving. A list of sound IDs can be used too.
 +
| -  
 +
|- style="background-color:#ddffdd;"
 +
| '''selectWeaponMale/selectWeaponFemale'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when a weapon of a unit wearing this armor is selected. A list of sound IDs can be used too.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''annoyedMale/annoyedFemale'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when a unit wearing this armor is repeatedly manually selected. A list of sound IDs can be used too.
 +
| -  
 
|-
 
|-
−
| '''cost'''
+
| '''size'''
−
| Number of man-days (on average, the final time will be 50-150% this value) required to complete this project.
+
| Size of the unit wearing this armor, in Battlescape grid units. 1 means 1x1 unit, 2 means 2x2 unit, other sizes are not supported.
 +
| 1
 +
|-
 +
| '''weight'''
 +
| Physical weight of the armor when worn.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''visibilityAtDark'''
 +
| How far can the unit wearing this armor see during darkness. Default 0 uses 9 for X-Com, but for Aliens it uses the maxViewDistance variable (default 20).
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''visibilityAtDay'''
 +
| How far can the unit wearing this armor see during the day. Default 0 uses the maxViewDistance variable (default 20). Both of these variables only affect how far away units may be seen. Terrain revealed is always based on maxViewDistance, day or night.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''personalLight'''
 +
| Intensity of the personal light for the unit wearing this armor.
 +
| 15
 +
|- style="background-color:#ddffdd;"
 +
| '''camouflageAtDay'''
 +
| Makes the unit wearing this armor less visible during the day. Positive numbers set absolute distance (e.g. 7 means that unit is visible from 7 tiles away), negative numbers set relative distance (e.g. -10 means that unit is visible from a distance that is 10 tiles shorter than usual). Cannot decrease visibility below 1 tile.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''camouflageAtDark'''
 +
| Makes the unit wearing this armor less visible during darkness. Positive or negative, same as above.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''antiCamouflageAtDay'''
 +
| Cancels enemy camouflage by a specified amount (of tiles) during the day. Cannot increase visibility beyond the usual (e.g. camo = -5 and antiCamo = 7 still only evens out, it doesn't provide 2 additional tiles of visibility).
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''antiCamouflageAtDark'''
 +
| Cancels enemy camouflage by a specified amount (of tiles) during darkness. Cannot increase visibility beyond the usual.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''heatVision'''
 +
| Allows seeing better through smoke. Percentage (0-100%) value defining how much smoke is ignored.
 
| 0
 
| 0
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''points'''
+
| '''psiVision'''
−
| [[Score]] earned for completing this project.
+
| Allow "seeing" through walls. Units with this armor can sense enemies that are 'psiVision' tiles (or less) away, in '''any''' direction.
 +
 
 +
Note: cannot sense enemies that are '''fearImmune'''.
 
| 0
 
| 0
 
|-
 
|-
−
| '''needItem'''
+
| '''stats'''
−
| Does this project require an [[#Items|item]] of the same name?
+
| Like soldier stats (see below) but these are treated as stat bonuses while wearing a given type of armor.
−
| false
 
−
|-
 
−
| '''dependencies'''
 
−
| List of research projects that can unlock access to this one. If the full list is researched, or if one of the projects on the list "unlocks" this one,  it becomes available.
 
 
| -
 
| -
 
|-
 
|-
−
| '''unlocks'''
+
| '''damageModifier'''
−
| List of research projects unlocked, regardless of other dependencies, but not requirements, by completing this project (for example, any live alien unlocks "alien origins").
+
| List of decimal damage modifiers (1.0 = 100%) this armor applies to each damage type (see [[#Items|Items section]]) received. Modifiers must be specified for all damage types, in this order:
−
| -
+
* None
−
|-
+
* Armor Piercing
−
| '''requires'''
+
* Incendiary
−
| List of research projects unilaterally required before this project can be unlocked (for example, "the martian solution" will not even be considered for unlocking until AFTER "alien origins" is completed).
+
* High Explosive
−
| -
+
* Laser
 +
* Plasma
 +
* Stun
 +
* Melee
 +
* Acid
 +
* Smoke
 +
<div style="background:#ddffdd;">In OXCE, there are 10 additional (nameless) damage types, which you can name and use for any purpose you like (e.g. create Electric damage, Freeze damage, EMP damage or whatever). You are also not forced to specify all 20 values if you are using less. If you for example only use 2 additional damage types, it is enough to specify only 12 (10 vanilla + 2 additional).
 +
</div>
 +
|  
 +
- 1.0<br>
 +
- 1.0<br>
 +
- 1.0<br>
 +
- 1.0<br>
 +
- 1.0<br>
 +
- 1.0<br>
 +
- 1.0<br>
 +
- 1.0<br>
 +
- 1.0<br>
 +
- 1.0
 
|-
 
|-
−
| '''getOneFree'''
+
| '''loftempsSet'''
−
| List of "bonus" research projects that may be granted when completing this project (for example, alien medics will give you information on other alien races). Used in Alien Navigators (gives random alien Mission), Medics (random alien interrogation or autopsy) or Engineers (gives UFO type).  
+
| List of [[LOFTEMPS]] IDs (1 for 1x1 units, 4 for 2x2 units) used to represent a unit wearing this armor in 3D voxel space.
 +
| -
 +
|- style="color:#666666;"
 +
| '''loftemps'''
 +
| ''Deprecated:'' use '''loftempsSet''' instead.
 
| -
 
| -
 
|-
 
|-
−
| '''cutscene'''
+
| '''deathFrames'''
−
| The name of the cutscene to play when this project is completed.  If the cutscene is "wingame" or "losegame", the player is returned to the main menu after the cutscene plays.
+
| Number of "death frames" = sprites in the death animation sequence.
−
| -
+
| 3
−
|}
+
|- style="background-color:#ddffdd;"
 +
| '''overKill'''
 +
| Defines how much damage (over the maximum HP) is needed to vaporize/disintegrate a unit upon hit. Defined as percentage, e.g. 0.6 = 60% of maximum HP.
  
−
=== Manufacture ===
+
Notes:
−
 
+
* If a unit is disintegrated, it will have a different death animation and it will not leave any corpse.
−
Defines a [[Manufacture|manufacture project]] that X-COM engineers can produce, listed in ''"manufacture:"''.
+
* Weapons can be configured to cause disintegration or not (e.g. explosives vs bullets), see '''IgnoreOverKill''' (by default all weapons ignore overkill).
−
 
+
| 0.5
−
{| class="wikitable" width="100%"
 
−
! width="150"| Value
 
−
! width="*"  | Description
 
−
! width="80" | Default
 
 
|-
 
|-
−
| '''name'''
+
| '''constantAnimation'''
−
| String ID of the manufacturing project's name (and the item it produces).
+
| Set it to "true" for units that constantly show an animation, such as: Biodrone, Celatid, Silacoid.
−
| ''required''
+
| false
 +
|-
 +
| '''forcedTorso'''
 +
| Soldier sprites have female and male torsos. Some armors reuse these sprites for flying/non flying torso without difference between genders. This can be controlled by the parameter:
 +
* 0 = use gender-specific torso
 +
* 1 = use male torso
 +
* 2 = use female torso
 +
| 0
 
|-
 
|-
−
| '''category'''
+
| '''spriteFaceGroup'''
−
| String ID of the manufacturing project's category.
+
| [[PALETTES.DAT#Color Indexes|Palette]] offset (1-15) used for replacing colors when drawing units. Replacement is based on unit's avatar (gender & look). Default 0 (unused).
−
| -
+
As the name suggests, it is usually used to recolor faces.
 +
| ''example:'' <br> 6
 
|-
 
|-
−
| '''requires'''
+
| '''spriteHairGroup'''
−
| List of [[#Research|topics]] (string IDs) that must be researched to unlock this project. If none are specified, this project is unlocked from the start.
+
| [[PALETTES.DAT#Color Indexes|Palette]] offset (1-15) used for replacing colors when drawing units. Replacement is based on unit's avatar (gender & look). Default 0 (unused).
−
| -
+
As the name suggests, it is usually used to recolor hair.
 +
| ''example:'' <br> 9
 
|-
 
|-
−
| '''space'''
+
| '''spriteUtileGroup'''
−
| Amount of [[Workshop]] space required to begin this project.
+
| [[PALETTES.DAT#Color Indexes|Palette]] offset (1-15) used for replacing colors when drawing units. Replacement is based on unit's avatar (gender & look). Default 0 (unused).
 +
Doesn't have any suggested use, feel free to use it to recolor anything you want :)
 
| 0
 
| 0
 
|-
 
|-
−
| '''time'''
+
| '''spriteRankGroup'''
−
| Number of man hours (on average) required per item.
+
| [[PALETTES.DAT#Color Indexes|Palette]] offset (1-15) used for replacing colors when drawing units. Replacement is based on unit's "rank" (see below for details). Default 0 (unused).
 +
Doesn't have any suggested use, feel free to use it to recolor anything you want... for example Floater robes :)
 
| 0
 
| 0
 
|-
 
|-
−
| '''cost'''
+
| '''spriteFaceColor'''
−
| Monetary deduction per item manufactured.
+
| New color index (0-255) for "face pixels". List of 8 values corresponding to the following avatars:
−
| 0
+
* Male Blond, Female Blond, Male Brown, Female Brown, Male Asian, Female Asian, Male African, Female African
 +
Aliens and civilians use random value from this list. Value 0 means "no change".
 +
Example: [96, 96, 96, 96, 160, 160, 163, 163]
 +
| -
 
|-
 
|-
−
| '''requiredItems'''
+
| '''spriteHairColor'''
−
| List of [[#Items|items]] required and consumed per item manufactured.
+
| New color index (0-255) for "hair pixels". List of 8 values corresponding to the same avatars as above.
 +
Aliens and civilians use random value from this list. Value 0 means "no change".
 +
Example: [144, 144, 164, 164, 245, 245, 166, 166]
 
| -
 
| -
 
|-
 
|-
−
| '''producedItems'''
+
| '''spriteUtileColor'''
−
| List of [[#Items|items]] produced per each item consumed. If not specified, defaults to 1 item with the same string ID as the manufacture.
+
| New color index (0-255) for "util pixels". List of 8 values corresponding to the same avatars as above.
−
| 1
+
Aliens and civilians use a random value from this list. Value 0 means "no change".
 +
| -
 
|-
 
|-
−
|}
+
| '''spriteRankColor'''
−
 
+
| New color index (0-255) for "rank pixels".
−
=== UFOpaedia Article ===
+
For soldiers, a list of 6 values corresponding to the following xcom ranks:
 +
* STR_ROOKIE, STR_SQUADDIE, STR_SERGEANT, STR_CAPTAIN, STR_COLONEL, STR_COMMANDER
 +
For aliens, a list of 7 values corresponding to the following alien ranks:
 +
* STR_LIVE_SOLDIER, STR_LIVE_ENGINEER, STR_LIVE_MEDIC, STR_LIVE_NAVIGATOR, STR_LIVE_LEADER, STR_LIVE_COMMANDER, STR_LIVE_TERRORIST
 +
For civilians, a list of 8 values... one will be chosen randomly (since civilians don't have ranks).
 +
Value 0 means "no change".
 +
| -
 +
|-
 +
| '''units'''
 +
| List of soldier types this armor applies to. Empty = applies to all soldier types.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''customArmorPreviewIndex'''
 +
| Allows to have different icons for different types of armor on the [Craft Info] screen. Defined either as a single index into the '''CustomArmorPreviews''' spritesheet, or as a list of indices (for bigger icons).
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''allowsRunning'''
 +
| Does this armor allow running? Defaults are: true = for 1x1 units, false = for 2x2 units.
 +
| vanilla
 +
|- style="background-color:#ddffdd;"
 +
| '''allowsStrafing'''
 +
| Does this armor allow strafing? Defaults are: true = for 1x1 units, false = for 2x2 units.
 +
| vanilla
 +
|- style="background-color:#ddffdd;"
 +
| '''allowsKneeling'''
 +
| Does this armor allow kneeling? Defaults are: true = for xcom soldiers, false = for xcom vehicles, aliens and civilians.
 +
| vanilla
 +
|- style="background-color:#ddffdd;"
 +
| '''allowsMoving'''
 +
| Does this armor allow moving?
 +
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''allowTwoMainWeapons'''
 +
| During autoequip (e.g. when equipping built-in armor weapons), allow 2 main weapons. Only applies to XCOM, aliens and civilians have it allowed by default.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''instantWoundRecovery'''
 +
| Should the health of a unit with this armor be automatically set back to maximum after the battle is over?
 +
 
 +
Note: used for example for vehicles implemented as soldier types (so that they can gain experience too).
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''standHeight'''
 +
| Overrides the unit's/soldier's normal standHeight when wearing this armor.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''kneelHeight'''
 +
| Overrides the unit's/soldier's normal kneelHeight when wearing this armor.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''floatHeight'''
 +
| Overrides the unit's/soldier's normal floatHeight when wearing this armor.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''fearImmune'''
 +
| Is this unit immune to morale loss (and '''psiVision''')? Defaults are: false = for 1x1 units, true = for 2x2 units.
 +
| vanilla
 +
|- style="background-color:#ddffdd;"
 +
| '''bleedImmune'''
 +
| Is this unit immune to bleeding? Defaults are: false = for 1x1 xcom soldiers, true = for everything else.
 +
 
 +
Note: game option ''alienBleeding'' affects the defaults too.
 +
| vanilla
 +
|- style="background-color:#ddffdd;"
 +
| '''painImmune'''
 +
| Is this unit immune to stun damage? Defaults are: false = for 1x1 units, true = for 2x2 units.
 +
 
 +
Note: weapons can be modded to ignore this immunity (by default all weapons with damageType=6 (stun) will ignore it).
 +
| vanilla
 +
|- style="background-color:#ddffdd;"
 +
| '''zombiImmune'''
 +
| Is this unit immune to "zombification"? Defaults are: false = for 1x1 units, true = for 2x2 units.
 +
 
 +
Note: this setting works for 1x1 units only; save your time and don't try changing it for 2x2 units.
 +
| vanilla
 +
|- style="background-color:#ddffdd;"
 +
| '''ignoresMeleeThreat'''
 +
| Is this unit immune to CQC? Defaults are: false = for 1x1 units, true = for 2x2 units.
 +
| <=
 +
|- style="background-color:#ddffdd;"
 +
| '''createsMeleeThreat'''
 +
| Is this unit capable of CQC? Defaults are: false = for 2x2 units, true = for 1x1 units.
 +
| <=
 +
|- style="background-color:#ddffdd;"
 +
| '''meleeDodgeBackPenalty'''
 +
| Defines the penalty to unit's melee dodge ability (see '''meleeDodge''') when attacked from behind. Defined as percentage, e.g. 0.7 = 70%.
  
−
Defines an article in the in-game [[UFOpaedia]], listed in ''"ufopaedia:"''.
+
Note: The full penalty applies from behind, from sides the penalty is adjusted accordingly. There is no penalty for frontal assault.
 +
| 0.0
 +
|}
 +
 
 +
The following group of attributes has rather complicated definition (listed in a separate table just for convenience).
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
 
! width="150"| Value
 
! width="150"| Value
 
! width="*"  | Description
 
! width="*"  | Description
−
! width="80" | Default
+
! width="100" | Default
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''id'''
+
| '''psiDefence'''
−
| String ID of the article name. This must match the ID of the object associated with this article, if applicable.
+
| Formulae for psi defense value.
−
| ''required''
+
| vanilla
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''title'''
+
| '''meleeDodge'''
−
| String ID of the article title. If omitted, the '''id''' is used.
+
| Formulae for melee dodge chance.
−
| -
+
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''recovery.time'''
 +
| Formulae for TU recovery at the beginning of a new turn.
 +
 
 +
Note: this and all attributes below are defined under parent attribute '''recovery''' and a child attribute (time, energy, morale, etc.)
 +
| vanilla
 +
|- style="background-color:#ddffdd;"
 +
| '''recovery.energy'''
 +
| Formulae for Energy recovery at the beginning of a new turn.
 +
| vanilla
 +
|- style="background-color:#ddffdd;"
 +
| '''recovery.morale'''
 +
| Formulae for Morale recovery at the beginning of a new turn.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''recovery.health'''
 +
| Formulae for HP recovery at the beginning of a new turn.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''recovery.stun'''
 +
| Formulae for Stun Level recovery at the beginning of a new turn.
 +
| vanilla
 +
|- style="background-color:#ddffdd;"
 +
| '''recovery.mana'''
 +
| Formulae for mana recovery at the beginning of a new turn.
 +
| 0
 +
|}
 +
 
 +
<div style="background:#ddffdd;">Easiest way to explain how the formulaes are defined is using examples:
 +
 
 +
  armors:
 +
    - type: STR_TEST_ARMOR_1
 +
      meleeDodge:
 +
        reactions: 0.2              # 20% of reactions
 +
    - type: STR_TEST_ARMOR_2
 +
      recovery:
 +
        health:
 +
          stunNormalized: -0.1      # -10% of normalized stun
 +
        energy:
 +
          flatHundred: 0.1          # 10% of 100 = 10 :)
 +
          healthCurrent: 0.25        # 25% of current health
 +
 
 +
Armor 1 has melee dodge equal to 20% of soldier's reactions stat.
 +
 
 +
Armor 2 has negative HP recovery of 10% of soldier's normalized stun level (simulating slowly losing HP when in shock); and positive energy recovery of 10 + 25% of soldier's current health.
 +
 
 +
There are even more complicated examples with squared and cubed stats, see [[#Items|Items]] ruleset for some examples of that.
 +
 
 +
Possible keywords to use in the formulaes include:
 +
* flatOne, flatHundred, strength, psi, psiSkill, psiStrength, throwing, bravery, firing, health, tu, reactions, stamina, melee, strengthMelee, strengthThrowing, firingReactions, rank, fatalWounds, healthCurrent, tuCurrent, energyCurrent, moraleCurrent, stunCurrent, healthNormalized, tuNormalized, energyNormalized, moraleNormalized, stunNormalized, energyRegen, mana, manaCurrent, manaNormalized
 +
 
 +
'''FIXME''': describe what each keyword means
 +
</div>
 +
 
 +
=== Player Units (Soldiers) ===
 +
 
 +
Defines a [[soldier]] recruited by X-COM, listed in ''"soldiers:"''.
 +
 
 +
Unit stats are represented as follows:
 +
* [[Time Units|tu]]
 +
* [[Energy|stamina]]
 +
* [[Health|health]]
 +
* [[Bravery|bravery]] (always a multiple of 10)
 +
* [[Reactions|reactions]]
 +
* [[Firing Accuracy|firing]]
 +
* [[Throwing Accuracy|throwing]]
 +
* [[Strength|strength]]
 +
* [[Psi Strength|psiStrength]]
 +
* [[Psi Skill|psiSkill]]
 +
* [[Melee Accuracy|melee]]
 +
* [https://openxcom.org/forum/index.php/topic,7241.0.html mana] - OXCE only
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 
|-
 
|-
−
| '''type_id'''
+
| '''type'''
−
| Type of this article:
+
| String ID of the soldier type.
−
* 0 = Unknown
+
| ''required''
−
* 1 = [[Craft]]
 
−
* 2 = [[Craft Armaments]]
 
−
* 3 = [[HWP]]
 
−
* 4 = [[Equipment (EU)|Equipment]]
 
−
* 5 = [[Armour]]
 
−
* 6 = [[Base Facilities]]
 
−
* 7 = Text & Image (eg. [[Alien Life Forms]], [[UFO Components]])
 
−
* 8 = Text (eg. [[Alien Research]])
 
−
* 9 = [[UFO]]
 
−
* 10 = [[TFTD]]
 
−
* 11 = TFTD [[Subs]]
 
−
* 12 = TFTD [[Sub_Armaments]]
 
−
* 13 = TFTD [[Submersible_Weapons_Systems]]
 
−
* 14 = TFTD [[Equipment_(TFTD)]]
 
−
* 15 = TFTD Armour
 
−
* 16 = TFTD [[Base_Facilities_(TFTD)]]
 
−
* 17 = TFTD [[Alien_Subs]]
 
−
| 0
 
 
|-
 
|-
−
| '''section'''
+
| '''requires'''
−
| String ID of the UFOpaedia section this article belongs in.
+
| List of [[#Research|topics]] (string IDs) that must be researched to unlock this soldier type. If none are specified, this soldier type is unlocked from the start.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''requiresBuyBaseFunc'''
 +
| A list of services (for a given base) required to be able to hire this soldier type.
 
| -
 
| -
 
|-
 
|-
−
| '''requires'''
+
| '''minStats'''
−
| List of [[#Research|topics]] (string IDs) that must be researched to unlock this article. If none are specified, this article is unlocked from the start.
+
| Minimum values used to generate the soldier's [[Starting Stats]]. In this case, ''psiSkill'' is treated as the initial stat (not generated).
 
| -
 
| -
 
|-
 
|-
−
| '''image_id'''
+
| '''maxStats'''
−
| Filename of the [[UP001.SPK-UP042.SPK|background image]] displayed on this article, if applicable.
+
| Maximum values used to generate the soldier's [[Starting Stats]]. In this case, ''psiSkill'' is treated as the minimum value for the first month of psi training (actual value is 100%-150%).
 
| -
 
| -
 
|-
 
|-
−
| '''text'''
+
| '''statCaps'''
−
| String ID of the description displayed on this article.
+
| Maximum stats this soldier can gain through [[Experience]]. '''NOTE:''' A stat will still go over the limit once, and then will no longer increase (see [[Experience#Regarding Caps|Regarding Caps]]).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''trainingStatCaps'''
 +
| Maximum stats this soldier can gain through combat/martial training in the base.
 +
| '''statCaps'''
 +
|- style="background-color:#ddffdd;"
 +
| '''dogfightExperience'''
 +
| A list of probabilities (0-100%) to improve a stat (only bravery, firing or reactions) after a successful Dogfight.
 +
 
 +
  - type: STR_SOLDIER
 +
    dogfightExperience:
 +
      bravery: 20  # 20% chance of improvement by 10
 +
      reactions: 50 # 50% chance to improve by 1
 +
      firing: 100  # guaranteed to improve by 1
 +
 
 +
| -
 +
|-
 +
| '''armor'''
 +
| String ID of the [[#Armor|armor]] this soldier uses by default.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''armorForAvatar'''
 +
| When avatar display is activated in the Battlescape UI (instead of rank display)... which armor should the unit be wearing?
 +
 
 +
Note: things like Power/Flying Armor don't show the soldier's face, so you'd want to use Jumpsuits or Personal Armor.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''avatarOffsetX'''
 +
| Horizontal offset (in pixels) in the inventory sprite used for avatar display.
 +
| 67
 +
|- style="background-color:#ddffdd;"
 +
| '''avatarOffsetY'''
 +
| Vertical offset (in pixels) in the inventory sprite used for avatar display.
 +
| 48
 +
|- style="background-color:#ddffdd;"
 +
| '''flagOffset'''
 +
| Offset in the flag sprite collection to use for this soldier type.
 +
 
 +
Note: OXCE supports flag display per "nationality" (or better said per name pool file).
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''allowPromotion'''
 +
| Does this soldier type support promotion? Hint: combat dogs don't need a military hierarchy :)
 +
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''allowPiloting'''
 +
| Is this soldier type capable of piloting a craft? Sorry, no doggies piloting a Skyranger.
 +
| true
 +
|-
 +
| '''costBuy'''
 +
| Amount of money spent for hiring this soldier type. If set to 0, the soldier type will not be available in the Purchase/Recruit screen.
 +
| 0
 +
|-
 +
| '''costSalary'''
 +
| Amount of money spent monthly for employing this soldier type.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''costSalarySquaddie'''
 +
| Bonus to a salary for a Squaddie.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''costSalarySergeant'''
 +
| Bonus to a salary for a Sergeant.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''costSalaryCaptain'''
 +
| Bonus to a salary for a Captain.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''costSalaryColonel'''
 +
| Bonus to a salary for a Colonel.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''costSalaryCommander'''
 +
| Bonus to a salary for a Commander.
 +
| 0
 +
|-
 +
| '''standHeight'''
 +
| Height of this soldier when standing.
 +
| 0
 +
|-
 +
| '''kneelHeight'''
 +
| Height of this soldier when kneeling.
 +
| 0
 +
|-
 +
| '''floatHeight'''
 +
| Distance between the bottom of this unit and the ground.
 +
| 0
 +
|-
 +
| '''femaleFrequency'''
 +
| The probability that a female soldier is hired.
 +
| 50
 +
|-
 +
| '''value'''
 +
| The soldier's base value, without experience modifiers. Used for scoring in Debriefing.
 +
| 20
 +
|-
 +
| '''transferTime'''
 +
| The amount of time (in hours) it takes for new recruits of this soldier type to arrive at a base. If 0, global personnel transfer time is used instead.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''moraleLossWhenKilled'''
 +
| Percentage modifier for morale loss when this unit is killed.
 +
 
 +
Hint: set 0% for xcom security cameras and 500% for doggies.
 +
| 100
 +
|-
 +
| '''deathMale'''
 +
| Death sound(s) for male soldiers. Either a single sound ID or a list of sound IDs from [[#Extra_Sounds|BATTLE.CAT]].
 +
| -
 +
|-
 +
| '''deathFemale'''
 +
| Death sound(s) for female soldiers. Either a single sound ID or a list of sound IDs from [[#Extra_Sounds|BATTLE.CAT]].
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''selectUnitMale/selectUnitFemale'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this soldier is manually selected. A list of sound IDs can be used too.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''startMovingMale/startMovingFemale'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this soldier starts moving. A list of sound IDs can be used too.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''selectWeaponMale/selectWeaponFemale'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this soldier's weapon is selected. A list of sound IDs can be used too.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''annoyedMale/annoyedFemale'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this soldier is repeatedly manually selected. A list of sound IDs can be used too.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''panicMale'''
 +
| Panic sound(s) for male soldiers. Either a single sound ID or a list of sound IDs from [[#Extra_Sounds|BATTLE.CAT]].
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''panicFemale'''
 +
| Panic sound(s) for female soldiers. Either a single sound ID or a list of sound IDs from [[#Extra_Sounds|BATTLE.CAT]].
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''berserkMale'''
 +
| Berserk sound(s) for male soldiers. Either a single sound ID or a list of sound IDs from [[#Extra_Sounds|BATTLE.CAT]].
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''berserkFemale'''
 +
| Berserk sound(s) for female soldiers. Either a single sound ID or a list of sound IDs from [[#Extra_Sounds|BATTLE.CAT]].
 +
| -
 +
|-
 +
| '''soldierNames'''
 +
| List of soldier name files/paths. Use '''delete''' to clear previously-loaded names.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''statStrings'''
 +
| Override of global stat strings for this soldier type.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''rankStrings'''
 +
| Override for classic xcom ranks. You can have for example only Rookies and Veterans for a certain soldier type.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''rankSprite'''
 +
| Offset for rank sprites for this soldier type in BASEBITS.PCK
 +
| 42
 +
|- style="background-color:#ddffdd;"
 +
| '''rankBattleSprite'''
 +
| Offset for rank sprites for this soldier type in SMOKE.PCK
 +
| 20
 +
|- style="background-color:#ddffdd;"
 +
| '''rankTinySprite'''
 +
| Offset for rank sprites for this soldier type in TinyRanks
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''skillIconSprite'''
 +
| Sprite ID from SPICONS.DAT used to draw the soldier skills icon.
 +
| 1
 +
|- style="background-color:#ddffdd;"
 +
| '''skills'''
 +
| A list of soldier skills.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7974.0.html
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''showTypeInInventory'''
 +
| If set to true, the soldier type will be displayed in the inventory screen.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''specialWeapon'''
 +
| Allows to define a special weapon on the soldier type (instead of the armor type).
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7859.0.html
 +
| -
 +
|}
 +
 
 +
=== Soldier Transformation ===
 +
 
 +
<div style="background:#ddffdd;">Defines rules for soldier transformations, listed in ''"soldierTransformation:"''.
 +
 
 +
Allows doing things like:
 +
* transforming soldiers into MECs
 +
* resurrecting/cloning dead soldiers... useful for streamers/LPers, who want to easily maintain viewer's names
 +
* assigning soldier bonuses
 +
* and much more...
 +
 
 +
'''More info''': https://openxcom.org/forum/index.php/topic,6331.0.html
 +
</div>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''name'''
 +
| String ID of the soldier transformation type.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''requires'''
 +
| A list of research projects required before this project appears in the list of available transformations, the default empty list means this project is available from the beginning of the game.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''requiresBaseFunc'''
 +
| A list of services required at a base in order to do this project, the default empty list means no special services are required.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''producedItem'''
 +
| The item a soldier should be transformed into. The soldier is completely removed from the game.
 +
 
 +
Modding tips: sacrifices for special resources/weapons, transform specialists into resources needed to build special facilities, etc.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''producedSoldierType'''
 +
| The type of soldier produced by this project - any soldier undergoing this transformation will be switched to this type. If left empty, the soldier type does not change.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''producedSoldierArmor'''
 +
| The armor the soldier will have when the project finishes, only used when '''keepSoldierArmor''' is false. Leaving it empty will give the soldier the default armor for the correspondiing soldier type.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''keepSoldierArmor'''
 +
| Determines whether or not the soldier will keep the armor they're wearing through this transformation.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''createsClone'''
 +
| Determines whether the selected soldier has the transformation done to them or a new soldier is created that is a copy of the original and the transformation is done to the new soldier.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''needsCorpseRecovered'''
 +
| If your project allows dead soldiers, this determines whether or not you needed to have a corpse item available at the end of the battle in which the soldier died. This does not mean you need the corpse item in your stores, just that it would have been recovered if ''recover: true'' was set on the item.
 +
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''allowsDeadSoldiers'''
 +
| Can dead soldiers undergo this transformation? If so, they are brought back to life at the base you started this project in.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''allowsLiveSoldiers'''
 +
| Can live, non-wounded soldiers undergo this transformation?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''allowsWoundedSoldiers'''
 +
| Can wounded soldiers undergo this transformation?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''allowedSoldierTypes'''
 +
| This list determines which soldier types can undergo this transformation, the default empty list means nobody can have this project done to them.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''requiredPreviousTransformations'''
 +
| A list of transformation projects that must be done to a soldier before they're eligible for this project, the default empty list means no previous projects are required.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''forbiddenPreviousTransformations'''
 +
| A list of transformation projects that a soldier cannot have undergone in order to be eligible for this project, the default empty list means no previous projects are forbidden.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''minRank'''
 +
| The minimum rank a soldier must have in order to be eligible for this project, from 0=rookie to 5=commander.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''includeBonusesForMinStats'''
 +
| If set to true, soldier bonuses will be included when comparing soldier stats against '''requiredMinStats'''.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''requiredMinStats'''
 +
| The minimum stats a soldier must have in order to be eligible for this project, defaults to all 0 so any soldier is eligible.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''requiredItems'''
 +
| A list of items that must be consumed from the base's stores in which you start this project, the default empty list means no items are used.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''requiredCommendations'''
 +
| A list of commendations (with a minimum decoration level) required to start this project. The default empty list means no commendations are required.
 +
 
 +
Example: https://openxcom.org/forum/index.php/topic,7405.msg117870.html#msg117870
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''cost'''
 +
| The cost of the project in dollars.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''transferTime'''
 +
| Soldiers can be put in a transfer back to the base where they started if this parameter is greater than the default of 0 hours. New clones or resurrected soldiers are automatically given a transfer to the base with a default of 24 hours.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''recoveryTime'''
 +
| The amount of wound recovery time a soldier is given after this project completes and the transfer, if any, is completed. The default value is 0 days.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''flatOverallStatChange'''
 +
| A direct change to the soldier's overall stats when undergoing this project, can be positive or negative - tu: 5 means the soldier will gain 5 max time units, while tu: -5 means the soldier will lose 5 max time units. The default of 0 means no change.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''flatMin'''<br>
 +
'''flatMax'''
 +
| Similar to '''flatOverallStatChange''', but allows to specify a range from which the game chooses randomly.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7196.msg117768.html#msg117768
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''percentOverallStatChange'''
 +
| A percent change to the soldier's overall stats when undergoing this project, can be positive or negative - tu: 5 means the soldier will gain an extra 5% of their max time units, while tu: -5 means the soldier will lose 5% of their max time units. The default of 0 means no change.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''percentMin'''<br>
 +
'''percentMax'''
 +
| Similar to '''percentOverallStatChange''', but allows to specify a range from which the game chooses randomly.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''percentGainedStatChange'''
 +
| A percent change to the soldier's stats, but instead of taking a portion of the overall stats, this only applies to the stats they've trained up from their initial values, can be positive or negative - firing: -100 means the soldier will lose all of the firing accuracy they trained since joining, while firing: 10 means they gain 10% of the amount they trained over their initial values. The default of 0 means no change.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''percentGainedMin'''<br>
 +
'''percentGainedMax'''
 +
| Similar to '''percentGainedStatChange''', but allows to specify a range from which the game chooses randomly.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''showMinMax'''
 +
| If enabled, the GUI will show random improvement as min/max range. If disabled, it will show just a question mark.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''rerollStats'''
 +
| This attribute allows you to specify, which stats should be completely re-rolled.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7196.msg117767.html#msg117767
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''lowerBoundAtMinStats'''
 +
| Determines whether or not any changes in stats from this project should go below the minStats defined on the new soldier type.
 +
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''upperBoundAtMaxStats'''
 +
| Determines whether or not any changes in stats from this project should go above the maxStats defined on the new soldier type.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''upperBoundAtStatCaps'''
 +
| Determines whether or not any changes in stats from this project should go above the statCaps defined on the new soldier type.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''upperBoundType'''
 +
| Determines how strictly to apply '''upperBoundAtMaxStats''' and '''upperBoundAtStatCaps'''. Possible values:
 +
* 0 = dynamic (i.e. soft when not changing the soldier type; hard when changing the soldier type)
 +
* 1 = soft (if the soldier is already above the maximum before the transformation, don't reduce his overflown stats)
 +
* 2 = hard (always reduce if above the maximum)
 +
| 0
 +
 
 +
 
 +
|- style="background-color:#ddffdd;"
 +
| '''reset'''
 +
| The reset flag can be used to clear the bonuses gained by previous transformations. It also clears the list of previously performed transformations.
 +
 
 +
For example:
 +
1. you train karate and gain a bonus
 +
2. then you transform the guy into a MEC and want to lose all the previous bonuses (since MECs can't benefit from karate training... I hope)
 +
 
 +
Note: stats gained by "classic" transformations (i.e. those that are NOT bonuses) will NOT be reset; only bonuses can be reset
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''soldierBonusType'''
 +
| ID of a soldier bonus applied to a soldier undergoing this transformation.
 +
| -
 +
|}
 +
 
 +
=== Soldier Bonuses ===
 +
 
 +
<div style="background:#ddffdd;">
 +
Defines rules for soldier bonuses, listed in ''"soldierBonuses:"''.
 +
 
 +
Bonuses can be manually awarded by the player via '''soldier transformations'''; or automatically awarded together with a '''soldier commendations/medals'''.
 +
 
 +
'''More info''': https://openxcom.org/forum/index.php/topic,7405.0.html
 +
</div>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''name'''
 +
| String ID of the soldier bonus type.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''visibilityAtDark'''
 +
| Defines the bonus to night vision (in tiles). Cannot go beyond global maximum view distance.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''stats'''
 +
| Defines the bonus to soldier's stats (same way as the armor can). Can go even beyond any cap/maximum.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''recovery'''
 +
| Defines the bonus to soldier's resource recovery every turn (same way as the armor can). Affects time units, energy, health, stun, morale and mana.
 +
| -
 +
|}
 +
 
 +
=== Soldier Skillls ===
 +
 
 +
<div style="background:#ddffdd;">
 +
Defines rules for soldier skills, listed in ''"skills:"''.
 +
 
 +
'''More info''': https://openxcom.org/forum/index.php/topic,7974.0.html
 +
</div>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''type'''
 +
| String ID of the soldier skill type.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''targetMode'''
 +
| Target mode for the skill. Possible options:
 +
* 0 = No target needed (just activation, script takes over) - BA_NONE
 +
* 10  = Melee-range targeting (1 tile) - BA_HIT
 +
* 7,8,9 = Firearm ranged targeting - BA_AUTO = 7, BA_SNAP = 8, BA_AIMED = 9
 +
* 11,13,14 = Psi targeting (with or without LOS) - BA_USE = 11, BA_MINDCONTROL = 13, BA_PANIC = 14
 +
* 6 = Thrown targeting - BA_THROW
 +
* 12 = Waypoint targeting - BA_LAUNCH
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''isPsiRequired'''
 +
| Is Psi Skill required for this skill to work?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''requiredBonuses'''
 +
| Defines the list of required soldier bonuses for this skill.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''costUse'''
 +
| Defines the use cost for this skill.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''flatUse'''
 +
| Defines the flat vs. percentage cost flags for the use cost of this skill.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''compatibleWeapons'''
 +
| Defines the list of weapons which are compatible with this skill.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''checkHandsOnly'''
 +
| Should the check for compatible items only consider the hands (or also the inventory and specialweapon)?
 +
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''battleType'''
 +
| Defines the battle type of compatible items (0-11). E.g. 1=firearm, 3=melee weapon, 9=psiamp, etc.
 +
 
 +
This is used as fall-back if no '''compatibleWeapons''' are specified or found.
 +
| -
 +
|}
 +
 
 +
=== Soldier Commendations ===
 +
 
 +
'''FIXME''' Someone please document this...
 +
 
 +
<div style="background:#ddffdd;">
 +
In OXCE, you can also use soldier commendations to assign soldier bonuses (see above).
 +
Bonuses are defined per decoration level.
 +
You don't need to define all decoration levels... if a soldier has a higher decoration level than defined, the highest available is used.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7405.msg116840.html#msg116840
 +
 
 +
Example:
 +
 
 +
  commendations:
 +
    - type: STR_MEDAL_ALIENS_KILLED
 +
      description: STR_MEDAL_ALIENS_KILLED_DESCRIPTION
 +
      sprite: 1
 +
      soldierBonusTypes: [STR_KILL1, STR_KILL2, STR_KILL3, STR_KILL4]          # various bonuses for various decoration levels
 +
      criteria:
 +
        killsWithCriteriaCareer: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
 +
      killCriteria:
 +
        -
 +
          - [1, ["STATUS_DEAD", "FACTION_HOSTILE"]]
 +
 
 +
</div>
 +
 
 +
=== AI Units (Aliens/Civilians) ===
 +
 
 +
Defines an [[Alien Life Forms|alien]] (enemy) or [[civilian]] (neutral) unit, listed in ''"units:"''. Every different alien rank is a different unit, since they have completely different stats. Unit stats are represented as follows:
 +
* [[Time Units|tu]]
 +
* [[Energy|stamina]]
 +
* [[Health|health]]
 +
* [[Bravery|bravery]] (always a multiple of 10)
 +
* [[Reactions|reactions]]
 +
* [[Firing Accuracy|firing]]
 +
* [[Throwing Accuracy|throwing]]
 +
* [[Strength|strength]]
 +
* [[Psi Strength|psiStrength]]
 +
* [[Psi Skill|psiSkill]]
 +
* [[Melee Accuracy|melee]]
 +
* [https://openxcom.org/forum/index.php/topic,7241.0.html mana] - OXCE only
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| String ID of the unit name.
 +
| ''required''
 +
|-
 +
| '''race'''
 +
| String ID of the unit race (for alien units).
 +
| -
 +
|-
 +
| '''rank'''
 +
| String ID of the unit rank (for alien units).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''spotter'''
 +
| The spotter score. Determines how many turns sniper AI units can act on this unit seeing your troops.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''sniper'''
 +
| The sniper score. Determines the chances of firing from out of LOS on spotted units.
 +
| 0
 +
|-
 +
| '''stats'''
 +
| Battlescape stats of this unit.
 +
| -
 +
|-
 +
| '''armor'''
 +
| String ID of the [[#Armor|armor]] this unit uses by default.
 +
| -
 +
|-
 +
| '''standHeight'''
 +
| Height of this unit when standing.
 +
| 0
 +
|-
 +
| '''kneelHeight'''
 +
| Height of this unit when kneeling. Not supported in OpenXcom yet, for future use?
 +
| 0
 +
|-
 +
| '''floatHeight'''
 +
| Distance between the bottom of this unit and the ground.
 +
| 0
 +
|-
 +
| '''value'''
 +
| [[Score]] this unit is worth.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''civilianRecoveryType'''
 +
| Gets the type of staff (soldier/engineer/scientists) or type of item to be recovered when a civilian is saved.
 +
| -
 +
|-
 +
| '''intelligence'''
 +
| Intelligence of this unit's AI. The higher the value, the longer this unit remembers player troops between turns.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''waitIfOutsideWeaponRange'''
 +
| Should the unit get "stuck" trying to fire from outside of weapon range? OXC bug, that may serve as "feature" in rare cases.
 +
 
 +
Note: the default value is to fix the OXC bug.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''canSurrender'''
 +
| Can this unit surrender?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''autoSurrender'''
 +
| Does this unit surrender automatically, if all other units surrendered too?
 +
| false
 +
|-
 +
| '''aggression'''
 +
| Aggression of this unit's AI. The higher the value, the more ruthless the unit, the more likely to make a frontal/melee assault. Less aggressive units tend to set up ambushes.
 +
Possible values are:
 +
* 0 = mostly passive
 +
* 1 = balanced
 +
* 2+ = mostly aggressive (meaningful values are between 2 and 8)
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''isLeeroyJenkins'''
 +
| Unit marked as "leeroy" must have a melee weapon (and be able to use it). It will completely ignore vanilla AI "decision making" and run around (using vanilla patrol routine) until it spots someone and then charge at the nearest target (if multiple spotted).
 +
 
 +
Charge is mostly vanilla/OXCE, with the following differences:
 +
* ignore remaining TUs (charge even if not enough TUs to attack now)
 +
* ignore dangerous tiles (grenades? pfff!)
 +
* ignore OXCE melee dodge (leeroy is not intelligent enough to attack from behind)
 +
| false
 +
|-
 +
| '''energyRecovery'''
 +
| Energy recovered by the unit each turn.
 +
| 30
 +
|-
 +
| '''specab'''
 +
| Special ability of this unit:
 +
* 0 = None
 +
* 1 = [[Cyberdisc|Explodes on Death]] (Requires '''power''' and '''blastRadius''' properties to be set on the corpse)
 +
* 2 = [[Silacoid|Burns Floor]]
 +
* 3 = [[Bio-Drone|Burns Floor and explodes on Death]]
 +
| 0
 +
|-
 +
| '''spawnUnit'''
 +
| String ID of the unit used to respawn on death (e.g. [[Zombie]]s respawn as [[Chrysallid]]s).
 +
| -
 +
|-
 +
| '''livingWeapon'''
 +
| Is this unit a living weapon?
 +
If yes, it ignores any weapon loadout associated with its rank in the alien deployment and only attacks with a weapon derived from its name (must be marked as '''fixedWeapon'''). The weapon's name is the unit's type without the first 4 letters (STR_) and with a suffix (_WEAPON). For example: STR_REAPER => REAPER_WEAPON.
 +
| false
 +
|-
 +
| '''meleeWeapon'''
 +
| This unit's built-in melee weapon (e.g. Lobsterman's Claws). Does not appear in the inventory.
 +
| -
 +
|-
 +
| '''psiWeapon'''
 +
| This unit's built-in psi weapon. Ignored if the unit doesn't have any psi skill. Does not appear in the inventory.
 +
| ALIEN_PSI_WEAPON
 +
|-
 +
| '''capturable'''
 +
| Can this unit be captured alive?
 +
 
 +
Note: units which cannot be captured alive are insta-killed when they fall unconscious.
 +
| true
 +
|-
 +
| '''builtInWeaponSets'''
 +
| A set of lists of weapons this unit can come pre-equipped with. Game will pick one set "at random" (randomness comes from the current alien tech level definition). These weapons WILL appear in inventory slots (references items).
 +
| -
 +
|- style="color:#666666;"
 +
| '''builtInWeapons'''
 +
| ''Deprecated:'' use '''builtInWeaponSets''' instead.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''moraleLossWhenKilled'''
 +
| Percentage modifier for morale loss when this unit is killed.
 +
 
 +
Tip: set for example 50% for cannon fodder and 300% for VIPs.
 +
| 100
 +
|-
 +
| '''deathSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this unit dies. No value means no sound upon death. A list of sound IDs can be used too, the game then chooses one randomly each time.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''selectUnitSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this unit is manually selected. A list of sound IDs can be used too.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''startMovingSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this unit starts moving. A list of sound IDs can be used too.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''selectWeaponSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this unit's weapon is selected. A list of sound IDs can be used too.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''annoyedSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this unit is repeatedly manually selected. A list of sound IDs can be used too.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''panicSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this unit panics. A list of sound IDs can be used too.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''berserkSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this unit berserks. A list of sound IDs can be used too.
 +
| -
 +
|-
 +
| '''aggroSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this unit aggros.
 +
| -1
 +
|-
 +
| '''moveSound'''
 +
| Sound ID from [[#Extra_Sounds|BATTLE.CAT]] played when this unit moves.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''showFullNameInAlienInventory'''
 +
| Defines whether the [Alien Inventory] screen (accessible via middle-click on a unit) should display a unit's type/name or just a unit's race.
 +
 
 +
Possible options:
 +
* -1 = use global setting (show the race by default)
 +
* 0 = show the race (e.g. Sectoid)
 +
* 1 = show the type (e.g. Sectoid Leader)
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''pickUpWeaponsMoreActively'''
 +
| Allows AI to pick up weapons more actively. More info: https://openxcom.org/forum/index.php/topic,6882.0.html
 +
 
 +
Possible options:
 +
* -1 = use global setting (disabled by default)
 +
* 0 = disabled
 +
* 1 = enabled
 +
| -1
 +
|}
 +
 
 +
=== Alien Races ===
 +
 
 +
Defines a [[Alien Life Forms|race]] used in [[Alien Missions]], listed in ''"alienRaces:"''. Heavily tied with deployment data.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''id'''
 +
| String ID of the alien race name.
 +
| ''required''
 +
|-
 +
| '''members'''
 +
| Alien crew associated with this alien race (e.g. race units + terrorist units), defined by a list of unit string IDs. Order here will define rank in terms of deployment. Generally speaking the order is:
 +
* 0 - Commander
 +
* 1 - Leader
 +
* 2 - Engineer
 +
* 3 - Medic
 +
* 4 - Navigator
 +
* 5 - Soldier
 +
* 6 - Terrorist 1
 +
* 7 - Terrorist 2
 +
but of course, not all races have all ranks, so the "fill in" rank would be listed multiple times (see Ethereals).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''membersRandom'''
 +
| Alternative to '''members'''. Instead of defining just a single unit type per alien rank, you can define any number of unit types here and one will be chosen randomly (each time a new unit is generated). To increase a chance of a certain unit type being selected, you can add it multiple times.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''retaliationMission'''
 +
| String ID of an alien mission, that can be generated after a dogfight against this race. If empty, a random retaliation mission will be used instead.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''retaliationAggression'''
 +
| A flat percentage to modify the dogfight retaliation odds for this race. Positive value increases odds, negative value decreases odds.
 +
Example: Normal retaliation odds for Veteran difficulty (in UFO) are 12%. If this number is set to 20, the odds will increase to 32%.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''baseCustomMission'''
 +
| String ID of an alien deployment ('''not alien mission!!''') override for all alien bases inhabited by this alien race.
 +
 
 +
Applies to:
 +
* all starting condition checks
 +
* additional mission description, see '''alertDescription'''
 +
* everything done during the Battlescape generation
 +
* everything done during the Debriefing
 +
 
 +
Does '''not''' apply to anything else (that depends on alien deployment), for example:
 +
* alien base supply mission
 +
* alien base hunt missions
 +
* alien base upgrades
 +
* etc.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''baseCustomDeploy'''
 +
| A lighter version of '''baseCustomMission''', which only overrides the [[#Deployment Data|deployment data]] used during the Battlescape generation.
 +
 
 +
Note: if both '''baseCustomMission''' and '''baseCustomDeploy''' are specified, [[#Deployment Data|deployment data]] is taken from '''baseCustomDeploy''' and everything else is taken from '''baseCustomMission'''.
 +
| -
 +
|}
 +
 
 +
=== Alien Deployments ===
 +
 
 +
Defines a Battlescape deployment data used in [[Alien Missions]] (such as alien and map configurations), listed in ''"alienDeployments:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| String ID of the deployment name.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''isHidden'''
 +
| If enabled, the mission will not appear in the mission list in New Battle GUI. Doesn't work when debug is enabled in options.cfg.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''customUfo'''
 +
| String ID of a UFO to be used in mapscripts in addUFO command. This allows to reuse the same script for many deployments.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7631.0.html
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''startingCondition'''
 +
| String ID of a [[#Battle Starting Conditions|starting condition]] for missions using this deployment.
 +
 
 +
Note: overrides any globe texture starting condition.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''enviroEffects'''
 +
| String ID of [[#Battle Enviro Effects|enviro effects]] for missions using this deployment.
 +
 
 +
Note: overrides any mission terrain enviro effects.
 +
| -
 +
|-
 +
| '''data'''
 +
| List of deployment data for each alien rank on this mission (see below).
 +
| -
 +
|-
 +
| '''width'''
 +
| Width of the Battlescape map in grid units.
 +
| 0
 +
|-
 +
| '''length'''
 +
| Length of the Battlescape map in grid units.
 +
| 0
 +
|-
 +
| '''height'''
 +
| Vertical height of the Battlescape map in grid units.
 +
| 0
 +
|-
 +
| '''civilians'''
 +
| Maximum number of civilians to spawn. The actual number of civilians spawned will be between 50-100% of the specified maximum.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''civilianSpawnNodeRank'''
 +
| Map node rank to spawn civilians on.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,6477.0.html
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''civiliansByType'''
 +
| A list of additional civilians to spawn, each list item is defined by a civilian type ID and a maximum number (type: number). The actual number of civilians spawned will be again between 50-100% of the specified maximum, but this time the 50% is rounded up (for '''civilians''' attribute it is rounded down).
 +
| -
 +
|-
 +
| '''terrains'''
 +
| List of string IDs of the [[#Terrains|terrains]] to choose from when generating the map. Not used for UFO land/crash sites, terrain comes from the Geoscape globe texture.
 +
| -
 +
|-
 +
| '''shade'''
 +
| Shade of the map (0-15, where 0 is full daytime and 15 is full nighttime). If not specified (e.g. for UFO land/crash sites), the shade comes from the Geoscape globe.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''minShade'''
 +
| Minimum shade of the map (0-15). Used only when '''shade''' is not set, to adjust the shade coming from the Geoscape globe.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''maxShade'''
 +
| Maximum shade of the map (0-15). Used only when '''shade''' is not set, to adjust the shade coming from the Geoscape globe.
 +
| -1
 +
|-
 +
| '''nextStage'''
 +
| String ID of the next deployment stage to use after this one, for multi-stage missions.
 +
| -
 +
|-
 +
| '''race'''
 +
| Sets (overrides) the alien race to use when generating the map.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''randomRace'''
 +
| Sets (overrides) the alien race to use when generating the map. Unlike '''race''' attribute, this is a list of multiple possible races; one is chosen randomly at runtime.
 +
| -
 +
|-
 +
| '''finalDestination'''
 +
| Sets whether this mission is where you send your [[Avenger|uber-craft]] to win the game.
 +
| false
 +
|-
 +
| '''winCutscene'''
 +
| Sets the cutscene to play when you win the mission. If set to "winGame" or "loseGame", the player will be returned to the main menu after the cutscene plays.
 +
| -
 +
|-
 +
| '''loseCutscene'''
 +
| Sets the cutscene to play when you lose the mission. If set to "winGame" or "loseGame", the player will be returned to the main menu after the cutscene plays.
 +
| -
 +
|-
 +
| '''abortCutscene'''
 +
| Sets the cutscene to play when you abort the mission. If set to "winGame" or "loseGame", the player will be returned to the main menu after the cutscene plays.
 +
| -
 +
|-
 +
| '''script'''
 +
| Map script used to generate the map (overrides the map script from terrain definition).
 +
| -
 +
|-
 +
| '''alert'''
 +
| String ID of the message to display in the alert popup when this mission spawns on the Geoscape.
 +
| STR_ALIENS_TERRORISE
 +
|-
 +
| '''alertBackground'''
 +
| String ID of the background image to use in the alert popup when this mission spawns on the Geoscape.
 +
| BACK03.SCR
 +
|- style="background-color:#ddffdd;"
 +
| '''alertDescription'''
 +
| String ID of the additional mission description (displayed when clicking on the [Info] button on the [Target Info] screen).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''alertSound'''
 +
| Sound ID from GEO.CAT to be played when the [Mission Detected] screen pops up.
 +
| -1
 +
|-
 +
| '''briefing'''
 +
| Data for the mission briefing (see below).
 +
| -
 +
|-
 +
| '''markerName'''
 +
| String ID that identifies this mission type on the Geoscape.
 +
| STR_TERROR_SITE
 +
|-
 +
| '''markerIcon'''
 +
| What icon should be used to represent this base/site (taken from GlobeMarkers section in extraSprites)
 +
| -1
 +
|-
 +
| '''depth'''
 +
| [''min'', ''max''] -- Defines the depth range to randomly choose from for this mission.
 +
| [0, 0]
 +
|-
 +
| '''duration'''
 +
| [''min'', ''max''] -- Minimum and maximum duration of this mission on the Geoscape (in hours).
 +
 
 +
'''Important''': mission duration should be at least 2 hours... if it's just 1 hour and it spawns at the whole hour, it also despawns at the same moment... and crashes the game!
 +
| [0, 0]
 +
|-
 +
| '''music'''
 +
| The list of musics this mission can choose from (if not specified, the music is taken from the terrain).
 +
| -
 +
|-
 +
| '''points'''
 +
| Negative score applied for each day this mission is active (applied daily for bases, or every half hour for mission sites)
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''unlockedResearch'''
 +
| String ID of a research topic that will be granted for free (only if the mission is finished successfully).
 +
 
 +
Note: there will be no Ufopaedia article shown nor any other related effect; the research will just be silently added into the list of finished research projects.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''missionBountyItem'''
 +
| String ID of an item that will be added to base stores for free (only if the mission is finished successfully).
 +
 
 +
Note: the player will be informed in the Debriefing screen.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''bughuntMinTurn'''
 +
| Possibility to override global bug hunt minimum turn for this alien deployment only (usually to set a higher number for longer missions).
 +
| 0 (no change)
 +
|}
 +
 
 +
The following group of attributes is related only to alien bases (listed in a separate table just for convenience).
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''alienBase'''
 +
| Does this deployment correspond to an alien base assault? Used only in New Battle mode.
 +
| false
 +
|-
 +
| '''genMission'''
 +
| Which alien mission should this base generate?
 +
Usually supply mission - can be used to generate any mission type except Mission Sites (UFO will be generated, but the site will never appear)
 +
| -
 +
|-
 +
| '''genMissionFreq'''
 +
| Daily chance for the base mission to be generated.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''genMissionLimit'''
 +
| Maximum number of times the '''genMission''' can be generated.
 +
| 1000
 +
|- style="background-color:#ddffdd;"
 +
| '''baseSelfDestructCode'''
 +
| Discovering this research topic destroys all corresponding alien bases immediately.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''baseDetectionRange'''
 +
| Radar detection range (in nautical miles) for an alien base. If more than 0, the base actively scans for xcom craft and generates xcom craft hunt missions.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''baseDetectionChance'''
 +
| Chance (0-100%) of the base radar detecting a craft that enters its range.
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''huntMissionMaxFrequency'''
 +
| The maximum frequency (in minutes) of hunt missions generated by an alien base.
 +
| 60
 +
|- style="background-color:#ddffdd;"
 +
| '''huntMissionWeights'''
 +
| A weighted list of hunt missions a base can generate, listed by "number of months passed".
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''alienBaseUpgrades'''
 +
| A weighted list of alien base upgrades, listed by "number of months passed".
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''fakeUnderwaterSpawnChance'''
 +
| Chance (in percent) for the alien base to spawn on "fake underwater" globe texture.
 +
| 0
 +
|}
 +
 
 +
The following group of attributes is related to mission objectives (listed in a separate table just for convenience).
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''allowObjectiveRecovery'''
 +
| Can map objects of type defined by '''objectiveType''' be recovered or not?
 +
| false
 +
|-
 +
| '''objectiveType'''
 +
| Defines which type of MCD to check for when tallying mission objectives.
 +
| -1
 +
|-
 +
| '''objectivesRequired'''
 +
| How many of the tile types (defined in '''objectiveType''') must be destroyed in order for the mission to be considered a success.
 +
| 0
 +
|-
 +
| '''objectivePopup'''
 +
| Defines the message that will appear between turns, after the objective requirements have been fulfilled.
 +
| -
 +
|-
 +
| '''objectiveComplete'''
 +
| The string and score adjustment to be shown on the mission debriefing.
 +
| [-, 0]
 +
|-
 +
| '''objectiveFailed'''
 +
| The string and score adjustment to be shown on the mission debriefing.
 +
| [-, 0]
 +
|-
 +
| '''despawnPenalty'''
 +
| How many points the aliens will receive when this site despawns due to XCom negligence.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''abortPenalty'''
 +
| How many points the xcom will lose when this mission is aborted.
 +
| 0
 +
|-
 +
| '''cheatTurn'''
 +
| When the aliens became aware of all your units (in vanilla it was after turn 20)
 +
| 20
 +
|-
 +
| '''turnLimit'''
 +
| The amount of turns before the mission ends automatically.
 +
| 0 (no limit)
 +
|-
 +
| '''chronoTrigger'''
 +
| What happens when the timer reaches 0. Possible values:
 +
* 0 = Lose
 +
* 1 = Abort
 +
* 2 = Win
 +
* <span style="background:#ddffdd;">3 = Win + all enemies surrender</span>
 +
| 0
 +
|-
 +
| '''escapeType'''
 +
| Which type of tiles can be used for escape. Possible values:
 +
* 0 = None
 +
* 1 = Exit tiles
 +
* 2 = Entry tiles
 +
* 3 = Either
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''keepCraftAfterFailedMission'''
 +
| Defines whether the craft should be lost after a failed mission or not. Useful for example for timed missions where the craft doesn't wait for you (e.g. escape/extraction missions).
 +
| false
 +
|}
 +
 
 +
Notes:
 +
* turnLimit is used to define the turn where the game ends, default is 0 (no limit). If the value is changed from default then the game will display the number of turns on the 'Hidden Movement' screens as '1/20', '2/20', etc., and the numbers will switch to red when there's less than 3 turns remaining.
 +
* chronoTrigger is used with turnLimit and defines what happens when the turn limit is reached. There are 3 possible settings:
 +
** 0 (default) = forces a Loss, meaning that the player loses everything if the mission isn't completed by the time the turn limit is reached. All units are declared dead or MIA when the game ends. This is ideal for bomb defusal type missions.
 +
** 1 = forces a Abort, this is almost the same as above, with the exception that there must be at least 1 soldier on an exit-only area (like the green room on the 1st stage of Cydonia) to win at the end of the turn limit. This setting is better used for multi-stage missions where you'll need to bring at least 1 soldier to the next stage.
 +
** 2 = forces a Win, where if you have at least 1 live unit at the end of the turn limit you'll win the mission, regardless of where the soldiers are. This is meant for Survival scenarios.
 +
** <span style="background:#ddffdd;">3 = forces a Win, same way as in option 2, but additionally all remaining enemies surrender.</span>
 +
** Regardless of the setting, the player can always still win by eliminating all alien units before the turn limit, or fail the mission by losing all units.
 +
* cheatTurn allows to define the turn where the AI becomes aware of all your units (default is 20) for individual missions. Once this turn is reached the aliens will be forced to go into attack mode and engage your units. This is effectively a cheat for the AI which was present on the original game.
 +
 
 +
==== Deployment Data ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''alienRank'''
 +
| [[Alien Rank|Rank]] associated with this deployment data, as defined by the order of the race in question (see above)
 +
| ''required''
 +
|-
 +
| '''lowQty'''
 +
| Minimum quantity of aliens to spawn on beginner/experienced.
 +
| ''required''
 +
|-
 +
| '''highQty'''
 +
| Minimum quantity of aliens to spawn on superhuman. (minimum quantity for veteran/genius is the median of this and the previous value)
 +
| ''required''
 +
|-
 +
| '''dQty'''
 +
| Delta in Quantity, i.e. random number of aliens to spawn on top of the minimum (all difficulties).
 +
| ''required''
 +
|-
 +
| '''extraQty'''
 +
| Functionally identical to dQty, spawns a random number of additional aliens.
 +
| 0
 +
|-
 +
| '''percentageOutsideUfo'''
 +
| Percentage (0-100%) of aliens to spawn outside of the UFO (in UFO land/crash sites).
 +
| ''required''
 +
|-
 +
| '''itemSets'''
 +
| Three lists (one for each alien technology level) of [[#Items|items]] (string IDs) for the aliens to equip.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''extraRandomItems'''
 +
| One or more item lists with extra equipment. One item will be chosen from each list randomly.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7055.msg111746.html#msg111746
 +
| -
 +
|}
 +
 
 +
==== Briefing Data ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''palette'''
 +
| The color swatch to use from [[BACKPALS.DAT]].
 +
| 0
 +
|-
 +
| '''textOffset'''
 +
| Number of pixels to vertically offset the briefing text.  Larger values move the text further down the screen.
 +
| 0
 +
|-
 +
| '''title'''
 +
| String ID for a custom briefing title text. Defaults to the same name as the ''alienDeployment''.
 +
| -
 +
|-
 +
| '''desc'''
 +
| String ID for a custom briefing description text. Defaults to the same name as the ''alienDeployment + _BRIEFING''.
 +
| -
 +
|-
 +
| '''music'''
 +
| The ID of the music to play.
 +
| GMDEFEND
 +
|-
 +
| '''cutscene'''
 +
| Sets the cutscene to play before the mission briefing.
 +
| -
 +
|-
 +
| '''background'''
 +
| The background screen to show.
 +
| BACK16.SCR
 +
|-
 +
| '''showCraft'''
 +
| Whether to show the name of craft that arrived at the mission site.
 +
| true
 +
|-
 +
| '''showTarget'''
 +
| Whether to display the mission target name.
 +
| true
 +
|}
 +
 
 +
=== Battle Starting Conditions ===
 +
 
 +
<div style="background:#ddffdd;">Defines various pre-conditions and limitations applied before a certain Battlescape mission, listed in ''"startingConditions:"''.
 +
 
 +
Starting conditions can be defined on alien deployments only (not on terrains):
 +
</div>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''type'''
 +
| String ID of the starting condition.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''defaultArmor'''
 +
| If a soldier's armor is not permitted on a mission (see '''allowedArmors''' and '''forbiddenArmors''' below), it will be replaced by a default armor. Default armor is defined for each soldier type separately as a weighted list of possible armor replacements. There is also a special armor ID "noChange" representing no change needed (i.e. giving you a chance to keep the original armor even if it is not allowed... don't ask me why, ask modders!)
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''allowedArmors''' '''forbiddenArmors'''
 +
| A list of allowed/forbidden armors for a mission. Only one of these two attributes can be used.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''allowedVehicles''' '''forbiddenVehicles'''
 +
| A list of allowed/forbidden vehicles (HWP/SWS) for a mission. Not permitted vehicles will stay at the base. Only one of these two attributes can be used.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''allowedItems''' '''forbiddenItems'''
 +
| A list of allowed/forbidden items (weapons, equipment, etc.) for a mission. Not permitted items will stay at the base. Only one of these two attributes can be used.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''allowedItemCategories''' '''forbiddenItemCategories'''
 +
| A list of allowed/forbidden item categories (categories are freely definable by modders) for a mission. This is used to simplify/shorten the definition of allowed/forbidden items. Only one of these two attributes can be used.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''allowedCraft''' '''forbiddenCraft'''
 +
| A list of allowed/forbidden craft for a mission. Not permitted craft cannot target the mission destination at all. Only one of these two attributes can be used.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''allowedSoldierTypes''' '''forbiddenSoldierTypes'''
 +
| A list of allowed/forbidden soldier types for a mission. If there are any not permitted soldier types onboard a craft, it won't be able to target the mission destination at all. Only one of these two attributes can be used.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''requiredItems'''
 +
| A list of items (and their quantities) required for a mission (e.g. a skeleton key from EU2012).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''destroyRequiredItems'''
 +
| Defines whether required items should be destroyed or not (when craft landing is confirmed).
 +
| false
 +
|}
 +
 
 +
=== Battle Enviro Effects ===
 +
 
 +
<div style="background:#ddffdd;">Defines various effects applied during a certain Battlescape mission, listed in ''"enviroEffects:"''.
 +
 
 +
Enviro effects can be defined on alien deployments and on terrains. If both are defined, deployment's enviro effects will be used.
 +
</div>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''type'''
 +
| String ID of the enviro effects.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''paletteTransformations'''
 +
| A list of palette transformations (oldPaletteName: newPaletteName) to apply during the mission (or mission stage). New palettes should be similar to original palettes, they should only convey visual effects like pollution, underwater environment, etc. For UFO-based mods only one palette (PAL_BATTLESCAPE) needs to be changed, for TFTD-based mods up to 4 palettes (for each depth).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''environmentalConditions'''
 +
| A set of [[#Environmental Conditions|environmental conditions]] (one for each faction: STR_FRIENDLY, STR_HOSTILE or STR_NEUTRAL), see below. Environmental conditions define a special effect applied to each unit of a given faction at the beginning of their turn. This can be for example damage in toxic environment, stun in harsh environment, morale decrease in tough battles, etc.
 +
 
 +
Note: the player is informed about the effects applied on the [Next Turn] screen.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''armorTransformations'''
 +
| A list of armor transformations (oldArmorName: newArmorName) to apply during the mission (or mission stage). This can be only visual (e.g. replace helmetless armors with armors with a helmet when going underwater or in space) or also functional (effectively changing unit's stats and armor properties). The change is only temporary and reverted to original armor when the mission ends.
 +
 
 +
Note: if the armor is transformed, it is not checked if it is allowed or not and it is not replaced with default armor either.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''mapBackgroundColor'''
 +
| Possibility to change the color of the background outside of the map boundaries. Used for example to visually indicate the type of environment.
 +
| 15
 +
|- style="background-color:#ddffdd;"
 +
| '''inventoryShockIndicator'''
 +
| String ID of the shock indicator sprite (in the inventory). Used to override the global one, for example in normal environment it can indicate body shock, in underwater environment drowning and in space suffocating.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''mapShockIndicator'''
 +
| String ID of the shock indicator sprite (on the map). Used to override the global one.
 +
| -
 +
|}
 +
 
 +
==== Environmental Conditions ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''globalChance'''
 +
| Chance (0-100%) that this environmental condition will be turned on. Dice roll is performed only once, when the battle starts.
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''chancePerTurn'''
 +
| Chance (0-100%) that a unit will be affected. Dice roll is performed each turn, for each unit separately.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''firstTurn'''
 +
| When should the environmental condition start affecting the units. XCOM units cannot be affected before their first turn (aliens and civilians can).
 +
| 1
 +
|- style="background-color:#ddffdd;"
 +
| '''lastTurn'''
 +
| When should the environmental condition stop affecting the units.
 +
| 1000
 +
|- style="background-color:#ddffdd;"
 +
| '''message'''
 +
| String ID of the message displayed on the [Next Turn] screen, explaining to the player what is happening.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''color'''
 +
| Color (0-255) of the above message.
 +
| 29
 +
|- style="background-color:#ddffdd;"
 +
| '''weaponOrAmmo'''
 +
| The item (a weapon or ammo) that defines the actual effect. Compared to normal weapons, there are some limitations. See notes below.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''side'''
 +
| The unit side where the effect is applied. Possible options:
 +
* -1 = random,
 +
* 0 = front
 +
* 1 = left
 +
* 2 = right
 +
* 3 = rear
 +
* 4 = under
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''bodyPart'''
 +
| The unit body part where the effect is applied. Possible options:
 +
* -1 = random
 +
* 0 = head
 +
* 1 = torso
 +
* 2 = right arm
 +
* 3 = left arm
 +
* 4 = right leg
 +
* 5 = left leg
 +
| -1
 +
|}
 +
 
 +
<div style="background:#ddffdd;">
 +
Note: there are limitations to what the effect can do, since we're not using a projectile and nobody is actually shooting
 +
* no power bonus based on shooting unit's stats (nobody is shooting, duh!)
 +
* no power range reduction (there is no projectile, range = 0)
 +
* no AOE damage from explosions (targets are damaged directly without affecting anyone/anything else)
 +
* no terrain damage
 +
* no self-destruct
 +
* no vanilla target morale loss when hurt; vanilla morale loss for fatal wounds still applies though
 +
* no setting target on fire (...could be added/implemented if needed)
 +
* no fire extinguisher
 +
</div>
 +
 
 +
=== Custom Palettes ===
 +
 
 +
<div style="background:#ddffdd;">Defines custom 8bit palettes, listed in ''"customPalettes:"''.
 +
 
 +
These palettes can:
 +
* either '''globally''' override the default game palettes
 +
* or serve as additional palettes used only in certain situations (see '''paletteTransformations''')
 +
</div>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''type'''
 +
| String ID of the custom palette.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''target'''
 +
| String ID of the target palette:
 +
* for global palette replacement, use one of the game's default palette names:
 +
** '''UFO''': BACKPALS.DAT, PAL_BASESCAPE, PAL_BATTLEPEDIA, PAL_BATTLESCAPE, PAL_GEOSCAPE, PAL_GRAPHS and PAL_UFOPAEDIA
 +
** '''TFTD''': BACKPALS.DAT, PAL_BASESCAPE, PAL_BATTLESCAPE, PAL_BATTLESCAPE_1, PAL_BATTLESCAPE_2, PAL_BATTLESCAPE_3, PAL_GEOSCAPE and PAL_GRAPHS
 +
* for additional palettes, just use the same name as for '''type'''
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''file'''
 +
| Path to a file containing the palette definition, in JASC format.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''palette'''
 +
| Alternative to '''file'''. You can specify the palette directly in the ruleset using a list of RGB values. Using this method, you don't have to specify all 256 colors; you can also use it to just change a few colors and leave the rest unchanged.
 +
| -
 +
|}
 +
 
 +
=== Research ===
 +
 
 +
Defines a [[Research|research topic]] that X-COM scientists can investigate, listed in ''"research:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''name'''
 +
| String ID of the research project's name.
 +
| ''required''
 +
|-
 +
| '''lookup'''
 +
| String ID of the research project's display result (used when multiple projects give the same result, e.g. researching Sectoid Engineer and Sectoid Navigator both give the same live Sectoid info in the Ufopaedia).
 +
| -
 +
|-
 +
| '''cutscene'''
 +
| The name of the cutscene to play when this project is completed. If the cutscene is "wingame" or "losegame", the player is returned to the main menu after the cutscene plays.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''spawnedItem'''
 +
| Item to be added to base stores, when the research is completed.
 +
 
 +
Tip: allows you to create unique items in limited quantities (e.g. special weapons, keys to special missions, etc.). Don't forget to inform the player in the pedia article!
 +
| -
 +
|-
 +
| '''cost'''
 +
| Number of man-days (on average, the final time will be 50-150% this value) required to complete this project.
 +
| 0
 +
|-
 +
| '''points'''
 +
| [[Score]] earned for completing this project.
 +
| 0
 +
|-
 +
| '''dependencies'''
 +
| List of research projects that can unlock access to this one. If the full list is researched, or if one of the projects on the list "unlocks" this one, it becomes available.
 +
| -
 +
|-
 +
| '''unlocks'''
 +
| List of research projects unlocked, regardless of other dependencies, but not requirements, by completing this project (for example, any live alien unlocks "Alien Origins").
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''disables'''
 +
| A list of research projects disabled by completing this project.
 +
 
 +
Notes:
 +
* this is one of the ways how to branch your "story", e.g. create alternative endings
 +
* it can also be used to hide obsolete stuff in the market, workshop, pedia, etc.
 +
* disabled topics cannot be re-enabled again, ever
 +
| -
 +
|-
 +
| '''getOneFree'''
 +
| List of "bonus" research projects that may be granted when completing this project. Examples: alien navigators (give random alien mission info), medics (give random alien interrogation or autopsy), engineers (give random UFO type info).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''getOneFreeProtected'''
 +
| A list of additional "bonus" research projects that may be granted when completing this project. Each topic in the list is "protected" by another topic, which allows you finer control over when the player gets the bonus.
 +
 
 +
For example: you could divide the topics into early-game, mid-game and late-game and protect each group by some "gateway topic".
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''sequentialGetOneFree'''
 +
| Should the topics from '''getOneFree''' and '''getOneFreeProtected''' be given randomly (false) or sequentially (true).
 +
| false
 +
|-
 +
| '''requires'''
 +
| List of research projects absolutely required before this project can be unlocked. For example, "The Martian Solution" will not even be considered for unlocking until AFTER "Alien Origins" is completed.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''requiresBaseFunc'''
 +
| A list of services (for a given base) required to start this project.
 +
| -
 +
|-
 +
| '''needItem'''
 +
| Does this project require an [[#Items|item]] of the same name?
 +
| false
 +
|-
 +
| '''destroyItem'''
 +
| Will this item be destroyed (removed from stores) after research is finished?
 +
| false
 +
|-
 +
| '''unlockFinalMission'''
 +
| If true, this research topic allows to send a spacecraft to the final mission.
 +
| false
 +
|}
 +
 
 +
=== Manufacture ===
 +
 
 +
Defines a [[Manufacture|manufacture project]] that X-COM engineers can produce, listed in ''"manufacture:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''name'''
 +
| String ID of the manufacturing project's name.
 +
| ''required''
 +
|-
 +
| '''category'''
 +
| String ID of the manufacturing project's category.
 +
Important: craft manufacturing projects MUST be defined in the STR_CRAFT category.
 +
| -
 +
|-
 +
| '''requires'''
 +
| List of [[#Research|topics]] (string IDs) that must be researched to unlock this project. If none are specified, this project is unlocked from the start.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''requiresBaseFunc'''
 +
| A list of services required (in the given base) to be able to start this project.
 +
| -
 +
|-
 +
| '''space'''
 +
| Amount of [[Workshop]] space required to begin this project.
 +
| 0
 +
|-
 +
| '''time'''
 +
| Number of man-hours required per production.
 +
| 0
 +
|-
 +
| '''cost'''
 +
| Monetary deduction per production.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''refund'''
 +
| Whether the resources needed for a project should be refunded when a project is cancelled before completion.
 +
 
 +
Notes:
 +
* if enabled, the ''STOP PRODUCTION'' button is replaced by a ''REFUND'' button
 +
* in case you didn't know: in vanilla, when you started a manufacture project (even with 0 engineers allocated and no time passed yet), all the resources were irrevocably gone
 +
| false
 +
|-
 +
| '''requiredItems'''
 +
| List of [[#Items|items]] required and consumed per production.
 +
| -
 +
|-
 +
| '''producedItems'''
 +
| List of [[#Items|items]] manufactured per production. If not specified, defaults to 1 item with the same string ID as the manufacture project.
 +
| '''name''': 1
 +
|- style="background-color:#ddffdd;"
 +
| '''randomProducedItems'''
 +
| List of item sets with weights. One item set is chosen randomly for production.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,6867.msg109423.html#msg109423
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''spawnedPersonType'''
 +
| Allows to "manufacture" soldiers, scientists and engineers. More info here: https://openxcom.org/forum/index.php/topic,4187.msg78212.html#msg78212
 +
 
 +
Note: you can't use existing soldiers as "input" here, only items or prisoners. For transformation of existing soldiers (e.g. from normal humans to MECs), please use the [[#Soldier Transformation|Soldier Transformation]] functionality and ruleset.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''spawnedPersonName'''
 +
| When "manufacturing" a soldier, you can (optionally) specify also his/her name.
 +
| -
 +
|}
 +
 
 +
==== Manufacture Shortcuts ====
 +
 
 +
<div style="background:#ddffdd;">Copies an existing manufacture project and allows break down of certain components into simpler components, listed in ''"manufactureShortcut:"''.</div>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''name'''
 +
| String ID of the new manufacturing project's name.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''startFrom'''
 +
| String ID of the manufacturing project to copy.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''breakDownItems'''
 +
| List of manufacture projects (string IDs) to break down. Break down is recursive (i.e. repeats until there is nothing more to break down).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''breakDownRequires'''
 +
| Whether the research requirements should be broken down or not.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''breakDownRequiresBaseFunc'''
 +
| Whether the base services requirements should be broken down or not.
 +
| true
 +
|}
 +
 
 +
=== UFOpaedia Article ===
 +
 
 +
Defines an article in the in-game [[UFOpaedia]], listed in ''"ufopaedia:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''id'''
 +
| String ID of the article name. This must match the ID of the object associated with this article, if applicable.
 +
| ''required''
 +
|-
 +
| '''title'''
 +
| String ID of the article title. If omitted, the '''id''' is used.
 +
| -
 +
|-
 +
| '''type_id'''
 +
| Type of this article:
 +
* 1 = [[Craft]]
 +
* 2 = [[Craft Armaments]]
 +
* 3 = [[HWP]]
 +
* 4 = [[Equipment (EU)|Equipment]]
 +
* 5 = [[Armour]]
 +
* 6 = [[Base Facilities]]
 +
* 7 = Text & Image (eg. [[Alien Life Forms]], [[UFO Components]])
 +
* 8 = Text (eg. [[Alien Research]])
 +
* 9 = [[UFO]]
 +
* 10 = [[TFTD]]
 +
* 11 = TFTD [[Subs]]
 +
* 12 = TFTD [[Sub Armaments]]
 +
* 13 = TFTD [[Submersible Weapons Systems]]
 +
* 14 = TFTD [[Equipment (TFTD)|Equipment]]
 +
* 15 = TFTD [[Armour (TFTD)|Armour]]
 +
* 16 = TFTD [[Base Facilities (TFTD)|Base Facilities]]
 +
* 17 = TFTD [[Alien Subs]]
 +
 
 +
<span style="background:#ddffdd;">In OXCE, the TFTD-style articles can also be used in UFO-based mods.</span>
 +
| ''required''
 +
|-
 +
| '''section'''
 +
| String ID of the UFOpaedia section this article belongs to.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''hiddenCommendation'''
 +
| If set on a Commendation article (determined by '''section'''), the article will remain hidden until the corresponding commendation is awarded to at least one soldier.
 +
| false
 +
|-
 +
| '''requires'''
 +
| List of [[#Research|topics]] (string IDs) that must be researched to unlock this article. If none are specified, this article is unlocked from the start.
 +
<span style="background:#ddffdd;">If using lootable weapons ('alien' weapons that can be used without research) needing a research to fully unlock, make sure to define it on both the weapon and ammo.
 +
Otherwise the damage reading is visible on the inventory screen using [ALT] on a clip. </span>
 +
| -
 +
|-
 +
| '''image_id'''
 +
| Filename of the [[UP001.SPK-UP042.SPK|background image]] displayed on this article, if applicable.
 +
 
 +
<div style="background:#ddffdd;">
 +
In OXCE:
 +
* This attribute can be used also for ''Vehicle'' articles
 +
* If the name contains a '''"_CPAL" suffix''', its (custom) palette will be used instead of the default one. Relevant for ''Craft, CraftWeapon, TextImage and Vehicle (HWP)'' articles. More info here: https://openxcom.org/forum/index.php/topic,4957.0.html</div>
 +
| -
 +
|-
 +
| '''text'''
 +
| String ID of the description displayed on this article.
 +
 
 +
<span style="background:#ddffdd;">In OXCE, you can use the {ALT} keyword to switch between primary and secondary color.</span>
 
| -
 
| -
 
|-
 
|-
 
| '''text_width'''
 
| '''text_width'''
−
| Maximum width of the text displayed, only applicable to ''Text & Image'' articles.
+
| Maximum width of the text displayed, only applicable to ''TextImage'' articles.
−
| 150
+
| EU (0), TFTD (157)
−
|-
+
|-
−
| '''rect_stats'''
+
| '''rect_stats'''
−
| Rectangle ('''x''', '''y''', '''width''', '''height''') of the stats text on the screen, only applicable to ''Craft'' articles.
+
| Rectangle ('''x''', '''y''', '''width''', '''height''') of the stats text on the screen, only applicable to ''Craft'' articles.
−
| 0
+
| -
−
|-
+
|-
−
| '''rect_text'''
+
| '''rect_text'''
−
| Rectangle ('''x''', '''y''', '''width''', '''height''') of the description text on the screen, only applicable to ''Craft'' articles.
+
| Rectangle ('''x''', '''y''', '''width''', '''height''') of the description text on the screen, only applicable to ''Craft'' articles.
−
| 0
+
 
−
|-
+
<span style="background:#ddffdd;">In OXCE, it is also applicable to ''TextImage'' articles.</span>
−
| '''weapon'''
+
| -
−
| String ID of the weapon, only applicable to ''HWP'' articles.
+
|-
−
| -
+
| '''weapon'''
−
|}
+
| String ID of the weapon, only applicable to ''Vehicle'' (HWP/SWS) articles.
−
 
+
| -
−
=== UFO Trajectories ===
+
|- style="background-color:#ddffdd;"
−
 
+
| '''pages'''
−
Defines a trajectory carried out by an UFO during an [[#Alien Missions|alien mission]], listed in ''"ufoTrajectories:"''.
+
| Configuration of additional pages for an article.
−
 
+
* Each page can have its own title and text description.
−
{| class="wikitable" width="100%"
+
* Additionally, you can define which '''ammoSlot''' will be used to limit the display of supported attack types and compatible ammo.
−
! width="150"| Value
+
* If multiple pages have same value of '''ammoSlot''', then each page will show successive group of 3 ammo items available for this slot.
−
! width="*"  | Description
+
 
−
! width="80" | Default
+
Example:
 +
 
 +
  - id: STR_PISTOL
 +
    pages:
 +
      - title: STR_PISTOL
 +
        text: STR_PISTOL_UFOPEDIA
 +
        ammoSlot: 0                  # default for all pages
 +
      - title: STR_PISTOL
 +
        text: STR_PISTOL_UFOPEDIA_2
 +
        ammoSlot: 1                  # ammo and attack types relevant for the second ammo slot (0 = first slot)
 +
      - title: STR_PISTOL_UFOPEDIA_TITLE_3
 +
        text: STR_PISTOL_UFOPEDIA_3
 +
       
 +
| Only one page using standard '''title''' and '''text'''.
 +
|}
 +
 
 +
=== UFO Trajectories ===
 +
 
 +
Defines a trajectory carried out by an UFO during an [[#Alien Missions|alien mission]], listed in ''"ufoTrajectories:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''id'''
 +
| String ID of the trajectory name.
 +
| ''required''
 +
|-
 +
| '''groundTimer'''
 +
| Amount of seconds for the UFO to spend on Ground waypoints.
 +
| 5
 +
|-
 +
| '''waypoints'''
 +
| List of items defining the waypoints and flight segments for the UFO to traverse, defined as ''[zone, altitude, speed]''.<br>
 +
'''zone''': Regional missionZone index (used to randomly generate the waypoint's coordinates).<br>
 +
'''altitude''': UFO altitude:
 +
* 0 - Ground
 +
* 1 - Very Low
 +
* 2 - Low
 +
* 3 - High
 +
* 4 - Very High
 +
'''speed''': UFO speed as a percentage (0-100%) of its maximum speed.
 +
| -
 +
|}
 +
 
 +
Each trajectory has X flight segments and X+1 waypoints... please pause reading here and think for a while why that is the case.
 +
 
 +
The best explanation how the flight segments and waypoints are encoded in the ruleset is done via an example:
 +
 
 +
  waypoints:
 +
    - [A, B, C]
 +
    - [D, E, F]
 +
    - [G, H, I]
 +
    - [J, K, L]
 +
    - [M, N, P]
 +
 
 +
This example can be interpreted as:
 +
# go from zone A to zone D at altitude B and speed C
 +
# go from zone '''D to zone D''' at altitude E and speed F
 +
# go from zone D to zone G at altitude H and speed I
 +
# go from zone G to zone J at altitude K and speed L
 +
# go from zone J to zone M at altitude N and speed P
 +
 
 +
This example contains 5 flight segments (AD, DD, DG, GJ and JM) and 6 waypoints (A, D, D, G, J and M).
 +
 
 +
Please note especially the second line, where zone D is targeted AGAIN, this happens automatically/internally and always on the second line.
 +
 
 +
Also, if any altitude (B, E, H, K or N) would be zero (0 = Ground), the UFO would first wait landed in the start zone for some time before taking off to the destination zone (at altitude 1 = Very Low).
 +
 
 +
=== Alien Missions ===
 +
 
 +
Defines an [[Alien Missions|alien mission]] carried out by UFOs on the Geoscape, listed in ''"alienMissions:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| String ID of the mission type.
 +
| ''required''
 +
|-
 +
| '''points'''
 +
| [[Score]] allocated to aliens for successfully completing this mission.
 +
| 0
 +
|-
 +
| '''waves'''
 +
| List of UFO waves to spawn as this mission progresses, as described below.
 +
| ''required''
 +
|-
 +
| '''objective'''
 +
| Missions are split by objective:
 +
* 0 = score (default if omitted)
 +
* 1 = infiltration
 +
* 2 = alien base
 +
* 3 = mission site (terror etc)
 +
* 4 = retaliation
 +
* 5 = supply
 +
| 0
 +
|-
 +
| '''spawnUfo'''
 +
| UFO to spawn for retaliation.
 +
| -
 +
|-
 +
| '''spawnZone'''
 +
| Regional missionZone to use when spawning mission sites / alien bases.
 +
| -1
 +
|-
 +
| '''missionWeights'''
 +
| Only works for alien retaliation missions spawned during dogfights. If your mod has multiple possible retaliation missions, the game chooses one randomly, but considering weights defined in this attribute. The weights are defined as a list of (month: weight) pairs. If nothing is specified, weight is 1 (for all months).
 +
| -
 +
|-
 +
| '''retaliationOdds'''
 +
| Probability (0-100%) that a UFO shot down while performing this mission will generate a Retaliation mission.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''endlessInfiltration'''
 +
| Should an infiltration mission end after the first cycle (false) or continue indefinitely (true)?
 +
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''despawnEvenIfTargeted'''
 +
| Should a mission site expire/despawn even if it is targeted by an xcom craft or not?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''interruptResearch'''
 +
| Discovering this research topic interrupts the mission immediately.
 +
| -
 +
|-
 +
| '''siteType'''
 +
| Alien deployment to use when spawning mission sites / alien bases. If not specified, alienDeployment from Geoscape texture is used.
 +
 
 +
Note: for alien bases there is one more hardcoded fallback (STR_ALIEN_BASE_ASSAULT) if both deployments mentioned above are missing.
 +
| -
 +
|-
 +
| '''raceWeights'''
 +
| List of alien races likely to carry out this mission, and the % chance of them being allocated to this mission, listed by "number of months after game beginning".
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''operationType'''
 +
| From where does this mission operate?
 +
 
 +
Possible options:
 +
* 0 = from space
 +
* 1 = from an existing alien base in the mission region
 +
* 2 = from a new alien base in the mission region
 +
* 3 = from a new alien base in the mission region if necessary, otherwise from an existing alien base
 +
* 4 = from an existing alien base anywhere on Earth
 +
* 5 = from a new alien base anywhere on Earth if necessary, otherwise from an existing alien base
 +
* 6 = a hunt mission spawned from an existing alien base
 +
 
 +
More description for this and the following attributes here: https://openxcom.org/forum/index.php/topic,6557.msg104669.html#msg104669
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''operationSpawnZone'''
 +
| The missionZone for spawning the operation base (if necessary), see above.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''operationBaseType'''
 +
| The type of operation base to spawn (references alien deployment), see above.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''targetBaseOdds'''
 +
| The odds of this mission targeting an xcom base. Works only for '''genMission''' spawned by an alien base.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''regionWeights'''
 +
| The region distribution over game time. Works only for '''genMission''' spawned by an alien base.
 +
| -
 +
|}
 +
 
 +
==== Waves ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''ufo'''
 +
| String ID of the [[#UFOs|UFO]] to spawn.
 +
| ''required''
 +
|-
 +
| '''count'''
 +
| Number of UFOs to spawn.
 +
| 0
 +
|-
 +
| '''trajectory'''
 +
| String ID of the [[#UFO Trajectories|trajectory]] for this UFO to use when entering Earth's atmosphere.
 +
| ''required''
 +
|-
 +
| '''timer'''
 +
| How long after the previous wave should this wave arrive? (in minutes)
 +
 
 +
Notes:
 +
* The timer can vary between 50-150% of the stated value, so a UFO with a 9000 value will be spawned between 4500-13500 minutes (each day has 1440 minutes)
 +
* If the UFO is crashed/destroyed the timer of the next UFO on the wave will be delayed by (30 * (RNG::generate(0, 400) + 48)) minutes, or between 1.0 and 9.3 days
 +
| 0
 +
|-
 +
| '''objective'''
 +
| ''true'' Marks this wave as the one that carries out the mission objective. Only for mission site / supply missions.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''hunterKillerPercentage'''
 +
| The chance (0-100%) to become a hunter-killer UFO upon spawning.
 +
 
 +
Possible options:
 +
* -1 = take the info from RuleUfo
 +
*  0 = not a hunter-killer
 +
*  1-99 = percentage chance to be flagged as hunter-killer upon spawn
 +
*  100 = always a hunter-killer
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''huntMode'''
 +
| Algorithm to use when prioritizing xcom targets.
 +
 
 +
Possible options:
 +
* -1 = take the info from RuleUfo
 +
* 0 = prefer hunting xcom interceptors
 +
* 1 = prefer hunting xcom transports
 +
* 2 = random preference (0 or 1) determined at spawn
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''huntBehavior'''
 +
| Algorithm to use when considering retreating from the dogfight.
 +
 
 +
Possible options:
 +
* -1 = take the info from RuleUfo
 +
* 0 = flee if you're losing
 +
* 1 = never flee, never crash (is destroyed instead of crashing)
 +
* 2 = random preference (0 or 1) determined at spawn
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''escort'''
 +
| Does this wave escort/protect the previous wave(s)?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''interruptPercentage'''
 +
| The chance (0-100%) to interrupt the alien mission when successfully shooting down a UFO from this wave.
 +
 
 +
Possible options:
 +
*  0 = cannot interrupt
 +
*  1-99 = percentage chance to be interrupted
 +
*  100 = always interrupted
 +
| 0
 +
|}
 +
 
 +
=== Mission Scripts ===
 +
 
 +
MissionScripts determines how many missions are spawned each month.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| Name of the script used for overwriting or deleting purposes.
 +
| ''required''
 +
|-
 +
| '''firstMonth'''
 +
| Months this command runs on, 0 runs on startup of a new game
 +
| 0
 +
|-
 +
| '''lastMonth'''
 +
| Do not run after this month. In this context we mean "run once". -1 denotes no limit.
 +
| -1
 +
|-
 +
| '''label'''
 +
| A numeric label that can be used for conditional execution of commands. Each label should be unique within the command list (0=default no need for uniqueness).
 +
| 0
 +
|-
 +
| '''conditionals'''
 +
| Defines the conditions that allows 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.
 +
 
 +
Commands that are not yet executed are always in failed state.
 +
| -
 +
|-
 +
| '''missionWeights'''
 +
| The type of mission to spawn (omit to pick one from the alien strategy mission table). These are split into monthly chunks, and can contain multiple entries including weighted odds, but there is a caveat here: You cannot mix and match missions with mission site objectives (i.e. terror sites) with regular missions. They are generated too differently. Using '''executionOdds''' and '''conditionals''' instead can achieve exactly the same thing. Similarly, terror missions should not appear in regional mission weights (regions.rul).
 +
| -
 +
|-
 +
| '''executionOdds'''
 +
| % chances of this command executing.
 +
| 100
 +
|-
 +
| '''targetBaseOdds'''
 +
| % chances of this mission targeting a region containing an xcom base... instead of a random region (which CAN also contain an xcom base).
 +
| 0
 +
|-
 +
| '''startDelay'''
 +
| Number of minutes to delay the start of the mission (rounded down to the nearest 30). For 0 the wave timer from the mission itself is used.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''randomDelay'''
 +
| Additional randomized delay (in minutes). Total delay = '''startDelay''' + RNG(0, '''randomDelay''')
 +
| 0
 +
|-
 +
| '''raceWeights'''
 +
| List which can override established monthly race weights if desired.
 +
| -
 +
|-
 +
| '''regionWeights'''
 +
| List which can override established monthly region weights if desired. This will come into play only if the mission doesn't target an xcom base.
 +
If the list is omitted: for a terror type mission, all regions that meet the criteria will be weighed equally. For regular missions the normal regional distribution weights will be applied.
 +
| -
 +
|-
 +
| '''minDifficulty'''
 +
| This command only applies to difficulty levels of this or above.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''minScore'''
 +
| This command only applies if last month's rating was above this threshold. Not checked before first month.
 +
| -infinity
 +
|- style="background-color:#ddffdd;"
 +
| '''maxScore'''
 +
| This command only applies if last month's rating was below this threshold. Not checked before first month.
 +
| infinity
 +
|- style="background-color:#ddffdd;"
 +
| '''minFunds'''
 +
| This command only applies if the new month's funds are above this threshold. Not checked before first month.
 +
| -infinity
 +
|- style="background-color:#ddffdd;"
 +
| '''maxFunds'''
 +
| This command only applies if the new month's funds are below this threshold. Not checked before first month.
 +
| infinity
 +
|-
 +
| '''researchTriggers'''
 +
| A list of research topics that can influence the execution of this mission. For example
 +
* "''STR_THE_ULTIMATE_THREAT: true''" means the mission would only run if the player has researched the Ultimate Threat.
 +
* "''STR_TLETH_TH_ALIEN_CITY: false''" means the mission would only run if the player has not researched T'Leth.
 +
Several research triggers can be combined and for the mission to appear all must be fulfilled.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''itemTriggers'''
 +
| A list of items that can influence the execution of this script. Similar to research triggers; checks the presence of items in the base stores (not anywhere else).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''facilityTriggers'''
 +
| A list of base facilities that can influence the execution of this script. Similar to research triggers; checks the presence of a facility (in any xcom base).
 +
| -
 +
|-
 +
| '''maxRuns'''
 +
| This mission type can only execute this number of times, -1 for infinite.
 +
| -1
 +
|-
 +
| '''avoidRepeats'''
 +
| This is used to ensure different coordinates for this mission. It means "store an array of ''x'' previous coordinates, and don't use them again".
 +
| 0
 +
|-
 +
| '''varName'''
 +
| This is an internal variable name, used for tracking '''maxRuns''' and '''avoidRepeats'''.
 +
| -
 +
|-
 +
| '''useTable'''
 +
| Check if this mission type appears in the mission tables. If ''true'' remove it from there.
 +
 
 +
Note: this is used for "classic approach" (before mission scripts existed), where missions were pre-generated at the beginning of the campaign in alien strategy table and removed from there one by one to avoid repetitions.
 +
| true
 +
|}
 +
 
 +
==== Guidelines/Tips ====
 +
 
 +
Relevant ruleset files for editing alien missions of "mission site" type (e.g. terror sites):
 +
 
 +
* '''missionScripts.rul''' - this is where alienMissions are generated
 +
* '''alienMissions.rul''' - alienMissions provide a link to the region (unless overridden by missionScript); and define missionWaves, which ultimately provide links to UFO trajectories
 +
* '''ufoTrajectories.rul''' - provides a link to regional missionZones (= places where the the UFOs start/end, change direction, land, and potentially create mission sites)
 +
** Note: mission sites can also be spawned without actual UFOs if so desired (e.g. TFTD artifact sites/shipping lanes)
 +
* '''regions.rul''' - defines the missionZones; and provides a link to textures (=battlescape appearance)
 +
** Note: textures can be either terrain-based (used for UFO landing/crash sites) or alienDeployment-based (used for mission sites)
 +
* '''globe.rul''' - defines the textures
 +
** Note: the alienDeployment-based textures are usually recognizable by their negative IDs
 +
* '''alienDeployments.rul''' - contains detailed information for the battlescape map generator (terrains, mapScripts, etc.)
 +
 
 +
=== Arc Scripts ===
 +
 
 +
<div style="background:#ddffdd;">
 +
ArcScripts determine high-level game progression. They are executed just before the monthly MissionScripts.
 +
 
 +
Technically they are just "time-triggered research discoveries". More info: https://openxcom.org/forum/index.php/topic,7125.0.html
 +
</div>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''type'''
 +
| Name of the arc script used for overwriting or deleting purposes.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''sequentialArcs'''
 +
| The names of research topics to be "discovered", each month 0 or 1, processed sequentially.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''randomArcs'''
 +
| The names and weights of research topics to be "discovered", each month 0 or 1, chosen randomly considering weights.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''firstMonth'''
 +
| Months this command runs on, 0 runs on startup of a new game.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''lastMonth'''
 +
| Do not run after this month. -1 denotes no limit.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''executionOdds'''
 +
| % chances of this command executing.
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''maxArcs'''
 +
| Maximum number of arcs this command can generate (together during the whole game), -1 for infinite.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''minDifficulty'''
 +
| This command only applies to difficulty levels of this or above.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''maxDifficulty'''
 +
| This command only applies to difficulty levels of this or below.
 +
| 4
 +
|- style="background-color:#ddffdd;"
 +
| '''minScore'''
 +
| This command only applies if last month's rating was above this threshold. Not checked before first month.
 +
| -infinity
 +
|- style="background-color:#ddffdd;"
 +
| '''maxScore'''
 +
| This command only applies if last month's rating was below this threshold. Not checked before first month.
 +
| infinity
 +
|- style="background-color:#ddffdd;"
 +
| '''minFunds'''
 +
| This command only applies if the new month's funds are above this threshold. Not checked before first month.
 +
| -infinity
 +
|- style="background-color:#ddffdd;"
 +
| '''maxFunds'''
 +
| This command only applies if the new month's funds are below this threshold. Not checked before first month.
 +
| infinity
 +
|- style="background-color:#ddffdd;"
 +
| '''researchTriggers'''
 +
| A list of research topics that can influence the execution of this script. For example
 +
* "''STR_MARTIAL_SOLUTION: true''" means the command would only run if the player has researched The Martian Solution.
 +
* "''STR_CYDONIA_OR_BUST: false''" means the command would only run if the player has not researched Cydonia or Bust yet.
 +
Several research triggers can be combined and all must be fulfilled.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''itemTriggers'''
 +
| A list of items that can influence the execution of this script. Similar to research triggers; checks the presence of items in the base stores (not anywhere else).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''facilityTriggers'''
 +
| A list of base facilities that can influence the execution of this script. Similar to research triggers; checks the presence of a facility (in any xcom base).
 +
| -
 +
|}
 +
 
 +
==== Guidelines/Tips ====
 +
 
 +
<div style="background:#ddffdd;">
 +
Possible usage, for inspiration:
 +
* Randomly give the player research A, B or C at the beginning - each research then unlocks specific tech at game start, giving the player different starting items/research for each new campaign
 +
* Randomly give the player (each month) one research topic D, E, F, etc. - each research then unlocks specific mission(s) for that month
 +
* Give tech G on month 0, tech H on month 1 and tech I on month 2 - for multi-mission story arcs spawning in sequence across several months
 +
* Give tech J and spawn corresponding mission, if mission is victory receive tech K, which then unlocks additional mission next month - for making missions dependent on the previous one
 +
* If research L is completed or if month X is achieved, give tech M at beginning of next month with the UFOPedia notification - this can be used to provide tips, tutorials, in-game message, whatever relevant info you want to give the player
 +
</div>
 +
 
 +
=== Event Scripts ===
 +
 
 +
<div style="background:#ddffdd;">
 +
EventScripts determine when custom geoscape events occur. They are executed just after the monthly MissionScripts.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7215.msg116753.html#msg116753
 +
</div>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''type'''
 +
| Name of the event script used for overwriting or deleting purposes.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''oneTimeSequentialEvents'''
 +
| The list of one time sequential events to spawn. First not-previously-generated event is spawned.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''oneTimeRandomEvents'''
 +
| The list of one time events to spawn. One random not-previously-generated event is spawned. Weights are considered.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''eventWeights'''
 +
| The type of events to spawn. These are split into monthly chunks, and can contain multiple entries including weighted odds.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''firstMonth'''
 +
| Months this command runs on, 0 runs on startup of a new game.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''lastMonth'''
 +
| Do not run after this month. -1 denotes no limit.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''executionOdds'''
 +
| % chances of this command executing.
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''minDifficulty'''
 +
| This command only applies to difficulty levels of this or above.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''maxDifficulty'''
 +
| This command only applies to difficulty levels of this or below.
 +
| 4
 +
|- style="background-color:#ddffdd;"
 +
| '''minScore'''
 +
| This command only applies if last month's rating was above this threshold. Not checked before first month.
 +
| -infinity
 +
|- style="background-color:#ddffdd;"
 +
| '''maxScore'''
 +
| This command only applies if last month's rating was below this threshold. Not checked before first month.
 +
| infinity
 +
|- style="background-color:#ddffdd;"
 +
| '''minFunds'''
 +
| This command only applies if the new month's funds are above this threshold. Not checked before first month.
 +
| -infinity
 +
|- style="background-color:#ddffdd;"
 +
| '''maxFunds'''
 +
| This command only applies if the new month's funds are below this threshold. Not checked before first month.
 +
| infinity
 +
|- style="background-color:#ddffdd;"
 +
| '''researchTriggers'''
 +
| A list of research topics that can influence the execution of this script. For example
 +
* "''STR_MARTIAL_SOLUTION: true''" means the command would only run if the player has researched The Martian Solution.
 +
* "''STR_CYDONIA_OR_BUST: false''" means the command would only run if the player has not researched Cydonia or Bust yet.
 +
Several research triggers can be combined and all must be fulfilled.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''itemTriggers'''
 +
| A list of items that can influence the execution of this script. Similar to research triggers; checks the presence of items in the base stores (not anywhere else).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''facilityTriggers'''
 +
| A list of base facilities that can influence the execution of this script. Similar to research triggers; checks the presence of a facility (in any xcom base).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''affectsGameProgression'''
 +
| If set to true, research topics from '''researchTriggers''' will display a small disclaimer in the TechTreeViewer about affecting game progression.
 +
| false
 +
|}
 +
 
 +
==== Events ====
 +
 
 +
<div style="background:#ddffdd;">
 +
Defines a Geoscape event that pops up, gives the player some background info and awards funds, score, items and/or research, listed in ''"events:"''.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7215.msg116753.html#msg116753
 +
</div>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''name'''
 +
| String ID of the event name. Use {0} placeholder (in the actual translation) for region/city name.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''description'''
 +
| String ID of the event description. Use {0} placeholder (in the actual translation) for region/city name.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''background'''
 +
| String ID of the background image to use in the window when this event pops up on the Geoscape.
 +
| BACK13.SCR
 +
|- style="background-color:#ddffdd;"
 +
| '''music'''
 +
| String ID of the music to play when this event pops up on the Geoscape.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''regionList'''
 +
| List of regions, where this event can occur. The region name can be a part of the event name and/or description.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''city'''
 +
| Whether or not the event occurs in a random city (of the given region(s)). The city name can be a part of the event name and/or description.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''points'''
 +
| How many score/rating points are awarded to xcom when this event pops up. If there is a region, points are awarded to that region's activity, otherwise to the research score.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''funds'''
 +
| How much money is awarded to xcom when this event pops up.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''everyItemList'''
 +
| A list of item IDs. When this event pops up they are all transferred to the HQ (within 1 hour).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''everyMultiItemList'''
 +
| A list of item IDs and their quantities. When this event pops up they are all transferred to the HQ (within 1 hour).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''randomItemList'''
 +
| A list of item IDs. When this event pops up one of them is selected randomly and transferred to the HQ (within 1 hour).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''weightedItemList'''
 +
| A weighted list of item IDs. When this event pops up one of them is selected randomly (respecting given weights) and transferred to the HQ (within 1 hour).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''researchList'''
 +
| A list of research topic IDs. One (from the not-yet-discovered) is randomly selected when this event pops up and granted for free.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''interruptResearch'''
 +
| String ID of a research topic that will prevent (an already generated/scheduled) event from popping up.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''timer'''
 +
| Number of minutes (after generation) after which the event should pop up. Minimum is 60. Should be a multiple of 30.
 +
| 60
 +
|- style="background-color:#ddffdd;"
 +
| '''timerRandom'''
 +
| Additional random timer in minutes. Total delay = '''timer''' + RNG(0, '''timerRandom''').
 +
| 0
 +
|}
 +
 
 +
=== Alien Tech Levels ===
 +
 
 +
This is a list of alien Tech Levels, listed in ''"alienItemLevels:"''.
 +
 
 +
Each line in the list corresponds to the Tech Level for one game month (first line is for the first month, second line for second month, etc.). The game will use the most recent available line in the event the game goes on forever (and there are not enough lines defined).
 +
 
 +
Each line contains item set probabilities, with a number between 0 and 2 representing an item set (from plasma pistols to heavy plasmas, as defined in the deployments), expressing a 10% probability for that item set being used.
 +
 
 +
* 0 = first item set (e.g. plasma pistol/clip)
 +
* 1 = second item set (e.g. plasma rifle/clip)
 +
* 2 = third item set (e.g. heavy plasma/clip)
 +
 
 +
For example:
 +
  [ 2, 0, 0, 0, 0, 0, 0, 1, 1, 1 ]
 +
would represent a 60% chance for pistols, 30% for rifles and 10% for heavy weapons.
 +
 
 +
Note that the order does not matter, but the length DOES. Each line MUST have exactly 10 digits.
 +
 
 +
If the above is still confusing, here's more explanation:
 +
* There are 10 fields in a line; each field represents 10%
 +
* There are six instances of '0'... 6x10% = 60% chance of plasma pistol
 +
* There are three instances of '1'... 3x10% = 30% chance of plasma rifle
 +
* There is only one instance of '2'... 1x10% = 10% chance of heavy plasma
 +
 
 +
Just in case: you can use more (or less) than 3 item sets (0, 1, 2), but you will need to modify all the alien deployments accordingly too!
 +
 
 +
=== Extra Sprites ===
 +
 
 +
Adds or replaces sprites in an existing [[Image Formats|X-COM image file]], listed in ''"extraSprites:"''.
 +
 
 +
'''VERY IMPORTANT:'''
 +
* You can use many different image formats, but not all of them work on all platforms (e.g. 8bit GIF does '''not''' work on Mac)... please use 8bit PNG format for maximum compatibility
 +
* OpenXcom is able to handle 24bit images (in some cases), but they are '''not''' officially supported... please use 8bit images for maximum compatibility
 +
* OpenXcom is able to handle transparency index other than zero (in most cases), but it is '''not''' officially supported... please use transparency index zero for maximum compatibility
 +
* OpenXcom displays '''everything''' using 8bit palettes
 +
** you can find '''official''' palettes for both UFO and TFTD (in various formats) here: https://github.com/MeridianOXC/OpenXcom/tree/oxce-plus/bin/common/Palettes
 +
** '''FIXME''': add a detailed guide describing which palettes are used for which images
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| Name of the original sprite/spritesheet to modify or new sprite/spritesheet to create.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''typeSingle'''
 +
| Alternative to '''type''', used for defining single sprites with less verbose ruleset. Changes the default value for '''singleImage''' to ''true''.
 +
| -
 +
|-
 +
| '''files'''
 +
| List of the new sprites to add/replace, listed as ''spriteID: filepath''.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''fileSingle'''
 +
| Alternative to '''files''', used for defining single sprites with less verbose ruleset.
 +
| -
 +
|-
 +
| '''width'''
 +
| Width of the whole sprite/spritesheet in pixels.
 +
| 320
 +
|-
 +
| '''height'''
 +
| Height of the whole sprite/spritesheet in pixels.
 +
| 200
 +
|-
 +
| '''singleImage'''
 +
| Is the image file just a single sprite (true) or a spritesheet (false)?
 +
| false
 +
|-
 +
| '''subX'''
 +
| Width of the subdivision in pixels. If a subdivision is specified, then the image file (a spritesheet) is divided into chunks (sprites).
 +
| 0
 +
|-
 +
| '''subY'''
 +
| Height of the subdivision in pixels. If a subdivision is specified, then the image file (a spritesheet) is divided into chunks (sprites).
 +
| 0
 +
|}
 +
 
 +
Example:
 +
- type: GIANTBUNNY.PCK
 +
  width: 32
 +
  height: 40
 +
  files:
 +
    0: Resources/Bunny/Bunny00.png
 +
    1: Resources/Bunny/Bunny01.bmp
 +
    2: Resources/Bunny/Bunny02.gif
 +
 
 +
Another example: (takes advantage of the ability to drop numerous images into a single folder that will then behave like a spritesheet)
 +
 
 +
- type: GIANTBUNNY.PCK
 +
  width: 32
 +
  height: 40
 +
  files:
 +
    0: Resources/Bunny/sprite/
 +
 
 +
Files within the specified folder should be numbered sequentially from the number defined above. "0" in this case.
 +
 
 +
==== Negative indices and cross-referencing other mods ====
 +
 
 +
Since Q2/2019, it is officially not possible to use negative sprite and sound indices (both in OXC and OXCE).
 +
 
 +
The xcom1 terror weapons (their bigobs) have been moved to positive indices as follows:
 +
* Chrysssalid weapon from -1 to 61
 +
* Cyberdisc/Celatid/Sectopod weapon from -2 to 60
 +
* Reaper weapon from -3 to 59
 +
* Silacoid weapon from -4 to 58
 +
* Zombie weapon from -5 to 57
 +
 
 +
Similar mapping was done also for xcom2 terror weapons.
 +
 
 +
If you were using these bigobs in your mod, you have 2 options how to fix it:
 +
# Option 1 (recommended): define/copy these bigobs in your mod as any other custom sprites, i.e. don't reuse the openxcom ones
 +
# Option 2: you can reuse the openxcom ones using a special syntax, which allows you to access objects from different mods, see example below
 +
 
 +
  items:
 +
    - type: STR_MY_CUSTOM_SECTOPOD_WEAPON
 +
      bigSprite: { mod: xcom1, index: 60 }
 +
 
 +
This example shows how to access sprite number 60 from xcom1 mod. There is also a special keyword '''master''', which allows you to access the master mod. The following example is equivalent to the previous example:
 +
 
 +
  items:
 +
    - type: STR_MY_CUSTOM_SECTOPOD_WEAPON
 +
      bigSprite: { mod: master, index: 60 }
 +
 
 +
'''Disclaimer:''' please be careful when addressing other mods than your own, the mod authors may decide to change their numbering at any time, rendering your references incorrect. Using this feature for anything else than addressing xcom1/xcom2 terror weapons is at your own risk.
 +
 
 +
==== Alternative for single sprites (OXCE only) ====
 +
 
 +
<div style="background:#ddffdd;">Bigger mods can contain '''a lot''' of sprites.
 +
 
 +
To make the ruleset smaller and easier to read, you can use the following alternative way of defining single sprites.
 +
 
 +
Standard method:
 +
 
 +
  - type: SpriteName
 +
    singleImage: true
 +
    files:
 +
      0: Resources/MyImage.png
 +
 
 +
Alternative method:
 +
 
 +
  - typeSingle: SpriteName
 +
    fileSingle: Resources/MyImage.png
 +
 
 +
Notice how only 2 lines are needed instead of 4; and the beginning of both values is nicely aligned.
 +
</div>
 +
 
 +
==== Reserved sprite/spritesheet names ====
 +
 
 +
'''FIXME''': add info about reserved names in OpenXcom too.
 +
 
 +
<div style="background:#ddffdd;">
 +
OXCE adds several new sprites and spritesheets with pre-defined names, that serve various purposes. Most of these sprites are "empty" by default and not used. But modders have the option to define these sprites and activate extra functionality behind them.
 +
 
 +
Below is the list of new sprites and spritesheets ('''FIXME''': add description and links/examples):
 +
* '''spritesheets''':
 +
** CustomArmorPreviews
 +
** CustomItemPreviews
 +
** DayNightIndicator
 +
** TinyRanks
 +
* '''sprites''':
 +
** AvatarBackground
 +
** AlienInventory, AlienInventory2
 +
** BigStunIndicator, BigWoundIndicator, BigBurnIndicator, BigShockIndicator
 +
** FloorStunIndicator, FloorWoundIndicator, FloorBurnIndicator, FloorShockIndicator
 +
** Flag[X]
 +
</div>
 +
 
 +
=== Extra Sounds ===
 +
 
 +
Adds or replaces sounds in an existing [[SOUND|X-COM sound file]], listed in ''"extraSounds:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| ID of the original sound file to modify:
 +
* BATTLE.CAT - Battlescape sounds, corresponds to ''SOUND1.CAT'' or ''SAMPLE2.CAT'' (55 sounds).
 +
* INTRO.CAT - Intro sounds, corresponds to ''INTRO.CAT'' or ''SAMPLE3.CAT'', probably best not to mess with these.
 +
* GEO.CAT - Geoscape sounds, corresponds to ''SOUND2.CAT'' or ''SAMPLE.CAT'' (14 sounds).
 +
| ''required''
 +
|-
 +
| '''files'''
 +
| List of the new sounds to add/replace, listed as ''soundID: filepath''.
 +
| -
 +
|}
 +
 
 +
Example:
 +
- type: BATTLE.CAT
 +
  files:
 +
    55: Resources/Sounds/sample.wav
 +
 
 +
<div style="background:#ffdddd;">
 +
'''When using .wav files, please pay attention to the file format!'''
 +
 
 +
OpenXcom should work fine with:
 +
* uncompressed mono/stereo PCM
 +
* low bit depth (8bit or 16bit), '''16bit recommended''', 24bit is known to NOT work
 +
* low and standard sample rates (8-48 kHz), 22050 Hz or 44100 Hz recommended
 +
</div>
 +
 
 +
=== Music ===
 +
 
 +
Custom music options can be defined in the Music.rul file.  More details [[Audio Options (OpenXcom)#Custom Music|here]].
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| Name of the music track.
 +
| ''required''
 +
|-
 +
| '''catPos'''
 +
| The track's index in the catalog (CAT) file. Only relevant for music stored in CAT files, obviously.
 +
| -
 +
|-
 +
| '''normalization'''
 +
| The track's normalization level. Only relevant for music stored in CAT files.
 +
| 0.76
 +
|}
 +
 
 +
=== Extra Strings ===
 +
 
 +
Adds or replaces text strings in an existing [[Translations (OpenXcom)|OpenXcom language file]], listed in ''"extraStrings:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| Filename of the original language file to modify (without file extension).
 +
| ''required''
 +
|-
 +
| '''strings'''
 +
| List of the new strings to add/replace, listed as ''stringID: text''.
 +
| -
 +
|}
 +
 
 +
Example:
 +
- type: en-US
 +
  strings:
 +
    STR_SNIPER_RIFLE: Sniper Rifle
 +
    STR_SNIPER_RIFLE_CLIP: Sniper Rifle Clip
 +
- type: en-GB
 +
  strings:
 +
    STR_SNIPER_RIFLE: Sniper Rifle
 +
    STR_SNIPER_RIFLE_CLIP: Sniper Rifle Clip
 +
- type: de
 +
  strings:
 +
    STR_SNIPER_RIFLE: Scharfschützengewehr
 +
    STR_SNIPER_RIFLE_CLIP: Scharfschützengewehrmunition
 +
- type: ru
 +
  strings:
 +
    STR_SNIPER_RIFLE: Снайперская винтовка
 +
    STR_SNIPER_RIFLE_CLIP: Магазин к снайп. винтовке
 +
 
 +
'''Did you know?'''
 +
* Translations can also be provided in the same format as OpenXcom provides them for default languages (en-US and en-GB)
 +
* The advantage over using extraStrings is that the format can be used in Transifex, so that popular mods can be easily translated into many languages by many people in a more coordinated way
 +
 
 +
=== Interfaces ===
 +
 
 +
Defines various properties (most notably colors) and behavior of OpenXcom UI screens, listed in ''"interfaces:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| Name of the interface. Each OpenXcom screen has a unique corresponding interface.
 +
| ''required''
 +
|-
 +
| '''palette'''
 +
| Name of the palette (e.g. PAL_BASESCAPE) to be used for this screen. Not all screens support this.
 +
| -
 +
|-
 +
| '''parent'''
 +
| Name of the parent interface (from which some attributes are inherited).
 +
 
 +
For example research/manufacture screens have a hierarchy of screens opening on top of each other.
 +
| -
 +
|-
 +
| '''music'''
 +
| Music to play when the corresponding screen is opened.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''sound'''
 +
| Sound effect (from GEO.CAT) to play when the corresponding screen is opened.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''backgroundImage'''
 +
| Background image for the corresponding screen.
 +
| -
 +
|-
 +
| '''elements'''
 +
| List of detailed definitions for various elements on the screen (window, text, buttons, lists, etc.). See below.
 +
| -
 +
|}
 +
 
 +
==== Elements ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''id'''
 +
| Name of the interface element.
 +
| ''required''
 +
|-
 +
| '''size'''
 +
| Some elements have configurable size. Defined as [width, height].
 +
| -
 +
|-
 +
| '''pos'''
 +
| Some elements have configurable position. Defined as [x, y], where x<320 and y<200.
 +
| -
 +
|-
 +
| '''color'''
 +
| Most elements have configurable primary color (0-255). Elements called ''palette'' only have range between 0-15 (palette offsets).
 +
| -
 +
|-
 +
| '''color2'''
 +
| Some elements have configurable alternative/secondary color (0-255).
 +
| -
 +
|-
 +
| '''border'''
 +
| Some elements have configurable border/tertiary color (0-255).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''custom'''
 +
| A generic-purpose attribute.
 +
 
 +
Currently used only for inventory interface, specifies which stats are displayed.
 +
| 0
 +
|-
 +
| '''TFTDMode'''
 +
| Is used in TFTD for inversion behavior in some elements, mostly buttons.
 +
| -
 +
|}
 +
 
 +
'''Tip''': which elements support which attributes can be determined by inspecting the vanilla xcom1/xcom2 ruleset.
 +
 
 +
=== StatStrings ===
 +
 
 +
[[Statstrings]] are used to automatically rename soldiers. They are case-sensitive and processed in the order in which they are specified. Processing is stopped either at the end of the list, or when a first rule with a name longer than 1 character (e.g. "Snpr") matches.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''string'''
 +
| String to add to name.
 +
| ''required''
 +
|-
 +
| '''psiStrength'''<br>
 +
'''psiSkill'''<br>
 +
'''bravery'''<br>
 +
'''strength'''<br>
 +
'''firing'''<br>
 +
'''reactions'''<br>
 +
'''stamina'''<br>
 +
'''tu'''<br>
 +
'''health'''<br>
 +
'''throwing'''
 +
| One or more stat ranges are AND-ed together to find a match.
 +
 
 +
Each range has a format [min, max]. Use YAML standard tilde (~) to indicate empty value (interpreted as 0 for min and as 255 for max).
 +
| -
 +
|-
 +
| '''melee'''<br>
 +
'''psiTraining'''
 +
| New attributes (only available in OpenXcom).
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''manaPool'''
 +
| New attribute (only available in OXCE).
 +
| -
 +
|}
 +
 
 +
Example:
 +
  statStrings:
 +
  - string: "x"
 +
    psiStrength: [~, 30]
 +
  - string: "P"
 +
    psiStrength: [80, ~]
 +
  - string: "p"
 +
    psiStrength: [60, 79]
 +
  - string: "K"
 +
    psiSkill: [60, ~]
 +
  - string: "k"
 +
    psiSkill: [30, 59]
 +
  - string: "b"
 +
    bravery: [60, ~]
 +
  - string: "c"
 +
    bravery: [~, 10]
 +
  - string: "w"
 +
    strength: [~, 25]
 +
  - string: "Snpr"
 +
    firing: [60, ~]
 +
    reactions: [60, ~]
 +
  - string: "M"
 +
    firing: [70, ~]
 +
  - string: "m"
 +
    firing: [60, 69]
 +
  - string: "Sct"
 +
    reactions: [50, ~]
 +
    tu: [60, ~]
 +
  - string: "R"
 +
    reactions: [60, ~]
 +
  - string: "r"
 +
    reactions: [50, 59]
 +
 
 +
=== Cutscenes ===
 +
 
 +
Defines a video playlist or a slideshow sequence, listed in ''"cutscenes:"''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''type'''
 +
| String ID of the cutscene.
 +
| ''required''
 +
|- style="background-color:#ddffdd;"
 +
| '''winGame'''
 +
| Whether or not the cutscene ends the game with victory.
 +
 
 +
More info about multiple game endings: https://openxcom.org/forum/index.php/topic,7476.0.html
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''loseGame'''
 +
| Whether or not the cutscene ends the game with defeat.
 +
| false
 +
|-
 +
| '''useUfoAudioSequence'''
 +
| Whether to use the audio sequence for the original UFO intro movie.  This should only ever be set to true for the UFO intro.
 +
| false
 +
|-
 +
| '''videos'''
 +
| A list of video filenames to play with the FLC player. Required if this cutscene is a video playlist.
 +
| -
 +
|-
 +
| '''audioTracks'''
 +
| A list of audio filenames to play along the videos specified in '''videos'''. Optional.
 +
| -
 +
|-
 +
| '''slideshow'''
 +
| Info for playing a slideshow (see below). Required if this cutscene is a slideshow.
 +
| -
 +
|}
 +
 
 +
==== Slideshow Data ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''transitionSeconds'''
 +
| The number of seconds to wait before automatically transitioning to the next slide.  The user can always force a transition by a mouse click.
 +
| 30
 +
|-
 +
| '''musicId'''
 +
| The ID of the music to play.
 +
| -
 +
|-
 +
| '''slides'''
 +
| List of slide data elements (see below).
 +
| ''required''
 +
|}
 +
 
 +
==== Slide Data ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''imagePath'''
 +
| The path to the image file to display in the background.
 +
 
 +
'''Note''': the palette for the slide is taken directly from the image, so the caption text color will be determined by the image palette.
 +
| ''required''
 +
|-
 +
| '''caption'''
 +
| The string ID of the caption text.
 +
| -
 +
|-
 +
| '''captionSize'''
 +
| The size of the text box, in pixels, in which to display the caption.
 +
| [320, 200]
 +
|-
 +
| '''captionPos'''
 +
| The screen position at which to display the caption.
 +
| [0, 0]
 +
|-
 +
| '''captionColor'''
 +
| The palette index to use for the caption color.
 +
| ''required''
 +
|-
 +
| '''transitionSeconds'''
 +
| Override for '''transitionSeconds''' from Slideshow Data, so that each slide can have a different value.
 +
| 0
 +
|-
 +
| '''captionAlign'''
 +
| The horizontal text alignment for the caption text. Possible values: 0 = left, 1 = center, 2 = right.
 +
| 0
 +
|}
 +
 
 +
=== Global Variables ===
 +
 
 +
The following ruleset doesn't belong into any category/hierarchy, it's just standalone settings you can put into any file, on the top level. It mostly contains constants that were deemed worthy making moddable.
 +
 
 +
In vanilla ruleset files, these are located in ''vars.rul'' and in ''difficulty.rul''.
 +
 
 +
==== Resources ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''fontName'''
 +
| Name of *.dat file, placed in Language folder, which describes used [[Font collection (OpenXcom)|font collection]].
 +
| Font.dat
 +
|- style="background-color:#ddffdd;"
 +
| '''disableUnderwaterSounds'''
 +
| Redirects the game to BATTLE.CAT whenever it would want to access BATTLE2.CAT, i.e. underwater sounds will be the same as surface sounds.
 +
 
 +
Hint: a debug option for people working on hybrid UFO/TFTD mods to (for the time being) prevent crashes on missing sounds.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''enableUnitResponseSounds'''
 +
| Enables/disables unit response sounds.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7371.0.html
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''unitResponseSoundsFrequency'''
 +
| Sets the probabilities of unit response sounds being played (each time). First number is for "select unit" sound, second for "start moving" sound, third for "select weapon" sound and fourth for the "annoyed" sound.
 +
| [100, 100, 100, 20]
 +
|- style="background-color:#ddffdd;"
 +
| '''unitResponseSounds'''
 +
| Custom unit response sounds per individual soldier name... when soldier type/armor/gender is just not RPG enough :) Hardcore.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7371.0.html
 +
 
 +
Syntax:
 +
 
 +
  unitResponseSounds:
 +
    - name: Starving Poet
 +
      selectUnitSound:  [200, 201, 202, 203, 204]
 +
      startMovingSound:  [210, 211, 212, 213]
 +
      selectWeaponSound: [220, 221, 222, 223]
 +
      annoyedSound:      [230, 231, 232, 233]
 +
    - name: Ivan Dogovich
 +
      selectUnitSound:  [300, 301, 302, 303, 304, 305]
 +
      startMovingSound:  [310, 311, 312, 313]
 +
      selectWeaponSound: [320, 321, 322, 323]
 +
      annoyedSound:      [330, 331, 332, 333, 334, 335]
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''baseNamesFirst'''<br>
 +
'''baseNamesMiddle'''<br>
 +
'''baseNamesLast'''
 +
| Data for the random base name generator. '''baseNamesMiddle''' and '''baseNamesLast''' are optional. Example:
 +
 
 +
  baseNamesFirst:
 +
    - Big
 +
    - Huge
 +
    - Large
 +
    - Stinky
 +
  baseNamesMiddle:
 +
    - Rat
 +
    - Pirate
 +
  baseNamesLast:
 +
    - Bay
 +
    - Port
 +
    - Haven
 +
    - Tavern
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''operationNamesFirst'''<br>
 +
'''operationNamesLast'''
 +
| Data for the random operation name generator. '''operationNamesLast''' is optional. Example:
 +
 
 +
  operationNamesFirst:
 +
    - Blind
 +
    - Burning
 +
    - Cold
 +
    - Dark
 +
    - Devil's
 +
    - Enduring
 +
    - Fallen
 +
  operationNamesLast:
 +
    - Blade
 +
    - Dream
 +
    - Future
 +
    - Justice
 +
    - Rain
 +
    - Star
 +
    - Thunder
 +
| -
 +
|}
 +
 
 +
==== Сampaign ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''startingTime'''
 +
| Specifies the date and time at the beginning of the game.
 +
| Friday 1.1.1999 12:00:00
 +
|-
 +
| '''initialFunding'''
 +
| Amount of money (in thousands of dollars) the player starts with.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''monthlyRatings'''
 +
| A list of monthly ratings. Each item contains a minimum required score and a corresponding String ID of the rating. Example:
 +
 
 +
  monthlyRatings:
 +
    5000: STR_MT_RATING_AMAZING
 +
    2000: STR_MT_RATING_PERFECT
 +
    1000: STR_MT_RATING_VERY_GOOD
 +
    500: STR_MT_RATING_GOOD
 +
    250: STR_MT_RATING_OK
 +
    0: STR_MT_RATING_MEH
 +
    -350: STR_MT_RATING_BAD
 +
    -99999: STR_MT_RATING_TERRIBLE
 +
 
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''performanceBonusFactor'''
 +
| Defines whether the player receives a financial bonus based on the monthly score. If set for example to 1000 and monthly score is 650, the player receives an extra $650000. In case of a negative monthly score, there is no penalty.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''customTrainingFactor'''
 +
| Additional RNG for stat improvement using martial/combat training facilities. Can be used to slow down training (cannot speed it up). If set for example to 20, the training speed will be five times slower than normal (i.e. training at 20% speed).
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''psiUnlockResearch'''
 +
| In OpenXcom, this is set to Psi-Lab requirements (i.e. the building with '''psiLabs''' > 0). In OXCE, you can set a different research topic to allow Psi screening (using the ''Psi-Strength Evaluation'' advanced option) before the actual Psi training (in Psi Labs) is possible.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''fakeUnderwaterBaseUnlockResearch'''
 +
| Research topic required to be able to build bases on "fake underwater" globe textures.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''allowAlienBasesOnWrongTextures'''
 +
| If a valid location cannot be found after 100 random attempts, use an invalid location (land texture vs. fake underwater texture).
 +
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''allowCountriesToCancelAlienPact'''
 +
| If enabled, XCOM can convince countries that left the XCOM project to come back... by destroying the alien base that was created when the aliens signed a pact with a given country.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''buildInfiltrationBaseCloseToTheCountry'''
 +
| If enabled, alien infiltration bases will be built in or near the infiltrated country (as opposed to anywhere in the whole region).
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''chanceToStopRetaliation'''
 +
| If an XCOM base is found and a battleship sent to attack it is shot down by base defense facilities, aliens will keep sending new battleships ''forever''. This setting defines a chance that they reconsider their decision and stop sending more battleships.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''lessAliensDuringBaseDefense'''
 +
| If enabled, less aliens will spawn in base defense missions, roughly proportional to damage dealt to the invading UFO. At least one alien of each rank is guaranteed to spawn.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''gameOver'''
 +
| A list of cutscene names for special events. More info: https://openxcom.org/forum/index.php/topic,7476.msg117830.html#msg117830
 +
 
 +
  gameOver:
 +
    loseMoney: loseGame      # cutscene ID that should be played when the player loses due to poor economy management
 +
    loseRating: loseGame      # cutscene ID that should be played when the player loses due to poor rating
 +
    loseDefeat: loseGame      # cutscene ID that should be played when the player loses the last base
 +
| <=
 +
|}
 +
 
 +
==== Basescape/Personnel ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''timePersonnel'''
 +
| Time (in hours) it takes for newly hired personnel to arrive at a base.
 +
| 0
 +
|-
 +
| '''costEngineer'''
 +
| Monthly salary of a single engineer (in dollars). Please note that hiring cost is twice as much.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''costHireEngineer'''
 +
| Cost of hiring a single engineer. If not specified (0), it costs twice as much as the monthly salary.
 +
| 0
 +
|-
 +
| '''costScientist'''
 +
| Monthly salary of a single scientist (in dollars). Please note that hiring cost is twice as much.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''costHireScientist'''
 +
| Cost of hiring a single scientist. If not specified (0), it costs twice as much as the monthly salary.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''soldiersPerSergeant'''
 +
| How many soldiers (of any rank) are required to unlock a new sergeant promotion.
 +
| 5
 +
|- style="background-color:#ddffdd;"
 +
| '''soldiersPerCaptain'''
 +
| How many soldiers (of any rank) are required to unlock a new captain promotion.
 +
| 11
 +
|- style="background-color:#ddffdd;"
 +
| '''soldiersPerColonel'''
 +
| How many soldiers (of any rank) are required to unlock a new colonel promotion.
 +
| 23
 +
|- style="background-color:#ddffdd;"
 +
| '''soldiersPerCommander'''
 +
| How many soldiers (of any rank) are required to unlock the commander promotion. There can be only one commander at a time.
 +
| 30
 +
|- style="background-color:#ddffdd;"
 +
| '''shortRadarRange'''
 +
| The maximum radar range still considered as short (for [Base Info] screen purposes). If not specified (0), the smallest range from all radar facilities is used.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''buildTimeReductionScaling'''
 +
| When upgrading base facilities, reduce the build time reduction by this factor (in percent). Or in simpler words, increase the upgrade time.
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''useCustomCategories'''
 +
| Should custom item categories be used in Buy/Sell/Transfer screens? If not, default OpenXcom categories (Craft Armament, Equipment, Components, Aliens) are used.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''shareAmmoCategories'''
 +
| If enabled, firearms will "inherit" the categories of their ammo (only the available ammo counts). Affected are: 1/ Craft Equipment screen and 2/ Starting conditions (allowed/disabled item categories). Not affected: Buy/Sell/Transfer screens.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''maxLookVariant'''
 +
| The maximum supported lookVariant (0-63) used in [Change Soldier Avatar] dialog.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''flagByKills'''
 +
| OXCE allows to display flags next to soldier names, based on their nationality (resp. based on the name pool from which their name was chosen). If this setting is used, the flag will depend on the number of kills from soldier's diary instead.
 +
 
 +
  flagByKills: [10,20,30]
 +
 
 +
Example above means:
 +
* 0-10 kills = Flag0 sprite is used
 +
* 11-20 = Flag1 sprite
 +
* 21-30 = Flag2 sprite
 +
* 31+ = Flag3 sprite
 +
 
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''alienInventoryOffsetX'''
 +
| Hand slots of the "alien inventory" (inventory accessible via Middle-button-click) will be shifted to the right by this much.
 +
| 80
 +
|- style="background-color:#ddffdd;"
 +
| '''alienInventoryOffsetBigUnit'''
 +
| Hand slots of the "alien inventory" (inventory accessible via Middle-button-click) will be shifted away from each other by this much for 2x2 units.
 +
| 32
 +
|}
 +
 
 +
==== Interception ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''drawEnemyRadarCircles'''
 +
| When should the alien UFO (hunter-killer) and alien base radar ranges be drawn? Possible options:
 +
* 0 = never drawn
 +
* 1 = drawn for bases if discovered and for UFOs if hyper-detected
 +
* 2 = drawn for bases if discovered and for UFOs if detected
 +
| 1
 +
|- style="background-color:#ddffdd;"
 +
| '''pilotAccuracyZeroPoint'''
 +
| Average firing accuracy for a pilot (where the accuracy bonus is 0%).
 +
| 55
 +
|- style="background-color:#ddffdd;"
 +
| '''pilotAccuracyRange'''
 +
| The firing accuracy impact (as a percentage of the distance to the zero point) on the pilot's aim in dogfights.
 +
| 40
 +
|- style="background-color:#ddffdd;"
 +
| '''pilotReactionsZeroPoint'''
 +
| Average reactions for a pilot (where the dodge bonus is 0%).
 +
| 55
 +
|- style="background-color:#ddffdd;"
 +
| '''pilotReactionsRange'''
 +
| The reactions impact (as a percentage of the distance to the zero point) on the pilot's dodge ability in dogfights.
 +
| 60
 +
|- style="background-color:#ddffdd;"
 +
| '''pilotBraveryThresholds'''
 +
| The pilot's bravery needed for [Very Bold, Bold, Normal] approach speed during dogfights. If neither is reached, approach speed is Cowardly.
 +
| [90, 80, 30]
 +
|- style="background-color:#ddffdd;"
 +
| '''showDogfightDistanceInKm'''
 +
| Should the distance between the craft and a UFO be shown in kilometers (true) or in vanilla units (false)? Vanilla units equal to 8-times the distance in kilometers.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''ufoGlancingHitThreshold'''
 +
| The threshold for defining a glancing hit on a UFO during interception. Defined as a percentage of damage needed to shoot it down (i.e. half of '''damageMax''').
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''ufoBeamWidthParameter'''
 +
| The parameter for drawing the width of a UFO's beam weapon based on power. The width of the beam in pixels will be weapon power divided by this parameter, but at least 3 pixels. For example if the weapon power is 250 and parameter is 50, the beam size in pixels will be 5.
 +
| 1000
 +
|- style="background-color:#ddffdd;"
 +
| '''ufoTractorBeamSizeModifiers'''
 +
| The modifiers to a tractor beam's power based on a UFO's size.
 +
 
 +
  ufoTractorBeamSizeModifiers:
 +
    - 400 # very small, tractor beams are 400% or 4x as effective
 +
    - 200
 +
    - 100
 +
    - 50
 +
    - 25 # very large, tractor beams are 25% or 1/4x as effective
 +
 
 +
| [400, 200, 100, 50, 25]
 +
|- style="background-color:#ddffdd;"
 +
| '''hunterKillerFastRetarget'''
 +
| If enabled, the UFO hunter-killers can reconsider their target every 5 seconds on low game speeds (5sec/1min) and every 10 minutes on all other game speeds. If disabled, it is only every 10 minutes on all game speeds.
 +
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''escortRange'''
 +
| Range (in nautical miles) in which the craft is considered to be escorted by a nearby craft.
 +
| 20
 +
|- style="background-color:#ddffdd;"
 +
| '''escortsJoinFightAgainstHK'''
 +
| Should craft escorts join the fight against HK automatically (true)? Or is only fighting one-on-one allowed (false)?
 +
| true
 +
|- style="background-color:#ddffdd;"
 +
| '''crewEmergencyEvacuationSurvivalChance'''
 +
| The chance of soldiers (that are not pilots) surviving craft destruction by a UFO hunter-killer (jumping out with a parachute).
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''pilotsEmergencyEvacuationSurvivalChance'''
 +
| The chance of pilots surviving craft destruction by a UFO hunter-killer (emergency seat ejection).
 +
| 100
 +
|}
 +
 
 +
==== Pedia ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''pediaReplaceCraftFuelWithRangeType'''
 +
| What type of information should be shown in craft articles for the fuel capacity/range? Possible options:
 +
* -1 = Fuel capacity
 +
* 0 = Maximum theoretical range
 +
* 1 = Minimum and maximum theoretical max range
 +
* 2 = Average theoretical max range
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''hidePediaInfoButton'''
 +
| Show the INFO button (where applicable) or not?
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''extraNerdyPediaInfo'''
 +
| Display extra item info (accuracy modifier and power bonus) in the main pedia article or not?
 +
| false
 +
|}
 +
 
 +
==== Battlescape ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''alienFuel'''
 +
| Name of an item representing alien fuel and a quantity to recover from a single fuel cell. Format: [name, quantity].
 +
| [-, -]
 +
|- style="background-color:#ddffdd;"
 +
| '''baseDefenseMapFromLocation'''
 +
| Whether or not to load additional base defense terrain from globe texture. 0 = no, 1 = yes.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,5108.0.html
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''lighting'''
 +
| Configuration of light propagation:
 +
* '''enhanced''': flags to switch between vanilla and directional light propagation (1 = directional for tiles and fire, 2 = directional for items, 4 = directional for units); add the numbers together to turn on multiple flags (e.g. 1+2+4=7 = directional lighting for all light sources)
 +
* '''maxStatic''': maximum range/radius for tile and fire light propagation
 +
* '''maxDynamic''': maximum range/radius for item and unit light propagation
 +
 
 +
Defaults:
 +
 
 +
  lighting:
 +
    enhanced: 0
 +
    maxStatic: 16  #Careful, affects overall game performance!
 +
    maxDynamic: 24  #Careful, affects overall game performance!
 +
 
 +
| <=
 +
|- style="background-color:#ddffdd;"
 +
| '''maxViewDistance'''
 +
| Maximum view distance (in tiles). If you want to use bigger/custom view distances (in general, or per armor), you need to set this variable to the maximum of all view distances you're using.
 +
 
 +
'''VERY IMPORTANT''': Although optimized (in OXCE) a lot compared to OpenXcom, this setting still has huge impact on game performance! The performance decrease is exponential, i.e. changing value from 20 to 40 doesn't decrease the performance only by a factor of 2, but much much more. Recommended maximum value is up to 30. If you're willing to sacrifice game performance you can go up to 40. Above 40, it's unplayable.
 +
| 20
 +
|- style="background-color:#ddffdd;"
 +
| '''maxDarknessToSeeUnits'''
 +
| The threshold of shade/darkness for LoS calculation. Shade ranges (for value set to 9):
 +
* 0 = no shade: Daylight, full visibility.
 +
* 1-9 = partial shade: Dusk/Dawn, also full visibility.
 +
* 10-15 = full shade: Night, decreased visibility for XCOM.
 +
| 9
 +
|- style="background-color:#ddffdd;"
 +
| '''noLOSAccuracyPenaltyGlobal'''
 +
| A global default value for accuracy penalty (in percent), when shooting at a unit or tile outside of LoS (line of sight). Can be overridden per weapon.
 +
| -1
 +
|- style="background-color:#ddffdd;"
 +
| '''kneelBonusGlobal'''
 +
| A global default value for accuracy bonus, when kneeling. Can be overridden per weapon. 115 means 15% bonus (100+15).
 +
| 115
 +
|- style="background-color:#ddffdd;"
 +
| '''oneHandedPenaltyGlobal'''
 +
| A global default value for accuracy penalty, when using a two-handed weapon with just one hand. Can be overridden per weapon. 80 means 20% penalty (100-20).
 +
| 80
 +
|- style="background-color:#ddffdd;"
 +
| '''enableCloseQuartersCombat'''
 +
| Whether or not CQC (close quarters combat) feature should be enabled. 0 = no, 1 = yes.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''closeQuartersAccuracyGlobal'''
 +
| A global default "accuracy" value for CQC check. Can be overridden per weapon.
 +
 
 +
'''FIXME''': add a full example of CQC check, with all variables included.
 +
| 100
 +
|- style="background-color:#ddffdd;"
 +
| '''closeQuartersTuCostGlobal'''
 +
| Amount of time units the target unit (victim) needs to have to be able to perform CQC. If CQC is triggered, TUs will be also spent. If CQC is not triggered, TUs will '''not''' be spent.
 +
| 12
 +
|- style="background-color:#ddffdd;"
 +
| '''closeQuartersEnergyCostGlobal'''
 +
| Amount of energy the target unit (victim) needs to have to be able to perform CQC. If CQC is triggered, energy will be also spent. If CQC is not triggered, energy will '''not''' be spent.
 +
| 8
 +
|- style="background-color:#ddffdd;"
 +
| '''tooMuchSmokeThreshold'''
 +
| A technical parameter, which you may want to change if you want to be able to (always) extinguish fire from map tiles using smoke.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,4057.msg59352.html#msg59352
 +
| 10
 +
|- style="background-color:#ddffdd;"
 +
| '''hiddenMovementBackgrounds'''
 +
| A list of sprites for "Hidden Movement" backgrounds. Chosen randomly at the beginning of a mission. Purely cosmetic.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''showFullNameInAlienInventory'''
 +
| A global default value for showing unit name (true) or unit race (false) in the [Alien Inventory] screen. Can be overridden per unit type.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''destroyedFacility'''
 +
| A global default value defining a special "rubble" facility that remains after a normal facility is destroyed (during base defense or via alien missile attacks/bombardment). Must have size 1. Can be overridden per facility type.
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''giveScoreAlsoForResearchedArtifacts'''
 +
| Whether the game awards score (in Debriefing) also for researched alien artifacts (true) or only for not yet researched artifacts (false).
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''missionRatings'''
 +
| A list of mission ratings. Each item contains a minimum required mission score and a corresponding String ID of the rating. Example:
 +
 
 +
  missionRatings:
 +
    2000: STR_MS_RATING_HOLY_COW
 +
    1000: STR_MS_RATING_AMAZING
 +
    750: STR_MS_RATING_PERFECT
 +
    500: STR_MS_RATING_VERY_GOOD
 +
    350: STR_MS_RATING_GOOD
 +
    150: STR_MS_RATING_OK
 +
    0: STR_MS_RATING_MEH
 +
    -200: STR_MS_RATING_BAD
 +
    -350: STR_MS_RATING_WORSE
 +
    -500: STR_MS_RATING_TERRIBLE
 +
    -1000: STR_MS_RATING_DISASTER
 +
    -99999: STR_MS_RATING_EPIC_FAIL
 +
 
 +
| -
 +
|- style="background-color:#ddffdd;"
 +
| '''statisticalBulletConservation'''
 +
| If enabled, there's a chance to recover a full clip depending on how much ammo has remained.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''stunningImprovesMorale'''
 +
| If enabled, stunning enemies improves morale in a similar way killing an enemy does.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7439.0.html
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''tuRecoveryWakeUpNewTurn'''
 +
| Percentage of max TU that should be given to a unit that wakes up from unconsciousness at a beginning of a new turn.
 +
| 100
 +
|}
 +
 
 +
==== Mana ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''mana'''
 +
| Global switches to turn mana GUI and features on/off.
 +
 
 +
More info: https://openxcom.org/forum/index.php/topic,7241.0.html
 +
 
 +
Example:
 +
 
 +
  mana:
 +
    enabled: false
 +
    battleUI: false
 +
    unlockResearch: STR_SORCERY    # empty by default
 +
    trainingPrimary: false
 +
    trainingSecondary: false
 +
    woundThreshold: 200            # default is 200
 +
    replenishAfterMission: true
 +
 
 +
| see example
 +
|- style="background-color:#ddffdd;"
 +
| '''health'''
 +
| Health recovery modding options. Allows soldiers to go into battle even with missing health.
 +
 
 +
More info: FIXME
 +
 
 +
Example:
 +
 
 +
  health:
 +
    woundThreshold: 100            # default is 100
 +
    replenishAfterMission: true
 +
 
 +
| see example
 +
|}
 +
 
 +
==== AI ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''minReactionAccuracy'''
 +
| Minimum firing accuracy for reaction fire. Used to prevent AI making shots that are unlikely to hit, which only makes them waste ammo and TUs. Instead they could wait until the target comes closer or shoot at another target.
 +
| 0
 +
|-
 +
| '''turnAIUseGrenade'''
 +
| Defines a turn, from which the aliens are allowed to use grenades.
 +
| 3
 +
|-
 +
| '''turnAIUseBlaster'''
 +
| OXC: Defines a turn, from which the aliens are allowed to use any AoE weapons (blaster launcher, small launcher, etc.).
 +
<span style="background:#ddffdd;">OXCE: Defines a turn, from which the aliens are allowed to use waypoint-based weapons.</span>
 +
| 3
 +
|- style="background-color:#ddffdd;"
 +
| '''ai.useDelayBlaster'''
 +
| Alias for '''turnAIUseBlaster'''.
 +
| 3
 +
|- style="background-color:#ddffdd;"
 +
| '''ai.useDelayFirearm'''
 +
| Defines a turn, from which the aliens are allowed to use firearms.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''ai.useDelayGrenade'''
 +
| Alias for '''turnAIUseGrenade'''.
 +
| 3
 +
|- style="background-color:#ddffdd;"
 +
| '''ai.useDelayMelee'''
 +
| Defines a turn, from which the aliens are allowed to use melee weapons.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''ai.useDelayPsionic'''
 +
| Defines a turn, from which the aliens are allowed to use psi amps.
 +
 
 +
Example:
 +
 
 +
  ai:
 +
    useDelayBlaster: 3
 +
    useDelayFirearm: 1
 +
    useDelayGrenade: 1
 +
    useDelayMelee: 1
 +
    useDelayPsionic: 2
 +
 
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''ai.fireChoiceIntelCoeff'''<br/>'''ai.fireChoiceAggroCoeff'''
 +
| More info here: https://openxcom.org/forum/index.php/topic,5679.0.html
 +
| 5<br/>5
 +
|- style="background-color:#ddffdd;"
 +
| '''ai.extendedFireModeChoice'''<br/>'''ai.respectMaxRange'''
 +
| More info here: https://openxcom.org/forum/index.php/topic,5980.0.html
 +
| false<br/>false
 +
|- style="background-color:#ddffdd;"
 +
| '''ai.destroyBaseFacilities'''
 +
| More info here: https://openxcom.org/forum/index.php/topic,6663.0.html
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''ai.pickUpWeaponsMoreActively'''<br/>'''ai.pickUpWeaponsMoreActivelyCiv'''
 +
| More info here: https://openxcom.org/forum/index.php/topic,6882.0.html
 +
| false<br/>false
 +
|}
 +
 
 +
===== Surrendering, Bughunt =====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''surrenderMode'''
 +
| Allows enemies to surrender (they will be taken as prisoners). Possible options:
 +
* 0 = no surrender
 +
* 1 = if all remaining standing enemies can surrender; and they want to surrender at this very moment (their current status is panicking or berserking)... end the battle
 +
* 2 = if all remaining standing enemies can surrender; and they have panicked/berserked at least once or have been stunned at least once... end the battle
 +
* 3 = same as option 2, but enemies must also have empty hands
 +
 
 +
In all 3 cases, enemies marked as "auto surrender" are not checked and count as surrendered.
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''bughuntMinTurn'''
 +
| Earliest turn on which the "bughunt mode" can be activated. Once activated, it won't be turned off (except on multi-stage missions). During bughunt mode, you can see all remaining enemies on the minimap.
 +
| 999
 +
|- style="background-color:#ddffdd;"
 +
| '''bughuntMaxEnemies'''
 +
| Maximum amount of active enemies for bughunt mode to trigger.
 +
| 2
 +
|- style="background-color:#ddffdd;"
 +
| '''bughuntRank'''
 +
| If VIPs are still active, bughunt won't trigger. Possible options:
 +
* -1 = no VIPs
 +
* 0 = aliens with rank 0 are VIPs
 +
* 1 = aliens with rank 0 and 1 are VIPs
 +
* 2 = aliens with rank 0, 1 and 2 are VIPs
 +
* and so on...
 +
| 0
 +
|- style="background-color:#ddffdd;"
 +
| '''bughuntLowMorale'''
 +
| Defines a threshold for "low morale".
 +
| 40
 +
|- style="background-color:#ddffdd;"
 +
| '''bughuntTimeUnitsLeft'''
 +
| Defines a threshold for "too much TUs".
 +
 
 +
If a unit doesn't have any weapon (in both hands) or if a unit has "low morale" or if a unit has "too much TUs" (i.e. cannot/doesn't move for whatever reason)... it counts as powerless and bug hunt can be activated.
 +
 
 +
If there is still a unit that is not powerless, bug hunt won't be activated.
 +
| 60
 +
|}
 +
 
 +
==== Difficulty Settings ====
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''startingDifficulty'''
 +
| Pre-selected difficulty when starting a new game. Possible options:
 +
* 0 = beginner
 +
* 1 = experienced
 +
* 2 = veteran
 +
* 3 = genius
 +
* 4 = superhuman
 +
| 0
 +
|-
 +
| '''difficultyCoefficient'''
 +
| Difficulty coefficients (per 5 game difficulty levels) affecting various game mechanics, for example:
 +
* Monthly rating threshold for losing the game (together with '''defeatScore''') | (defeatScore) +100 points * difficultyCoefficient
 +
* UFO firing rate during dogfight | -2 gs * difficultyCoefficient
 +
* UFO escape countdown during dogfight | (100-200%) -30 gs * difficultyCoefficient
 +
* Retaliation odds after shooting down UFO | (4%) +4% * difficultyCoefficient
 +
* Odds of shootdown-triggered retaliation targeting xcom base region or not | (50%) +6% * difficultyCoefficient (needs confirmation)
 +
* Chance of aliens facing in the direction of the xcom craft at a start of a mission | 25% * difficultyCoefficient
 +
* Various AI decisions (in Battlescape)
 +
* Together with '''statGrowthMultipliers''' affects how alien stats change with difficulty level | + (statGrowthMultipliers/100) * difficultyCoefficient
 +
* Does not affect aimAndArmorMultipliers.
 +
| [0, 1, 2, 3, 4]
 +
|-
 +
| '''aimAndArmorMultipliers'''
 +
| Affects armor values and firing accuracy of aliens for different difficulty levels.
 +
| [0.5, 1.0, 1.0, 1.0, 1.0]
 +
|-
 +
| '''statGrowthMultipliers'''
 +
| Affects unit stats of aliens for different difficulty levels.
 +
| -
 +
|-
 +
| '''defeatScore'''
 +
| Monthly score threshold for losing the game on Beginner difficulty. Other difficulties have different thresholds, affected by '''difficultyCoefficient'''.
 +
| 0
 +
|-
 +
| '''defeatFunds'''
 +
| Debt threshold (at a start of a month) for losing the game, on all difficulty levels.
 +
| 0
 +
|}
 +
 
 +
==== Other Constants ====
 +
 
 +
These are constants that were needed to support TFTD in OpenXcom. You are most likely never going to need to modify them, but we list them here for completeness sake. They are defined as an associative array of values (a list of values syntax is deprecated) under the ''constants:'' entry.
 +
 
 +
Some of these constants can be considered as difficulty settings, and vanilla ruleset defines them in ''difficulty.rul''.
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''damageRange'''
 +
| Defines the damage range for projectile weapons. 100 means 0-200% range, 50 means 50-150% range, 25 means 75-125% range, etc.
 +
| 100
 +
|-
 +
| '''explosiveDamageRange'''
 +
| Defines the damage range for AOE weapons (e.g. explosives).
 +
| 50
 +
|-
 +
| '''fireDamageRange'''
 +
| Defines the damage range for incendiary weapons. Format is: [min, max].
 +
| [5, 10]
 +
|}
 +
 
 +
These constants can be especially interesting for hybrid mods (UFO/TFTD hybrids).
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''explosionOffset'''
 +
| Explosion offset in X1.PCK
 +
 
 +
Note: this defines the land explosion offset. Underwater explosion offset is smaller by 8. For example, if you define land offset to be 24, underwater offset will be automatically set to 16.
 +
| 0
 +
|-
 +
| '''smokeOffset'''
 +
| Surface smoke animation offset in SMOKE.PCK
 +
| 8
 +
|-
 +
| '''underwaterSmokeOffset'''
 +
| Underwater smoke animation offset in SMOKE.PCK
 +
| 0
 +
|}
 +
 
 +
<div style="background:#ddffdd;">And there are a few OXCE-only constants, that were put into this section for technical reasons.
 +
</div>
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|- style="background-color:#ddffdd;"
 +
| '''extendedItemReloadCost'''
 +
| If set to true, the item reload cost equals to "cost of moving ammo to hand" + "cost of reload".
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''extendedRunningCost'''
 +
| If set to true, running soldiers will ignore mutual surprise (i.e. will not stop running when spotting a new enemy).
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''extendedHwpLoadOrder'''
 +
| If set to true, craft load order is: 2x2 HWPs, 2x2 soldiers, 1x1 HWPs, 1x1 soldiers.
 +
If false, load order is: all HWPs, all soldiers.
 +
| false
 +
|- style="background-color:#ddffdd;"
 +
| '''extendedMeleeReactions'''
 +
| Enables reactions to melee attacks.
 +
* 0 = vanilla, cannot react to melee attacks
 +
* 1 = can react to melee attacks, if attacked from the front
 +
* 2 = can react to melee attacks, if attacked from any side
 +
| 0
 +
|}
 +
 
 +
The rest is defined in ''vars.rul'' (for TFTD), or left untouched at default values (for UFO:EU).
 +
 
 +
{| class="wikitable" width="100%"
 +
! width="150"| Value
 +
! width="*"  | Description
 +
! width="80" | Default
 +
|-
 +
| '''doorSound'''
 +
| Sound of normal doors opening.
 +
| 3
 +
|-
 +
| '''slidingDoorSound'''
 +
| Sound of sliding doors opening.
 +
| 20
 +
|-
 +
| '''slidingDoorClose'''
 +
| Sound of sliding doors closing.
 +
| 21
 +
|-
 +
| '''smallExplosion'''
 +
| Sound of a small explosion (power <= 80).
 +
| 2
 +
|-
 +
| '''largeExplosion'''
 +
| Sound of a large explosion (power > 80).
 +
| 5
 +
|-
 +
| '''itemDrop'''
 +
| Sound of item dropping (in the inventory).
 +
| 38
 +
|-
 +
| '''itemThrow'''
 +
| Sound of item being thrown.
 +
| 39
 +
|-
 +
| '''itemReload'''
 +
| Reload sound.
 +
| 17
 +
|-
 +
| '''walkOffset'''
 +
| Offset for various footstep sounds.
 +
| 22
 +
|-
 +
| '''flyingSound'''
 +
| Sound of a unit flying.
 +
| 15
 
|-
 
|-
−
| '''id'''
+
| '''buttonPress'''
−
| String ID of the trajectory name.
+
| Sound played when a button is pressed.
−
| ''required''
 
−
|-
 
−
| '''groundTimer'''
 
−
| Amount of seconds for the UFO to spend on Ground waypoints.
 
 
| 0
 
| 0
 
|-
 
|-
−
| '''waypoints'''
+
| '''windowPopup'''
−
| List of waypoints for the UFO to traverse, defined as ''[zone, altitude, speed]''.<br>
+
| Sounds played (one chosen randomly) when a window pops up.
−
'''zone''': Globe zone where the waypoint is located.<br>
+
| [1, 2, 3]
−
'''altitude''': UFO altitude after reaching this waypoint:
 
−
* 0 - Ground
 
−
* 1 - Very Low
 
−
* 2 - Low
 
−
* 3 - High
 
−
* 4 - Very High
 
−
'''speed''': UFO speed after reaching this waypoint, as a percentage (0-100%) of its maximum speed.
 
−
| -
 
−
|}
 
−
 
 
−
=== Alien Missions ===
 
−
 
 
−
Defines an [[Alien Missions|alien mission]] carried out by UFOs on the Geoscape, listed in ''"alienMissions:"''.
 
−
 
 
−
{| class="wikitable" width="100%"
 
−
! width="150"| Value
 
−
! width="*"  | Description
 
−
! width="80" | Default
 
−
|-
 
−
| '''type'''
 
−
| String ID of the mission type.
 
−
| ''required''
 
 
|-
 
|-
−
| '''points'''
+
| '''ufoFire'''
−
| [[Score]] allocated to aliens for successfully completing this mission.
+
| Sound of a UFO firing.
−
| 0
+
| 8
 
|-
 
|-
−
| '''raceWeights'''
+
| '''ufoHit'''
−
| List of alien races likely to carry out this mission, and the % chance of them being allocated to this mission, listed by "number of months after game beginning".
+
| Sound of a UFO being hit.
−
| ''required''
+
| 12
 
|-
 
|-
−
| '''waves'''
+
| '''ufoCrash'''
−
| List of UFO waves to spawn as this mission progresses, as described below.
+
| Sound of a UFO crashing.
−
| ''required''
+
| 10
−
|}
 
−
 
 
−
==== Waves ====
 
−
 
 
−
{| class="wikitable" width="100%"
 
−
! width="150"| Value
 
−
! width="*"  | Description
 
−
! width="80" | Default
 
 
|-
 
|-
−
| '''ufo'''
+
| '''ufoExplode'''
−
| String ID of the [[#UFOs|UFO]] to spawn.
+
| Sound of a UFO being destroyed.
−
| ''required''
+
| 11
 
|-
 
|-
−
| '''count'''
+
| '''interceptorHit'''
−
| Number of UFOs to spawn.
+
| Sound of an XCOM interceptor being hit.
−
| 0
+
| 10
 
|-
 
|-
−
| '''trajectory'''
+
| '''interceptorExplode'''
−
| String ID of the [[#UFO Trajectories|trajectory]] for this UFO to use when entering Earth's atmosphere.
+
| Sound of an XCOM interceptor being destroyed.
−
| ''required''
+
| 13
 
|-
 
|-
−
| '''timer'''
+
| '''geoscapeCursor'''
−
| How long after the previous wave should this wave arrive? (in seconds)
+
| Palette offset for a cursor when using PAL_GEOSCAPE palette.
−
| 0
+
| 252
 
|-
 
|-
−
|}
+
| '''basescapeCursor'''
−
 
+
| Palette offset for a cursor when using PAL_BASESCAPE palette.
−
=== Alien Item Levels ===
+
| 252
−
 
 
−
This is a list of item level probabilities, with a number between 0 and 2 representing an item level from plasma pistols to heavy plasmas, as defined in the deployments, expressing a 10% probability for that item level being used.
 
−
 
 
−
0 = first set (plasma pistol/clip)
 
−
1 = second set (plasma rifle/clip)
 
−
2 = third set (heavy plasma/clip)
 
−
 
 
−
For example:
 
−
[ 2, 0, 0, 0, 0, 0, 0, 1, 1, 1 ]
 
−
would represent a 60% chance for pistols, 30% rifles, and 10% heavy weapons.<br>
 
−
Note that the order does not matter, but the length DOES. each line MUST have 10 digits.
 
−
 
 
−
The above can be confusing. There are 10 fields; each number represents 10%.<br>
 
−
There are six instances of '0'. 6x10% = 60% chance of plasma pistol<br>
 
−
There are three instances of '1'. 3x10% = 30% chance of plasma rifle<br>
 
−
There is only one instance of '2'. 1x10% = 10% chance of heavy plasma<br>
 
−
 
 
−
Each line represents a month after the beginning of the game, and there is no limit to the number defined.<br>
 
−
OpenXCom will use the most recently available item level in the event the game goes on forever.
 
−
 
 
−
=== Extra Sprites ===
 
−
 
 
−
Adds or replaces sprites in an existing [[Image Formats|X-COM image file]], listed in ''"extraSprites:"''.
 
−
 
 
−
{| class="wikitable" width="100%"
 
−
! width="150"| Value
 
−
! width="*"  | Description
 
−
! width="80" | Default
 
 
|-
 
|-
−
| '''type'''
+
| '''battlescapeCursor'''
−
| Filename of the original/new image to modify.
+
| Palette offset for a cursor when using PAL_BATTLESCAPE* palettes.
−
| ''required''
+
| 144
 
|-
 
|-
−
| '''width'''
+
| '''ufopaediaCursor'''
−
'''height'''
+
| Palette offset for a cursor when using PAL_UFOPAEDIA palette.
−
| Size of the sprite(s) in pixels.
+
| 252
−
| 0
 
−
0
 
 
|-
 
|-
−
| '''singleImage'''
+
| '''graphsCursor'''
−
| Is the image file just a single sprite (true) or a spritesheet (false)?
+
| Palette offset for a cursor when using PAL_GRAPHS palette.
−
| false
+
| 252
 
|-
 
|-
−
| '''subX'''
+
| '''goodDebriefingMusic'''
−
'''subY'''
+
| Music played in the Debriefing when the score is positive.
−
| Size of the subdivision in pixels. If a subdivision is specified, then the image file is divided into chunks to form the sprites (eg. spritesheets).
+
| GMMARS
−
| 0
 
−
0
 
 
|-
 
|-
−
| '''files'''
+
| '''badDebriefingMusic'''
−
| List of the new sprites to add/replace, listed as ''spriteID: filename''.
+
| Music played in the Debriefing when the score is zero or negative.
−
| -
+
| GMMARS
 
|}
 
|}
  
−
Example:
+
=== Recommended/Fixed User Options ===
−
- type: GIANTBUNNY.PCK
 
−
  width: 32
 
−
  height: 40
 
−
  files:
 
−
    0: Resources/Bunny/Bunny00.png
 
−
    1: Resources/Bunny/Bunny01.bmp
 
−
    2: Resources/Bunny/Bunny02.gif
 
−
 
 
−
=== Extra Sounds ===
 
−
 
 
−
Adds or replaces sounds in an existing [[SOUND|X-COM sound file]], listed in ''"extraSounds:"''.
 
  
−
{| class="wikitable" width="100%"
+
<div style="background:#ddffdd;">
−
! width="150"| Value
+
OpenXcom offers various settings in the [Options > Advanced] screen.
−
! width="*"  | Description
 
−
! width="80" | Default
 
−
|-
 
−
| '''type'''
 
−
| ID of the original sound file to modify:
 
−
* BATTLE.CAT - Battlescape sounds, corresponds to ''SOUND1.CAT'' or ''SAMPLE2.CAT'' (55 sounds).
 
−
* INTRO.CAT - Intro sounds, corresponds to ''INTRO.CAT'' or ''SAMPLE3.CAT'', probably best not to mess with these.
 
−
* GEO.CAT - Geoscape sounds, corresponds to ''SOUND2.CAT'' or ''SAMPLE.CAT'' (14 sounds).
 
−
| ''required''
 
−
|-
 
−
| '''files'''
 
−
| List of the new sounds to add/replace, listed as ''soundID: filename''.
 
−
| -
 
−
|}
 
  
−
Example:
+
Some of these settings however are actually not user settings, but rather mod settings. Or in other words, some settings are either not compatible with some mods or change the mod balance in an unacceptable way. Therefore, OXCE gives modders the option to fix these settings. i.e. set them to a desired value and not allow users to change them.
−
- type: BATTLE.CAT
 
−
  files:
 
−
    55: Resources/Sounds/sample.wav
 
  
−
=== Music ===
+
All these fixed options are listed in ''"fixedUserOptions:"''. For example:
  
−
Custom music options can be defined in the Music.rul file.  More details [[Audio Options (OpenXcom)#Custom Music|here]].
+
  fixedUserOptions:
 +
    battleUFOExtenderAccuracy: true
 +
    battleInstantGrenade: false
 +
    allowPsiStrengthImprovement: false
  
−
=== Extra Strings ===
+
Since OXCE v6.5.1, there is also a possibility to only recommend some settings... meaning the settings will be changed only once by a mod (when activated) and the user will still be able to change the settings manually.
  
−
Adds or replaces text strings in an existing [[Translations (OpenXcom)|OpenXcom language file]], listed in ''"extraStrings:"''.
+
All these recommended options are listed in ''"recommendedUserOptions:"''. For example:
  
−
{| class="wikitable" width="100%"
+
  recommendedUserOptions:
−
! width="150"| Value
+
    oxceNightVisionColor: 2
−
! width="*"  | Description
+
    oxceManufactureScrollSpeed: 5
−
! width="80" | Default
+
    oxceManufactureScrollSpeedWithCtrl: 1
−
|-
+
    oxceResearchScrollSpeed: 1
−
| '''type'''
+
    oxceResearchScrollSpeedWithCtrl: 5
−
| Filename of the original language file to modify, sans extension.
 
−
| ''required''
 
−
|-
 
−
| '''strings'''
 
−
| List of the new strings to add/replace, listed as ''stringID: text''.
 
−
| -
 
−
|}
 
  
−
Example:
+
Below is a list of possible options to fix, their default English names and possible values, grouped by category.
−
- type: en-US
+
* There are more options (than listed below) in each category, but they are real user settings, so we don't list them here.
−
  strings:
+
* The codes are the same as used in ''options.cfg'' configuration file.
−
    STR_SNIPER_RIFLE: Sniper Rifle
+
</div>
−
    STR_SNIPER_RIFLE_CLIP: Sniper Rifle Clip
 
−
- type: en-GB
 
−
  strings:
 
−
    STR_SNIPER_RIFLE: Sniper Rifle
 
−
    STR_SNIPER_RIFLE_CLIP: Sniper Rifle Clip
 
−
- type: de
 
−
  strings:
 
−
    STR_SNIPER_RIFLE: Scharfschützengewehr
 
−
    STR_SNIPER_RIFLE_CLIP: Scharfschützengewehrmunition
 
−
- type: ru
 
−
  strings:
 
−
    STR_SNIPER_RIFLE: Снайперская винтовка
 
−
    STR_SNIPER_RIFLE_CLIP: Магазин к снайп. винтовке
 
  
−
=== Interfaces ===
+
==== General ====
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
−
! width="150"| Value
+
! width="200"| Code
−
! width="*"  | Description
+
! width="*"  | Name
−
! width="80" | Default
+
! width="200" | Possible values
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''type'''
+
| '''playIntro'''
−
| ''?''
+
| Play intro; this is normally a user option. A modder working on a total conversion mod may want to disable it though.
−
| -
+
| true/false
−
|-
 
−
| '''elements'''
 
−
| ''?''
 
−
| -
 
−
|-
 
−
| '''id'''
 
−
| ''?''
 
−
| -
 
−
|-
 
−
| '''color'''
 
−
| ''?''
 
−
| -
 
 
|}
 
|}
  
−
=== StatStrings ===
+
==== Geoscape ====
−
 
 
−
[[Statstrings]] are used for automatically renaming soldiers.  They are case sensitive and they are processed in the order in which they are specified.
 
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
−
! width="150"| Value
+
! width="200"| Code
−
! width="*"  | Description
+
! width="*"  | Name
−
! width="80" | Default
+
! width="200" | Possible values
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''string'''
+
| '''aggressiveRetaliation'''
−
| String to add to name.
+
| Aggressive retaliation
−
| ''required''
+
| true/false
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''psiStrength'''<br>
+
| '''customInitialBase'''
−
'''psiSkill'''<br>
+
| Custom initial base
−
'''bravery'''<br>
+
| true/false
−
'''strength'''<br>
+
|- style="background-color:#ddffdd;"
−
'''firing'''<br>
+
| '''allowBuildingQueue'''
−
'''reactions'''<br>
+
| Allow building queue; this is normally a user option.
−
'''stamina'''<br>
+
| true/false
−
'''tu'''<br>
+
|- style="background-color:#ddffdd;"
−
'''health'''<br>
+
| '''craftLaunchAlways'''
−
'''throwing'''
+
| Force craft launch
−
| One or more stat ranges are ANDed together for success. Each range has a minVal and maxVal. Use YAML standard tilde (~) to indicate null. ((~) = 0 as minvalue; (~) =255 as maxvalue)
+
| true/false
−
| -
+
|- style="background-color:#ddffdd;"
 +
| '''storageLimitsEnforced'''
 +
| Storage limits for recovered items
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''canSellLiveAliens'''
 +
| Live alien sale
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''anytimePsiTraining'''
 +
| Psionic training at any time
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''psiStrengthEval'''
 +
| Psi-Strength Evaluation
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''canTransferCraftsWhileAirborne'''
 +
| Airborne transfers
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''retainCorpses'''
 +
| Retain interrogated aliens
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''fieldPromotions'''
 +
| Field promotions; this is normally a user option.
 +
| true/false
 
|}
 
|}
  
−
Example:
+
==== Battlescape ====
−
  statStrings:
 
−
  - string: "x"
 
−
    psiStrength: [~, 30]
 
−
  - string: "P"
 
−
    psiStrength: [80, ~]
 
−
  - string: "p"
 
−
    psiStrength: [60, 79]
 
−
  - string: "K"
 
−
    psiSkill: [60, ~]
 
−
  - string: "k"
 
−
    psiSkill: [30, 59]
 
−
  - string: "b"
 
−
    bravery: [60, ~]
 
−
  - string: "c"
 
−
    bravery: [~, 10]
 
−
  - string: "w"
 
−
    strength: [~, 25]
 
−
  - string: "Snpr"
 
−
    firing: [60, ~]
 
−
    reactions: [60, ~]
 
−
  - string: "M"
 
−
    firing: [70, ~]
 
−
  - string: "m"
 
−
    firing: [60, 69]
 
−
  - string: "Sct"
 
−
    reactions: [50, ~]
 
−
    tu: [60, ~]
 
−
  - string: "R"
 
−
    reactions: [60, ~]
 
−
  - string: "r"
 
−
    reactions: [50, 59]
 
−
 
 
−
==Font==
 
−
 
 
−
Defines the [[Font collection (OpenXcom)|font collection]] used by default.
 
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
−
! width="150"| Value
+
! width="200"| Code
−
! width="*"  | Description
+
! width="*"  | Name
−
! width="80" | Default
+
! width="200" | Possible values
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''fontName'''
+
| '''sneakyAI'''
−
| Name of *.dat file, placed in Language folder, which describes used [[Font collection (OpenXcom)|font collection]].
+
| Sneaky AI
−
| Font.dat
+
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''battleUFOExtenderAccuracy'''
 +
| UFO Extender accuracy
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''battleInstantGrenade'''
 +
| Instant grenades
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''includePrimeStateInSavedLayout'''
 +
| Save pre-primed grenades
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''battleExplosionHeight'''
 +
| Explosion height
 +
| 0-3
 +
|- style="background-color:#ddffdd;"
 +
| '''weaponSelfDestruction'''
 +
| Alien weapon self-destruction
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''allowPsionicCapture'''
 +
| Allow psi-capture
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''allowPsiStrengthImprovement'''
 +
| Allow Psi-Strength Improvement
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''strafe'''
 +
| Alternate movement methods
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''noAlienPanicMessages'''
 +
| Suppress panic messages for aliens
 +
| true/false
 +
|- style="background-color:#ddffdd;"
 +
| '''alienBleeding'''
 +
| Alien bleeding
 +
| true/false
 
|}
 
|}
  
−
== Cutscenes ==
+
==== Extended ====
−
 
 
−
Defines a video playlist or a slideshow sequence, listed in ''"cutscenes:"''.
 
  
 
{| class="wikitable" width="100%"
 
{| class="wikitable" width="100%"
−
! width="150"| Value
+
! width="200"| Code
−
! width="*"  | Description
+
! width="*"  | Name
−
! width="80" | Default
+
! width="200" | Possible values
−
|-
+
|- style="background-color:#ddffdd;"
−
| '''type'''
+
| '''oxceStartUpTextMode'''
−
| String ID of the cutscene.
+
| Allows to modify the text that is displayed during the game start up. Possible options:
−
| ''required''
+
* 0 = vanilla (default)
−
|-
+
* 1 = remove dos4gw and soundblaster text
−
| '''useUfoAudioSequence'''
+
* 2 = remove all text
−
| Whether to use the audio sequence for the original UFO intro movie.  This should only ever be set to true for the UFO intro.
+
| 0-2
−
| "false"
+
|- style="background-color:#ddffdd;"
−
|-
+
| '''oxceWoundedDefendBaseIf'''
−
| '''videos'''
+
| Wounded soldiers defend the base too, if their health is above the given percentage threshold.
−
| A list of video filenames to play with the FLC player.
+
| 0-100
−
| ''required if this is cutscene is a video playlist''
 
−
|-
 
−
| '''slideshow'''
 
−
| Info for playing a slideshow (see below).
 
−
| ''required if this is cutscene is a slideshow''
 
 
|}
 
|}
  
−
==== Slideshow Data ====
+
=== Scripts ===
−
 
 
−
{| class="wikitable" width="100%"
 
−
! width="150"| Value
 
−
! width="*"  | Description
 
−
! width="80" | Default
 
−
|-
 
−
| '''transitionSeconds'''
 
−
| The number of seconds to wait before automatically transitioning to the next slide.  The user can always force a transition faster by clicking.
 
−
| 30
 
−
|-
 
−
| '''musicId'''
 
−
| The id of the music to play.
 
−
| -
 
−
|-
 
−
| '''slides'''
 
−
| List of slide data elements (see below).
 
−
| ''required''
 
−
|}
 
  
−
==== Slide Data ====
+
<div style="background:#ddffdd;">
 +
OXCE offers the ability to use a custom '''scripting language''' to modify game logic on certain places via script hooks.
  
−
{| class="wikitable" width="100%"
+
Scripts that change game graphics are run every frame. Others like hitUnit are only run when the event itself happens.
−
! width="150"| Value
 
−
! width="*"  | Description
 
−
! width="80" | Default
 
−
|-
 
−
| '''imagePath'''
 
−
| The path to the image file to display in the background.  The palette for the slide is taken from the image, so caption text color will be determined by the image palette.
 
−
| ''required''
 
−
|-
 
−
| '''caption'''
 
−
| The string ID of the caption text.
 
−
| -
 
−
|-
 
−
| '''captionSize'''
 
−
| The size of the text box, in pixels, in which to display the caption.
 
−
| [320, 200]
 
−
|-
 
−
| '''captionPos'''
 
−
| The screen position at which to display the caption.
 
−
| [0, 0]
 
−
|-
 
−
| '''captionColor'''
 
−
| The palette index to use for the caption color.
 
−
| ''required''
 
−
|}
 
  
−
==References==
+
Currently supported are ('''FIXME''' add short description to each hook):
 +
* '''Unit scripts'''
 +
** recolorUnitSprite: Runs for every pixel of a units graphic. Change to any color.
 +
** selectUnitSprite: Runs for every part of a units graphic. E.g. Change the graphic used for legs.
 +
** selectMoveSoundUnit: Runs for each unit step.
 +
** reactionUnitAction: Runs when an unit performs an action that triggers reaction fire.
 +
** reactionUnitReaction: Runs when a unit sees another unit perform an action that triggers reaction fire.
 +
** hitUnit: When a unit is hit it allows adjusting damage and the part of the body it affects. Runs before damageUnit
 +
** damageUnit: Used to alter the final change to stats of a unit when its hit by a weapon. If unit receives a hit with 0 power this script doesnt run.
 +
** healUnit: Used to alter effect of medikit on unit. Can alter exp from usage of it.
 +
** createUnit: Runs when new unit is created
 +
** newTurnUnit: Runs for every unit every turn (this includes alien, civilian and xcom turns)
 +
** returnFromMissionUnit: Runs for every unit at the end of a mission.
 +
** awardExperience: Runs whenever a unit performs an action that can earn it experience.
 +
** [[VisibilityUnit_(OpenXcom)|visibilityUnit]]: Runs to check if two units of opposing factions can see each other.
 +
* '''Item scripts'''
 +
** recolorItemSprite: Runs for every pixel of sprite. Change color.
 +
** selectItemSprite: Run to change the graphic of an item when its on the floor or in the hands of a soldier
 +
** reactionWeaponAction: Runs for the weapon that triggered reaction shots by firing.
 +
** createItem: Runs when a new item is created.
 +
** newTurnItem: Runs for each item each turn. (this includes alien, civilian and xcom turns)
 +
* '''Stat bonus scripts'''
 +
** For armors: psiDefence, meleeDodge, recovery (time, energy, morale, health, stun, mana)
 +
** For items: damageBonus, meleeBonus, accuracyMultiplier, meleeMultiplier, throwMultiplier, closeQuartersMultiplier
 +
** For units: applySoldierBonuses: Runs once for each bonus of each soldier on mission start.
 +
The syntax of the scripting language and a detailed description of the capabilities of each script hook is beyond the scope of this reference guide. For more information, see [[ModScript (OpenXcom)]].
  
−
<references />
+
If you're interested, please seek help on:
 +
* the OXCE forum: https://openxcom.org/forum/index.php/board,22.0.html
 +
* or the OpenXcom discord: https://discord.gg/kd5UDeT
 +
</div>
  
 
[[Category:OpenXcom]]
 
[[Category:OpenXcom]]

Revision as of 22:00, 16 June 2020

DID YOU KNOW?

OpenXcom (and also OpenXcom Extended) have a ruleset syntax validation and auto-completion tool (a plugin for VSCode), which automatically finds and highlights all your syntax errors.

More info: https://openxcom.org/forum/index.php/topic,6552.0.html

Give it a try!

A reference of the customizable values of everything in a ruleset, according to the latest OpenXcom nightly.

  • Last full review: 19th May 2020, by Meridian
  • Synchronized with: OpenXcom v1.0 (2020-05-04 nightly build) and OpenXcom Extended v6.5.1 (2020-05-21)

IMPORTANT: The OpenXcom Extended (OXCE) ruleset is highlighted using light green background, just like the one used in this disclaimer. Anything marked green does not work with OpenXcom (OXC).

Some guidelines:

  • If a value is omitted from the ruleset, the default is used. You cannot omit required values.
  • Text strings (eg. names) are represented by string IDs from the language files
  • Numerical IDs (used for sprites, sounds, etc.) start at 0, not 1.
  • Boolean (yes/no) values are represented by true/false.
  • World coordinates are represented in degrees (see WORLD.DAT).
  • Money amounts (prices, costs, etc.) are represented in dollars.
  • All file paths are case insensitive, but IDs (such as string IDs, music names, or cutscene names) are case sensitive. In general, though, if it works on one operating system, it will work on all operating systems.
  • Items are ordered as they come in the ruleset. To override this, you can specify a listOrder attribute. You can find the default listOrders in Ruleset List Order.
  • OXCE allows inheritance for almost all types of rulesets, via the refNode attribute. You can use this to create copies of weapons, armors, facilities, etc. that inherit everything from another existing object and just modify a few attributes to save space, prevent copy/paste mistakes and have automatic update/synch when the original item changes. Below is an example for creating a new Laser Sniper Rifle item from an existing Laser Rifle item:
 items:
   - &STR_LASER_RIFLE           # Let's mark laser rifle info with an anchor
     type: STR_LASER_RIFLE
     size: 0.2
     costSell: 36900
     weight: 8
 #
 # a million other attributes...
 #
   - type: STR_LASER_SNIPER_RIFLE
     refNode: *STR_LASER_RIFLE  # First, let's inherit everything from the STR_LASER_RIFLE anchor.
     bigSprite: xxx             # And now let's give it a new sprite,
     accuracyAimed: 160         # increase aimed shot accuracy
     tuAuto: 0                  # and disable auto shot.


Starting Base

Defines the content of the base at the start of game.

In OXCE, you can optionally define different starting bases for each game difficulty using the following top-level names:
  • startingBaseBeginner
  • startingBaseExperienced
  • startingBaseVeteran
  • startingBaseGenius
  • startingBaseSuperhuman

If you don't define some of them, the default starting base will be used instead of the missing ones.

The default starting base will also be used for New Battle screen.

Value Description Default
randomSoldiers Determines number and type of starting X-Com soldiers.

If a mod contains more than one type of soldiers, this can also be specified with: 

 randomSoldiers:
   STR_SOLDIER: 3
   STR_ANOTHER_SOLDIER: 7
0
scientists Determines number of starting scientists. 0
engineers Determines number of starting engineers. 0
facilities List of starting base facilities and their position (x and y coordinates being 0-5). -
items List of starting items in the base, excluding items on crafts. -
crafts List of starting crafts in the base and items on board. -

OpenXcom uses the same format to define a starting base as for saving/loading a real base (except for randomSoldiers attribute). That means you can also define various other parameters in your mod, for example:

  • predefined soldiers (if you don't like to start with randomly generated ones, but like it a bit more RPG)
  • transfers that arrive at specified times (you could control various game events/progression with these items)
  • base detected by aliens flag (which would allow you for example to start the campaign with an early scripted base defense mission)
  • and so on...

The easiest way to create this ruleset, is to copy it from an existing saved game, correct the indentation and manually change the actual content. The following table completes the list of highest-level attributes you can use.

Value Description Default
soldiers List of starting base soldiers, their names, stats and everything else. -
transfers List of items, soldiers, engineers and/or scientists inbound to the starting base with a specified time lag. -
research List of ongoing research projects in the starting base. -
productions List of ongoing manufacturing projects in the starting base. -
retaliationTarget Flag saying whether the aliens know about your starting base or not. false

Globe

Defines the drawing of landmasses and borders on the globe. Also defines mapping between geoscape textures and battlescape appearance.

Value Description Default
data Path to a file, which contains polygon and texture information. (For example WORLD.DAT). -
polygons List of polygons drawn on the globe surface. A triangle consist of seven values: the first number defines the texture, followed by three pairs of (x,y) globe coordinates. Only polygons with 3 or 4 vertices are reliably shown on the globe, i.e. 7 or 9 values per entry.

Note that:

  • data and polygons define the same thing... use one or another, not both
  • each time you define data or polygons, their previous definition is completely deleted (i.e. globe can be defined only as a whole, not incrementally)
 -
polylines List of border lines. Each list entry consist of a list of (x,y) globe coordinates.

Note that:

  • each time you define polylines, their previous definition is completely deleted (i.e. they can be defined only as a whole, not incrementally)
 -
textures List of globe textures that determine the battlescape appearance of a certain place on the globe. -
countryColor Color of the country labels (0-255). 239
cityColor Color of the city labels (0-255). 138
baseColor Color of the xcom base labels (0-255). 133
lineColor Border line color (0-255). 162
oceanPalette Color range (defined as palette offset) of the "oceans", or better said of the "globe sections not covered by polygons" (0-15). 12
oceanShading Whether ocean shading (32-color) should be used or not.

Notes:

  • normally land uses 16-color shading and ocean uses 32-color shading... where "ocean" is defined as "lack of texture", i.e. for UFO lack of land and for TFTD lack of water
  • for hybrids (i.e. mods that combine UFO and TFTD textures together), there is no "ocean" anymore, because the globe is fully covered by textures (land and water textures)
  • thus the original 32 colors used for ocean shading can be:
    • re-used to provide more colors for the textures (2 distinct color ranges, 16 colors each)
    • ignored for ocean shading purposes, and used for texture shading purposes instead
 true

(Globe) Textures

Value Description Default
id ID of the texture.
  • Terrain-based textures have positive IDs (0, 1, 2, ...) and are used for drawing globe polygons
  • AlienDeployment-based textures have negative IDs (-1, -2, -3, ...) and are not used for drawing globe polygons
 required
terrain List of terrains (can be more than one) that correspond to each Geoscape texture.

Terrains can be restricted to certain areas on the globe with area: ([lon1, lon2, lat1, lat2]) and weight: NUMBER that gives their chance of appearance.

These textures are primarily used for UFO landing/crash sites.

Example 1: 

globe:
  textures:
    - id: 0
      terrain:
        - name: FOREST
          area: [0, 360, -90, 0]
        - name: JUNGLE
          area: [0, 360, 0, 90]

Example 2: 

globe:
  textures:
    - id: 11
      terrain:
        - name: PIPES
          weight: 50
        - name: SEABED
          weight: 25
        - name: CORAL
          weight: 25
-
deployments Defined by weighted alien deployments (can be more than one), which determine appearance for mission sites (e.g. terror sites, artifact sites, shipping lanes, etc.).

Example: 

globe:
  textures:
    - id: -4
      deployments:
        STR_CARGO_SHIP_P1: 50
        STR_CRUISE_SHIP_P1: 50
-
baseTerrain In OXCE, the terrain-based textures can additionally have separate terrain defined for base defense missions.

This terrain can be used in map scripting to replace the generic "dirt" blocks with something more fitting (e.g. snow in the arctic or jungle near the equator).

More info: https://openxcom.org/forum/index.php/topic,5108.0.html

-
startingCondition In OXCE, the textures can have their own starting conditions (with lower priority than deployment starting conditions). -
fakeUnderwater In OXCE, the (land) textures can also be flagged as fake underwater textures using this boolean attribute.

Such terrain can support underwater missions, underwater bases/facilities and have separate starting conditions.

More info: https://openxcom.org/forum/index.php/topic,7374.msg116684.html#msg116684

false

Countries

Defines one of the funding nations, listed in "countries:". They're used for activity graphs and player scoring.

In OXCE, the same kind of ruleset can be used to define "extra globe labels" so that you can label continents, or anything else on non-Earth globes (e.g. Moon, Mars, Dune, etc.). Of course, nothing is stopping you from using this on the Earth globe too. Listed under its own top-level category "extraGlobeLabels:".
Value Description Default
type String ID of the country name. required
fundingBase Country's base funding, in thousands. The starting funding can be anywhere between 1x and 2x the base funding. 0
fundingCap Country's funding cap, in thousands. Once a country reaches this maximum, it will no longer increase its funding. 0
labelLon

labelLat

Longitude and latitude coordinates of the country's label on the globe. This label is only shown when the globe is zoomed in and "detail" is turned on. 0.0

0.0

labelColor Color (0-255) of the country label. 0 (not used)
areas List of "rectangles" on the globe defined as [lon1 lon2 lat1 lat2]. Any activity within these areas counts towards the country's graph activity and affects their opinion of the player. -
zoomLevel Minimum globe zoom level at which this extra globe label becomes visible.

Note: doesn't work for countries. Only for extra globe labels.

0

Regions

Defines one of the world regions, listed in "regions:". They're used for base placement, activity graphs and mission spawning.

Value Description Default
type String ID of the region name. required
cost Amount of money spent building an X-COM base in this region (first base is free). 0
areas List of "rectangles" on the globe defined as [lon1, lon2, lat1, lat2]. Any activity within these areas counts towards the region's graph activity.

Example: 

 regions:
   - type: STR_EUROPE
     areas:
       - [335, 60, -70, -35]
-
regionWeight Weight of this region when selecting regions for alien missions. 0
missionWeights Weighted list of the different mission types for this region (eg. STR_ALIEN_RESEARCH: 14). -
missionZones List of mission zones. Mission zones are used for generating waypoints for UFO trajectories, and also for spawning mission sites and alien bases. Each mission zone itself is a list of "mission areas", where each mission area is defined by:
  • a "rectangle" ([lon1, lon2, lat1, lat2]) defining a relevant section of the globe (does not need to be within the region itself); or a single point (a city) on the globe

Zones used for mission site spawning additionally have:

  • a texture ID (from globe ruleset, this should be the alienDeployment-based texture, usually the ID is a negative number)
  • and optionally a city string ID (will be displayed on the globe if defined)

Example: ([lon1, lon2, lat1, lat2, textureID, STR_CITY_NAME]).

Important: Crossing the prime meridian in missionZones requires a different syntax! (lon2 cannot be smaller than lon1)

Wrong example: 

 [350,   8, 20, 30]

Correct example: 

 [350, 368, 20, 30]  # 368 (=8+360) also represents 8 degrees, and satisfies the lon2 >= lon1 condition

PS: This syntax exception does not apply to areas.

-
missionRegion Spawn mission in this region instead (used for regions without land). -

Base Facilities

Defines one of the facilities that can be built in an X-COM base, listed in "facilities:".

Value Description Default
type String ID of the facility name. required
fakeUnderwater Defines whether the facility can be built in a standard base, fake underwater base (used by hybrid mods), or both.

Possible options:

  • -1 = both (default)
  • 0 = only standard base
  • 1 = only fake underwater base
 -1
requires List of topics (string IDs) that must be researched to unlock this facility. If none are specified, this facility is unlocked from the start. -
requiresBaseFunc A list of services required to build this facility. -
provideBaseFunc A list of services this facility provides after being built. -
forbiddenBaseFunc A list of services that cannot be used anymore after this facility is built. -
spriteShape Sprite ID from BASEBITS.PCK used to draw the facility's outer shape in the Basescape and UFOpaedia. -1
spriteFacility Sprite ID from BASEBITS.PCK used to draw the facility's contents in the Basescape and UFOpaedia. Drawn on top of spriteShape. Not required for buildings size 2 or larger. -1
missileAttraction A weight (i.e. not a percentage) of how likely will alien missiles/bombardments hit this type of facility. 100
destroyedFacility String ID of the destroyed version of this facility (must have the same size).

Note: destruction can happen either in Base Defense mission or via Alien missiles/bombardment.

-
lift Is this facility an Access Lift? All base facilities must be connected to the lift. false
hyper Is this facility a Hyperwave Decoder? Displays extra information for detected UFOs. Only valid for radar facilities. If "true", the radar detection chance will be taken from radarChance value. false
mind Is this facility a Mind Shield? Reduces the chance of UFOs finding your base. Does stack (detection chance is inversely proportional to the number of mind shields). false
mindPower The power of the mind shield provided by this facility. 1
grav Is this facility a Grav Shield? Doubles the power of your base defenses. Does not stack. false
size Size of the facility, in grid units. Every facility is square, so a size of 1 means 1x1, 2 means 2x2, etc. Bigger facilities are made up of multiple sprites, for example a 2x2 facility will use 4 sprites for spriteShape and 4 sprites for spriteFacility (top-left, top-right, bottom-left, bottom-right). 1
buildCost Amount of money spent to build this facility in the base. 0
refundValue Amount of money refunded when the facility is dismantled. 0
buildCostItems Items needed to build a facility and items "refunded" when the facility is dismantled. 
 - type: STR_MY_FACILITY
   buildCostItems:
     STR_ALIEN_ALLOYS:
       build: 100
       refund: 75
     STR_ALIEN_ENTERTAINMENT:
       build: 1
       refund: 1
-
buildTime Amount of days it takes for this facility to be built. 0
monthlyCost Amount of money spent monthly for the maintenance of this facility. 0
storage Amount of storage space (for items) this facility provides. See Base Stores. 0
storageTiles A list of tile positions where to place items in this facility's storage. If empty, vanilla checkerboard pattern will be used. -
personnel Amount of personnel (soldiers, scientsts, engineers) these quarters can contain. 0
aliens Amount of live aliens this facility can contain. Only checked if the storageLimitsEnforced option is enabled. 0
prisonType What type of prisoners (aliens) can be held in this facility.

More info: https://openxcom.org/forum/index.php/topic,4830.msg69933.html#msg69933

0
crafts Amount of X-COM craft this facility can contain. 0
labs Amount of lab space this facility provides for research projects. 0
workshops Amount of workshop space this facility provides for manufacture projects. 0
psiLabs Amount of soldier space this facility provides for psionic training. 0
trainingRooms Amount of soldier space this facility provides for combat/martial training. 0
radarRange Maximum radar detection range of this facility, in nautical miles. 0
radarChance Chance (0-100%) of this radar detecting a UFO that enters its range. 0
sightRange Range at which the facility can detect alien bases in nautical miles. 0
sightChance Chance (0-100%) of this facility detecting an alien base that enters its sight range. More info: https://openxcom.org/forum/index.php/topic,8119.0.html 0
defense Offensive power provided by this base defense against attacking UFOs. 0
hitRatio Chance (0-100) of the base defense hitting an attacking UFO. 0
fireSound Sound ID from GEO.CAT played when the base defense fires. 0
hitSound Sound ID from GEO.CAT played when the base defense hits a target. 0
mapName Map associated to this facility in Battlescape base defenses. -
verticalLevels Can be used instead of mapName. Allows generating a base facility map as if it were an addBlock map script command.

More info: https://openxcom.org/forum/index.php/topic,5316.0.html

-
maxAllowedPerBase Maximum number of facilities of this type allowed to be built per base. 0 (not used)
manaRecoveryPerDay How much mana does the facility recover per day. The facility setting is NOT cumulative, more facilities don't provide more regen. If there are multiple facilities of different type with different regen rate, the best (highest) regen rate is used. 0
healthRecoveryPerDay How much health/HP does the facility recover per day. The facility setting is NOT cumulative, more facilities don't provide more regen. If there are multiple facilities of different type with different regen rate, the best (highest) regen rate is used.

FIXME: add a link to more detailed description of this feature!

0
sickBayAbsoluteBonus
sickBayRelativeBonus 		How much additional HP is healed per day. 
 - type: STR_FIELD_HOSPITAL
   sickBayAbsoluteBonus: 0.75
   sickBayRelativeBonus: 0.0
 - type: STR_SURGERY_ROOM
   sickBayAbsoluteBonus: 0.25
   sickBayRelativeBonus: 1.0
 - type: STR_REGENERATION_ROOM
   sickBayAbsoluteBonus: 0.0
   sickBayRelativeBonus: 10.0
 - type: STR_GOAULD_SARCOPHAGUS
   sickBayAbsoluteBonus: 90.0
   sickBayRelativeBonus: 0.0

Examples, considering the ruleset above:

  • with no facilities: 1 hp healed per day
  • with one field hospital: 1.75 hp per day
  • with one surgery room: 1.25 hp per day + 1% of soldier's max hp
  • with 2 field hospitals and 2 surgery rooms: 3 hp per day + 2% of soldier's max hp
  • with regeneration room: 10% of soldier's max hp... i.e. fully recovered in 10 days or less
  • with Goa'uld sarcophagus: 90 hp per day... i.e. fully healed overnight
 0.0
0.0
leavesBehindOnSell A facility to leave behind a dismantled facility (must be of the same size); or a list of 1x1 facilities to fill in the old facility's place. -
removalTime How long facilities left behind when this one is sold should take to build.

Possible options:

  • -1 = take buildTime from the other facilities' rulesets
  • 0 = instant
  • 1+ = that many days

Note: doesn't do anything without leavesBehindOnSell

0
canBeBuiltOver Can this facility be built over? false
buildOverFacilities A list of other base facilities this one can be built over. If empty, it can be built over anything with canBeBuiltOver: true. -
rightClickActionType Which screen should open when R-clicking on this facility in the base view?

Possible options:

  • 0 = OpenXcom default
  • 1 = Prison (Alien Containment)
  • 2 = Manufacturing
  • 3 = Research
  • 4 = Martial Training
  • 5 = Psi Training
  • 6 = Barracks
  • 7 = Market (Sell)
  • other = go to Geoscape
 0

Crafts

Defines one of the X-COM crafts that go on interception missions, listed in "crafts:".

Value Description Default
type String ID of the craft name. required
requires List of topics (string IDs) that must be researched to unlock this craft. If none are specified, this craft is unlocked from the start. -
requiresBuyBaseFunc A list of services required to buy this craft. -
sprite Sprite ID from BASEBITS.PCK used to draw this craft in the Basescape and from INTICON.PCK used to draw the damage indicator in dogfights.

Note that:

  • the corresponding id for INTICON.PCK for the minimized craft icon is sprite+0
  • the corresponding id for INTICON.PCK for the dogfight image is sprite+11
  • the corresponding id for BASEBITS.PCK is sprite+33
 -1
marker Sprite ID from GlobeMarkers spritesheet, used for drawing craft icon on the globe. Usually 3x3 pixels, but can be modded to be bigger.

Note: if not modded, sprite id 1 is used (=vanilla craft marker)

-1
weapons Amount of craft weapons this craft can equip. The UI can only display a max of 2 weapons.

In OXCE, you can have up to 4 weapons (or other accessories)

0
weaponTypes A list defining compatible weapon types for this craft type. Up to 4 slots, and each slot can have up to 4 compatible weapon types.

Example: [0, [0, 1], [2,3], [0,2,4]]

[0, 0, 0, 0]
weaponStrings A list describing the craft's weapon slots (up to 4 slots). [STR_WEAPON_ONE, STR_WEAPON_TWO]
soldiers Amount of soldiers this craft can carry. 0
pilots How many pilots are required to pilot this craft.

Notes:

  • pilots are also soldiers and will be fighting in the Battlescape
  • pilots give bonuses/penalties to the craft performance in the Dogfights (based on their skills)
  • pilots gain experience via Dogfights
  • you can manually assign pilots to the craft; if you don't want to, they can be assigned automatically
 0
allowLanding Should this craft be able to start a Battlescape mission?

Note: you may want to set false to your manned/piloted interceptors.

true
vehicles Amount of vehicles this craft can carry. 0
costBuy Amount of money spent for purchasing this craft. If set to 0, the craft will not be available in the Purchase/Recruit screen. 0
costRent Amount of money spent monthly for renting this craft. If set to 0, the craft is not on rental and won't count towards base maintenance. 0
costSell Amount of money gained for selling this craft. 0
forceShowInMonthlyCosts Forces this craft type to appear in Monthly Costs breakdown, even if not present at the base.

Note: Skyranger, Interceptor, Triton and Barracuda have this turned on (for backwards-compatibility).

false
refuelItem Item required for refueling this craft. If no item is specified, the craft uses human fuel. 0
repairRate Amount of damage restored every hour while Repairing in base. 1
refuelRate Amount of fuel restored every 30 mins while Refueling in base. If specified, a refuelItem is spent each time. 1
transferTime Number of hours it takes to purchase/transfer this craft to a base. 0
score Score lost when this craft is destroyed. 0
battlescapeTerrainData Terrain associated to this craft in Battlescape missions. -
craftInventoryTile Coordinates [x, y, z] of the craft inventory tile (weapon's pile) in the craft. If not specified, tile occupied by the first soldier is used. -
mapVisible Should the craft map be visible at the beginning of the battle? Used for some funky effects (see W40k mod for examples). true
deployment Custom positions for the unit deployment in the craft, listed as: [x, y, z, facing]

If not specified, units are placed on empty spots from top-left to bottom-right facing top-right.

-
keepCraftAfterFailedMission Defines whether the craft should be lost after a failed mission or not. Useful for example to implement paratroopers; or any kind of troop deployment without a craft physically being on the map. false
spacecraft Can this craft go to Cydonia? false
notifyWhenRefueled Should a pop up window inform the player once this craft is fully refueled? false
autoPatrol Should this craft automatically return to its patrol destination after refueling? false
maxAltitude Maximum altitude (0-4) this craft can dogfight to. -1
maxItems Amount of items this craft can carry. 0
shieldRechargedAtBase How many shield points are recharged when landed at base per hour. 1000

Craft Stats

The following attributes define so called "craft stats". They are listed in a separate table, just for convenience... but are still part of the Craft ruleset.

Note: In OXCE, all these stats are dynamic, i.e. can be modified by equipping craft weapons/accessories.

Value Description Default
fuelMax Maximum amount of fuel this craft can carry. Crafts use up fuel based on their speed while traveling. 0
damageMax Maximum amount of damage this craft can take. If this amount is exceeded, the craft is destroyed. 0
speedMax Maximum speed in nautical miles. Crafts travel at max speed when flying and half speed when patrolling. 0
accel Acceleration value shown in the UFOpaedia. 0
radarRange Detection range of the craft's radar in nautical miles. Every craft radar has a detection chance dependent on its radarChance. 672
radarChance Chance (0-100%) of this craft radar detecting a UFO that enters its range. 100
sightRange Range at which the craft can detect alien bases in nautical miles. 1696
hitBonus Flat bonus percentage to hit chances of all equipped weapons. 0
avoidBonus Flat bonus percentage to dodge chances against enemy fire. 0
powerBonus Multiplier for the power of craft weapons, e.g. 20 = weapons' power increased to 120% of their original power, -20 = decreased to 80%. 0
armor Amount of blocked damage per hit. 0
shieldCapacity Craft's maximum shield capacity. 0
shieldRecharge Defines the percent chance of recharging a point of shielding per game second (GS) during a Dogfight. Values under 100 are the percent chance, for over 100, every +100 means an automatic +1 to shields per GS. Thus shieldRecharge: 250 means +2 shields/GS, with a 50% chance of +1 more. 0
shieldRechargeInGeoscape Similar to shieldRecharge, but acts every 5 seconds in the Geoscape. Giving it a value of -1 means instant recharge as soon as 5 seconds pass! 0
shieldBleedThrough Defines the percent of damage that passes the shield when it goes down. A value of 0 means that with even just 1 shield point, any single hit will be blocked, while 100 means 100% of the damage left after the shield blocks it will go on to damage the craft. 0

Craft Weapons

Defines one of the weapons equipped by X-COM craft for shooting down UFOs, listed in "craftWeapons:".

Value Description Default
type String ID of the weapon name. required
weaponType A weapon's type/category. Used to limit certain weapons/accessories to certain craft weapon slots. 0
sprite Sprite ID from BASEBITS.PCK used to draw the weapon in the Basescape and from INTICON.PCK used to draw the weapon in dogfights.

Note that:

  • the corresponding id for INTICON.PCK is sprite+5
  • the corresponding id for BASEBITS.PCK is sprite+48
 -1
sound Sound ID from GEO.CAT played when this weapon fires. -1
stats Contains the same set of attributes as Craft Stats. These dynamically increase/decrease the stats of a craft, when equipped.

Examples:

  • you can increase the craft's range by equipping an extra fuel tank
  • you can increase the craft's hit chance by equipping advanced targeters
  • you can increase the craft's radar range/chance by equipping an extra radar
  • and so on...
 -
hidePediaInfo Allows hiding the weapon's stats in the Ufopedia.

Note: this can be used for example when the craft weapon is not really a weapon, but only an equipment/booster (e.g. radar booster, extra fuel tank, etc.).

false
damage Amount of damage this weapon does to enemy UFOs. 0
shieldDamageModifier Defines the percent of power that a weapon does to shields. 100
range Maximum range of this weapon in dogfights (in kilometers). 0
accuracy Chance (0-100%) of each shot hitting the enemy UFO. 0
reloadCautious Time this weapon takes to fire between each shot in Cautious Mode. 0
reloadStandard Time this weapon takes to fire between each shot in Standard Mode. 0
reloadAggressive Time this weapon takes to fire between each shot in Aggressive Mode. 0
ammoMax Maximum amount of ammo this weapon can carry. 0
rearmRate Amount of ammo restored every hour while the craft is Rearming in base. If specified, clips are spent depending on their clipSize, and reamRate should be a multiple of clipSize. If the clipSize of the specified ammo is 0, no clips are spent. 1
projectileType Type of the weapon projectile, used for the projectile sprite in dogfights: 2
projectileSpeed Speed of the weapon projectile in dogfights. 0
launcher String ID of the item required to equip this weapon. -
clip String ID of the item required to rearm this weapon. -
underwaterOnly Is this craft weapon restricted to underwater use only? false
tractorBeamPower How much the weapon slows down the maximum speed of a UFO when it's in range and the weapon is active.

Note: Tractor beams allow you to effectively decrease the maximum speed of a UFO during interception, preventing their escape. If you have powerful enough beams targeting the UFO, you can even cause it to land or splash down in the water!

0

Items

Defines the Geoscape and Battlescape properties of an item that can be stored in X-COM bases, listed in "items:".

Naming, Categorization and Storage

Value Description Default
type String ID of the internal item name. required
name String ID of the displayed item name, for cases where it's different from the internal name. If omitted, type is used. Only affects inventory screens and battlescape internals. Does not change the name of items in geoscape lists. =type
nameAsAmmo Extension for the name of weapons loaded with this item as ammo. -
battleType Defines the weapon's behavior in the Battlescape: 0
requires List of topics (string IDs) that must be researched to unlock this item. If none are specified, this item is unlocked from the start. Soldiers can only use unlocked items in the Battlescape. -
requiresBuy A list of research topics required to be able to buy this item.

Note: you can use the item even if the requirements are not met... you just can't buy it.

-
requiresBuyBaseFunc A list of services (for a given base) required to be able to buy this item. -
size Space occupied by this item in Base Stores. Can be a decimal value. 0.0
costBuy Amount of money spent for purchasing this item. If set to 0, this item will not be available in the Purchase/Recruit screen. 0
costSell Amount of money gained for selling this item. 0
transferTime Number of hours it takes to purchase/transfer this item to a base. 24
categories A list of categories this item belongs to. -
monthlyMaintenance Monthly maintenance cost of items in Stores. For example your tanks could have a small monthly maintenance cost. 0
monthlySalary Monthly salary of "other employees" (represented as items in Stores). This is practically identical to monthlyMaintenance, it just shows on a different place in the [Monthly costs] screen.

Note: the "other employees" can't do much (yet), but you could use them for example to increase your Stores capacity (by giving them negative size)... representing increased storage effectiveness by hiring specialized logistics personnel (or outsourcing storage completely).

0

Sprites and Particles

Value Description Default
customItemPreviewIndex Allows to have different icons for different types of Vehicles (HWP/SWS) on the [Craft Info] screen. Defined either as a single index into the CustomItemPreviews spritesheet, or as a list of indices (for bigger icons). -
bigSprite Sprite ID from BIGOBS.PCK used to draw this item in a soldier's inventory and UFOpaedia. -1
specialIconSprite Sprite ID from SPICONS.DAT used to draw this item when used as specialWeapon (in Armor definition). -1
floorSprite Sprite ID from FLOOROB.PCK used to draw this item on the floor of a Battlescape tile. -1
handSprite Sprite ID from HANDOB.PCK used to draw this item on a soldier's hand in the Battlescape.

modders: each handobject needs 8 images (8 directions) define the extrasprites accordingly

120
bulletSprite Sprite ID from BulletSprites.png used to draw this weapon's projectile on the Battlescape:

for modders: the bulletsprite needs to be put into the extraSprites type "Projectiles" the bulletsprite can contain up to 35 3x3 images. The corresponding file id is 35*[bulletSprite]

-1
bulletSpeed How much faster (or slower, if you use a negative number) is a projectile fired from this weapon compared to the average. 0
explosionSpeed How much faster (or slower, if you use a negative number) is an explosion animated compared to the average. 0
turretType Sprite ID from TANKS.PCK of the turret to assign to this tank: -1
vaporColor The color offset (0-3 in TFTD) to use for the vapor trail. -1
vaporDensity The vapor cloud density (number of particles) for the vapor trail. 0
vaporProbability The vapor cloud probability (0-100%) for the vapor trail. 15
vaporColorSurface The color offset (0-3 in TFTD) to use for the vapor trail (for surface deployments, i.e. non-underwater). -1
vaporDensitySurface The vapor cloud density (number of particles) for the vapor trail (for surface deployments, i.e. non-underwater). 0
vaporProbabilitySurface The vapor cloud probability (0-100%) for the vapor trail (for surface deployments, i.e. non-underwater). 15

Sounds and Animations

Value Description Default
explosionHitSound Sound ID from BATTLE.CAT played when explosion happens. Can be a list with multiple options. If not specified, default explosion sound is used. -
reloadSound Sound ID from BATTLE.CAT played when this weapon is reloaded. Can be a list with multiple options. If not specified, default reload sound is used. -
fireSound Sound ID from BATTLE.CAT played when this weapon fires. In OXCE, can be a list with multiple options. -1
hitSound Sound ID from BATTLE.CAT played when this weapon hits a target. In OXCE, can be a list with multiple options. -1
psiSound Sound ID from BATTLE.CAT played when this weapon performs a psi attack (only Panic/MindControl). Can be a list with multiple options. -
hitMissSound Sound ID from BATTLE.CAT played when this weapon misses a psi attack (Use/Panic/MindControl). Can be a list with multiple options. -
psiMissSound Sound ID from BATTLE.CAT played when this weapon misses a psi attack (only Panic/MindControl). Can be a list with multiple options. -
meleeSound Sound ID from BATTLE.CAT played when this weapon attacks a target with melee. In OXCE, can be a list with multiple options. 39
meleeHitSound Sound ID from BATTLE.CAT played when this weapon hits a target with melee. In OXCE, can be a list with multiple options. -1
meleeMissSound Sound ID from BATTLE.CAT played when this weapon misses a target with melee. Can be a list with multiple options. -
hitAnimation Sprite ID from SMOKE.PCK used to draw the weapon's "hit explosion". In OXCE, it applies also to Use action of psi weapons.

NOTE: Do not define this value for melee/psi weapons, they use HIT.PCK and therefore meleeAnimation instead.

NOTE: Explosive style weapons (Damage type: smoke, incendiary, stun, & High Explosive) use X1.PCK and should always be set to the first above water sprite (spriteID for UFO, spriteID + 8 for TFTD). TFTD spritesheet should start with 8 underwater images, followed by 8 above water images.

-1
hitMissAnimation Sprite ID from SMOKE.PCK used to draw the weapon's "miss explosion". Applies only to Use action of psi weapons. -1
meleeAnimation Sprite ID from HIT.PCK played when this weapon hits a target with melee. 0
meleeMissAnimation Sprite ID from HIT.PCK played when this weapon misses a target with melee. -1
psiAnimation Sprite ID from HIT.PCK played when this weapon hits a target with psi attack (only Panic/MindControl). For Use action on psi weapons, define hitAnimation. -1
psiMissAnimation Sprite ID from HIT.PCK played when this weapon misses a target with psi attack (only Panic/MindControl). For Use action on psi weapons, define hitMissAnimation. -1
It can be pretty confusing, which sound/animation is played when... so here's an attempt to illustrate what happens. For each combination of "event" and "type of attack", there are multiple variables... the first variable that is not empty is used.
Bullets (non-explosive) Melee weapon (or gun-butt) Psi weapon (panic/MC) Psi weapon (Use)
Hit sound hitSound meleeSound+meleeHitSound psiSound > hitSound hitSound
Miss sound - meleeMissSound > meleeSound psiMissSound > hitMissSound > psiSound > hitSound hitMissSound > hitSound
Hit animation hitAnimation meleeAnimation psiAnimation > meleeAnimation hitAnimation
Miss animation - meleeMissAnimation > meleeAnimation psiMissAnimation > meleeMissAnimation > psiAnimation > meleeAnimation hitMissAnimation > hitAnimation

Power and Damage types

Value Description Default
power Weapon power. Usually corresponds to weapon's average damage. For some weapons/items, it determines the range (e.g. for incendiary or smoke). 0
hidePower Allows hiding the weapon's power (and the entire ammo section) in the Ufopedia.

Note: this can be used for example when the weapon is mostly scripted and the damage info is more confusing than helpful.

false
damageType What type of damage does this weapon do:
  • 0 - None
  • 1 - Armor Piercing
  • 2 - Incendiary
  • 3 - High Explosive
  • 4 - Laser
  • 5 - Plasma
  • 6 - Stun
  • 7 - Melee
  • 8 - Acid
  • 9 - Smoke

Notes:

  • A damage type other than 0-9 will do nothing in OpenXcom.
  • In OXCE, there are 10 more damage types (10-19), which have same default settings as AP/Laser/Plasma/Acid damage types in OpenXcom.
 0
blastRadius Size of the projectile explosions. 0 for no explosion. -1 to automatically calculate based on weapon power and damage type (actual blastRadius currently is capped due Explosion calculations).

Note: blastRadius is deprecated in OXCE. Use damageAlter.FixRadius instead. If both are specified, FixRadius is taken.

-1
damageAlter OpenXcom has 10 damage types and the mechanics of all 10 of them are completely hardcoded. In OXCE, you can use one of these hardcoded damage types as a starting point, but still be able to override all damage aspects for every item. To do this, you always use a pair of attributes for default and override:
  • for normal/primary damage: default is in damageType and overrides in damageAlter
  • for secondary melee damage: default is in meleeType and overrides in meleeAlter

Damage override has many attributes, which are all described in Item Damage Types.

Small example: 

 - type: STR_HWP_DISC_PLASMA_CANNON
   damageType: 5
   damageAlter:
     RandomType: 6
     IgnoreOverKill: false
     ToArmorPre: 0.05
     ToStun: 0.75
     RandomWound: false
     ToWound: 0.12
     FireThreshold: 25.0
-
meleePower Damage this weapon will do when using melee. This only applies to Firearms, and is only available as stun damage. For normal melee weapons, use regular power and damage types. 0
meleeType Default damage type for secondary melee attack. Automatically set to damage type 7 (melee) for items with battleType = 3 (melee weapon). -
meleeAlter Damage type details for meleeType.

Damage override has many attributes, which are all described in Item Damage Types.

-
strengthApplied Add the attacking unit's strength to this weapon's damage.

Note: strengthApplied is deprecated in OXCE. Use damageBonus instead, which is also more configurable. If both are specified, damageBonus is taken.

false
damageBonus Formulae for additional weapon power bonus (not damage bonus!). Defined as a sum of polynomials of up to third degree with various unit stats as parameters :) If you didn't understand the previous sentence, don't be sad, just look at an example. FIXME: add more description and examples later.

Example: 

 - type: STR_EXAMPLE_1
   damageBonus:
     bravery: 2.5
     flatHundred: -1.25
 - type: STR_EXAMPLE_2
   damageBonus:
     firing: [0.0, 0.01]

In the first example the power bonus is "250% of soldier's bravery minus 125".

In the second example the power bonus is "0% of firing accuracy plus 1% of firing accuracy squared".

-
meleeBonus Same as damageBonus, but applies to secondary melee attacks. -

Accuracy

Value Description Default
noLOSAccuracyPenalty The penalty (in percent) to accuracy applied when attacking a unit or a tile outside of LOS. Overrides global setting. -1
accuracyAimed
accuracySnap
accuracyAuto
accuracyMelee 		The base accuracy (in percent) applied to a soldier's Firing Accuracy when firing an Aimed/Snap/Auto shot or doing a Melee attack.

Note: in OXCE, it doesn't need to be applied only to firing accuracy, a combination of many other attributes can be used instead, see accuracyMultiplier and meleeMultiplier.

0
0
0
0
accuracyPanic
accuracyMindControl
accuracyUse 		The accuracy bonus (in flat percent) applied during psi attacks (Panic/MindControl/Use). accuracyMultiplier is also used in the calculations. 20
0
0
accuracyThrow The base accuracy (in percent) applied when throwing items. See also throwMultiplier. 100
accuracyCloseQuarters The base accuracy (in percent) applied when checking CQC (close quarters combat) score. Overrides global setting. See also closeQuartersMultiplier. -1
blockBothHands Does this weapon block both hands? If true, you cannot use this weapon while holding anything in the offhand. false
twoHanded Is this weapon two-handed? If true, incurs an accuracy penalty if used with both hands occupied. Note that the handsprite of a twoHanded item is also drawn at a slightly different position than a one handed item. false
oneHandedPenalty Override for the global one-handed penalty (which applies only to weapons marked as twoHanded). 20% penalty would be encoded as "80" (i.e. 100 minus 20), meaning you will use the weapon at 80% of its usual accuracy. -1
kneelBonus Override for the global kneel bonus (which applies to all weapons). 15% bonus would be encoded as "115" (i.e. 100 + 15), meaning you will use the weapon at 115% of its usual accuracy. -1
skillApplied Is melee accuracy skill applied to the accuracy of an attack made with this item? Only affects melee attacks.

Note: skillApplied is deprecated in OXCE. Use meleeMultiplier instead, which is also more configurable. If both are specified, meleeMultiplier is taken.

true
accuracyMultiplier Formulae defining the skills (i.e. various units stats) affecting the unit's accuracy when using this item in Aimed/Snap/Auto shots and in Psi attacks (Panic/MindControl/Use).

Example: 

 - type: STR_EXAMPLE
   accuracyMultiplier:
     firing: 0.0
     throwing: 0.5
     melee: 0.5

In this example, the accuracy is based on 50% of unit's throwing skill and 50% of unit's melee skill... and 0% of unit's firing skill.

-
meleeMultiplier Same as accuracyMultiplier, but used for Melee attacks (primary and secondary). -
throwMultiplier Same as accuracyMultiplier, but used for Throwing. -
closeQuartersMultiplier Same as accuracyMultiplier, but used for CQC scoring. -

Waypoints, Shotguns, Range Limits and Accuracy/Power Dropoff

Value Description Default
waypoints Gives the integer number of waypoints the weapon can use. (eg. Blaster Launcher). Can also be used to make ammo items use the waypoint system. "-1" means unlimited waypoints. 0
sprayWaypoints Waypoints for "spray shots", i.e. autoshots in multiple directions.

More info here: https://openxcom.org/forum/index.php/topic,6423.0.html

0
shotgunPellets Number of projectiles fired per unit of ammunition. (note: due to engine limitations it is currently impossible to draw multiple projectiles in flight.) 0
shotgunBehavior
shotgunSpread
shotgunChoke 		Attributes affecting how shotguns work.

More info: https://openxcom.org/forum/index.php/topic,4834.0.html

0
100
100
maxRange Maximum range at which this weapon can operate. 200
aimRange Maximum effective range with this weapon before which range-based dropoff occurs. 200
snapRange Maximum effective range with snap shot before which range-based dropoff occurs. (ufoextender accuracy only) 15
autoRange Maximum effective range with auto shot before which range-based dropoff occurs. (ufoextender accuracy only) 7
minRange Range-based dropoff will work in reverse for ranges below this. 0
dropoff The value by which the accuracy lowers for each tile after (or before) the thresholds above. 2
powerRangeThreshold Number of tiles defining the effective range (i.e. range with no power reduction). Beyond this range power reduction is applied. 0
powerRangeReduction Weapon's power dropoff per tile beyond effective range. 0

Compatible ammo and Action Mapping

Value Description Default
clipSize The amount of ammo stored in each weapon clip. If -1 is specified, this weapon has infinite ammo. If specified for a HWP, clipSize determines the maximum amount of shots which can be loaded into the HWP weapon. Use clipsize -1 for melee weapons. 0
compatibleAmmo List of string IDs of the ammo items that can be loaded on this weapon. If none are specified, the weapon doesn't need ammo. -
tuLoad
tuUnload 		Amount of Time Units required to load/unload this item.

Note: in OXCE, when loading a weapon, you need to additionally pay the cost of moving the ammo from its current inventory slot into a hand slot! Consider that when balancing reload costs.

Update: since OXCE v6.2, the OXCE behavior is now turned off by default. It can be enabled using the extendedItemReloadCost setting.

15
8
ammo In OXCE, you can load multiple different types of ammo into one gun at the same time. This allows you to create, for example, a rifle with a built-in grenade launcher. There are up to 4 ammo slots, which can be assigned to Aimed/Snap/Auto actions. Going back to the rifle with a grenade launcher example, you could have the rifle with Aimed and Snap and sacrifice the Auto action for implementing let's say a Snap shot for the grenade launcher.

Example: 

 - type: STR_WEAPON_WITH_4_AMMO_SLOTS
   ammo:
     0:
       compatibleAmmo: [ STR_AMMO_1, STR_AMMO_2 ]
       tuLoad: 5
       tuUnload: 2
     1:
       compatibleAmmo: [ STR_AMMO_3 ]
       tuLoad: 10
       tuUnload: 4
     2:
       compatibleAmmo: [ STR_AMMO_4, STR_AMMO_5 ]
       tuLoad: 10
       tuUnload: 4
     3:
       compatibleAmmo: [ STR_GRENADE_AMMO ]
       tuLoad: 20
       tuUnload: 8
-
autoShots How many auto shots does this weapon fire. 3
arcingShot Does this weapon fire in an arc? false
confAimed
confSnap
confAuto
confMelee 		A mapping between actions and ammo slots (see above).

Example: 

 - type: STR_RIFLE_WITH_A_GRENADE_LAUNCHER
   confAimed:
     shots: 1
     followProjectiles: true    # default
     name: STR_AIMED_SHOT
     ammoSlot: 0
     arcing: false
   confSnap:
     shots: 2
     followProjectiles: false   # the camera stays still while shooting (prevents minigun seizures)
     name: STR_DOUBLE_SNAP_SHOT
     ammoSlot: 0
     arcing: false
   confAuto:
     shots: 1
     name: STR_LAUNCH_GRENADE
     ammoSlot: 3
     arcing: true
   confMelee:
     name: STR_PUNCH_IN_THE_FACE
-
psiAttackName Besides panic attack and mind control, weapons of psi-amp type can have also a third type of attack, bound to "use" attributes (for example costUse). This attribute defines what should be the name of such attack in the action menu (e.g. Seduce, VooDoo spell, etc.). -
primeActionName Name of the prime action in the action menu. Default is STR_PRIME_GRENADE.

Tip: in OXCE more item battleTypes can be primed than in OpenXcom, for example also battleType 10 (Electro-flares).

<=
primeActionMessage Message for the player informing about the priming of an item. Default is STR_GRENADE_IS_ACTIVATED. <=
unprimeActionName Name of the un-prime action in the action menu. -
unprimeActionMessage Message for the player informing about the un-priming of an item. Default is STR_GRENADE_IS_DEACTIVATED. <=

Cost of use

Value Description Default
tuAimed
tuSnap
tuAuto
tuMelee 		The percentage (0-100%) of Time Units (from the soldier's total) required to fire an Aimed/Snap/Auto Shot or doing a Melee attack. If 0, the weapon does not have the corresponding attack. 0
0
0
0
tuUse Amount of Time Units required to use this item (for non-offensive items). It's a flat rate if flatRate is true, otherwise it's a percentage (0-100%). 0
tuMindControl
tuPanic 		Amount of Time Units required to use this item. If not specified, defaults to tuUse. -1
-1
tuThrow
tuPrime
tuUnprime 		Amount of Time Units required to throw/prime/unprime this item. 25
50
25
costAimed
costSnap
costAuto
costMelee
costUse
costMindControl
costPanic
costThrow
costPrime
costUnprime 		Extended way of defining the cost of item use. Instead of spending only time units, you can also define to spend energy, morale, HP, mana and stun. All costXXX settings override tuXXX settings, for example costAimed overrides tuAimed, etc.

Example: 

 - type: STR_FUNNY_WEAPON
   costAimed:
     time: 90
     energy: 20
     morale: 65
     mana: 5
-
flatRate If true, then TU costs for this weapon are a flat rate (instead of a percentage of unit TUs). false
flatAimed
flatSnap
flatAuto
flatMelee
flatUse
flatThrow
flatPrime
flatUnprime 		Extended way of defining if the cost of item use is flat or in percentage. You can now define it for various actions separately. If defined, the more specific setting (e.g. flatAimed) overrides the less specific setting (flatRate).

Example: 

 - type: STR_FUNNY_WEAPON
   costAimed:
     time: 90
     energy: 20
     mana: 5
   flatAimed:
     time: false   # 90% of TU
     energy: true  # 20 energy (flat)
     mana: true    # 5 mana (flat)
-

Debriefing/Recovery

Value Description Default
experienceTrainingMode Defines which skill(s) should improve when the soldiers gain experience by hitting enemy units (or healing fatal wounds of any units).

More info: https://openxcom.org/forum/index.php/topic,4230.0.html

0
manaExperience How much mana experience points does the weapon provide. 
 manaExperience: 250    # this means 2 points + 50% chance for a 3rd point (on every hit on hostile unit)
0
recover Is this item recoverable? (gets transported to the X-COM base on mission success) true
recoverCorpse Since the recover flag applies to both live body (prisoner capture) and dead body (corpse recovery) in OpenXcom, OXCE adds this new flag to allow recovery of a live body, but disable recovery of the corpse (used in mods mostly to ignore dead bodies of killed humans). true
recoveryPoints Score gained for recovering this alien artifact. 0
liveAlien Does this item represent a live alien? (counts towards Alien Containment) false
prisonType What type of prison (alien containment) facility can accommodate a unit (marked as liveAlien) represented by this item.

More info: https://openxcom.org/forum/index.php/topic,4830.msg69933.html#msg69933

0
specialType MCD value in map files to which this item corresponds for mission recovery. -1
recoveryDividers Definition how special items (with specialType > 1) should be recovered from the mission.

More info here: https://openxcom.org/forum/index.php/topic,6616.0.html

-
recoveryTransformations Allows recovering items as other items (for example alien weapons as alien weapon fragments).

More info here: https://openxcom.org/forum/index.php/topic,6868.0.html

-

Medikits

Value Description Default
medikitActionName Name of the use action in the action menu. Default is STR_USE_MEDI_KIT. <=
medikitType Defines, which functions can this medikit perform. Possible options:
  • 0 = All functions
  • 1 = Heal only
  • 2 = Stimulant only
  • 3 = Painkiller only
 0
allowSelfHeal Deprecated. Use medikitTargetSelf instead. false
medikitTargetSelf Is it possible to use the medikit on oneself (true)? Or only on other units (false)? Ignores other settings. false
medikitTargetImmune Is it possible to use the medikit on units that cannot bleed (true)? Or only on other units (false)? false
medikitTargetMatrix Says what targets are allowed for a medikit item. It is a composite attribute (a bit map), individual parts:
  • 1 = friendly on the ground
  • 2 = friendly standing
  • 4 = neutral on the ground
  • 8 = neutral standing
  • 16 = hostile on the ground
  • 32 = hostile standing

So, for example:

  • 0 = cannot use on anyone
  • 3 (1+2) = can use only on friendlies
  • 31 (1+2+4+8+16) = can use on everyone except on standing hostiles/enemies
  • 63 = can use on everyone
  • etc.
 63
isConsumable Will this medikit be automatically refilled at the base (false)? Or will it disappear after the mission, if used at least once (true)?

Note: If you use multiple medikits, they will use the same "combination" algorithm as the guns use for bullet recovery in OpenXcom. Using two medikits let's say just once will not make both of them disappear, because there will be enough "stuff" left to fully recover one of them.

false
painKiller Amount of painkillers contained in a Medi-Kit. 0
heal Amount of heals contained in a Medi-Kit. 0
stimulant Amount of stimulants contained in a Medi-Kit. 0
woundRecovery Amount of Fatal Wounds treated by each heal of a Medi-Kit. 0
healthRecovery Amount of Health recovered by each heal of a Medi-Kit. 0
stunRecovery Amount of Stun removed by each stimulant of a Medi-Kit. 0
energyRecovery Amount of Energy recovered by each stimulant of a Medi-Kit. 0
manaRecovery Amount of Mana recovered by each stimulant of a Medi-Kit. 0
painKillerRecovery Strength of the pain killers (1.0 = 100%). Linear factor affecting vanilla morale recovery (based on lost health). 1.0
moraleRecovery Additional points of morale to restore when pain killers are used. Does not depend on lost health (or anything else). 0
medikitBackground Sprite ID of the medikit background.

Tip: size and position of buttons can also be adjusted using Interface ruleset (but only globally for all medikit items).

-

Inventory

Value Description Default
weight Weight occupied by this item in a soldier's inventory. 3
invWidth Item width in a soldier's inventory (in grid units). 1
invHeight Item height in a soldier's inventory (in grid units). 1
fixedWeapon Is this weapon fixed (cannot be dropped from the Inventory)? (it's part of a unit, e.g. tanks and terrorist units) false
fixedWeaponShow Should the fixed weapon be drawn on the unit in the Battlescape or not? Normally, the weapon is not drawn (for example Reaper or Cyberdisc weapon... because it's a part of the unit itself), but in mods you may have for example fixed weapons on certain armors, which you want to display as normal "carried" weapons. false
defaultInventorySlot An inventory slot where a fixedWeapon should be placed when it is created. -
defaultInvSlotX A position within the inventory slot where a fixedWeapon should be placed when it is created. 0
defaultInvSlotY A position within the inventory slot where a fixedWeapon should be placed when it is created. 0
supportedInventorySections A list of inventory slots, where this item can be (manually) placed. If empty, all slots are OK. -
ignoreInBaseDefense Items marked with this flag will not appear in the Base Defense mission.

Note: mods, which have items used mostly in Geoscape (e.g. random resources used for manufacturing), but still recoverable from Battlescape should use this flag so that the ground inventory is not spammed by useless junk slowing the game down (significantly! if there are thousands of such items).

false
ignoreInCraftEquip Items marked with this flag will not appear in Craft Inventory Equipment screen.

Defaults:

  • true for corpses (battleType=11) and geoscape-only items (battleType=0)
  • false for all other items
 <=
specialUseEmptyHand Whether this specialWeapon is used when clicking on the empty hand slot in soldier's inventory. Used for punching/kicking with bare hands :) false

Things that go BOOM

Value Description Default
fuseType Defines how item priming works.

Possible options:

  • -3 No priming. Flares always glow if defaultBehavior is true.
  • -2 Can be primed (without timer). Proxies work normally. Grenades explode instantly after throwing. Flares glow only after priming.
  • -1 Can be primed (for manually specified amount of turns). Grenades explode after set time. Proxies and flares disappear after set time.
  • 0-23 Can be primed (for fixed amount of turns).

Defaults:

  • -2 for proximity grenades
  • -1 for grenades
  • -3 for everything else
 <=
fuseTriggerEvents Defines how fuse triggers work. Contains 5 sub-attributes:
  • defaultBehavior: everything works as in vanilla
  • throwTrigger: timer starts only after throwing
  • throwExplode: items explode (grenades) or are removed (other) on throw; affected by specialChance
  • proximityTrigger: timer starts only after moving into item's proximity
  • proximityExplode: item explode (grenades, proxies) or are removed (other) after moving into item's proximity; affected by specialChance

Example/Defaults: 

 fuseTriggerEvents:
   defaultBehavior: true
   throwTrigger: false
   throwExplode: false
   proximityTrigger: false
   proximityExplode: false
<=
specialChance The chance (0-100%) of special effects happening, including:
  • mine triggering (see above)
  • corpse explosion (e.g. of a bio-drone corpse)
  • zombification (e.g. by a chryssalid weapon)
 100
isExplodingInHands Does the item explode also when still in a unit's inventory? false
hiddenOnMinimap Is the item visible on the minimap?

Tip: use for example for mines hidden underground

false

Miscellaneous

Value Description Default
isFireExtinguisher Can this item be used to extinguish fire on units? false
armor How much damage is needed to destroy this item on the ground. 20
attraction Represents how likely an alien is to pick up this item. Values below 5 will be ignored (by design). 0
LOSRequired Does this item require line of sight? (only applies to mind probes and psi-amps) false
psiRequired Does using this item require psi skill > 0 ? Items of battleType=9 (psi-amps) have this flag set to true by default. false
psiTargetMatrix Says what targets are allowed for a psiamp item. It is a composite attribute (a bit map), individual parts:
  • 1 = friendly
  • 2 = hostile
  • 4 = neutral

So, for example:

  • 0 = cannot use on anyone
  • 1 = can use only on friendlies
  • 6 (2+4) = can use only on hostiles and neutrals
  • etc.

Note: Mind-controlling friendlies is never possible, hardcoded. Panicking friendlies is possible.

6
manaRequired Does using this item require mana research unlocked? false
underwaterOnly Can this item only be used underwater? false
landOnly Can this item only be used on land? false
zombieUnit String ID of the unit used for zombification (eg. Chrysallids turn units into Zombies). -
zombieUnitByArmorMale Overrides zombieUnit. Based on armor worn by the victim. A list of String ID pairs. -
zombieUnitByArmorFemale Overrides zombieUnit. Based on armor worn by the victim. A list of String ID pairs. -
zombieUnitByType Overrides zombieUnit. Based on the victim soldier/unit type. A list of String ID pairs. -
spawnUnit
spawnUnitFaction 		Used for spawning units from items.

More info: https://openxcom.org/forum/index.php/topic,6535.0.html

-
-1
ai.useDelay
ai.meleeHitCount 		1/ Used to override AI delay defined by global settings.

2/ How many times should an AI unit try to perform a melee attack (in the single go)? In vanilla, the unit used the melee attack until the target was neutralized or until it ran out of TUs. This attribute gives you the option to perform "hit and run". 

 ai:
   useDelay: 1
   meleeHitCount: 15
-1
25

Item Categories

Defines some extra behavior (and list order) of item categories, listed in "itemCategories:".

Value Description Default
type String ID of the item category name. required
hidden Defines whether this category should be hidden in the filter on the [Craft Equipment] screen.

Note: categories not shown to the player are still useful for the modder sometimes.

false
replaceBy Defines mapping between item categories.

Note: this is useful when you are still experimenting with the item categorization. If you defined too many categories for example, you can group them together easily here, instead of having to redefine all the items. And if you change your mind later, you can easily ungroup them again.

-

Item Damage Types

These are the sub-attributes you can use within attributes damageAlter and meleeAlter. Listed separately for convenience.

Value Description Default
FixRadius A blast radius.
  • -1 = dynamic blast radius
  • 0 = no blast radius
  • 1+ = fixed blast radius
 0
RandomType Defines how will be dice be rolled to determine damage based on power (primary damage calculation). Possible options:
  • 0 = default vanilla behavior dependent on damageType
  • 1 = 0-200% spread
  • 2 = 50-150% spread
  • 3 = flat damage equal to power
  • 4 = random damage in range defined by fireDamageRange
  • 5 = no damage
  • 6 = 0-200% spread (2 dice roll), i.e. 0-100% + 0-100%
  • 7 = 50-200% spread
 0
ResistType A damage type, i.e. what resistance of the target unit's armor is applied. Same values like damageType. 0
FireBlastCalc Vanilla fire/incendiary blast radius has a special formula. This option turns it on/off. false
IgnoreDirection Should the damage calculation ignore from which direction the projectile came? Used for example for smoke or fire. false
IgnoreSelfDestruct Killing using this damage prevents self-destruct (e.g. of Cyberdisc). Used for example on HE, Stun or Melee damage. false
IgnorePainImmunity Some units are immune to pain/stun (see painImmune on Armor). This allows you to ignore such immunity. Used for example on Stun damage. false
IgnoreNormalMoraleLose When units are hit, they lose morale. This option allows you to turn this effect on/off. false
IgnoreOverKill Disables overkill damage, i.e. units won't get vaporized/disintegrated when killed (by a hit doing a lot more damage than necessary to kill). false
ArmorEffectiveness How effective is a unit's front/side/rear/bottom armor against this damage. 1.0 is 100%. 1.0
RadiusEffectiveness If FixRadius = -1, the blast radius is not fixed, but dynamically calculated from Power (incl. Power bonus). This is a factor for such calculation. 0.0
RadiusReduction How much explosion Power decreases with distance from the center. 10.0
FireThreshold How much damage is needed to set a unit or a tile on fire. 1000
SmokeThreshold How much damage is needed to create smoke on a tile. 1000
ToArmorPre How much of the primary damage (Power x RandomType) is applied to the unit's armor before armor is considered. 0.0
RandomArmorPre Should the calculation above be randomized?

Example 1: Power = 100. Primary damage rolled = for example 140. ToArmorPre = 0.1. RandomArmorPre = false. Damage applied to a unit's armor will be 14.

Example 2: Power = 100. Primary damage rolled = for example 140. ToArmorPre = 0.1. RandomArmorPre = true. Damage applied to a unit's armor will be a random value between 0 and 14.

false
ToArmor How much of the primary damage is applied to the unit's armor after armor is considered. 0.1
RandomArmor Should the calculation above be randomized? false
ToHealth How much of the primary damage is applied to the unit's health. 1.0
RandomHealth Should the calculation above be randomized? false
ToStun How much of the primary damage is applied to the unit's stun level. 0.25
RandomStun Should the calculation above be randomized? true
ToWound
RandomWound 		Determines how many fatal wounds should be inflicted. Default settings equal to vanilla calculations. Formula is quite hard to describe in words, so here's the code: 
 if (damage > 0) {
   if (RandomWound) {
     if (RNG::generate(0, 10) < int(damage * ToWound)) {
       return RNG::generate(1,3);
     }
   } else {
     return (int)std::round(damage * ToWound);
   }
 }
1.0
true
ToTime How much of the primary damage is applied to the unit's TUs. 0.0
RandomTime Should the calculation above be randomized? false
ToEnergy How much of the primary damage is applied to the unit's energy. 0.0
RandomEnergy Should the calculation above be randomized? false
ToMana How much of the primary damage is applied to the unit's mana burn. 0.0
RandomMana Should the calculation above be randomized? false
ToMorale How much of the primary damage is applied to the unit's morale. 0.0
RandomMorale Should the calculation above be randomized? false
ToItem How much of the primary damage is applied to items. 0.0
RandomItem Should the calculation above be randomized? false
ToTile How much of the primary damage is applied to the terrain. 0.5
RandomTile Should the calculation above be randomized? false
TileDamageMethod Which tile damage method should be used?
  • For AOE (area-of-effect) weapons:
    • TileDamageMethod==1: (50%-150% * power * ToTile)
    • TileDamageMethod==2: ((power x RandomTile) * ToTile), which defaults to vanilla 50% damage for HE and 0% for stun, smoke and incendiary
  • For non-AOE (projectile) weapons:
    • TileDamageMethod==1: (50%-150% * power * ToTile), which defaults to vanilla 25%-75% damage for AP/laser/plasma/etc.
    • TileDamageMethod==2: ((damage x RandomTile) * ToTile)
 1
IMPORTANT: The defaults above are the generic defaults. For each damage type, there are also specific defaults that emulate the vanilla hardcoded damage types. For modding purposes, the specific defaults are relevant (they override the generic ones). Below is the summary of the specific defaults.
DT_NONE DT_AP DT_IN DT_HE DT_LASER DT_PLASMA DT_STUN DT_MELEE DT_ACID DT_SMOKE DT_10 ... DT_19
ResistType 1 2 3 4 5 6 7 8 9 10 ... 19
FireBlastCalc true
IgnoreOverKill true true true true true true true true true true
IgnoreSelfDestruct true true true true
IgnorePainImmunity true
IgnoreDirection true true
FixRadius -1 -1 -1 -1
RadiusEffectiveness 0.03 0.05 0.05 0.05
ArmorEffectiveness 0.0 0.0
FireThreshold 0
SmokeThreshold 0
ToHealth 1.0 0.0 0.0
ToArmor 0.0 0.0 0.0
ToWound 0.0 0.0 0.0
ToItem 0.0 1.0 0.0 0.0
ToTile 0.0 0.0 0.0
ToStun 0.0 1.0 1.0
RandomStun false
TileDamageMethod 2 2 2 2

UFOs

Defines one of the UFOs that invade Earth, listed in "ufos:".

Value Description Default
type String ID of the UFO name. required
size String ID of the UFO size. STR_VERY_SMALL
sprite Sprite ID from INTERWIN.DAT used to draw this UFO in the dogfight view and UFOpaedia.

Note: don't try to add more images if you don't want to punch yourself in the face - use modSprite instead.

-1
modSprite Filename used to draw this UFO in the dogfight view and UFOpaedia. -
marker Sprite ID from GlobeMarkers spritesheet, used for drawing flying UFO icon on the globe. Usually 3x3 pixels, but can be modded to be bigger.

Note: if not modded, sprite id 2 is used (=vanilla flying UFO marker).

-1
markerLand Sprite ID from GlobeMarkers spritesheet, used for drawing landed UFO icon on the globe. Usually 3x3 pixels, but can be modded to be bigger.

Note: if not modded, sprite id 3 is used (=vanilla landed UFO marker).

-1
markerCrash Sprite ID from GlobeMarkers spritesheet, used for drawing crashed UFO icon on the globe. Usually 3x3 pixels, but can be modded to be bigger.

Note: if not modded, sprite id 4 is used (=vanilla crashed UFO marker).

-1
power Damage power of this UFO's weapon in dogfights. 0
range Maximum range of this UFO's weapon in dogfights (in kilometers). 0
score Score gained when this UFO is destroyed, or half this score if it crash lands. 0
reload Time the UFO's weapon takes to fire between each shot. 0
breakOffTime Minimum amount of time for the UFO to be able to break off of a dogfight. 0
missionScore Negative points awarded each half hour the UFO is airborne, and twice this value when landed 1
battlescapeTerrainData Terrain associated to this UFO in Battlescape missions. required
hunterKillerPercentage The chance (0-100%) to become a hunter-killer UFO upon spawning (unless overridden by mission wave).

Possible options:

  • 0 = not a hunter-killer
  • 1-99 = percentage chance to be flagged as hunter-killer upon spawn
  • 100 = always a hunter-killer
 0
huntMode Algorithm to use when prioritizing xcom targets (unless overridden by mission wave).

Possible options:

  • 0 = prefer hunting xcom interceptors
  • 1 = prefer hunting xcom transports
  • 2 = random preference (0 or 1) determined at spawn
 0
huntBehavior Algorithm to use when considering retreating from the dogfight (unless overridden by mission wave).

Possible options:

  • 0 = flee if you're losing
  • 1 = never flee, never crash (since OXCE v6.5, they fight until 0% HP, not 50% HP)
  • 2 = random preference (0 or 1) determined at spawn
 2
huntSpeed When hunter-killer finds a target, it will change speed to a percentage of its maximum speed.

Possible options:

  • 0 = don't change speed, i.e. keep current speed
  • 1-99 = set speed to a percentage of maximum speed
  • 100 = speed up to maximum
  • 100+ = yes, you can go beyond maximum speed... but only during the chase, when intercepted, the maximum speed will be correctly considered for all relevant calculations and game mechanics
 100
missilePower Only relevant for retaliation UFOs. If not shot down during the base defense, it will destroy some base facilities or even the whole base (without ground mission!).

Possible options:

  • -1 = destroy everything
  • 0 = disabled (i.e. not a missile)
  • N = destroy N 1x1 buildings or equivalent

More info: https://openxcom.org/forum/index.php/topic,6668.0.html

0
unmanned Unmanned UFOs (e.g. missiles, drones, etc.) cannot crash land after dogfight and cannot be forced to land by a tractor beam. They fight until 0% HP (not 50% HP). false
splashdownSurvivalChance Chance (in percent) for a UFO to survive a crash landing on "fake underwater" globe texture. 100
fakeWaterLandingChance Chance (in percent) for a UFO to land on "fake underwater" globe texture. 0
fireSound UFO's fire sound in the Dogfight, from GEO.CAT. -1
alertSound Sound played when this type of UFO is detected, from GEO.CAT. -1
huntAlertSound Sound played when this type of UFO starts hunting an XCOM craft, from GEO.CAT. -1
raceBonus Modifies or overrides the UFO Stats per alien race.

You can use this to make the same type of UFO have different stats depending on the alien race. 

 - type: STR_TERROR_SHIP
   raceBonus:
     STR_MUTON:
       hitBonus: 20
       craftCustomDeploy: STR_MORE_SCARY_WEAPONS
       missionCustomDeploy: STR_TERROR_SITE_MUTONS
     STR_ETHEREAL:
       missionCustomDeploy: STR_END_OF_THE_WORLD
-

UFO Stats

The following attributes define so called "ufo stats". They are listed in a separate table, just for convenience... but are still part of the UFO ruleset.

Note: In OXCE, all these stats are dynamic, i.e. can depend on the alien race piloting the UFOs.

Value Description Default
damageMax Maximum amount of damage this UFO can take. If the UFO takes 50% damage, it crash lands. If it takes 100% damage, it is destroyed. 0
speedMax Maximum speed in nautical miles. 0
radarRange Detection range of the UFO's radar in nautical miles. Relevant for hunter-killer UFOs. 672
radarChance Chance (0-100%) of this UFO radar detecting a craft that enters its range. 100
sightRange UFO's sight range (for detecting X-COM bases) in nautical miles. 268
hitBonus Flat bonus percentage to hit chance. 0
avoidBonus Flat bonus percentage to dodge chances against enemy fire. 0
powerBonus Multiplier for the weapon power, e.g. 20 = weapon power increased to 120%, -20 = decreased to 80%. 0
armor Amount of blocked damage per hit. 0
shieldCapacity UFO's maximum shield capacity. 0
shieldRecharge Defines the percent chance of recharging a point of shielding per game second (GS) during a Dogfight. Values under 100 are the percent chance, for over 100, every +100 means an automatic +1 to shields per GS. Thus shieldRecharge: 250 means +2 shields/GS, with a 50% chance of +1 more. 0
shieldRechargeInGeoscape Similar to shieldRecharge, but acts every 5 seconds in the Geoscape. Giving it a value of -1 means instant recharge as soon as 5 seconds pass! 0
shieldBleedThrough Defines the percent of damage that passes the shield when it goes down. A value of 0 means that with even just 1 shield point, any single hit will be blocked, while 100 means 100% of the damage left after the shield blocks it will go on to damage the UFO. 0
craftCustomDeploy Overrides the deployment data used during the Battlescape generation, when the UFO crashes or lands. -
missionCustomDeploy Overrides the deployment data used during the Battlescape generation, when the UFO spawns a mission site. -

Inventory Sections

Defines one of the sections of the Battlescape inventory (eg. Backpack), listed in "invs:".

Value Description Default
id String ID of the inventory name. required
x

y

Pixel coordinates of this section on the inventory screen. 0

0

type Type of this section:
  • 0 = Slot section, can contain as many items as will fit on the slots.
  • 1 = Hand section, can only contain one item regardless of size.
  • 2 = Ground section, can contain infinite items.
 0
slots List of the grid slots ([x, y]) that this section is composed of. For example, to make a 2x2 section, you would have [0, 0] [0, 1] [1, 0] [1, 1]. -
costs List of Time Units costs to move an item from this section to another one (eg. STR_BACKPACK: 16 means it will cost 16 TUs to move an item from this section to the Backpack). -

Terrains

Defines one of the terrains used to generate a Battlescape map, listed in "terrains:".

Value Description Default
name String ID of the terrain name. required
mapDataSets List of filenames (each with matching MCD/PCK/TAB files) that contain the tiles of this terrain. -
mapBlocks List of map blocks (see below) that are used for generating a map. -
addOnly Normally, when loading mapBlocks, any map blocks loaded previously (e.g. from other mods) are deleted first and then new map blocks are added. If this attribute is true, the existing map blocks are not deleted and the new ones are added at the end of the list.

Note: does not apply to mapDataSets or anything else

false
civilianTypes List of units to use as civilians for this mission. [MALE_CIVILIAN, FEMALE_CIVILIAN]
music The list of musics this terrain can choose from (unless overridden by alienDeployment). -
depth Minimum and maximum possible depth, format is [minDepth, maxDepth]. Sets the battlescape depth (randomly, unless overridden by alienDeployment). [0, 0]
ambience The ambient sound effect. Sound ID from BATTLE.CAT. -1
ambientVolume The volume of the ambient sound effect. 0.5
ambienceRandom A list of ambient sound effects (IDs from BATTLE.CAT). Doesn't work when ambience is defined. Uses ambientVolume. A random sound effect is chosen each time a sound is played. -
ambienceRandomDelay The delay between random ambient sound effects in seconds. Chosen randomly between the defined min and max (after each sound played).

Note: the time passes only when the game is not "busy" (= when you see the map tiles animate). When the tiles don't animate, the timer for ambient sounds doesn't tick.

[20, 60]
script The map generation script name. DEFAULT
enviroEffects String ID of enviro effects for missions using this terrain.

Note: if enviro effects are defined both on terrain and on alien deployment, the deployment's enviro effects are used.

-

Map Blocks

Value Description Default
name Filename of the map. required
width Width of this map block in Battlescape grid units.

Note: in MapView tool (tested on version 1.6.0.0), this is called length. MapView's dimensions [w, l, h] correspond to OpenXcom's dimensions [l,w,h].

10
length Length of this map block in Battlescape grid units.

Note: in MapView tool (tested on version 1.6.0.0), this is called width. MapView's dimensions [w, l, h] correspond to OpenXcom's dimensions [l,w,h].

10
height Height of this map block in Battlescape grid units. 4
groups List (or single number) of groups this mapblock belongs to (used in mapscripts)

default usage:

  • 0 - Default
  • 1 - Landing Zone (for placing X-COM / alien craft) (used in addCraft/addUFO mapscript commands)
  • 2 - E-W Road (for city maps) (used in addLine mapscript command)
  • 3 - N-S Road (for city maps) (used in addLine mapscript command)
  • 4 - Road Crossing (for city maps) (used in addLine mapscript command)

Hint: all maps with an XCOM/Alien craft require at least one map block assigned to Group 1. This map block can only contain ground tiles (no walls or objects).

0
revealedFloors Map block floor to be revealed from the very beginning; use a list "[0, 1, ..]" to reveal multiple floors -
items An array of items to add to this mapblock, and the positions to place them at. -
fuseTimers This attribute allows you to pre-prime the items placed on the map using the items attribute. It's a list of items and information about minimum and maximum fuse timer.

Example: 

 items:
   STR_ELERIUM:
     - [0, 0, 0]
   STR_TIMEBOMB:
     - [2, 1, 0]
     - [6, 2, 0]
 fuseTimers:
   STR_TIMEBOMB: [0, 30]

In this example 3 items are placed on the map block: 1 Elerium item and 2 Timebomb items. Both Timebomb items will be pre-primed with a random delay between 0 and 30 (each item will have a different delay). Elerium item will not be pre-primed :)

-
randomizedItems A list of additional items to add to this mapblock, using a more randomized approach. Does not support pre-priming of items.

Example: 

 randomizedItems:
   - position: [12, 15, 2]
     amount: 3
     mixed: true
     itemList: [STR_ITEM_1, STR_ITEM_2, STR_ITEM_3, STR_ITEM_3]

In this example:

  • 3 items will be placed on the tile at coordinates [x,y,z] = [12, 15, 2]
  • all 3 items can be different (mixed: true); if you wanted 3 items of the same type use mixed: false
  • items are selected from the itemList randomly; to increase odds for a certain item type, you can add it to the list multiple times
    • in our example STR_ITEM_1 has 25% chance, STR_ITEM_2 also 25% chance and STR_ITEM_3 a 50% chance
 -

MCD Patches

FIXME Someone please document this...

Map Scripts

Defines how the battlescape maps are generated from the available map blocks.

Value Description Default
type name of the script required
commands List of MapCommands -

Map Command

Value Description Default
type Currently these commands are implemented:
  • addBlock - adds a mapblock can be combined with size, group, executions and blocks (for a weighted list)
  • addLine - adds a line of mapblocks from groups (roads for example)
  • addCraft - adds X-Com craft towards map
  • addUFO - can also be used to place 'UFO' maps (or any other single map) on missionSite (objective 3) missions.
  • digTunnel
  • fillArea
  • checkBlock
  • removeBlock
  • resize
 required
rects A list of possible areas on the map where (random) placement/checks/removal can happen. If not specified, entire map is considered.

Each item in the list is a group of four integers [x, y, width, height].

-
label 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, OpenXcom will convert them to positive (abs. value) anyway. If you try using non-unique labels, you'll get undefined behavior. 0
conditionals 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
size Size of map blocks that can be placed/checked/removed within rects. Only width (sizeX) and length (sizeY) are relevant. Can be specified as a single value, which is then used as both width and length; or as group of up to three values [x, y, z].

Also used for resize command type, which can use also the height value (sizeZ).

[1, 1, 0]
groups Defines what types of map blocks can be used within this command. Can be defined as a list or as a single value. 0
horizontalGroup Allows to override group used in addLine command. 2
verticalGroup Allows to override group used in addLine command. 3
crossingGroup Allows to override group used in addLine command. 4
blocks Alternative to groups. Here we define an explicit list of map blocks that can be used within this command.

Important: The list is defined by map block sequential IDs (not by name!), where first map block has sequential ID = 0 (not 1).

0
freqs Defines the distribution frequency for the groups or blocks (see above). If not used, all groups/blocks have frequency 1. 1
maxUses Defines the maximum number of uses for the groups or blocks (see above). If not used, all groups/blocks have frequency -1 (=unlimited). -1
tunnelData Parameter for digTunnel command type. Contains a level (default: 0) and a list of MCD replacement rules (MCDReplacements) -
direction Parameter for digTunnel and addLine command types. Values are: both, horizontal or vertical. -
executionChances The probability (0-100%) that this command will be executed (or fails). 100
executions This command will be executed multiple times with a value > 1. 1
UFOName String ID of the UFO to be placed. -
canBeSkipped Only relevant for addUFO command with no label defined. Determines, whether an unsuccessful addUFO command can be skipped (and logged into the log file) or whether the game should crash.

Note: this attribute is more or less deprecated. Maybe useful for testing/debugging?

true
craftName String ID of the craft to be placed.

Note: this can be used to replace the craft you arrived with (e.g. Skyranger) with a new vehicle you used to make the last section of your journey. For example a small submarine for an underwater mission or an APC for a mission, where you couldn't land or didn't want to make too much noise :)

-
terrain String ID of an alternate terrain to be used for this command only. Used for example when you want to sneak in a few blocks from FOREST terrain into a map made predominantly using FARM terrain.

There is a special constant globeTerrain, which takes a random terrain corresponding to the globe texture, where the mission takes place. More info here: https://openxcom.org/forum/index.php/topic,7536.0.html

There is also a special constant baseTerrain for base defense missions, which takes the terrain from the globe definition (see also baseDefenseMapFromLocation). More info: https://openxcom.org/forum/index.php/topic,5108.0.html

-
randomTerrain Alternative to terrain. A list of string IDs, one of them is chosen randomly.

More info: https://openxcom.org/forum/index.php/topic,7758.0.html

-
verticalLevels Allows using a set of map blocks (of various vertical sizes) stacked on top of each other... instead of just a single map block.

More info: https://openxcom.org/forum/index.php/topic,5316.0.html

-

Guidelines/Tips

  • There are 3 main 'types' of map generation in UFO/TFTD:
    • Random, where any map block (including XCom craft and/or UFOs/USOs) can be placed anywhere in the Battlescape;
    • Procedurally generated, where placement of certain maps is defined by rules (i.e. the roads on the Urban terrain used in terror sites in Enemy Unknown/UFO Defense);
    • Static, where only 1 or more maps are used (i.e. Cargo and Liner Ships in TFTD).
  • Map scripting in OpenXcom allows also for a mixture of 2 or even all the 3 described above, where some parts of the map will be static, others will be filled according to certain rules and the remainer filled randomly.
  • Every script requires at least 1 map block used for spawning XCom units. Usually that role is taken by XCom craft, except on the XCom Base, Alien Base and the 2nd part of the Cydonia mission. If the script can't place this map then OpenXcom will display a message saying that it couldn't place XCom units on the map.
  • Every space on the Battlescape needs to be filled, so the script should have enough mapblocks available for use. In the case of the vanilla terrains, the maxUses settings were designed mostly for 50x50 dimensions so any increases to those dimensions will require adjusting the maxUses settings. Otherwise the game will crash and display an error message that it couldn't generate the map.
  • The "addLine" command relies on groups 2, 3 and 4 as its vertical road, horizontal road and crossroad pieces.
  • The "addCraft" and "addUFO" commands will place blocks from group 1 as well, by default, if any are defined.

Armor

Defines a Battlescape unit's armor as well as visual representation (so every unit has an armor), listed in "armors:".

Value Description Default
type String ID of the armor name. required
requires The research required to equip this armor.

Modding hint: it is possible to equip one "store item" as several different armors, e.g. as armor with or without a helmet. This option allows you to limit some of those options by a research topic. You could use this also for example to define different armor variants for each game difficulty level, e.g. make armor stronger for beginners and weaker for veterans.

-
spriteSheet Sprite sheet from UNITS used to draw a unit wearing this armor. -
spriteInv Sprite used for the Inventory Backgrounds of a unit wearing this armor. -
layersDefaultPrefix layersSpecificPrefix layersDefinition Alternative way of defining/creating inventory sprites (a.k.a. paperdolls), in layers.

More info: https://openxcom.org/forum/index.php/topic,6290.msg104464.html#msg104464

-
-
-
allowInv Can the inventory of this armor be accessed or not? true
corpseItem Deprecated: use corpseGeo and corpseBattle instead. -
corpseBattle List of string IDs of the corpse items generated when a unit wearing this armor is killed/stunned (1 for 1x1 unit, 4 for 2x2 unit) on the Battlescape. -
corpseGeo String ID of the corpse item recovered in Debriefing. Defaults to corpseBattle if omitted.

Tip for modders: useful for example when you want to recover a "damaged" version of a soldier's armor.

-
storeItem String ID of the item that represents this armor in Base Stores for equipping. Set to STR_NONE to not require an item (eg. coveralls). -
specialWeapon Alternative method of defining a melee/psi weapon for aliens (and civilians); instead of defining it on the unit itself.

Note: in OXCE, this can be used also for Soldiers. It can be any type of weapon (not only melee/psi) and does not block the inventory. Instead it is accessed via a special icon.

-
builtInWeapons Alternative method of defining built-in weapons for aliens (and civilians); instead of defining them on the unit itself. Can be used also for Soldiers. -
frontArmor Protection provided on the front of the unit. 0
sideArmor Protection provided on the sides of the unit. 0
leftArmorDiff Used to define different armor values on the sides (left/right). If specified, left side armor = sideArmor + leftArmorDiff. 0
rearArmor Protection provided on the rear of the unit. 0
underArmor Protection provided under the unit (e.g. from explosions). 0
drawingRoutine Drawing routine used to put together the body parts in the unit's spriteSheet: 0
drawBubbles Set to true for units that breathe underwater, e.g. humans and humanoid aliens.

Note: in vanilla this is set to true for all units using drawingRoutine 13 and 14.

false
movementType Type of movement provided by this armor:
  • 0 = Walking
  • 1 = Flying
  • 2 = Sliding (no walking animation)
  • 3 = Floating (fly underwater, walk on the surface)
  • 4 = Sinking (walk underwater, fly on the surface)

it also defines the body of a tank (32-images) in your spriteSheet or the change in sprites while flying using a flying armor see: TANKS.PCK, XCOM_2.PCK

0
moveSound Sound ID from BATTLE.CAT played when a unit wearing this armor moves (overrides unit's moveSound). -1
deathMale/deathFemale Sound ID from BATTLE.CAT played when a unit wearing this armor dies. A list of sound IDs can be used too. -
selectUnitMale/selectUnitFemale Sound ID from BATTLE.CAT played when a unit wearing this armor is manually selected. A list of sound IDs can be used too. -
startMovingMale/startMovingFemale Sound ID from BATTLE.CAT played when a unit wearing this armor starts moving. A list of sound IDs can be used too. -
selectWeaponMale/selectWeaponFemale Sound ID from BATTLE.CAT played when a weapon of a unit wearing this armor is selected. A list of sound IDs can be used too. -
annoyedMale/annoyedFemale Sound ID from BATTLE.CAT played when a unit wearing this armor is repeatedly manually selected. A list of sound IDs can be used too. -
size Size of the unit wearing this armor, in Battlescape grid units. 1 means 1x1 unit, 2 means 2x2 unit, other sizes are not supported. 1
weight Physical weight of the armor when worn. 0
visibilityAtDark How far can the unit wearing this armor see during darkness. Default 0 uses 9 for X-Com, but for Aliens it uses the maxViewDistance variable (default 20). 0
visibilityAtDay How far can the unit wearing this armor see during the day. Default 0 uses the maxViewDistance variable (default 20). Both of these variables only affect how far away units may be seen. Terrain revealed is always based on maxViewDistance, day or night. 0
personalLight Intensity of the personal light for the unit wearing this armor. 15
camouflageAtDay Makes the unit wearing this armor less visible during the day. Positive numbers set absolute distance (e.g. 7 means that unit is visible from 7 tiles away), negative numbers set relative distance (e.g. -10 means that unit is visible from a distance that is 10 tiles shorter than usual). Cannot decrease visibility below 1 tile. 0
camouflageAtDark Makes the unit wearing this armor less visible during darkness. Positive or negative, same as above. 0
antiCamouflageAtDay Cancels enemy camouflage by a specified amount (of tiles) during the day. Cannot increase visibility beyond the usual (e.g. camo = -5 and antiCamo = 7 still only evens out, it doesn't provide 2 additional tiles of visibility). 0
antiCamouflageAtDark Cancels enemy camouflage by a specified amount (of tiles) during darkness. Cannot increase visibility beyond the usual. 0
heatVision Allows seeing better through smoke. Percentage (0-100%) value defining how much smoke is ignored. 0
psiVision Allow "seeing" through walls. Units with this armor can sense enemies that are 'psiVision' tiles (or less) away, in any direction.

Note: cannot sense enemies that are fearImmune.

0
stats Like soldier stats (see below) but these are treated as stat bonuses while wearing a given type of armor. -
damageModifier List of decimal damage modifiers (1.0 = 100%) this armor applies to each damage type (see Items section) received. Modifiers must be specified for all damage types, in this order:
  • None
  • Armor Piercing
  • Incendiary
  • High Explosive
  • Laser
  • Plasma
  • Stun
  • Melee
  • Acid
  • Smoke
In OXCE, there are 10 additional (nameless) damage types, which you can name and use for any purpose you like (e.g. create Electric damage, Freeze damage, EMP damage or whatever). You are also not forced to specify all 20 values if you are using less. If you for example only use 2 additional damage types, it is enough to specify only 12 (10 vanilla + 2 additional).

- 1.0
- 1.0
- 1.0
- 1.0
- 1.0
- 1.0
- 1.0
- 1.0
- 1.0
- 1.0

loftempsSet List of LOFTEMPS IDs (1 for 1x1 units, 4 for 2x2 units) used to represent a unit wearing this armor in 3D voxel space. -
loftemps Deprecated: use loftempsSet instead. -
deathFrames Number of "death frames" = sprites in the death animation sequence. 3
overKill Defines how much damage (over the maximum HP) is needed to vaporize/disintegrate a unit upon hit. Defined as percentage, e.g. 0.6 = 60% of maximum HP.

Notes:

  • If a unit is disintegrated, it will have a different death animation and it will not leave any corpse.
  • Weapons can be configured to cause disintegration or not (e.g. explosives vs bullets), see IgnoreOverKill (by default all weapons ignore overkill).
 0.5
constantAnimation Set it to "true" for units that constantly show an animation, such as: Biodrone, Celatid, Silacoid. false
forcedTorso Soldier sprites have female and male torsos. Some armors reuse these sprites for flying/non flying torso without difference between genders. This can be controlled by the parameter:
  • 0 = use gender-specific torso
  • 1 = use male torso
  • 2 = use female torso
 0
spriteFaceGroup Palette offset (1-15) used for replacing colors when drawing units. Replacement is based on unit's avatar (gender & look). Default 0 (unused).

As the name suggests, it is usually used to recolor faces.

example:
6
spriteHairGroup Palette offset (1-15) used for replacing colors when drawing units. Replacement is based on unit's avatar (gender & look). Default 0 (unused).

As the name suggests, it is usually used to recolor hair.

example:
9
spriteUtileGroup Palette offset (1-15) used for replacing colors when drawing units. Replacement is based on unit's avatar (gender & look). Default 0 (unused).

Doesn't have any suggested use, feel free to use it to recolor anything you want :)

0
spriteRankGroup Palette offset (1-15) used for replacing colors when drawing units. Replacement is based on unit's "rank" (see below for details). Default 0 (unused).

Doesn't have any suggested use, feel free to use it to recolor anything you want... for example Floater robes :)

0
spriteFaceColor New color index (0-255) for "face pixels". List of 8 values corresponding to the following avatars:
  • Male Blond, Female Blond, Male Brown, Female Brown, Male Asian, Female Asian, Male African, Female African

Aliens and civilians use random value from this list. Value 0 means "no change". Example: [96, 96, 96, 96, 160, 160, 163, 163]

-
spriteHairColor New color index (0-255) for "hair pixels". List of 8 values corresponding to the same avatars as above.

Aliens and civilians use random value from this list. Value 0 means "no change". Example: [144, 144, 164, 164, 245, 245, 166, 166]

-
spriteUtileColor New color index (0-255) for "util pixels". List of 8 values corresponding to the same avatars as above.

Aliens and civilians use a random value from this list. Value 0 means "no change".

-
spriteRankColor New color index (0-255) for "rank pixels".

For soldiers, a list of 6 values corresponding to the following xcom ranks:

  • STR_ROOKIE, STR_SQUADDIE, STR_SERGEANT, STR_CAPTAIN, STR_COLONEL, STR_COMMANDER

For aliens, a list of 7 values corresponding to the following alien ranks:

  • STR_LIVE_SOLDIER, STR_LIVE_ENGINEER, STR_LIVE_MEDIC, STR_LIVE_NAVIGATOR, STR_LIVE_LEADER, STR_LIVE_COMMANDER, STR_LIVE_TERRORIST

For civilians, a list of 8 values... one will be chosen randomly (since civilians don't have ranks). Value 0 means "no change".

-
units List of soldier types this armor applies to. Empty = applies to all soldier types. -
customArmorPreviewIndex Allows to have different icons for different types of armor on the [Craft Info] screen. Defined either as a single index into the CustomArmorPreviews spritesheet, or as a list of indices (for bigger icons). 0
allowsRunning Does this armor allow running? Defaults are: true = for 1x1 units, false = for 2x2 units. vanilla
allowsStrafing Does this armor allow strafing? Defaults are: true = for 1x1 units, false = for 2x2 units. vanilla
allowsKneeling Does this armor allow kneeling? Defaults are: true = for xcom soldiers, false = for xcom vehicles, aliens and civilians. vanilla
allowsMoving Does this armor allow moving? true
allowTwoMainWeapons During autoequip (e.g. when equipping built-in armor weapons), allow 2 main weapons. Only applies to XCOM, aliens and civilians have it allowed by default. false
instantWoundRecovery Should the health of a unit with this armor be automatically set back to maximum after the battle is over?

Note: used for example for vehicles implemented as soldier types (so that they can gain experience too).

false
standHeight Overrides the unit's/soldier's normal standHeight when wearing this armor. -1
kneelHeight Overrides the unit's/soldier's normal kneelHeight when wearing this armor. -1
floatHeight Overrides the unit's/soldier's normal floatHeight when wearing this armor. -1
fearImmune Is this unit immune to morale loss (and psiVision)? Defaults are: false = for 1x1 units, true = for 2x2 units. vanilla
bleedImmune Is this unit immune to bleeding? Defaults are: false = for 1x1 xcom soldiers, true = for everything else.

Note: game option alienBleeding affects the defaults too.

vanilla
painImmune Is this unit immune to stun damage? Defaults are: false = for 1x1 units, true = for 2x2 units.

Note: weapons can be modded to ignore this immunity (by default all weapons with damageType=6 (stun) will ignore it).

vanilla
zombiImmune Is this unit immune to "zombification"? Defaults are: false = for 1x1 units, true = for 2x2 units.

Note: this setting works for 1x1 units only; save your time and don't try changing it for 2x2 units.

vanilla
ignoresMeleeThreat Is this unit immune to CQC? Defaults are: false = for 1x1 units, true = for 2x2 units. <=
createsMeleeThreat Is this unit capable of CQC? Defaults are: false = for 2x2 units, true = for 1x1 units. <=
meleeDodgeBackPenalty Defines the penalty to unit's melee dodge ability (see meleeDodge) when attacked from behind. Defined as percentage, e.g. 0.7 = 70%.

Note: The full penalty applies from behind, from sides the penalty is adjusted accordingly. There is no penalty for frontal assault.

0.0

The following group of attributes has rather complicated definition (listed in a separate table just for convenience).

Value Description Default
psiDefence Formulae for psi defense value. vanilla
meleeDodge Formulae for melee dodge chance. 0
recovery.time Formulae for TU recovery at the beginning of a new turn.

Note: this and all attributes below are defined under parent attribute recovery and a child attribute (time, energy, morale, etc.)

vanilla
recovery.energy Formulae for Energy recovery at the beginning of a new turn. vanilla
recovery.morale Formulae for Morale recovery at the beginning of a new turn. 0
recovery.health Formulae for HP recovery at the beginning of a new turn. 0
recovery.stun Formulae for Stun Level recovery at the beginning of a new turn. vanilla
recovery.mana Formulae for mana recovery at the beginning of a new turn. 0
Easiest way to explain how the formulaes are defined is using examples: 
 armors:
   - type: STR_TEST_ARMOR_1
     meleeDodge:
       reactions: 0.2               # 20% of reactions
   - type: STR_TEST_ARMOR_2
     recovery:
       health:
         stunNormalized: -0.1       # -10% of normalized stun
       energy:
         flatHundred: 0.1           # 10% of 100 = 10 :)
         healthCurrent: 0.25        # 25% of current health

Armor 1 has melee dodge equal to 20% of soldier's reactions stat.

Armor 2 has negative HP recovery of 10% of soldier's normalized stun level (simulating slowly losing HP when in shock); and positive energy recovery of 10 + 25% of soldier's current health.

There are even more complicated examples with squared and cubed stats, see Items ruleset for some examples of that.

Possible keywords to use in the formulaes include:

  • flatOne, flatHundred, strength, psi, psiSkill, psiStrength, throwing, bravery, firing, health, tu, reactions, stamina, melee, strengthMelee, strengthThrowing, firingReactions, rank, fatalWounds, healthCurrent, tuCurrent, energyCurrent, moraleCurrent, stunCurrent, healthNormalized, tuNormalized, energyNormalized, moraleNormalized, stunNormalized, energyRegen, mana, manaCurrent, manaNormalized

FIXME: describe what each keyword means

Player Units (Soldiers)

Defines a soldier recruited by X-COM, listed in "soldiers:".

Unit stats are represented as follows:

Value Description Default
type String ID of the soldier type. required
requires List of topics (string IDs) that must be researched to unlock this soldier type. If none are specified, this soldier type is unlocked from the start. -
requiresBuyBaseFunc A list of services (for a given base) required to be able to hire this soldier type. -
minStats Minimum values used to generate the soldier's Starting Stats. In this case, psiSkill is treated as the initial stat (not generated). -
maxStats Maximum values used to generate the soldier's Starting Stats. In this case, psiSkill is treated as the minimum value for the first month of psi training (actual value is 100%-150%). -
statCaps Maximum stats this soldier can gain through Experience. NOTE: A stat will still go over the limit once, and then will no longer increase (see Regarding Caps). -
trainingStatCaps Maximum stats this soldier can gain through combat/martial training in the base. statCaps
dogfightExperience A list of probabilities (0-100%) to improve a stat (only bravery, firing or reactions) after a successful Dogfight. 
 - type: STR_SOLDIER
   dogfightExperience:
     bravery: 20   # 20% chance of improvement by 10
     reactions: 50 # 50% chance to improve by 1
     firing: 100   # guaranteed to improve by 1
-
armor String ID of the armor this soldier uses by default. -
armorForAvatar When avatar display is activated in the Battlescape UI (instead of rank display)... which armor should the unit be wearing?

Note: things like Power/Flying Armor don't show the soldier's face, so you'd want to use Jumpsuits or Personal Armor.

-
avatarOffsetX Horizontal offset (in pixels) in the inventory sprite used for avatar display. 67
avatarOffsetY Vertical offset (in pixels) in the inventory sprite used for avatar display. 48
flagOffset Offset in the flag sprite collection to use for this soldier type.

Note: OXCE supports flag display per "nationality" (or better said per name pool file).

0
allowPromotion Does this soldier type support promotion? Hint: combat dogs don't need a military hierarchy :) true
allowPiloting Is this soldier type capable of piloting a craft? Sorry, no doggies piloting a Skyranger. true
costBuy Amount of money spent for hiring this soldier type. If set to 0, the soldier type will not be available in the Purchase/Recruit screen. 0
costSalary Amount of money spent monthly for employing this soldier type. 0
costSalarySquaddie Bonus to a salary for a Squaddie. 0
costSalarySergeant Bonus to a salary for a Sergeant. 0
costSalaryCaptain Bonus to a salary for a Captain. 0
costSalaryColonel Bonus to a salary for a Colonel. 0
costSalaryCommander Bonus to a salary for a Commander. 0
standHeight Height of this soldier when standing. 0
kneelHeight Height of this soldier when kneeling. 0
floatHeight Distance between the bottom of this unit and the ground. 0
femaleFrequency The probability that a female soldier is hired. 50
value The soldier's base value, without experience modifiers. Used for scoring in Debriefing. 20
transferTime The amount of time (in hours) it takes for new recruits of this soldier type to arrive at a base. If 0, global personnel transfer time is used instead. 0
moraleLossWhenKilled Percentage modifier for morale loss when this unit is killed.

Hint: set 0% for xcom security cameras and 500% for doggies.

100
deathMale Death sound(s) for male soldiers. Either a single sound ID or a list of sound IDs from BATTLE.CAT. -
deathFemale Death sound(s) for female soldiers. Either a single sound ID or a list of sound IDs from BATTLE.CAT. -
selectUnitMale/selectUnitFemale Sound ID from BATTLE.CAT played when this soldier is manually selected. A list of sound IDs can be used too. -
startMovingMale/startMovingFemale Sound ID from BATTLE.CAT played when this soldier starts moving. A list of sound IDs can be used too. -
selectWeaponMale/selectWeaponFemale Sound ID from BATTLE.CAT played when this soldier's weapon is selected. A list of sound IDs can be used too. -
annoyedMale/annoyedFemale Sound ID from BATTLE.CAT played when this soldier is repeatedly manually selected. A list of sound IDs can be used too. -
panicMale Panic sound(s) for male soldiers. Either a single sound ID or a list of sound IDs from BATTLE.CAT. -
panicFemale Panic sound(s) for female soldiers. Either a single sound ID or a list of sound IDs from BATTLE.CAT. -
berserkMale Berserk sound(s) for male soldiers. Either a single sound ID or a list of sound IDs from BATTLE.CAT. -
berserkFemale Berserk sound(s) for female soldiers. Either a single sound ID or a list of sound IDs from BATTLE.CAT. -
soldierNames List of soldier name files/paths. Use delete to clear previously-loaded names. -
statStrings Override of global stat strings for this soldier type. -
rankStrings Override for classic xcom ranks. You can have for example only Rookies and Veterans for a certain soldier type. -
rankSprite Offset for rank sprites for this soldier type in BASEBITS.PCK 42
rankBattleSprite Offset for rank sprites for this soldier type in SMOKE.PCK 20
rankTinySprite Offset for rank sprites for this soldier type in TinyRanks 0
skillIconSprite Sprite ID from SPICONS.DAT used to draw the soldier skills icon. 1
skills A list of soldier skills.

More info: https://openxcom.org/forum/index.php/topic,7974.0.html

-
showTypeInInventory If set to true, the soldier type will be displayed in the inventory screen. false
specialWeapon Allows to define a special weapon on the soldier type (instead of the armor type).

More info: https://openxcom.org/forum/index.php/topic,7859.0.html

-

Soldier Transformation

Defines rules for soldier transformations, listed in "soldierTransformation:".

Allows doing things like:

  • transforming soldiers into MECs
  • resurrecting/cloning dead soldiers... useful for streamers/LPers, who want to easily maintain viewer's names
  • assigning soldier bonuses
  • and much more...

More info: https://openxcom.org/forum/index.php/topic,6331.0.html

Value Description Default
name String ID of the soldier transformation type. required
requires A list of research projects required before this project appears in the list of available transformations, the default empty list means this project is available from the beginning of the game. -
requiresBaseFunc A list of services required at a base in order to do this project, the default empty list means no special services are required. -
producedItem The item a soldier should be transformed into. The soldier is completely removed from the game.

Modding tips: sacrifices for special resources/weapons, transform specialists into resources needed to build special facilities, etc.

-
producedSoldierType The type of soldier produced by this project - any soldier undergoing this transformation will be switched to this type. If left empty, the soldier type does not change. -
producedSoldierArmor The armor the soldier will have when the project finishes, only used when keepSoldierArmor is false. Leaving it empty will give the soldier the default armor for the correspondiing soldier type. -
keepSoldierArmor Determines whether or not the soldier will keep the armor they're wearing through this transformation. false
createsClone Determines whether the selected soldier has the transformation done to them or a new soldier is created that is a copy of the original and the transformation is done to the new soldier. false
needsCorpseRecovered If your project allows dead soldiers, this determines whether or not you needed to have a corpse item available at the end of the battle in which the soldier died. This does not mean you need the corpse item in your stores, just that it would have been recovered if recover: true was set on the item. true
allowsDeadSoldiers Can dead soldiers undergo this transformation? If so, they are brought back to life at the base you started this project in. false
allowsLiveSoldiers Can live, non-wounded soldiers undergo this transformation? false
allowsWoundedSoldiers Can wounded soldiers undergo this transformation? false
allowedSoldierTypes This list determines which soldier types can undergo this transformation, the default empty list means nobody can have this project done to them. required
requiredPreviousTransformations A list of transformation projects that must be done to a soldier before they're eligible for this project, the default empty list means no previous projects are required. -
forbiddenPreviousTransformations A list of transformation projects that a soldier cannot have undergone in order to be eligible for this project, the default empty list means no previous projects are forbidden. -
minRank The minimum rank a soldier must have in order to be eligible for this project, from 0=rookie to 5=commander. 0
includeBonusesForMinStats If set to true, soldier bonuses will be included when comparing soldier stats against requiredMinStats. false
requiredMinStats The minimum stats a soldier must have in order to be eligible for this project, defaults to all 0 so any soldier is eligible. -
requiredItems A list of items that must be consumed from the base's stores in which you start this project, the default empty list means no items are used. -
requiredCommendations A list of commendations (with a minimum decoration level) required to start this project. The default empty list means no commendations are required.

Example: https://openxcom.org/forum/index.php/topic,7405.msg117870.html#msg117870

-
cost The cost of the project in dollars. 0
transferTime Soldiers can be put in a transfer back to the base where they started if this parameter is greater than the default of 0 hours. New clones or resurrected soldiers are automatically given a transfer to the base with a default of 24 hours. 0
recoveryTime The amount of wound recovery time a soldier is given after this project completes and the transfer, if any, is completed. The default value is 0 days. 0
flatOverallStatChange A direct change to the soldier's overall stats when undergoing this project, can be positive or negative - tu: 5 means the soldier will gain 5 max time units, while tu: -5 means the soldier will lose 5 max time units. The default of 0 means no change. -
flatMin

flatMax

Similar to flatOverallStatChange, but allows to specify a range from which the game chooses randomly.

More info: https://openxcom.org/forum/index.php/topic,7196.msg117768.html#msg117768

-
percentOverallStatChange A percent change to the soldier's overall stats when undergoing this project, can be positive or negative - tu: 5 means the soldier will gain an extra 5% of their max time units, while tu: -5 means the soldier will lose 5% of their max time units. The default of 0 means no change. -
percentMin

percentMax

Similar to percentOverallStatChange, but allows to specify a range from which the game chooses randomly. -
percentGainedStatChange A percent change to the soldier's stats, but instead of taking a portion of the overall stats, this only applies to the stats they've trained up from their initial values, can be positive or negative - firing: -100 means the soldier will lose all of the firing accuracy they trained since joining, while firing: 10 means they gain 10% of the amount they trained over their initial values. The default of 0 means no change. -
percentGainedMin

percentGainedMax

Similar to percentGainedStatChange, but allows to specify a range from which the game chooses randomly. -
showMinMax If enabled, the GUI will show random improvement as min/max range. If disabled, it will show just a question mark. false
rerollStats This attribute allows you to specify, which stats should be completely re-rolled.

More info: https://openxcom.org/forum/index.php/topic,7196.msg117767.html#msg117767

false
lowerBoundAtMinStats Determines whether or not any changes in stats from this project should go below the minStats defined on the new soldier type. true
upperBoundAtMaxStats Determines whether or not any changes in stats from this project should go above the maxStats defined on the new soldier type. false
upperBoundAtStatCaps Determines whether or not any changes in stats from this project should go above the statCaps defined on the new soldier type. false
upperBoundType Determines how strictly to apply upperBoundAtMaxStats and upperBoundAtStatCaps. Possible values:
  • 0 = dynamic (i.e. soft when not changing the soldier type; hard when changing the soldier type)
  • 1 = soft (if the soldier is already above the maximum before the transformation, don't reduce his overflown stats)
  • 2 = hard (always reduce if above the maximum)
 0


reset The reset flag can be used to clear the bonuses gained by previous transformations. It also clears the list of previously performed transformations.

For example: 1. you train karate and gain a bonus 2. then you transform the guy into a MEC and want to lose all the previous bonuses (since MECs can't benefit from karate training... I hope)

Note: stats gained by "classic" transformations (i.e. those that are NOT bonuses) will NOT be reset; only bonuses can be reset

false
soldierBonusType ID of a soldier bonus applied to a soldier undergoing this transformation. -

Soldier Bonuses

Defines rules for soldier bonuses, listed in "soldierBonuses:".

Bonuses can be manually awarded by the player via soldier transformations; or automatically awarded together with a soldier commendations/medals.

More info: https://openxcom.org/forum/index.php/topic,7405.0.html

Value Description Default
name String ID of the soldier bonus type. required
visibilityAtDark Defines the bonus to night vision (in tiles). Cannot go beyond global maximum view distance. 0
stats Defines the bonus to soldier's stats (same way as the armor can). Can go even beyond any cap/maximum. -
recovery Defines the bonus to soldier's resource recovery every turn (same way as the armor can). Affects time units, energy, health, stun, morale and mana. -

Soldier Skillls

Defines rules for soldier skills, listed in "skills:".

More info: https://openxcom.org/forum/index.php/topic,7974.0.html

Value Description Default
type String ID of the soldier skill type. required
targetMode Target mode for the skill. Possible options:
  • 0 = No target needed (just activation, script takes over) - BA_NONE
  • 10 = Melee-range targeting (1 tile) - BA_HIT
  • 7,8,9 = Firearm ranged targeting - BA_AUTO = 7, BA_SNAP = 8, BA_AIMED = 9
  • 11,13,14 = Psi targeting (with or without LOS) - BA_USE = 11, BA_MINDCONTROL = 13, BA_PANIC = 14
  • 6 = Thrown targeting - BA_THROW
  • 12 = Waypoint targeting - BA_LAUNCH
 0
isPsiRequired Is Psi Skill required for this skill to work? false
requiredBonuses Defines the list of required soldier bonuses for this skill. -
costUse Defines the use cost for this skill. -
flatUse Defines the flat vs. percentage cost flags for the use cost of this skill. -
compatibleWeapons Defines the list of weapons which are compatible with this skill. -
checkHandsOnly Should the check for compatible items only consider the hands (or also the inventory and specialweapon)? true
battleType Defines the battle type of compatible items (0-11). E.g. 1=firearm, 3=melee weapon, 9=psiamp, etc.

This is used as fall-back if no compatibleWeapons are specified or found.

-

Soldier Commendations

FIXME Someone please document this...

In OXCE, you can also use soldier commendations to assign soldier bonuses (see above). Bonuses are defined per decoration level. You don't need to define all decoration levels... if a soldier has a higher decoration level than defined, the highest available is used.

More info: https://openxcom.org/forum/index.php/topic,7405.msg116840.html#msg116840

Example: 

 commendations:
   - type: STR_MEDAL_ALIENS_KILLED
     description: STR_MEDAL_ALIENS_KILLED_DESCRIPTION
     sprite: 1
     soldierBonusTypes: [STR_KILL1, STR_KILL2, STR_KILL3, STR_KILL4]           # various bonuses for various decoration levels
     criteria:
       killsWithCriteriaCareer: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
     killCriteria:
       -
         - [1, ["STATUS_DEAD", "FACTION_HOSTILE"]]

AI Units (Aliens/Civilians)

Defines an alien (enemy) or civilian (neutral) unit, listed in "units:". Every different alien rank is a different unit, since they have completely different stats. Unit stats are represented as follows:

Value Description Default
type String ID of the unit name. required
race String ID of the unit race (for alien units). -
rank String ID of the unit rank (for alien units). -
spotter The spotter score. Determines how many turns sniper AI units can act on this unit seeing your troops. 0
sniper The sniper score. Determines the chances of firing from out of LOS on spotted units. 0
stats Battlescape stats of this unit. -
armor String ID of the armor this unit uses by default. -
standHeight Height of this unit when standing. 0
kneelHeight Height of this unit when kneeling. Not supported in OpenXcom yet, for future use? 0
floatHeight Distance between the bottom of this unit and the ground. 0
value Score this unit is worth. 0
civilianRecoveryType Gets the type of staff (soldier/engineer/scientists) or type of item to be recovered when a civilian is saved. -
intelligence Intelligence of this unit's AI. The higher the value, the longer this unit remembers player troops between turns. 0
waitIfOutsideWeaponRange Should the unit get "stuck" trying to fire from outside of weapon range? OXC bug, that may serve as "feature" in rare cases.

Note: the default value is to fix the OXC bug.

false
canSurrender Can this unit surrender? false
autoSurrender Does this unit surrender automatically, if all other units surrendered too? false
aggression Aggression of this unit's AI. The higher the value, the more ruthless the unit, the more likely to make a frontal/melee assault. Less aggressive units tend to set up ambushes.

Possible values are:

  • 0 = mostly passive
  • 1 = balanced
  • 2+ = mostly aggressive (meaningful values are between 2 and 8)
 0
isLeeroyJenkins Unit marked as "leeroy" must have a melee weapon (and be able to use it). It will completely ignore vanilla AI "decision making" and run around (using vanilla patrol routine) until it spots someone and then charge at the nearest target (if multiple spotted).

Charge is mostly vanilla/OXCE, with the following differences:

  • ignore remaining TUs (charge even if not enough TUs to attack now)
  • ignore dangerous tiles (grenades? pfff!)
  • ignore OXCE melee dodge (leeroy is not intelligent enough to attack from behind)
 false
energyRecovery Energy recovered by the unit each turn. 30
specab Special ability of this unit: 0
spawnUnit String ID of the unit used to respawn on death (e.g. Zombies respawn as Chrysallids). -
livingWeapon Is this unit a living weapon?

If yes, it ignores any weapon loadout associated with its rank in the alien deployment and only attacks with a weapon derived from its name (must be marked as fixedWeapon). The weapon's name is the unit's type without the first 4 letters (STR_) and with a suffix (_WEAPON). For example: STR_REAPER => REAPER_WEAPON.

false
meleeWeapon This unit's built-in melee weapon (e.g. Lobsterman's Claws). Does not appear in the inventory. -
psiWeapon This unit's built-in psi weapon. Ignored if the unit doesn't have any psi skill. Does not appear in the inventory. ALIEN_PSI_WEAPON
capturable Can this unit be captured alive?

Note: units which cannot be captured alive are insta-killed when they fall unconscious.

true
builtInWeaponSets A set of lists of weapons this unit can come pre-equipped with. Game will pick one set "at random" (randomness comes from the current alien tech level definition). These weapons WILL appear in inventory slots (references items). -
builtInWeapons Deprecated: use builtInWeaponSets instead. -
moraleLossWhenKilled Percentage modifier for morale loss when this unit is killed.

Tip: set for example 50% for cannon fodder and 300% for VIPs.

100
deathSound Sound ID from BATTLE.CAT played when this unit dies. No value means no sound upon death. A list of sound IDs can be used too, the game then chooses one randomly each time. -
selectUnitSound Sound ID from BATTLE.CAT played when this unit is manually selected. A list of sound IDs can be used too. -
startMovingSound Sound ID from BATTLE.CAT played when this unit starts moving. A list of sound IDs can be used too. -
selectWeaponSound Sound ID from BATTLE.CAT played when this unit's weapon is selected. A list of sound IDs can be used too. -
annoyedSound Sound ID from BATTLE.CAT played when this unit is repeatedly manually selected. A list of sound IDs can be used too. -
panicSound Sound ID from BATTLE.CAT played when this unit panics. A list of sound IDs can be used too. -
berserkSound Sound ID from BATTLE.CAT played when this unit berserks. A list of sound IDs can be used too. -
aggroSound Sound ID from BATTLE.CAT played when this unit aggros. -1
moveSound Sound ID from BATTLE.CAT played when this unit moves. -1
showFullNameInAlienInventory Defines whether the [Alien Inventory] screen (accessible via middle-click on a unit) should display a unit's type/name or just a unit's race.

Possible options:

  • -1 = use global setting (show the race by default)
  • 0 = show the race (e.g. Sectoid)
  • 1 = show the type (e.g. Sectoid Leader)
 -1
pickUpWeaponsMoreActively Allows AI to pick up weapons more actively. More info: https://openxcom.org/forum/index.php/topic,6882.0.html

Possible options:

  • -1 = use global setting (disabled by default)
  • 0 = disabled
  • 1 = enabled
 -1

Alien Races

Defines a race used in Alien Missions, listed in "alienRaces:". Heavily tied with deployment data.

Value Description Default
id String ID of the alien race name. required
members Alien crew associated with this alien race (e.g. race units + terrorist units), defined by a list of unit string IDs. Order here will define rank in terms of deployment. Generally speaking the order is:
  • 0 - Commander
  • 1 - Leader
  • 2 - Engineer
  • 3 - Medic
  • 4 - Navigator
  • 5 - Soldier
  • 6 - Terrorist 1
  • 7 - Terrorist 2

but of course, not all races have all ranks, so the "fill in" rank would be listed multiple times (see Ethereals).

-
membersRandom Alternative to members. Instead of defining just a single unit type per alien rank, you can define any number of unit types here and one will be chosen randomly (each time a new unit is generated). To increase a chance of a certain unit type being selected, you can add it multiple times. -
retaliationMission String ID of an alien mission, that can be generated after a dogfight against this race. If empty, a random retaliation mission will be used instead. -
retaliationAggression A flat percentage to modify the dogfight retaliation odds for this race. Positive value increases odds, negative value decreases odds.

Example: Normal retaliation odds for Veteran difficulty (in UFO) are 12%. If this number is set to 20, the odds will increase to 32%.

0
baseCustomMission String ID of an alien deployment (not alien mission!!) override for all alien bases inhabited by this alien race.

Applies to:

  • all starting condition checks
  • additional mission description, see alertDescription
  • everything done during the Battlescape generation
  • everything done during the Debriefing

Does not apply to anything else (that depends on alien deployment), for example:

  • alien base supply mission
  • alien base hunt missions
  • alien base upgrades
  • etc.
 -
baseCustomDeploy A lighter version of baseCustomMission, which only overrides the deployment data used during the Battlescape generation.

Note: if both baseCustomMission and baseCustomDeploy are specified, deployment data is taken from baseCustomDeploy and everything else is taken from baseCustomMission.

-

Alien Deployments

Defines a Battlescape deployment data used in Alien Missions (such as alien and map configurations), listed in "alienDeployments:".

Value Description Default
type String ID of the deployment name. required
isHidden If enabled, the mission will not appear in the mission list in New Battle GUI. Doesn't work when debug is enabled in options.cfg. false
customUfo String ID of a UFO to be used in mapscripts in addUFO command. This allows to reuse the same script for many deployments.

More info: https://openxcom.org/forum/index.php/topic,7631.0.html

-
startingCondition String ID of a starting condition for missions using this deployment.

Note: overrides any globe texture starting condition.

-
enviroEffects String ID of enviro effects for missions using this deployment.

Note: overrides any mission terrain enviro effects.

-
data List of deployment data for each alien rank on this mission (see below). -
width Width of the Battlescape map in grid units. 0
length Length of the Battlescape map in grid units. 0
height Vertical height of the Battlescape map in grid units. 0
civilians Maximum number of civilians to spawn. The actual number of civilians spawned will be between 50-100% of the specified maximum. 0
civilianSpawnNodeRank Map node rank to spawn civilians on.

More info: https://openxcom.org/forum/index.php/topic,6477.0.html

0
civiliansByType A list of additional civilians to spawn, each list item is defined by a civilian type ID and a maximum number (type: number). The actual number of civilians spawned will be again between 50-100% of the specified maximum, but this time the 50% is rounded up (for civilians attribute it is rounded down). -
terrains List of string IDs of the terrains to choose from when generating the map. Not used for UFO land/crash sites, terrain comes from the Geoscape globe texture. -
shade Shade of the map (0-15, where 0 is full daytime and 15 is full nighttime). If not specified (e.g. for UFO land/crash sites), the shade comes from the Geoscape globe. -1
minShade Minimum shade of the map (0-15). Used only when shade is not set, to adjust the shade coming from the Geoscape globe. -1
maxShade Maximum shade of the map (0-15). Used only when shade is not set, to adjust the shade coming from the Geoscape globe. -1
nextStage String ID of the next deployment stage to use after this one, for multi-stage missions. -
race Sets (overrides) the alien race to use when generating the map. -
randomRace Sets (overrides) the alien race to use when generating the map. Unlike race attribute, this is a list of multiple possible races; one is chosen randomly at runtime. -
finalDestination Sets whether this mission is where you send your uber-craft to win the game. false
winCutscene Sets the cutscene to play when you win the mission. If set to "winGame" or "loseGame", the player will be returned to the main menu after the cutscene plays. -
loseCutscene Sets the cutscene to play when you lose the mission. If set to "winGame" or "loseGame", the player will be returned to the main menu after the cutscene plays. -
abortCutscene Sets the cutscene to play when you abort the mission. If set to "winGame" or "loseGame", the player will be returned to the main menu after the cutscene plays. -
script Map script used to generate the map (overrides the map script from terrain definition). -
alert String ID of the message to display in the alert popup when this mission spawns on the Geoscape. STR_ALIENS_TERRORISE
alertBackground String ID of the background image to use in the alert popup when this mission spawns on the Geoscape. BACK03.SCR
alertDescription String ID of the additional mission description (displayed when clicking on the [Info] button on the [Target Info] screen). -
alertSound Sound ID from GEO.CAT to be played when the [Mission Detected] screen pops up. -1
briefing Data for the mission briefing (see below). -
markerName String ID that identifies this mission type on the Geoscape. STR_TERROR_SITE
markerIcon What icon should be used to represent this base/site (taken from GlobeMarkers section in extraSprites) -1
depth [min, max] -- Defines the depth range to randomly choose from for this mission. [0, 0]
duration [min, max] -- Minimum and maximum duration of this mission on the Geoscape (in hours).

Important: mission duration should be at least 2 hours... if it's just 1 hour and it spawns at the whole hour, it also despawns at the same moment... and crashes the game!

[0, 0]
music The list of musics this mission can choose from (if not specified, the music is taken from the terrain). -
points Negative score applied for each day this mission is active (applied daily for bases, or every half hour for mission sites) 0
unlockedResearch String ID of a research topic that will be granted for free (only if the mission is finished successfully).

Note: there will be no Ufopaedia article shown nor any other related effect; the research will just be silently added into the list of finished research projects.

-
missionBountyItem String ID of an item that will be added to base stores for free (only if the mission is finished successfully).

Note: the player will be informed in the Debriefing screen.

-
bughuntMinTurn Possibility to override global bug hunt minimum turn for this alien deployment only (usually to set a higher number for longer missions). 0 (no change)

The following group of attributes is related only to alien bases (listed in a separate table just for convenience).

Value Description Default
alienBase Does this deployment correspond to an alien base assault? Used only in New Battle mode. false
genMission Which alien mission should this base generate?

Usually supply mission - can be used to generate any mission type except Mission Sites (UFO will be generated, but the site will never appear)

-
genMissionFreq Daily chance for the base mission to be generated. 0
genMissionLimit Maximum number of times the genMission can be generated. 1000
baseSelfDestructCode Discovering this research topic destroys all corresponding alien bases immediately. -
baseDetectionRange Radar detection range (in nautical miles) for an alien base. If more than 0, the base actively scans for xcom craft and generates xcom craft hunt missions. 0
baseDetectionChance Chance (0-100%) of the base radar detecting a craft that enters its range. 100
huntMissionMaxFrequency The maximum frequency (in minutes) of hunt missions generated by an alien base. 60
huntMissionWeights A weighted list of hunt missions a base can generate, listed by "number of months passed". -
alienBaseUpgrades A weighted list of alien base upgrades, listed by "number of months passed". -
fakeUnderwaterSpawnChance Chance (in percent) for the alien base to spawn on "fake underwater" globe texture. 0

The following group of attributes is related to mission objectives (listed in a separate table just for convenience).

Value Description Default
allowObjectiveRecovery Can map objects of type defined by objectiveType be recovered or not? false
objectiveType Defines which type of MCD to check for when tallying mission objectives. -1
objectivesRequired How many of the tile types (defined in objectiveType) must be destroyed in order for the mission to be considered a success. 0
objectivePopup Defines the message that will appear between turns, after the objective requirements have been fulfilled. -
objectiveComplete The string and score adjustment to be shown on the mission debriefing. [-, 0]
objectiveFailed The string and score adjustment to be shown on the mission debriefing. [-, 0]
despawnPenalty How many points the aliens will receive when this site despawns due to XCom negligence. 0
abortPenalty How many points the xcom will lose when this mission is aborted. 0
cheatTurn When the aliens became aware of all your units (in vanilla it was after turn 20) 20
turnLimit The amount of turns before the mission ends automatically. 0 (no limit)
chronoTrigger What happens when the timer reaches 0. Possible values:
  • 0 = Lose
  • 1 = Abort
  • 2 = Win
  • 3 = Win + all enemies surrender
 0
escapeType Which type of tiles can be used for escape. Possible values:
  • 0 = None
  • 1 = Exit tiles
  • 2 = Entry tiles
  • 3 = Either
 0
keepCraftAfterFailedMission Defines whether the craft should be lost after a failed mission or not. Useful for example for timed missions where the craft doesn't wait for you (e.g. escape/extraction missions). false

Notes:

  • turnLimit is used to define the turn where the game ends, default is 0 (no limit). If the value is changed from default then the game will display the number of turns on the 'Hidden Movement' screens as '1/20', '2/20', etc., and the numbers will switch to red when there's less than 3 turns remaining.
  • chronoTrigger is used with turnLimit and defines what happens when the turn limit is reached. There are 3 possible settings:
    • 0 (default) = forces a Loss, meaning that the player loses everything if the mission isn't completed by the time the turn limit is reached. All units are declared dead or MIA when the game ends. This is ideal for bomb defusal type missions.
    • 1 = forces a Abort, this is almost the same as above, with the exception that there must be at least 1 soldier on an exit-only area (like the green room on the 1st stage of Cydonia) to win at the end of the turn limit. This setting is better used for multi-stage missions where you'll need to bring at least 1 soldier to the next stage.
    • 2 = forces a Win, where if you have at least 1 live unit at the end of the turn limit you'll win the mission, regardless of where the soldiers are. This is meant for Survival scenarios.
    • 3 = forces a Win, same way as in option 2, but additionally all remaining enemies surrender.
    • Regardless of the setting, the player can always still win by eliminating all alien units before the turn limit, or fail the mission by losing all units.
  • cheatTurn allows to define the turn where the AI becomes aware of all your units (default is 20) for individual missions. Once this turn is reached the aliens will be forced to go into attack mode and engage your units. This is effectively a cheat for the AI which was present on the original game.

Deployment Data

Value Description Default
alienRank Rank associated with this deployment data, as defined by the order of the race in question (see above) required
lowQty Minimum quantity of aliens to spawn on beginner/experienced. required
highQty Minimum quantity of aliens to spawn on superhuman. (minimum quantity for veteran/genius is the median of this and the previous value) required
dQty Delta in Quantity, i.e. random number of aliens to spawn on top of the minimum (all difficulties). required
extraQty Functionally identical to dQty, spawns a random number of additional aliens. 0
percentageOutsideUfo Percentage (0-100%) of aliens to spawn outside of the UFO (in UFO land/crash sites). required
itemSets Three lists (one for each alien technology level) of items (string IDs) for the aliens to equip. required
extraRandomItems One or more item lists with extra equipment. One item will be chosen from each list randomly.

More info: https://openxcom.org/forum/index.php/topic,7055.msg111746.html#msg111746

-

Briefing Data

Value Description Default
palette The color swatch to use from BACKPALS.DAT. 0
textOffset Number of pixels to vertically offset the briefing text. Larger values move the text further down the screen. 0
title String ID for a custom briefing title text. Defaults to the same name as the alienDeployment. -
desc String ID for a custom briefing description text. Defaults to the same name as the alienDeployment + _BRIEFING. -
music The ID of the music to play. GMDEFEND
cutscene Sets the cutscene to play before the mission briefing. -
background The background screen to show. BACK16.SCR
showCraft Whether to show the name of craft that arrived at the mission site. true
showTarget Whether to display the mission target name. true

Battle Starting Conditions

Defines various pre-conditions and limitations applied before a certain Battlescape mission, listed in "startingConditions:".

Starting conditions can be defined on alien deployments only (not on terrains):

Value Description Default
type String ID of the starting condition. required
defaultArmor If a soldier's armor is not permitted on a mission (see allowedArmors and forbiddenArmors below), it will be replaced by a default armor. Default armor is defined for each soldier type separately as a weighted list of possible armor replacements. There is also a special armor ID "noChange" representing no change needed (i.e. giving you a chance to keep the original armor even if it is not allowed... don't ask me why, ask modders!) -
allowedArmors forbiddenArmors A list of allowed/forbidden armors for a mission. Only one of these two attributes can be used. -
allowedVehicles forbiddenVehicles A list of allowed/forbidden vehicles (HWP/SWS) for a mission. Not permitted vehicles will stay at the base. Only one of these two attributes can be used. -
allowedItems forbiddenItems A list of allowed/forbidden items (weapons, equipment, etc.) for a mission. Not permitted items will stay at the base. Only one of these two attributes can be used. -
allowedItemCategories forbiddenItemCategories A list of allowed/forbidden item categories (categories are freely definable by modders) for a mission. This is used to simplify/shorten the definition of allowed/forbidden items. Only one of these two attributes can be used. -
allowedCraft forbiddenCraft A list of allowed/forbidden craft for a mission. Not permitted craft cannot target the mission destination at all. Only one of these two attributes can be used. -
allowedSoldierTypes forbiddenSoldierTypes A list of allowed/forbidden soldier types for a mission. If there are any not permitted soldier types onboard a craft, it won't be able to target the mission destination at all. Only one of these two attributes can be used. -
requiredItems A list of items (and their quantities) required for a mission (e.g. a skeleton key from EU2012). -
destroyRequiredItems Defines whether required items should be destroyed or not (when craft landing is confirmed). false

Battle Enviro Effects

Defines various effects applied during a certain Battlescape mission, listed in "enviroEffects:".

Enviro effects can be defined on alien deployments and on terrains. If both are defined, deployment's enviro effects will be used.

Value Description Default
type String ID of the enviro effects. required
paletteTransformations A list of palette transformations (oldPaletteName: newPaletteName) to apply during the mission (or mission stage). New palettes should be similar to original palettes, they should only convey visual effects like pollution, underwater environment, etc. For UFO-based mods only one palette (PAL_BATTLESCAPE) needs to be changed, for TFTD-based mods up to 4 palettes (for each depth). -
environmentalConditions A set of environmental conditions (one for each faction: STR_FRIENDLY, STR_HOSTILE or STR_NEUTRAL), see below. Environmental conditions define a special effect applied to each unit of a given faction at the beginning of their turn. This can be for example damage in toxic environment, stun in harsh environment, morale decrease in tough battles, etc.

Note: the player is informed about the effects applied on the [Next Turn] screen.

-
armorTransformations A list of armor transformations (oldArmorName: newArmorName) to apply during the mission (or mission stage). This can be only visual (e.g. replace helmetless armors with armors with a helmet when going underwater or in space) or also functional (effectively changing unit's stats and armor properties). The change is only temporary and reverted to original armor when the mission ends.

Note: if the armor is transformed, it is not checked if it is allowed or not and it is not replaced with default armor either.

-
mapBackgroundColor Possibility to change the color of the background outside of the map boundaries. Used for example to visually indicate the type of environment. 15
inventoryShockIndicator String ID of the shock indicator sprite (in the inventory). Used to override the global one, for example in normal environment it can indicate body shock, in underwater environment drowning and in space suffocating. -
mapShockIndicator String ID of the shock indicator sprite (on the map). Used to override the global one. -

Environmental Conditions

Value Description Default
globalChance Chance (0-100%) that this environmental condition will be turned on. Dice roll is performed only once, when the battle starts. 100
chancePerTurn Chance (0-100%) that a unit will be affected. Dice roll is performed each turn, for each unit separately. 0
firstTurn When should the environmental condition start affecting the units. XCOM units cannot be affected before their first turn (aliens and civilians can). 1
lastTurn When should the environmental condition stop affecting the units. 1000
message String ID of the message displayed on the [Next Turn] screen, explaining to the player what is happening. -
color Color (0-255) of the above message. 29
weaponOrAmmo The item (a weapon or ammo) that defines the actual effect. Compared to normal weapons, there are some limitations. See notes below. -
side The unit side where the effect is applied. Possible options:
  • -1 = random,
  • 0 = front
  • 1 = left
  • 2 = right
  • 3 = rear
  • 4 = under
 -1
bodyPart The unit body part where the effect is applied. Possible options:
  • -1 = random
  • 0 = head
  • 1 = torso
  • 2 = right arm
  • 3 = left arm
  • 4 = right leg
  • 5 = left leg
 -1

Note: there are limitations to what the effect can do, since we're not using a projectile and nobody is actually shooting

  • no power bonus based on shooting unit's stats (nobody is shooting, duh!)
  • no power range reduction (there is no projectile, range = 0)
  • no AOE damage from explosions (targets are damaged directly without affecting anyone/anything else)
  • no terrain damage
  • no self-destruct
  • no vanilla target morale loss when hurt; vanilla morale loss for fatal wounds still applies though
  • no setting target on fire (...could be added/implemented if needed)
  • no fire extinguisher

Custom Palettes

Defines custom 8bit palettes, listed in "customPalettes:".

These palettes can:

  • either globally override the default game palettes
  • or serve as additional palettes used only in certain situations (see paletteTransformations)
Value Description Default
type String ID of the custom palette. required
target String ID of the target palette:
  • for global palette replacement, use one of the game's default palette names:
    • UFO: BACKPALS.DAT, PAL_BASESCAPE, PAL_BATTLEPEDIA, PAL_BATTLESCAPE, PAL_GEOSCAPE, PAL_GRAPHS and PAL_UFOPAEDIA
    • TFTD: BACKPALS.DAT, PAL_BASESCAPE, PAL_BATTLESCAPE, PAL_BATTLESCAPE_1, PAL_BATTLESCAPE_2, PAL_BATTLESCAPE_3, PAL_GEOSCAPE and PAL_GRAPHS
  • for additional palettes, just use the same name as for type
 -
file Path to a file containing the palette definition, in JASC format. -
palette Alternative to file. You can specify the palette directly in the ruleset using a list of RGB values. Using this method, you don't have to specify all 256 colors; you can also use it to just change a few colors and leave the rest unchanged. -

Research

Defines a research topic that X-COM scientists can investigate, listed in "research:".

Value Description Default
name String ID of the research project's name. required
lookup String ID of the research project's display result (used when multiple projects give the same result, e.g. researching Sectoid Engineer and Sectoid Navigator both give the same live Sectoid info in the Ufopaedia). -
cutscene The name of the cutscene to play when this project is completed. If the cutscene is "wingame" or "losegame", the player is returned to the main menu after the cutscene plays. -
spawnedItem Item to be added to base stores, when the research is completed.

Tip: allows you to create unique items in limited quantities (e.g. special weapons, keys to special missions, etc.). Don't forget to inform the player in the pedia article!

-
cost Number of man-days (on average, the final time will be 50-150% this value) required to complete this project. 0
points Score earned for completing this project. 0
dependencies List of research projects that can unlock access to this one. If the full list is researched, or if one of the projects on the list "unlocks" this one, it becomes available. -
unlocks List of research projects unlocked, regardless of other dependencies, but not requirements, by completing this project (for example, any live alien unlocks "Alien Origins"). -
disables A list of research projects disabled by completing this project.

Notes:

  • this is one of the ways how to branch your "story", e.g. create alternative endings
  • it can also be used to hide obsolete stuff in the market, workshop, pedia, etc.
  • disabled topics cannot be re-enabled again, ever
 -
getOneFree List of "bonus" research projects that may be granted when completing this project. Examples: alien navigators (give random alien mission info), medics (give random alien interrogation or autopsy), engineers (give random UFO type info). -
getOneFreeProtected A list of additional "bonus" research projects that may be granted when completing this project. Each topic in the list is "protected" by another topic, which allows you finer control over when the player gets the bonus.

For example: you could divide the topics into early-game, mid-game and late-game and protect each group by some "gateway topic".

-
sequentialGetOneFree Should the topics from getOneFree and getOneFreeProtected be given randomly (false) or sequentially (true). false
requires List of research projects absolutely required before this project can be unlocked. For example, "The Martian Solution" will not even be considered for unlocking until AFTER "Alien Origins" is completed. -
requiresBaseFunc A list of services (for a given base) required to start this project. -
needItem Does this project require an item of the same name? false
destroyItem Will this item be destroyed (removed from stores) after research is finished? false
unlockFinalMission If true, this research topic allows to send a spacecraft to the final mission. false

Manufacture

Defines a manufacture project that X-COM engineers can produce, listed in "manufacture:".

Value Description Default
name String ID of the manufacturing project's name. required
category String ID of the manufacturing project's category.

Important: craft manufacturing projects MUST be defined in the STR_CRAFT category.

-
requires List of topics (string IDs) that must be researched to unlock this project. If none are specified, this project is unlocked from the start. -
requiresBaseFunc A list of services required (in the given base) to be able to start this project. -
space Amount of Workshop space required to begin this project. 0
time Number of man-hours required per production. 0
cost Monetary deduction per production. 0
refund Whether the resources needed for a project should be refunded when a project is cancelled before completion.

Notes:

  • if enabled, the STOP PRODUCTION button is replaced by a REFUND button
  • in case you didn't know: in vanilla, when you started a manufacture project (even with 0 engineers allocated and no time passed yet), all the resources were irrevocably gone
 false
requiredItems List of items required and consumed per production. -
producedItems List of items manufactured per production. If not specified, defaults to 1 item with the same string ID as the manufacture project. name: 1
randomProducedItems List of item sets with weights. One item set is chosen randomly for production.

More info: https://openxcom.org/forum/index.php/topic,6867.msg109423.html#msg109423

-
spawnedPersonType Allows to "manufacture" soldiers, scientists and engineers. More info here: https://openxcom.org/forum/index.php/topic,4187.msg78212.html#msg78212

Note: you can't use existing soldiers as "input" here, only items or prisoners. For transformation of existing soldiers (e.g. from normal humans to MECs), please use the Soldier Transformation functionality and ruleset.

-
spawnedPersonName When "manufacturing" a soldier, you can (optionally) specify also his/her name. -

Manufacture Shortcuts

Copies an existing manufacture project and allows break down of certain components into simpler components, listed in "manufactureShortcut:".
Value Description Default
name String ID of the new manufacturing project's name. required
startFrom String ID of the manufacturing project to copy. required
breakDownItems List of manufacture projects (string IDs) to break down. Break down is recursive (i.e. repeats until there is nothing more to break down). -
breakDownRequires Whether the research requirements should be broken down or not. false
breakDownRequiresBaseFunc Whether the base services requirements should be broken down or not. true

UFOpaedia Article

Defines an article in the in-game UFOpaedia, listed in "ufopaedia:".

Value Description Default
id String ID of the article name. This must match the ID of the object associated with this article, if applicable. required
title String ID of the article title. If omitted, the id is used. -
type_id Type of this article:

In OXCE, the TFTD-style articles can also be used in UFO-based mods.

required
section String ID of the UFOpaedia section this article belongs to. -
hiddenCommendation If set on a Commendation article (determined by section), the article will remain hidden until the corresponding commendation is awarded to at least one soldier. false
requires List of topics (string IDs) that must be researched to unlock this article. If none are specified, this article is unlocked from the start.

If using lootable weapons ('alien' weapons that can be used without research) needing a research to fully unlock, make sure to define it on both the weapon and ammo. Otherwise the damage reading is visible on the inventory screen using [ALT] on a clip.

-
image_id Filename of the background image displayed on this article, if applicable.

In OXCE:

  • This attribute can be used also for Vehicle articles
  • If the name contains a "_CPAL" suffix, its (custom) palette will be used instead of the default one. Relevant for Craft, CraftWeapon, TextImage and Vehicle (HWP) articles. More info here: https://openxcom.org/forum/index.php/topic,4957.0.html
 -
text String ID of the description displayed on this article.

In OXCE, you can use the {ALT} keyword to switch between primary and secondary color.

-
text_width Maximum width of the text displayed, only applicable to TextImage articles. EU (0), TFTD (157)
rect_stats Rectangle (x, y, width, height) of the stats text on the screen, only applicable to Craft articles. -
rect_text Rectangle (x, y, width, height) of the description text on the screen, only applicable to Craft articles.

In OXCE, it is also applicable to TextImage articles.

-
weapon String ID of the weapon, only applicable to Vehicle (HWP/SWS) articles. -
pages Configuration of additional pages for an article.
  • Each page can have its own title and text description.
  • Additionally, you can define which ammoSlot will be used to limit the display of supported attack types and compatible ammo.
  • If multiple pages have same value of ammoSlot, then each page will show successive group of 3 ammo items available for this slot.

Example: 

 - id: STR_PISTOL
   pages:
     - title: STR_PISTOL
       text: STR_PISTOL_UFOPEDIA
       ammoSlot: 0                  # default for all pages
     - title: STR_PISTOL
       text: STR_PISTOL_UFOPEDIA_2
       ammoSlot: 1                  # ammo and attack types relevant for the second ammo slot (0 = first slot)
     - title: STR_PISTOL_UFOPEDIA_TITLE_3
       text: STR_PISTOL_UFOPEDIA_3
Only one page using standard title and text.

UFO Trajectories

Defines a trajectory carried out by an UFO during an alien mission, listed in "ufoTrajectories:".

Value Description Default
id String ID of the trajectory name. required
groundTimer Amount of seconds for the UFO to spend on Ground waypoints. 5
waypoints List of items defining the waypoints and flight segments for the UFO to traverse, defined as [zone, altitude, speed].

zone: Regional missionZone index (used to randomly generate the waypoint's coordinates).
altitude: UFO altitude:

  • 0 - Ground
  • 1 - Very Low
  • 2 - Low
  • 3 - High
  • 4 - Very High

speed: UFO speed as a percentage (0-100%) of its maximum speed.

-

Each trajectory has X flight segments and X+1 waypoints... please pause reading here and think for a while why that is the case.

The best explanation how the flight segments and waypoints are encoded in the ruleset is done via an example: 

 waypoints:
   - [A, B, C]
   - [D, E, F]
   - [G, H, I]
   - [J, K, L]
   - [M, N, P]

This example can be interpreted as:

  1. go from zone A to zone D at altitude B and speed C
  2. go from zone D to zone D at altitude E and speed F
  3. go from zone D to zone G at altitude H and speed I
  4. go from zone G to zone J at altitude K and speed L
  5. go from zone J to zone M at altitude N and speed P

This example contains 5 flight segments (AD, DD, DG, GJ and JM) and 6 waypoints (A, D, D, G, J and M).

Please note especially the second line, where zone D is targeted AGAIN, this happens automatically/internally and always on the second line.

Also, if any altitude (B, E, H, K or N) would be zero (0 = Ground), the UFO would first wait landed in the start zone for some time before taking off to the destination zone (at altitude 1 = Very Low).

Alien Missions

Defines an alien mission carried out by UFOs on the Geoscape, listed in "alienMissions:".

Value Description Default
type String ID of the mission type. required
points Score allocated to aliens for successfully completing this mission. 0
waves List of UFO waves to spawn as this mission progresses, as described below. required
objective Missions are split by objective:
  • 0 = score (default if omitted)
  • 1 = infiltration
  • 2 = alien base
  • 3 = mission site (terror etc)
  • 4 = retaliation
  • 5 = supply
 0
spawnUfo UFO to spawn for retaliation. -
spawnZone Regional missionZone to use when spawning mission sites / alien bases. -1
missionWeights Only works for alien retaliation missions spawned during dogfights. If your mod has multiple possible retaliation missions, the game chooses one randomly, but considering weights defined in this attribute. The weights are defined as a list of (month: weight) pairs. If nothing is specified, weight is 1 (for all months). -
retaliationOdds Probability (0-100%) that a UFO shot down while performing this mission will generate a Retaliation mission. -1
endlessInfiltration Should an infiltration mission end after the first cycle (false) or continue indefinitely (true)? true
despawnEvenIfTargeted Should a mission site expire/despawn even if it is targeted by an xcom craft or not? false
interruptResearch Discovering this research topic interrupts the mission immediately. -
siteType Alien deployment to use when spawning mission sites / alien bases. If not specified, alienDeployment from Geoscape texture is used.

Note: for alien bases there is one more hardcoded fallback (STR_ALIEN_BASE_ASSAULT) if both deployments mentioned above are missing.

-
raceWeights List of alien races likely to carry out this mission, and the % chance of them being allocated to this mission, listed by "number of months after game beginning". required
operationType From where does this mission operate?

Possible options:

  • 0 = from space
  • 1 = from an existing alien base in the mission region
  • 2 = from a new alien base in the mission region
  • 3 = from a new alien base in the mission region if necessary, otherwise from an existing alien base
  • 4 = from an existing alien base anywhere on Earth
  • 5 = from a new alien base anywhere on Earth if necessary, otherwise from an existing alien base
  • 6 = a hunt mission spawned from an existing alien base

More description for this and the following attributes here: https://openxcom.org/forum/index.php/topic,6557.msg104669.html#msg104669

0
operationSpawnZone The missionZone for spawning the operation base (if necessary), see above. -1
operationBaseType The type of operation base to spawn (references alien deployment), see above. -
targetBaseOdds The odds of this mission targeting an xcom base. Works only for genMission spawned by an alien base. 0
regionWeights The region distribution over game time. Works only for genMission spawned by an alien base. -

Waves

Value Description Default
ufo String ID of the UFO to spawn. required
count Number of UFOs to spawn. 0
trajectory String ID of the trajectory for this UFO to use when entering Earth's atmosphere. required
timer How long after the previous wave should this wave arrive? (in minutes)

Notes:

  • The timer can vary between 50-150% of the stated value, so a UFO with a 9000 value will be spawned between 4500-13500 minutes (each day has 1440 minutes)
  • If the UFO is crashed/destroyed the timer of the next UFO on the wave will be delayed by (30 * (RNG::generate(0, 400) + 48)) minutes, or between 1.0 and 9.3 days
 0
objective true Marks this wave as the one that carries out the mission objective. Only for mission site / supply missions. -
hunterKillerPercentage The chance (0-100%) to become a hunter-killer UFO upon spawning.

Possible options:

  • -1 = take the info from RuleUfo
  • 0 = not a hunter-killer
  • 1-99 = percentage chance to be flagged as hunter-killer upon spawn
  • 100 = always a hunter-killer
 -1
huntMode Algorithm to use when prioritizing xcom targets.

Possible options:

  • -1 = take the info from RuleUfo
  • 0 = prefer hunting xcom interceptors
  • 1 = prefer hunting xcom transports
  • 2 = random preference (0 or 1) determined at spawn
 -1
huntBehavior Algorithm to use when considering retreating from the dogfight.

Possible options:

  • -1 = take the info from RuleUfo
  • 0 = flee if you're losing
  • 1 = never flee, never crash (is destroyed instead of crashing)
  • 2 = random preference (0 or 1) determined at spawn
 -1
escort Does this wave escort/protect the previous wave(s)? false
interruptPercentage The chance (0-100%) to interrupt the alien mission when successfully shooting down a UFO from this wave.

Possible options:

  • 0 = cannot interrupt
  • 1-99 = percentage chance to be interrupted
  • 100 = always interrupted
 0

Mission Scripts

MissionScripts determines how many missions are spawned each month.

Value Description Default
type Name of the script used for overwriting or deleting purposes. required
firstMonth Months this command runs on, 0 runs on startup of a new game 0
lastMonth Do not run after this month. In this context we mean "run once". -1 denotes no limit. -1
label A numeric label that can be used for conditional execution of commands. Each label should be unique within the command list (0=default no need for uniqueness). 0
conditionals Defines the conditions that allows 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.

Commands that are not yet executed are always in failed state.

-
missionWeights The type of mission to spawn (omit to pick one from the alien strategy mission table). These are split into monthly chunks, and can contain multiple entries including weighted odds, but there is a caveat here: You cannot mix and match missions with mission site objectives (i.e. terror sites) with regular missions. They are generated too differently. Using executionOdds and conditionals instead can achieve exactly the same thing. Similarly, terror missions should not appear in regional mission weights (regions.rul). -
executionOdds % chances of this command executing. 100
targetBaseOdds % chances of this mission targeting a region containing an xcom base... instead of a random region (which CAN also contain an xcom base). 0
startDelay Number of minutes to delay the start of the mission (rounded down to the nearest 30). For 0 the wave timer from the mission itself is used. 0
randomDelay Additional randomized delay (in minutes). Total delay = startDelay + RNG(0, randomDelay) 0
raceWeights List which can override established monthly race weights if desired. -
regionWeights List which can override established monthly region weights if desired. This will come into play only if the mission doesn't target an xcom base.

If the list is omitted: for a terror type mission, all regions that meet the criteria will be weighed equally. For regular missions the normal regional distribution weights will be applied.

-
minDifficulty This command only applies to difficulty levels of this or above. 0
minScore This command only applies if last month's rating was above this threshold. Not checked before first month. -infinity
maxScore This command only applies if last month's rating was below this threshold. Not checked before first month. infinity
minFunds This command only applies if the new month's funds are above this threshold. Not checked before first month. -infinity
maxFunds This command only applies if the new month's funds are below this threshold. Not checked before first month. infinity
researchTriggers A list of research topics that can influence the execution of this mission. For example
  • "STR_THE_ULTIMATE_THREAT: true" means the mission would only run if the player has researched the Ultimate Threat.
  • "STR_TLETH_TH_ALIEN_CITY: false" means the mission would only run if the player has not researched T'Leth.

Several research triggers can be combined and for the mission to appear all must be fulfilled.

-
itemTriggers A list of items that can influence the execution of this script. Similar to research triggers; checks the presence of items in the base stores (not anywhere else). -
facilityTriggers A list of base facilities that can influence the execution of this script. Similar to research triggers; checks the presence of a facility (in any xcom base). -
maxRuns This mission type can only execute this number of times, -1 for infinite. -1
avoidRepeats This is used to ensure different coordinates for this mission. It means "store an array of x previous coordinates, and don't use them again". 0
varName This is an internal variable name, used for tracking maxRuns and avoidRepeats. -
useTable Check if this mission type appears in the mission tables. If true remove it from there.

Note: this is used for "classic approach" (before mission scripts existed), where missions were pre-generated at the beginning of the campaign in alien strategy table and removed from there one by one to avoid repetitions.

true

Guidelines/Tips

Relevant ruleset files for editing alien missions of "mission site" type (e.g. terror sites):

  • missionScripts.rul - this is where alienMissions are generated
  • alienMissions.rul - alienMissions provide a link to the region (unless overridden by missionScript); and define missionWaves, which ultimately provide links to UFO trajectories
  • ufoTrajectories.rul - provides a link to regional missionZones (= places where the the UFOs start/end, change direction, land, and potentially create mission sites)
    • Note: mission sites can also be spawned without actual UFOs if so desired (e.g. TFTD artifact sites/shipping lanes)
  • regions.rul - defines the missionZones; and provides a link to textures (=battlescape appearance)
    • Note: textures can be either terrain-based (used for UFO landing/crash sites) or alienDeployment-based (used for mission sites)
  • globe.rul - defines the textures
    • Note: the alienDeployment-based textures are usually recognizable by their negative IDs
  • alienDeployments.rul - contains detailed information for the battlescape map generator (terrains, mapScripts, etc.)

Arc Scripts

ArcScripts determine high-level game progression. They are executed just before the monthly MissionScripts.

Technically they are just "time-triggered research discoveries". More info: https://openxcom.org/forum/index.php/topic,7125.0.html

Value Description Default
type Name of the arc script used for overwriting or deleting purposes. required
sequentialArcs The names of research topics to be "discovered", each month 0 or 1, processed sequentially. -
randomArcs The names and weights of research topics to be "discovered", each month 0 or 1, chosen randomly considering weights. -
firstMonth Months this command runs on, 0 runs on startup of a new game. 0
lastMonth Do not run after this month. -1 denotes no limit. -1
executionOdds % chances of this command executing. 100
maxArcs Maximum number of arcs this command can generate (together during the whole game), -1 for infinite. -1
minDifficulty This command only applies to difficulty levels of this or above. 0
maxDifficulty This command only applies to difficulty levels of this or below. 4
minScore This command only applies if last month's rating was above this threshold. Not checked before first month. -infinity
maxScore This command only applies if last month's rating was below this threshold. Not checked before first month. infinity
minFunds This command only applies if the new month's funds are above this threshold. Not checked before first month. -infinity
maxFunds This command only applies if the new month's funds are below this threshold. Not checked before first month. infinity
researchTriggers A list of research topics that can influence the execution of this script. For example
  • "STR_MARTIAL_SOLUTION: true" means the command would only run if the player has researched The Martian Solution.
  • "STR_CYDONIA_OR_BUST: false" means the command would only run if the player has not researched Cydonia or Bust yet.

Several research triggers can be combined and all must be fulfilled.

-
itemTriggers A list of items that can influence the execution of this script. Similar to research triggers; checks the presence of items in the base stores (not anywhere else). -
facilityTriggers A list of base facilities that can influence the execution of this script. Similar to research triggers; checks the presence of a facility (in any xcom base). -

Guidelines/Tips

Possible usage, for inspiration:

  • Randomly give the player research A, B or C at the beginning - each research then unlocks specific tech at game start, giving the player different starting items/research for each new campaign
  • Randomly give the player (each month) one research topic D, E, F, etc. - each research then unlocks specific mission(s) for that month
  • Give tech G on month 0, tech H on month 1 and tech I on month 2 - for multi-mission story arcs spawning in sequence across several months
  • Give tech J and spawn corresponding mission, if mission is victory receive tech K, which then unlocks additional mission next month - for making missions dependent on the previous one
  • If research L is completed or if month X is achieved, give tech M at beginning of next month with the UFOPedia notification - this can be used to provide tips, tutorials, in-game message, whatever relevant info you want to give the player

Event Scripts

EventScripts determine when custom geoscape events occur. They are executed just after the monthly MissionScripts.

More info: https://openxcom.org/forum/index.php/topic,7215.msg116753.html#msg116753

Value Description Default
type Name of the event script used for overwriting or deleting purposes. required
oneTimeSequentialEvents The list of one time sequential events to spawn. First not-previously-generated event is spawned. -
oneTimeRandomEvents The list of one time events to spawn. One random not-previously-generated event is spawned. Weights are considered. -
eventWeights The type of events to spawn. These are split into monthly chunks, and can contain multiple entries including weighted odds. -
firstMonth Months this command runs on, 0 runs on startup of a new game. 0
lastMonth Do not run after this month. -1 denotes no limit. -1
executionOdds % chances of this command executing. 100
minDifficulty This command only applies to difficulty levels of this or above. 0
maxDifficulty This command only applies to difficulty levels of this or below. 4
minScore This command only applies if last month's rating was above this threshold. Not checked before first month. -infinity
maxScore This command only applies if last month's rating was below this threshold. Not checked before first month. infinity
minFunds This command only applies if the new month's funds are above this threshold. Not checked before first month. -infinity
maxFunds This command only applies if the new month's funds are below this threshold. Not checked before first month. infinity
researchTriggers A list of research topics that can influence the execution of this script. For example
  • "STR_MARTIAL_SOLUTION: true" means the command would only run if the player has researched The Martian Solution.
  • "STR_CYDONIA_OR_BUST: false" means the command would only run if the player has not researched Cydonia or Bust yet.

Several research triggers can be combined and all must be fulfilled.

-
itemTriggers A list of items that can influence the execution of this script. Similar to research triggers; checks the presence of items in the base stores (not anywhere else). -
facilityTriggers A list of base facilities that can influence the execution of this script. Similar to research triggers; checks the presence of a facility (in any xcom base). -
affectsGameProgression If set to true, research topics from researchTriggers will display a small disclaimer in the TechTreeViewer about affecting game progression. false

Events

Defines a Geoscape event that pops up, gives the player some background info and awards funds, score, items and/or research, listed in "events:".

More info: https://openxcom.org/forum/index.php/topic,7215.msg116753.html#msg116753

Value Description Default
name String ID of the event name. Use {0} placeholder (in the actual translation) for region/city name. required
description String ID of the event description. Use {0} placeholder (in the actual translation) for region/city name. -
background String ID of the background image to use in the window when this event pops up on the Geoscape. BACK13.SCR
music String ID of the music to play when this event pops up on the Geoscape. -
regionList List of regions, where this event can occur. The region name can be a part of the event name and/or description. -
city Whether or not the event occurs in a random city (of the given region(s)). The city name can be a part of the event name and/or description. false
points How many score/rating points are awarded to xcom when this event pops up. If there is a region, points are awarded to that region's activity, otherwise to the research score. 0
funds How much money is awarded to xcom when this event pops up. 0
everyItemList A list of item IDs. When this event pops up they are all transferred to the HQ (within 1 hour). -
everyMultiItemList A list of item IDs and their quantities. When this event pops up they are all transferred to the HQ (within 1 hour). -
randomItemList A list of item IDs. When this event pops up one of them is selected randomly and transferred to the HQ (within 1 hour). -
weightedItemList A weighted list of item IDs. When this event pops up one of them is selected randomly (respecting given weights) and transferred to the HQ (within 1 hour). -
researchList A list of research topic IDs. One (from the not-yet-discovered) is randomly selected when this event pops up and granted for free. -
interruptResearch String ID of a research topic that will prevent (an already generated/scheduled) event from popping up. -
timer Number of minutes (after generation) after which the event should pop up. Minimum is 60. Should be a multiple of 30. 60
timerRandom Additional random timer in minutes. Total delay = timer + RNG(0, timerRandom). 0

Alien Tech Levels

This is a list of alien Tech Levels, listed in "alienItemLevels:".

Each line in the list corresponds to the Tech Level for one game month (first line is for the first month, second line for second month, etc.). The game will use the most recent available line in the event the game goes on forever (and there are not enough lines defined).

Each line contains item set probabilities, with a number between 0 and 2 representing an item set (from plasma pistols to heavy plasmas, as defined in the deployments), expressing a 10% probability for that item set being used.

  • 0 = first item set (e.g. plasma pistol/clip)
  • 1 = second item set (e.g. plasma rifle/clip)
  • 2 = third item set (e.g. heavy plasma/clip)

For example: 

 [ 2, 0, 0, 0, 0, 0, 0, 1, 1, 1 ]

would represent a 60% chance for pistols, 30% for rifles and 10% for heavy weapons.

Note that the order does not matter, but the length DOES. Each line MUST have exactly 10 digits.

If the above is still confusing, here's more explanation:

  • There are 10 fields in a line; each field represents 10%
  • There are six instances of '0'... 6x10% = 60% chance of plasma pistol
  • There are three instances of '1'... 3x10% = 30% chance of plasma rifle
  • There is only one instance of '2'... 1x10% = 10% chance of heavy plasma

Just in case: you can use more (or less) than 3 item sets (0, 1, 2), but you will need to modify all the alien deployments accordingly too!

Extra Sprites

Adds or replaces sprites in an existing X-COM image file, listed in "extraSprites:".

VERY IMPORTANT:

  • You can use many different image formats, but not all of them work on all platforms (e.g. 8bit GIF does not work on Mac)... please use 8bit PNG format for maximum compatibility
  • OpenXcom is able to handle 24bit images (in some cases), but they are not officially supported... please use 8bit images for maximum compatibility
  • OpenXcom is able to handle transparency index other than zero (in most cases), but it is not officially supported... please use transparency index zero for maximum compatibility
  • OpenXcom displays everything using 8bit palettes
Value Description Default
type Name of the original sprite/spritesheet to modify or new sprite/spritesheet to create. required
typeSingle Alternative to type, used for defining single sprites with less verbose ruleset. Changes the default value for singleImage to true. -
files List of the new sprites to add/replace, listed as spriteID: filepath. -
fileSingle Alternative to files, used for defining single sprites with less verbose ruleset. -
width Width of the whole sprite/spritesheet in pixels. 320
height Height of the whole sprite/spritesheet in pixels. 200
singleImage Is the image file just a single sprite (true) or a spritesheet (false)? false
subX Width of the subdivision in pixels. If a subdivision is specified, then the image file (a spritesheet) is divided into chunks (sprites). 0
subY Height of the subdivision in pixels. If a subdivision is specified, then the image file (a spritesheet) is divided into chunks (sprites). 0

Example: 

- type: GIANTBUNNY.PCK
  width: 32
  height: 40
  files:
    0: Resources/Bunny/Bunny00.png
    1: Resources/Bunny/Bunny01.bmp
    2: Resources/Bunny/Bunny02.gif

Another example: (takes advantage of the ability to drop numerous images into a single folder that will then behave like a spritesheet) 

- type: GIANTBUNNY.PCK
  width: 32
  height: 40
  files:
    0: Resources/Bunny/sprite/

Files within the specified folder should be numbered sequentially from the number defined above. "0" in this case.

Negative indices and cross-referencing other mods

Since Q2/2019, it is officially not possible to use negative sprite and sound indices (both in OXC and OXCE).

The xcom1 terror weapons (their bigobs) have been moved to positive indices as follows:

  • Chrysssalid weapon from -1 to 61
  • Cyberdisc/Celatid/Sectopod weapon from -2 to 60
  • Reaper weapon from -3 to 59
  • Silacoid weapon from -4 to 58
  • Zombie weapon from -5 to 57

Similar mapping was done also for xcom2 terror weapons.

If you were using these bigobs in your mod, you have 2 options how to fix it:

  1. Option 1 (recommended): define/copy these bigobs in your mod as any other custom sprites, i.e. don't reuse the openxcom ones
  2. Option 2: you can reuse the openxcom ones using a special syntax, which allows you to access objects from different mods, see example below
 items:
   - type: STR_MY_CUSTOM_SECTOPOD_WEAPON
     bigSprite: { mod: xcom1, index: 60 }

This example shows how to access sprite number 60 from xcom1 mod. There is also a special keyword master, which allows you to access the master mod. The following example is equivalent to the previous example: 

 items:
   - type: STR_MY_CUSTOM_SECTOPOD_WEAPON
     bigSprite: { mod: master, index: 60 }

Disclaimer: please be careful when addressing other mods than your own, the mod authors may decide to change their numbering at any time, rendering your references incorrect. Using this feature for anything else than addressing xcom1/xcom2 terror weapons is at your own risk.

Alternative for single sprites (OXCE only)

Bigger mods can contain a lot of sprites.

To make the ruleset smaller and easier to read, you can use the following alternative way of defining single sprites.

Standard method: 

 - type: SpriteName
   singleImage: true
   files:
     0: Resources/MyImage.png

Alternative method: 

 - typeSingle: SpriteName
   fileSingle: Resources/MyImage.png

Notice how only 2 lines are needed instead of 4; and the beginning of both values is nicely aligned.

Reserved sprite/spritesheet names

FIXME: add info about reserved names in OpenXcom too.

OXCE adds several new sprites and spritesheets with pre-defined names, that serve various purposes. Most of these sprites are "empty" by default and not used. But modders have the option to define these sprites and activate extra functionality behind them.

Below is the list of new sprites and spritesheets (FIXME: add description and links/examples):

  • spritesheets:
    • CustomArmorPreviews
    • CustomItemPreviews
    • DayNightIndicator
    • TinyRanks
  • sprites:
    • AvatarBackground
    • AlienInventory, AlienInventory2
    • BigStunIndicator, BigWoundIndicator, BigBurnIndicator, BigShockIndicator
    • FloorStunIndicator, FloorWoundIndicator, FloorBurnIndicator, FloorShockIndicator
    • Flag[X]

Extra Sounds

Adds or replaces sounds in an existing X-COM sound file, listed in "extraSounds:".

Value Description Default
type ID of the original sound file to modify:
  • BATTLE.CAT - Battlescape sounds, corresponds to SOUND1.CAT or SAMPLE2.CAT (55 sounds).
  • INTRO.CAT - Intro sounds, corresponds to INTRO.CAT or SAMPLE3.CAT, probably best not to mess with these.
  • GEO.CAT - Geoscape sounds, corresponds to SOUND2.CAT or SAMPLE.CAT (14 sounds).
 required
files List of the new sounds to add/replace, listed as soundID: filepath. -

Example: 

- type: BATTLE.CAT
  files:
    55: Resources/Sounds/sample.wav

When using .wav files, please pay attention to the file format!

OpenXcom should work fine with:

  • uncompressed mono/stereo PCM
  • low bit depth (8bit or 16bit), 16bit recommended, 24bit is known to NOT work
  • low and standard sample rates (8-48 kHz), 22050 Hz or 44100 Hz recommended

Music

Custom music options can be defined in the Music.rul file. More details here.

Value Description Default
type Name of the music track. required
catPos The track's index in the catalog (CAT) file. Only relevant for music stored in CAT files, obviously. -
normalization The track's normalization level. Only relevant for music stored in CAT files. 0.76

Extra Strings

Adds or replaces text strings in an existing OpenXcom language file, listed in "extraStrings:".

Value Description Default
type Filename of the original language file to modify (without file extension). required
strings List of the new strings to add/replace, listed as stringID: text. -

Example: 

- type: en-US
  strings:
    STR_SNIPER_RIFLE: Sniper Rifle
    STR_SNIPER_RIFLE_CLIP: Sniper Rifle Clip
- type: en-GB
  strings:
    STR_SNIPER_RIFLE: Sniper Rifle
    STR_SNIPER_RIFLE_CLIP: Sniper Rifle Clip
- type: de
  strings:
    STR_SNIPER_RIFLE: Scharfschützengewehr
    STR_SNIPER_RIFLE_CLIP: Scharfschützengewehrmunition
- type: ru
  strings:
    STR_SNIPER_RIFLE: Снайперская винтовка
    STR_SNIPER_RIFLE_CLIP: Магазин к снайп. винтовке

Did you know?

  • Translations can also be provided in the same format as OpenXcom provides them for default languages (en-US and en-GB)
  • The advantage over using extraStrings is that the format can be used in Transifex, so that popular mods can be easily translated into many languages by many people in a more coordinated way

Interfaces

Defines various properties (most notably colors) and behavior of OpenXcom UI screens, listed in "interfaces:".

Value Description Default
type Name of the interface. Each OpenXcom screen has a unique corresponding interface. required
palette Name of the palette (e.g. PAL_BASESCAPE) to be used for this screen. Not all screens support this. -
parent Name of the parent interface (from which some attributes are inherited).

For example research/manufacture screens have a hierarchy of screens opening on top of each other.

-
music Music to play when the corresponding screen is opened. -
sound Sound effect (from GEO.CAT) to play when the corresponding screen is opened. -1
backgroundImage Background image for the corresponding screen. -
elements List of detailed definitions for various elements on the screen (window, text, buttons, lists, etc.). See below. -

Elements

Value Description Default
id Name of the interface element. required
size Some elements have configurable size. Defined as [width, height]. -
pos Some elements have configurable position. Defined as [x, y], where x<320 and y<200. -
color Most elements have configurable primary color (0-255). Elements called palette only have range between 0-15 (palette offsets). -
color2 Some elements have configurable alternative/secondary color (0-255). -
border Some elements have configurable border/tertiary color (0-255). -
custom A generic-purpose attribute.

Currently used only for inventory interface, specifies which stats are displayed.

0
TFTDMode Is used in TFTD for inversion behavior in some elements, mostly buttons. -

Tip: which elements support which attributes can be determined by inspecting the vanilla xcom1/xcom2 ruleset.

StatStrings

Statstrings are used to automatically rename soldiers. They are case-sensitive and processed in the order in which they are specified. Processing is stopped either at the end of the list, or when a first rule with a name longer than 1 character (e.g. "Snpr") matches.

Value Description Default
string String to add to name. required
psiStrength

psiSkill
bravery
strength
firing
reactions
stamina
tu
health
throwing

One or more stat ranges are AND-ed together to find a match.

Each range has a format [min, max]. Use YAML standard tilde (~) to indicate empty value (interpreted as 0 for min and as 255 for max).

-
melee

psiTraining

New attributes (only available in OpenXcom). -
manaPool New attribute (only available in OXCE). -

Example: 

 statStrings:
 - string: "x"
   psiStrength: [~, 30]
 - string: "P"
   psiStrength: [80, ~]
 - string: "p"
   psiStrength: [60, 79]
 - string: "K"
   psiSkill: [60, ~]
 - string: "k"
   psiSkill: [30, 59]
 - string: "b"
   bravery: [60, ~]
 - string: "c"
   bravery: [~, 10]
 - string: "w"
   strength: [~, 25]
 - string: "Snpr"
   firing: [60, ~]
   reactions: [60, ~]
 - string: "M"
   firing: [70, ~]
 - string: "m"
   firing: [60, 69]
 - string: "Sct"
   reactions: [50, ~]
   tu: [60, ~]
 - string: "R"
   reactions: [60, ~]
 - string: "r"
   reactions: [50, 59]

Cutscenes

Defines a video playlist or a slideshow sequence, listed in "cutscenes:".

Value Description Default
type String ID of the cutscene. required
winGame Whether or not the cutscene ends the game with victory.

More info about multiple game endings: https://openxcom.org/forum/index.php/topic,7476.0.html

false
loseGame Whether or not the cutscene ends the game with defeat. false
useUfoAudioSequence Whether to use the audio sequence for the original UFO intro movie. This should only ever be set to true for the UFO intro. false
videos A list of video filenames to play with the FLC player. Required if this cutscene is a video playlist. -
audioTracks A list of audio filenames to play along the videos specified in videos. Optional. -
slideshow Info for playing a slideshow (see below). Required if this cutscene is a slideshow. -

Slideshow Data

Value Description Default
transitionSeconds The number of seconds to wait before automatically transitioning to the next slide. The user can always force a transition by a mouse click. 30
musicId The ID of the music to play. -
slides List of slide data elements (see below). required

Slide Data

Value Description Default
imagePath The path to the image file to display in the background.

Note: the palette for the slide is taken directly from the image, so the caption text color will be determined by the image palette.

required
caption The string ID of the caption text. -
captionSize The size of the text box, in pixels, in which to display the caption. [320, 200]
captionPos The screen position at which to display the caption. [0, 0]
captionColor The palette index to use for the caption color. required
transitionSeconds Override for transitionSeconds from Slideshow Data, so that each slide can have a different value. 0
captionAlign The horizontal text alignment for the caption text. Possible values: 0 = left, 1 = center, 2 = right. 0

Global Variables

The following ruleset doesn't belong into any category/hierarchy, it's just standalone settings you can put into any file, on the top level. It mostly contains constants that were deemed worthy making moddable.

In vanilla ruleset files, these are located in vars.rul and in difficulty.rul.

Resources

Value Description Default
fontName Name of *.dat file, placed in Language folder, which describes used font collection. Font.dat
disableUnderwaterSounds Redirects the game to BATTLE.CAT whenever it would want to access BATTLE2.CAT, i.e. underwater sounds will be the same as surface sounds.

Hint: a debug option for people working on hybrid UFO/TFTD mods to (for the time being) prevent crashes on missing sounds.

false
enableUnitResponseSounds Enables/disables unit response sounds.

More info: https://openxcom.org/forum/index.php/topic,7371.0.html

false
unitResponseSoundsFrequency Sets the probabilities of unit response sounds being played (each time). First number is for "select unit" sound, second for "start moving" sound, third for "select weapon" sound and fourth for the "annoyed" sound. [100, 100, 100, 20]
unitResponseSounds Custom unit response sounds per individual soldier name... when soldier type/armor/gender is just not RPG enough :) Hardcore.

More info: https://openxcom.org/forum/index.php/topic,7371.0.html

Syntax: 

 unitResponseSounds:
   - name: Starving Poet
     selectUnitSound:   [200, 201, 202, 203, 204]
     startMovingSound:  [210, 211, 212, 213]
     selectWeaponSound: [220, 221, 222, 223]
     annoyedSound:      [230, 231, 232, 233]
   - name: Ivan Dogovich
     selectUnitSound:   [300, 301, 302, 303, 304, 305]
     startMovingSound:  [310, 311, 312, 313]
     selectWeaponSound: [320, 321, 322, 323]
     annoyedSound:      [330, 331, 332, 333, 334, 335]
-
baseNamesFirst

baseNamesMiddle
baseNamesLast

Data for the random base name generator. baseNamesMiddle and baseNamesLast are optional. Example: 
 baseNamesFirst:
   - Big
   - Huge
   - Large
   - Stinky
 baseNamesMiddle:
   - Rat
   - Pirate
 baseNamesLast:
   - Bay
   - Port
   - Haven
   - Tavern
-
operationNamesFirst

operationNamesLast

Data for the random operation name generator. operationNamesLast is optional. Example: 
 operationNamesFirst:
   - Blind
   - Burning
   - Cold
   - Dark
   - Devil's
   - Enduring
   - Fallen
 operationNamesLast:
   - Blade
   - Dream
   - Future
   - Justice
   - Rain
   - Star
   - Thunder
-

Сampaign

Value Description Default
startingTime Specifies the date and time at the beginning of the game. Friday 1.1.1999 12:00:00
initialFunding Amount of money (in thousands of dollars) the player starts with. 0
monthlyRatings A list of monthly ratings. Each item contains a minimum required score and a corresponding String ID of the rating. Example: 
 monthlyRatings:
   5000: STR_MT_RATING_AMAZING
   2000: STR_MT_RATING_PERFECT
   1000: STR_MT_RATING_VERY_GOOD
   500: STR_MT_RATING_GOOD
   250: STR_MT_RATING_OK
   0: STR_MT_RATING_MEH
   -350: STR_MT_RATING_BAD
   -99999: STR_MT_RATING_TERRIBLE
-
performanceBonusFactor Defines whether the player receives a financial bonus based on the monthly score. If set for example to 1000 and monthly score is 650, the player receives an extra $650000. In case of a negative monthly score, there is no penalty. 0
customTrainingFactor Additional RNG for stat improvement using martial/combat training facilities. Can be used to slow down training (cannot speed it up). If set for example to 20, the training speed will be five times slower than normal (i.e. training at 20% speed). 100
psiUnlockResearch In OpenXcom, this is set to Psi-Lab requirements (i.e. the building with psiLabs > 0). In OXCE, you can set a different research topic to allow Psi screening (using the Psi-Strength Evaluation advanced option) before the actual Psi training (in Psi Labs) is possible. -
fakeUnderwaterBaseUnlockResearch Research topic required to be able to build bases on "fake underwater" globe textures. -
allowAlienBasesOnWrongTextures If a valid location cannot be found after 100 random attempts, use an invalid location (land texture vs. fake underwater texture). true
allowCountriesToCancelAlienPact If enabled, XCOM can convince countries that left the XCOM project to come back... by destroying the alien base that was created when the aliens signed a pact with a given country. false
buildInfiltrationBaseCloseToTheCountry If enabled, alien infiltration bases will be built in or near the infiltrated country (as opposed to anywhere in the whole region). false
chanceToStopRetaliation If an XCOM base is found and a battleship sent to attack it is shot down by base defense facilities, aliens will keep sending new battleships forever. This setting defines a chance that they reconsider their decision and stop sending more battleships. 0
lessAliensDuringBaseDefense If enabled, less aliens will spawn in base defense missions, roughly proportional to damage dealt to the invading UFO. At least one alien of each rank is guaranteed to spawn. false
gameOver A list of cutscene names for special events. More info: https://openxcom.org/forum/index.php/topic,7476.msg117830.html#msg117830 
 gameOver:
   loseMoney: loseGame       # cutscene ID that should be played when the player loses due to poor economy management
   loseRating: loseGame      # cutscene ID that should be played when the player loses due to poor rating
   loseDefeat: loseGame      # cutscene ID that should be played when the player loses the last base
<=

Basescape/Personnel

Value Description Default
timePersonnel Time (in hours) it takes for newly hired personnel to arrive at a base. 0
costEngineer Monthly salary of a single engineer (in dollars). Please note that hiring cost is twice as much. 0
costHireEngineer Cost of hiring a single engineer. If not specified (0), it costs twice as much as the monthly salary. 0
costScientist Monthly salary of a single scientist (in dollars). Please note that hiring cost is twice as much. 0
costHireScientist Cost of hiring a single scientist. If not specified (0), it costs twice as much as the monthly salary. 0
soldiersPerSergeant How many soldiers (of any rank) are required to unlock a new sergeant promotion. 5
soldiersPerCaptain How many soldiers (of any rank) are required to unlock a new captain promotion. 11
soldiersPerColonel How many soldiers (of any rank) are required to unlock a new colonel promotion. 23
soldiersPerCommander How many soldiers (of any rank) are required to unlock the commander promotion. There can be only one commander at a time. 30
shortRadarRange The maximum radar range still considered as short (for [Base Info] screen purposes). If not specified (0), the smallest range from all radar facilities is used. 0
buildTimeReductionScaling When upgrading base facilities, reduce the build time reduction by this factor (in percent). Or in simpler words, increase the upgrade time. 100
useCustomCategories Should custom item categories be used in Buy/Sell/Transfer screens? If not, default OpenXcom categories (Craft Armament, Equipment, Components, Aliens) are used. false
shareAmmoCategories If enabled, firearms will "inherit" the categories of their ammo (only the available ammo counts). Affected are: 1/ Craft Equipment screen and 2/ Starting conditions (allowed/disabled item categories). Not affected: Buy/Sell/Transfer screens. false
maxLookVariant The maximum supported lookVariant (0-63) used in [Change Soldier Avatar] dialog. 0
flagByKills OXCE allows to display flags next to soldier names, based on their nationality (resp. based on the name pool from which their name was chosen). If this setting is used, the flag will depend on the number of kills from soldier's diary instead. 
 flagByKills: [10,20,30]

Example above means:

  • 0-10 kills = Flag0 sprite is used
  • 11-20 = Flag1 sprite
  • 21-30 = Flag2 sprite
  • 31+ = Flag3 sprite
 -
alienInventoryOffsetX Hand slots of the "alien inventory" (inventory accessible via Middle-button-click) will be shifted to the right by this much. 80
alienInventoryOffsetBigUnit Hand slots of the "alien inventory" (inventory accessible via Middle-button-click) will be shifted away from each other by this much for 2x2 units. 32

Interception

Value Description Default
drawEnemyRadarCircles When should the alien UFO (hunter-killer) and alien base radar ranges be drawn? Possible options:
  • 0 = never drawn
  • 1 = drawn for bases if discovered and for UFOs if hyper-detected
  • 2 = drawn for bases if discovered and for UFOs if detected
 1
pilotAccuracyZeroPoint Average firing accuracy for a pilot (where the accuracy bonus is 0%). 55
pilotAccuracyRange The firing accuracy impact (as a percentage of the distance to the zero point) on the pilot's aim in dogfights. 40
pilotReactionsZeroPoint Average reactions for a pilot (where the dodge bonus is 0%). 55
pilotReactionsRange The reactions impact (as a percentage of the distance to the zero point) on the pilot's dodge ability in dogfights. 60
pilotBraveryThresholds The pilot's bravery needed for [Very Bold, Bold, Normal] approach speed during dogfights. If neither is reached, approach speed is Cowardly. [90, 80, 30]
showDogfightDistanceInKm Should the distance between the craft and a UFO be shown in kilometers (true) or in vanilla units (false)? Vanilla units equal to 8-times the distance in kilometers. false
ufoGlancingHitThreshold The threshold for defining a glancing hit on a UFO during interception. Defined as a percentage of damage needed to shoot it down (i.e. half of damageMax). 0
ufoBeamWidthParameter The parameter for drawing the width of a UFO's beam weapon based on power. The width of the beam in pixels will be weapon power divided by this parameter, but at least 3 pixels. For example if the weapon power is 250 and parameter is 50, the beam size in pixels will be 5. 1000
ufoTractorBeamSizeModifiers The modifiers to a tractor beam's power based on a UFO's size. 
 ufoTractorBeamSizeModifiers:
   - 400 # very small, tractor beams are 400% or 4x as effective
   - 200
   - 100
   - 50
   - 25 # very large, tractor beams are 25% or 1/4x as effective
[400, 200, 100, 50, 25]
hunterKillerFastRetarget If enabled, the UFO hunter-killers can reconsider their target every 5 seconds on low game speeds (5sec/1min) and every 10 minutes on all other game speeds. If disabled, it is only every 10 minutes on all game speeds. true
escortRange Range (in nautical miles) in which the craft is considered to be escorted by a nearby craft. 20
escortsJoinFightAgainstHK Should craft escorts join the fight against HK automatically (true)? Or is only fighting one-on-one allowed (false)? true
crewEmergencyEvacuationSurvivalChance The chance of soldiers (that are not pilots) surviving craft destruction by a UFO hunter-killer (jumping out with a parachute). 100
pilotsEmergencyEvacuationSurvivalChance The chance of pilots surviving craft destruction by a UFO hunter-killer (emergency seat ejection). 100

Pedia

Value Description Default
pediaReplaceCraftFuelWithRangeType What type of information should be shown in craft articles for the fuel capacity/range? Possible options:
  • -1 = Fuel capacity
  • 0 = Maximum theoretical range
  • 1 = Minimum and maximum theoretical max range
  • 2 = Average theoretical max range
 -1
hidePediaInfoButton Show the INFO button (where applicable) or not? false
extraNerdyPediaInfo Display extra item info (accuracy modifier and power bonus) in the main pedia article or not? false

Battlescape

Value Description Default
alienFuel Name of an item representing alien fuel and a quantity to recover from a single fuel cell. Format: [name, quantity]. [-, -]
baseDefenseMapFromLocation Whether or not to load additional base defense terrain from globe texture. 0 = no, 1 = yes.

More info: https://openxcom.org/forum/index.php/topic,5108.0.html

0
lighting Configuration of light propagation:
  • enhanced: flags to switch between vanilla and directional light propagation (1 = directional for tiles and fire, 2 = directional for items, 4 = directional for units); add the numbers together to turn on multiple flags (e.g. 1+2+4=7 = directional lighting for all light sources)
  • maxStatic: maximum range/radius for tile and fire light propagation
  • maxDynamic: maximum range/radius for item and unit light propagation

Defaults: 

 lighting:
   enhanced: 0
   maxStatic: 16   #Careful, affects overall game performance!
   maxDynamic: 24  #Careful, affects overall game performance!
<=
maxViewDistance Maximum view distance (in tiles). If you want to use bigger/custom view distances (in general, or per armor), you need to set this variable to the maximum of all view distances you're using.

VERY IMPORTANT: Although optimized (in OXCE) a lot compared to OpenXcom, this setting still has huge impact on game performance! The performance decrease is exponential, i.e. changing value from 20 to 40 doesn't decrease the performance only by a factor of 2, but much much more. Recommended maximum value is up to 30. If you're willing to sacrifice game performance you can go up to 40. Above 40, it's unplayable.

20
maxDarknessToSeeUnits The threshold of shade/darkness for LoS calculation. Shade ranges (for value set to 9):
  • 0 = no shade: Daylight, full visibility.
  • 1-9 = partial shade: Dusk/Dawn, also full visibility.
  • 10-15 = full shade: Night, decreased visibility for XCOM.
 9
noLOSAccuracyPenaltyGlobal A global default value for accuracy penalty (in percent), when shooting at a unit or tile outside of LoS (line of sight). Can be overridden per weapon. -1
kneelBonusGlobal A global default value for accuracy bonus, when kneeling. Can be overridden per weapon. 115 means 15% bonus (100+15). 115
oneHandedPenaltyGlobal A global default value for accuracy penalty, when using a two-handed weapon with just one hand. Can be overridden per weapon. 80 means 20% penalty (100-20). 80
enableCloseQuartersCombat Whether or not CQC (close quarters combat) feature should be enabled. 0 = no, 1 = yes. 0
closeQuartersAccuracyGlobal A global default "accuracy" value for CQC check. Can be overridden per weapon.

FIXME: add a full example of CQC check, with all variables included.

100
closeQuartersTuCostGlobal Amount of time units the target unit (victim) needs to have to be able to perform CQC. If CQC is triggered, TUs will be also spent. If CQC is not triggered, TUs will not be spent. 12
closeQuartersEnergyCostGlobal Amount of energy the target unit (victim) needs to have to be able to perform CQC. If CQC is triggered, energy will be also spent. If CQC is not triggered, energy will not be spent. 8
tooMuchSmokeThreshold A technical parameter, which you may want to change if you want to be able to (always) extinguish fire from map tiles using smoke.

More info: https://openxcom.org/forum/index.php/topic,4057.msg59352.html#msg59352

10
hiddenMovementBackgrounds A list of sprites for "Hidden Movement" backgrounds. Chosen randomly at the beginning of a mission. Purely cosmetic. -
showFullNameInAlienInventory A global default value for showing unit name (true) or unit race (false) in the [Alien Inventory] screen. Can be overridden per unit type. false
destroyedFacility A global default value defining a special "rubble" facility that remains after a normal facility is destroyed (during base defense or via alien missile attacks/bombardment). Must have size 1. Can be overridden per facility type. -
giveScoreAlsoForResearchedArtifacts Whether the game awards score (in Debriefing) also for researched alien artifacts (true) or only for not yet researched artifacts (false). false
missionRatings A list of mission ratings. Each item contains a minimum required mission score and a corresponding String ID of the rating. Example: 
 missionRatings:
   2000: STR_MS_RATING_HOLY_COW
   1000: STR_MS_RATING_AMAZING
   750: STR_MS_RATING_PERFECT
   500: STR_MS_RATING_VERY_GOOD
   350: STR_MS_RATING_GOOD
   150: STR_MS_RATING_OK
   0: STR_MS_RATING_MEH
   -200: STR_MS_RATING_BAD
   -350: STR_MS_RATING_WORSE
   -500: STR_MS_RATING_TERRIBLE
   -1000: STR_MS_RATING_DISASTER
   -99999: STR_MS_RATING_EPIC_FAIL
-
statisticalBulletConservation If enabled, there's a chance to recover a full clip depending on how much ammo has remained. false
stunningImprovesMorale If enabled, stunning enemies improves morale in a similar way killing an enemy does.

More info: https://openxcom.org/forum/index.php/topic,7439.0.html

false
tuRecoveryWakeUpNewTurn Percentage of max TU that should be given to a unit that wakes up from unconsciousness at a beginning of a new turn. 100

Mana

Value Description Default
mana Global switches to turn mana GUI and features on/off.

More info: https://openxcom.org/forum/index.php/topic,7241.0.html

Example: 

 mana:
   enabled: false
   battleUI: false
   unlockResearch: STR_SORCERY     # empty by default
   trainingPrimary: false
   trainingSecondary: false
   woundThreshold: 200             # default is 200
   replenishAfterMission: true
see example
health Health recovery modding options. Allows soldiers to go into battle even with missing health.

More info: FIXME

Example: 

 health:
   woundThreshold: 100             # default is 100
   replenishAfterMission: true
see example

AI

Value Description Default
minReactionAccuracy Minimum firing accuracy for reaction fire. Used to prevent AI making shots that are unlikely to hit, which only makes them waste ammo and TUs. Instead they could wait until the target comes closer or shoot at another target. 0
turnAIUseGrenade Defines a turn, from which the aliens are allowed to use grenades. 3
turnAIUseBlaster OXC: Defines a turn, from which the aliens are allowed to use any AoE weapons (blaster launcher, small launcher, etc.).

OXCE: Defines a turn, from which the aliens are allowed to use waypoint-based weapons.

3
ai.useDelayBlaster Alias for turnAIUseBlaster. 3
ai.useDelayFirearm Defines a turn, from which the aliens are allowed to use firearms. 0
ai.useDelayGrenade Alias for turnAIUseGrenade. 3
ai.useDelayMelee Defines a turn, from which the aliens are allowed to use melee weapons. 0
ai.useDelayPsionic Defines a turn, from which the aliens are allowed to use psi amps.

Example: 

 ai:
   useDelayBlaster: 3
   useDelayFirearm: 1
   useDelayGrenade: 1
   useDelayMelee: 1
   useDelayPsionic: 2
0
ai.fireChoiceIntelCoeff
ai.fireChoiceAggroCoeff 		More info here: https://openxcom.org/forum/index.php/topic,5679.0.html 5
5
ai.extendedFireModeChoice
ai.respectMaxRange 		More info here: https://openxcom.org/forum/index.php/topic,5980.0.html false
false
ai.destroyBaseFacilities More info here: https://openxcom.org/forum/index.php/topic,6663.0.html false
ai.pickUpWeaponsMoreActively
ai.pickUpWeaponsMoreActivelyCiv 		More info here: https://openxcom.org/forum/index.php/topic,6882.0.html false
false
Surrendering, Bughunt
Value Description Default
surrenderMode Allows enemies to surrender (they will be taken as prisoners). Possible options:
  • 0 = no surrender
  • 1 = if all remaining standing enemies can surrender; and they want to surrender at this very moment (their current status is panicking or berserking)... end the battle
  • 2 = if all remaining standing enemies can surrender; and they have panicked/berserked at least once or have been stunned at least once... end the battle
  • 3 = same as option 2, but enemies must also have empty hands

In all 3 cases, enemies marked as "auto surrender" are not checked and count as surrendered.

0
bughuntMinTurn Earliest turn on which the "bughunt mode" can be activated. Once activated, it won't be turned off (except on multi-stage missions). During bughunt mode, you can see all remaining enemies on the minimap. 999
bughuntMaxEnemies Maximum amount of active enemies for bughunt mode to trigger. 2
bughuntRank If VIPs are still active, bughunt won't trigger. Possible options:
  • -1 = no VIPs
  • 0 = aliens with rank 0 are VIPs
  • 1 = aliens with rank 0 and 1 are VIPs
  • 2 = aliens with rank 0, 1 and 2 are VIPs
  • and so on...
 0
bughuntLowMorale Defines a threshold for "low morale". 40
bughuntTimeUnitsLeft Defines a threshold for "too much TUs".

If a unit doesn't have any weapon (in both hands) or if a unit has "low morale" or if a unit has "too much TUs" (i.e. cannot/doesn't move for whatever reason)... it counts as powerless and bug hunt can be activated.

If there is still a unit that is not powerless, bug hunt won't be activated.

60

Difficulty Settings

Value Description Default
startingDifficulty Pre-selected difficulty when starting a new game. Possible options:
  • 0 = beginner
  • 1 = experienced
  • 2 = veteran
  • 3 = genius
  • 4 = superhuman
 0
difficultyCoefficient Difficulty coefficients (per 5 game difficulty levels) affecting various game mechanics, for example:
  • Monthly rating threshold for losing the game (together with defeatScore) | (defeatScore) +100 points * difficultyCoefficient
  • UFO firing rate during dogfight | -2 gs * difficultyCoefficient
  • UFO escape countdown during dogfight | (100-200%) -30 gs * difficultyCoefficient
  • Retaliation odds after shooting down UFO | (4%) +4% * difficultyCoefficient
  • Odds of shootdown-triggered retaliation targeting xcom base region or not | (50%) +6% * difficultyCoefficient (needs confirmation)
  • Chance of aliens facing in the direction of the xcom craft at a start of a mission | 25% * difficultyCoefficient
  • Various AI decisions (in Battlescape)
  • Together with statGrowthMultipliers affects how alien stats change with difficulty level | + (statGrowthMultipliers/100) * difficultyCoefficient
  • Does not affect aimAndArmorMultipliers.
 [0, 1, 2, 3, 4]
aimAndArmorMultipliers Affects armor values and firing accuracy of aliens for different difficulty levels. [0.5, 1.0, 1.0, 1.0, 1.0]
statGrowthMultipliers Affects unit stats of aliens for different difficulty levels. -
defeatScore Monthly score threshold for losing the game on Beginner difficulty. Other difficulties have different thresholds, affected by difficultyCoefficient. 0
defeatFunds Debt threshold (at a start of a month) for losing the game, on all difficulty levels. 0

Other Constants

These are constants that were needed to support TFTD in OpenXcom. You are most likely never going to need to modify them, but we list them here for completeness sake. They are defined as an associative array of values (a list of values syntax is deprecated) under the constants: entry.

Some of these constants can be considered as difficulty settings, and vanilla ruleset defines them in difficulty.rul.

Value Description Default
damageRange Defines the damage range for projectile weapons. 100 means 0-200% range, 50 means 50-150% range, 25 means 75-125% range, etc. 100
explosiveDamageRange Defines the damage range for AOE weapons (e.g. explosives). 50
fireDamageRange Defines the damage range for incendiary weapons. Format is: [min, max]. [5, 10]

These constants can be especially interesting for hybrid mods (UFO/TFTD hybrids).

Value Description Default
explosionOffset Explosion offset in X1.PCK

Note: this defines the land explosion offset. Underwater explosion offset is smaller by 8. For example, if you define land offset to be 24, underwater offset will be automatically set to 16.

0
smokeOffset Surface smoke animation offset in SMOKE.PCK 8
underwaterSmokeOffset Underwater smoke animation offset in SMOKE.PCK 0
And there are a few OXCE-only constants, that were put into this section for technical reasons.
Value Description Default
extendedItemReloadCost If set to true, the item reload cost equals to "cost of moving ammo to hand" + "cost of reload". false
extendedRunningCost If set to true, running soldiers will ignore mutual surprise (i.e. will not stop running when spotting a new enemy). false
extendedHwpLoadOrder If set to true, craft load order is: 2x2 HWPs, 2x2 soldiers, 1x1 HWPs, 1x1 soldiers.

If false, load order is: all HWPs, all soldiers.

false
extendedMeleeReactions Enables reactions to melee attacks.
  • 0 = vanilla, cannot react to melee attacks
  • 1 = can react to melee attacks, if attacked from the front
  • 2 = can react to melee attacks, if attacked from any side
 0

The rest is defined in vars.rul (for TFTD), or left untouched at default values (for UFO:EU).

Value Description Default
doorSound Sound of normal doors opening. 3
slidingDoorSound Sound of sliding doors opening. 20
slidingDoorClose Sound of sliding doors closing. 21
smallExplosion Sound of a small explosion (power <= 80). 2
largeExplosion Sound of a large explosion (power > 80). 5
itemDrop Sound of item dropping (in the inventory). 38
itemThrow Sound of item being thrown. 39
itemReload Reload sound. 17
walkOffset Offset for various footstep sounds. 22
flyingSound Sound of a unit flying. 15
buttonPress Sound played when a button is pressed. 0
windowPopup Sounds played (one chosen randomly) when a window pops up. [1, 2, 3]
ufoFire Sound of a UFO firing. 8
ufoHit Sound of a UFO being hit. 12
ufoCrash Sound of a UFO crashing. 10
ufoExplode Sound of a UFO being destroyed. 11
interceptorHit Sound of an XCOM interceptor being hit. 10
interceptorExplode Sound of an XCOM interceptor being destroyed. 13
geoscapeCursor Palette offset for a cursor when using PAL_GEOSCAPE palette. 252
basescapeCursor Palette offset for a cursor when using PAL_BASESCAPE palette. 252
battlescapeCursor Palette offset for a cursor when using PAL_BATTLESCAPE* palettes. 144
ufopaediaCursor Palette offset for a cursor when using PAL_UFOPAEDIA palette. 252
graphsCursor Palette offset for a cursor when using PAL_GRAPHS palette. 252
goodDebriefingMusic Music played in the Debriefing when the score is positive. GMMARS
badDebriefingMusic Music played in the Debriefing when the score is zero or negative. GMMARS

Recommended/Fixed User Options

OpenXcom offers various settings in the [Options > Advanced] screen.

Some of these settings however are actually not user settings, but rather mod settings. Or in other words, some settings are either not compatible with some mods or change the mod balance in an unacceptable way. Therefore, OXCE gives modders the option to fix these settings. i.e. set them to a desired value and not allow users to change them.

All these fixed options are listed in "fixedUserOptions:". For example: 

 fixedUserOptions:
   battleUFOExtenderAccuracy: true
   battleInstantGrenade: false
   allowPsiStrengthImprovement: false

Since OXCE v6.5.1, there is also a possibility to only recommend some settings... meaning the settings will be changed only once by a mod (when activated) and the user will still be able to change the settings manually.

All these recommended options are listed in "recommendedUserOptions:". For example: 

 recommendedUserOptions:
   oxceNightVisionColor: 2
   oxceManufactureScrollSpeed: 5
   oxceManufactureScrollSpeedWithCtrl: 1
   oxceResearchScrollSpeed: 1
   oxceResearchScrollSpeedWithCtrl: 5

Below is a list of possible options to fix, their default English names and possible values, grouped by category.

  • There are more options (than listed below) in each category, but they are real user settings, so we don't list them here.
  • The codes are the same as used in options.cfg configuration file.

General

Code Name Possible values
playIntro Play intro; this is normally a user option. A modder working on a total conversion mod may want to disable it though. true/false

Geoscape

Code Name Possible values
aggressiveRetaliation Aggressive retaliation true/false
customInitialBase Custom initial base true/false
allowBuildingQueue Allow building queue; this is normally a user option. true/false
craftLaunchAlways Force craft launch true/false
storageLimitsEnforced Storage limits for recovered items true/false
canSellLiveAliens Live alien sale true/false
anytimePsiTraining Psionic training at any time true/false
psiStrengthEval Psi-Strength Evaluation true/false
canTransferCraftsWhileAirborne Airborne transfers true/false
retainCorpses Retain interrogated aliens true/false
fieldPromotions Field promotions; this is normally a user option. true/false

Battlescape

Code Name Possible values
sneakyAI Sneaky AI true/false
battleUFOExtenderAccuracy UFO Extender accuracy true/false
battleInstantGrenade Instant grenades true/false
includePrimeStateInSavedLayout Save pre-primed grenades true/false
battleExplosionHeight Explosion height 0-3
weaponSelfDestruction Alien weapon self-destruction true/false
allowPsionicCapture Allow psi-capture true/false
allowPsiStrengthImprovement Allow Psi-Strength Improvement true/false
strafe Alternate movement methods true/false
noAlienPanicMessages Suppress panic messages for aliens true/false
alienBleeding Alien bleeding true/false

Extended

Code Name Possible values
oxceStartUpTextMode Allows to modify the text that is displayed during the game start up. Possible options:
  • 0 = vanilla (default)
  • 1 = remove dos4gw and soundblaster text
  • 2 = remove all text
 0-2
oxceWoundedDefendBaseIf Wounded soldiers defend the base too, if their health is above the given percentage threshold. 0-100

Scripts

OXCE offers the ability to use a custom scripting language to modify game logic on certain places via script hooks.

Scripts that change game graphics are run every frame. Others like hitUnit are only run when the event itself happens.

Currently supported are (FIXME add short description to each hook):

  • Unit scripts
    • recolorUnitSprite: Runs for every pixel of a units graphic. Change to any color.
    • selectUnitSprite: Runs for every part of a units graphic. E.g. Change the graphic used for legs.
    • selectMoveSoundUnit: Runs for each unit step.
    • reactionUnitAction: Runs when an unit performs an action that triggers reaction fire.
    • reactionUnitReaction: Runs when a unit sees another unit perform an action that triggers reaction fire.
    • hitUnit: When a unit is hit it allows adjusting damage and the part of the body it affects. Runs before damageUnit
    • damageUnit: Used to alter the final change to stats of a unit when its hit by a weapon. If unit receives a hit with 0 power this script doesnt run.
    • healUnit: Used to alter effect of medikit on unit. Can alter exp from usage of it.
    • createUnit: Runs when new unit is created
    • newTurnUnit: Runs for every unit every turn (this includes alien, civilian and xcom turns)
    • returnFromMissionUnit: Runs for every unit at the end of a mission.
    • awardExperience: Runs whenever a unit performs an action that can earn it experience.
    • visibilityUnit: Runs to check if two units of opposing factions can see each other.
  • Item scripts
    • recolorItemSprite: Runs for every pixel of sprite. Change color.
    • selectItemSprite: Run to change the graphic of an item when its on the floor or in the hands of a soldier
    • reactionWeaponAction: Runs for the weapon that triggered reaction shots by firing.
    • createItem: Runs when a new item is created.
    • newTurnItem: Runs for each item each turn. (this includes alien, civilian and xcom turns)
  • Stat bonus scripts
    • For armors: psiDefence, meleeDodge, recovery (time, energy, morale, health, stun, mana)
    • For items: damageBonus, meleeBonus, accuracyMultiplier, meleeMultiplier, throwMultiplier, closeQuartersMultiplier
    • For units: applySoldierBonuses: Runs once for each bonus of each soldier on mission start.

The syntax of the scripting language and a detailed description of the capabilities of each script hook is beyond the scope of this reference guide. For more information, see ModScript (OpenXcom).

If you're interested, please seek help on:

Retrieved from "https://www.ufopaedia.org/index.php?title=Ruleset_Reference_Nightly_(OpenXcom)&oldid=91101"