Ruleset Reference Nightly (OpenXcom)
A reference of all the customizable values of everything in a ruleset, according to the latest nightly. This page should be updated as new versions become available in order to explain the changes from version 1.0.
- Last full review: 27th December 2018, by Meridian
- Synchronized with: OpenXcom v1.0 (2018-12-26 nightly build)
Update of the ruleset reference with new ruleset added in OpenXcom Extended (OXCE) is currently in progress.
The new ruleset is highlighted using light green background, just like the one used in this disclaimer. ETA for the update is 6th January 2019. -- Meridian
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. You can find the default listOrders in Ruleset List Order.
Starting Base
Defines the content of the base at the start of game.
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:
|
- |
polylines | List of border lines. Each list entry consist of a list of (x,y) globe coordinates.
Note that:
|
- |
textures | List of textures that determine the battlescape appearance of a certain place on the globe. Textures can be:
Note that:
|
- |
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 |
Countries
Defines one of the funding nations, listed in "countries:". They're used for activity graphs and player scoring.
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 |
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. | - |
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. | - |
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:
Zones used for mission site spawning additionally have:
Example: ([lon1, lon2, lat1, lat2, textureID, STR_CITY_NAME]). |
- |
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 |
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. | - |
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. | -1 |
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 |
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 |
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 |
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 |
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 |
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 |
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. | - |
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. | - |
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:
|
-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 |
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 |
weapons | Amount of craft weapons this craft can equip. The UI can only display a max of 2 weapons. | 0 |
soldiers | Amount of soldiers this craft can carry. | 0 |
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 |
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 |
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 |
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. | - |
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. |
- |
spacecraft | Can this craft go to Cydonia? | false |
maxAltitude | Maximum altitude (0-4) this craft can dogfight to. | -1 |
maxItems | Amount of items this craft can carry. | 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 |
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:
|
-1 |
sound | Sound ID from GEO.CAT played when this weapon fires. | -1 |
damage | Amount of damage this weapon does to enemy UFOs. | 0 |
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 |
Items
Defines the Geoscape and Battlescape properties of an item that can be stored in X-COM bases, listed in "items:".
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. | =type |
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. | - |
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 |
weight | Weight occupied by this item in a soldier's inventory. | 3 |
bigSprite | Sprite ID from BIGOBS.PCK used to draw this item in a soldier's inventory and UFOpaedia. | -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 |
fireSound | Sound ID from BATTLE.CAT played when this weapon fires. | -1 |
hitSound | Sound ID from BATTLE.CAT played when this weapon hits a target. | -1 |
hitAnimation | Sprite ID from SMOKE.PCK used to draw the weapon's "hit explosion".
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 |
meleeSound | Sound ID from BATTLE.CAT played when this weapon attacks a target with melee. | 39 |
meleeHitSound | Sound ID from 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 |
power | Weapon power. Usually corresponds to weapon's average damage. For some weapons/items, it determines the range (e.g. for incendiary). | 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. | - |
damageType | What type of damage does this weapon do:
NOTE: A damage type other than 0-9 will do nothing. |
0 |
tuAuto
accuracyAuto |
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 |
tuSnap
accuracySnap |
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 |
tuAimed
accuracyAimed |
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.
The base accuracy (0-100%) applied to a soldier's Firing Accuracy when firing an Aimed Shot. |
0
0 |
tuMelee
accuracyMelee |
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. 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 |
battleType | Defines the weapon's behavior in the Battlescape:
|
0 |
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 |
fixedWeapon | Is this weapon fixed? (it's part of a unit, eg. tanks and terrorist units) | false |
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 |
invWidth | Item width in a soldier's inventory (in grid units). | 1 |
invHeight | Item height in a soldier's inventory (in grid units). | 1 |
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 |
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 |
recoveryPoints | Score gained for recovering this alien artifact. | 0 |
armor | How much damage is needed to destroy this item on the ground. | 20 |
turretType | Sprite ID from TANKS.PCK of the turret to assign to this tank:
|
-1 |
recover | Is this item recoverable? (gets transported to the X-COM base on mission success) | true |
liveAlien | Does this item represent a live alien? (counts towards Alien Containment) | 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 Explosion calculations). | -1 |
attraction | Represents how likely an alien is to pick up this item. Values below 5 will be ignored (by design). | 0 |
flatRate | If true, then TU costs for this weapon are a flat rate (instead of a percentage of unit TUs). | false |
arcingShot | Does this weapon fire in an arc? | false |
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 |
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 |
autoShots | How many auto shots does this weapon fire. | 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. Chrysallids turn units into Zombies). | none |
strengthApplied | Add the attacking unit's strength to this weapon's damage. | false |
skillApplied | Is melee skill applied to the accuracy of an attack made with this object? | true |
LOSRequired | Does this item require line of sight? (only applies to mind probes and psi-amps) | false |
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 |
underwaterOnly | Can this item only be used underwater? | false |
landOnly | Can this item only be used on land? | false |
specialType | MCD value in map files to which this item corresponds for mission recovery. | -1 |
vaporColor | The color offset (0-15) 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 |
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 |
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 |
accel | Acceleration value shown in the UFOpaedia. | 0 |
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 |
sightRange | UFO's sight range (for detecting X-COM bases) in nautical miles. | 268 |
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 |
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 |
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. | - |
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 |
script | The map generation script name. | DEFAULT |
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:
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. | - |
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:
|
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 |
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. | - |
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.
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 |
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 |
researchTriggers | A list of research topics that can influence the execution of this mission. For example
Several research triggers can be combined and for the mission to appear all must be fulfilled. |
0 |
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.)
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 |
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, do not use! | - |
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.
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. | - |
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 |
movementType | Type of movement provided by this armor:
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 |
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. | 0 |
visibilityAtDay | How far can the unit wearing this armor see during the day. | 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:
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 |
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, for backwards-compatibility only. Works only for 1x1 units! | - |
deathFrames | Number of "death frames" = sprites in the death animation sequence. | 3 |
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:
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:
For aliens, a list of 7 values corresponding to the following alien ranks:
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 |
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. | <= |
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 |
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
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:
- tu
- stamina
- health
- bravery (always a multiple of 10)
- reactions
- firing
- throwing
- strength
- psiStrength
- psiSkill
- melee
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. | - |
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). | - |
armor | String ID of the armor this soldier uses by default. | - |
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 |
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 |
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. | - |
soldierNames | List of soldier name files/paths. Use delete to clear previously-loaded names. | - |
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:
- tu
- stamina
- health
- bravery (always a multiple of 10)
- reactions
- firing
- throwing
- strength
- psiStrength
- psiSkill
- melee
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). | - |
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 |
intelligence | Intelligence of this unit's AI. The higher the value, the longer this unit remembers player troops between turns. | 0 |
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 |
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 |
builtInWeaponSets | A set of lists of weapons this unit can come pre-equipped with. Game will pick one set at random. These weapons WILL appear in inventory slots (references items). | - |
builtInWeapons | Deprecated, for backwards-compatibility only. Please use builtInWeaponSets. | - |
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. | - |
aggroSound | Sound ID from BATTLE.CAT played when this unit aggros. | -1 |
moveSound | Sound ID from BATTLE.CAT played when this unit moves. | -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:
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:
Does not apply to anything else (that depends on alien deployment), for example:
|
- |
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 |
startingCondition | String ID of a starting condition for missions using this deployment. | - |
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 |
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. | - |
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 |
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 |
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 |
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". | - |
The following group of attributes is related to mission objectives (listed in a separate table just for convenience).
Value | Description | Default |
---|---|---|
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 |
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. Can have three settings: 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 |
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 |
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
Starting conditions can be defined on alien deployments and on terrains:
- effects before a mission are always taken from the alien deployment (since terrain is yet unknown)
- effects during a mission are taken from the terrain in case a starting condition is defined on both deployment and terrain
Value | Description | Default |
---|---|---|
type | String ID of the starting condition. | 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 effects (one for each faction: STR_FRIENDLY, STR_HOSTILE or STR_NEUTRAL), see below. Environmental effects 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 no longer checked if it is allowed or not and it is not replaced with default armor either, see below. |
- |
defaultArmor | If a soldier's armor is not allowed on a mission (see allowedArmors 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 | A list of allowed armors for a mission. If empty, all armors are allowed. | - |
allowedVehicles | A list of allowed vehicles (HWP/SWS) for a mission. The rest will stay at the base. If empty, all vehicles are allowed. | - |
allowedItems | A list of allowed items (weapons, equipment, etc.) for a mission. | - |
allowedItemCategories | A list of allowed item categories (categories are freely definable by modders) for a mission. This is used to simplify/shorten the definition of allowed items.
Note: if both allowedItems and allowedItemCategories are empty, all items are allowed. Not allowed items will stay at the base. |
- |
allowedCraft | A list of allowed craft for a mission. Other craft cannot target the mission at all. If empty, all craft are allowed. | - |
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 |
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 |
---|---|---|
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
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. | - |
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"). | - |
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). | - |
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. | - |
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. | - |
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 |
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 |
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:
|
required |
section | String ID of the UFOpaedia section this article belongs to. | - |
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. | - |
image_id | Filename of the background image displayed on this article, if applicable. | - |
text | String ID of the description displayed on this article. | - |
text_width | Maximum width of the text displayed, only applicable to Text & Image 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. | - |
weapon | String ID of the weapon, only applicable to HWP/SWS articles. | - |
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).
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 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 |
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 |
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 |
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:
|
0 |
objective | true Marks this wave as the one that carries out the mission objective. Only for mission site / supply missions. | - |
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
- 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
Value | Description | Default |
---|---|---|
type | Name of the original sprite/spritesheet to modify or new sprite/spritesheet to create. | required |
files | List of the new sprites to add/replace, listed as spriteID: filepath. | - |
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.
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:
|
required |
files | List of the new sounds to add/replace, listed as soundID: filepath. | - |
Example:
- type: BATTLE.CAT files: 55: Resources/Sounds/sample.wav
Warning for adding .wav files: the game works with low bitrate, uncompressed mono PCM wav. Any other format is likely to not work.
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. | - |
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). | - |
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 |
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). | - |
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 |
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.
Game Parameters
In vanilla ruleset files, these are located in vars.rul.
Value | Description | Default |
---|---|---|
startingTime | Specifies the date and time at the beginning of the game. | Friday 1.1.1999 12:00:00 |
costEngineer | Monthly salary of a single engineer (in dollars). Please note that hiring cost is twice as much. | 0 |
costScientist | Monthly salary of a single scientist (in dollars). Please note that hiring cost is twice as much. | 0 |
timePersonnel | Time (in hours) it takes for newly hired personnel to arrive at a base. | 0 |
initialFunding | Amount of money (in thousands of dollars) the player starts with. | 0 |
alienFuel | Name of an item representing alien fuel and a quantity to recover from a single fuel cell. Format: [name, quantity]. | [-, -] |
fontName | Name of *.dat file, placed in Language folder, which describes used font collection. | Font.dat |
Difficulty Settings
In vanilla ruleset files, these are located in difficulty.rul.
Value | Description | Default |
---|---|---|
difficultyCoefficient | Difficulty coefficients (per 5 game difficulty levels) affecting various game mechanics, for example:
|
[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. | - |
turnAIUseGrenade | Defines a turn, from which the aliens are allowed to use explosives. | 3 |
turnAIUseBlaster | Defines a turn, from which the aliens are allowed to use waypoint-based weapons. | 3 |
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 a list of values 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] |
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 |
explosionOffset | Explosion offset in X1.PCK | 0 |
smokeOffset | Surface smoke animation offset in SMOKE.PCK | 8 |
underwaterSmokeOffset | Underwater smoke animation offset in SMOKE.PCK | 0 |
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 |