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

From UFOpaedia
Jump to navigation Jump to search
Line 1,280: Line 1,280:
 
* 21 = [[Xarquid]]
 
* 21 = [[Xarquid]]
 
| 0
 
| 0
 +
|-
 +
| '''constantAnimation'''
 +
| Set it to "true" for units that constantly show an animation, such as: Biodrone, Celatid, Silacoid.
 +
| false
 
|-
 
|-
 
| '''movementType'''
 
| '''movementType'''

Revision as of 05:54, 24 August 2015

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.

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.


Globe

Defines the drawing of landmasses and borders on the globe.

Value Description Default
data Path name of 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 reliable shown on the globe = 7 or 9 values per entry. -
polylines List of border lines. Each list entry consist of a list of (x,y) globe coordinates. -
textures List of terrains that correspond to each Geoscape texture. Terrains can be restricted to certain areas on the globe with area: ([lon1, lat1, lon2, lat2]) and weight: NUMBER gives their chance of appearance. -

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 lat1 lon2 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, lat1, lon2, 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 "rectangles" ([lon1, lat1, lon2, lat2]) defining the mission zones for this region. Mission zones are waypoints for UFO trajectories.

Mission zone 3 defines cities belonging to a region ([lon1, lat1, lon2, lat2, -1, STR_CITY_NAME]). They will be displayed on the globe and used for terror site missions. Cities can also have a zoom setting which determines the appearance of its name label according to the specified zoom level.

-
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 not stack. 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 alienContainmentLimitEnforced 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. -1
hitSound Sound ID from GEO.CAT played when the base defense hits a target. -1
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.

modders: the corresponding extrasprite file id for BASEBITS.PCK is sprite+33 INTICON.PCK contains a minimized icon id=sprite the file id for the dogfight image is sprite+11

-1
fuelMax Maximum amount of fuel this craft can carry. Crafts use up fuel based on their speed while travelling. 0
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 Aceeleration 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
maxItems Amount of items this craft can carry. 80
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 refuelling 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 100% detection chance. 600
transferTime Number of hours it takes to purchase/transfer this craft to a base. 0
score Score lost when this craft is destroyed. 0
spacecraft Can this craft go to Cydonia? false
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.

-

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.

modders: the corresponding extrasprites file id for INTICON.PCK is sprite+5 and sprite+48 for BASEBITS.PCK

-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 meters). 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 30 mins while the craft is Rearming in base. If specified, clips are spent depending on their 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. -

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. -
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. 999
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 0.

0
power Average damage of the weapon, in most cases it will be +-50% this value. 0
strengthApplied Add the attacking unit's strength to this weapon's damage. false
compatibleAmmo List of string IDs of the ammo items that can be loaded on this weapon. If none are specified, the weapon doesn't need ammo. -
damageType What type of damage does this weapon do:
  • 0 - None
  • 1 - Armor Piercing
  • 2 - Incendiary
  • 3 - High Explosive
  • 4 - Laser
  • 5 - Plasma
  • 6 - Stun
  • 7 - Melee
  • 8 - Acid
  • 9 - Smoke

NOTE: A damage type other than 0-9 will do nothing.

0
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. 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
waypoint Does this weapon use waypoints? (eg. Blaster Launcher). Can also be used to make ammo items use the waypoint system. false
fixedWeapon Is this weapon fixed? (it's part of a unit, eg. tanks and terrorist units) false
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 heal's 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
specialType MCD value in map files to which this item corresponds for mission recovery. -
recover Is this item recoverable? (gets transported to the X-COM base on mission success) true
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
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
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
attraction Represents how likely an alien is to pick up this item. Values below 5 will be ignored (by design). 0
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
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
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
meleePower Damage this weapon will do when using melee. This only applies to Firearms, and is only available as stun damage. For normal melee weapons, use regular power and damage types. 0
LOSRequired Does this item require line of sight? (only applies to mind probes and psi-amps) false
skillApplied Is melee skill applied to the accuracy of an attack made with this object? true

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.

don't try to add more images if you don't want to punch yourself in the face - use modsprite

-1
modSprite Filename used to draw this UFO in the dogfight view and UFOpaedia. -
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 Aceeleration 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 meters). 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
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
type String ID of the inventory name. required
x

y

Pixel coordinates of this section on the inventory screen. 0

0

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

Terrains

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

Value Description Default
name String ID of the terrain name. required
mapDataSets List of filenames (each with matching MCD/PCK/TAB files) that contain the tiles of this terrain. -
mapBlocks List of map blocks (see below) that are used for generating a map. -
civilianTypes List of units to use as civilians for this mission. [MALE_CIVILIAN, FEMALE_CIVILIAN]

Map Blocks

Value Description Default
name Filename of the map. required
width Width of this map block in Battlescape grid units. 0
length Length of this map block in Battlescape grid units. 0
height Height of this map block in Battlescape grid units. 1
groups List (or single number) of groups this mapblock belongs to (used in mapscripts)

default usage:

  • 0 - Default
  • 1 - Landing Zone (for placing X-COM / alien craft) (used in addcraft/ufo command)
  • 2 - E-W Road (for city maps) (used in addline command)
  • 3 - N-S Road (for city maps) (used in addline command)
  • 4 - Road Crossing (for city maps) (used in addline command)
 0
revealedFloors Map block floor to be revealed from the very beginning; use a list "[0, 1, ..]" to reveal multiple floors
items An array of items to add to this mapblock, an the positions to place them at. -1
  • hemisphere only applies to UFO missions, not Terror ones.
  • width/length defines the size of the map
    • be aware that the mapview "width"-label is the openxcom ruleset length parameter
    • be aware that the mapview "length"-label is the openxcom ruleset width parameter

Guidelines/Tips

  • All maps with an XCOM/Alien craft require at least one map block assigned to Group 1. This map block can only contain ground tiles (no walls or objects), otherwise the game will crash or the walls/objects will be removed.
  • All Terror terrains (listed under STR_TERROR_MISSION) require the Groups of Types 2, 3 and 4 (for a total of 3 maps, which are required to place roads).

Map Scripts

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

Map Command

Value Description Default
type Currently these commands are implemented:
  • addBlock
  • addLine
  • addCraft
  • addUFO
  • digTunnel
  • fillArea
  • checkBlock
  • removeBlock
  • resize

depending on the command type some of the following parameters are needed

required
label A numeric label that can be used for conditional execution of commands.

Each label should be unique within the command list (0=default no need for uniqueness).

0
conditionals Defines the conditions that allows the execution of this command.

eg. [1, -4] means it will be executed if command with label 1 was a success and command with label 4 failed. commands that are not yet executed are always in failed state.

0
executionChances the chance that this command will be executed (or fails) 100
executions this command will be executed multiple times with a value > 1 1
groups Defines the what mapblock are used within this command. Can be list of goups or a single number. 0
blocks Alternative to groups. Here we define a list of mapblocks that are used within this command. 0
rects A list of possible ranges where (random) placement/checks/removal can happen in a map.

Is a list of a list of four integers, representing x/y/height/width.

full map [0,0,mapSize_X,mapSize_Y]
size size of mapblocks that can be placed/checked/removed within rects. Also used for resize command type. ?
freqs For a list of mapblocks (defined by blocks?) we can define distribution frequency here. 1
maxUses For a list of mapblocks (defined by blocks?) we can define the maximal amount a mapblock can be used here. -1
direction used for addLine command type. Values are both, horizontal or vertical. Typically defines the road type distribution. -1
tunnelData Parameter for digTunnel command type. Contains level (default: 0) and a list of MCD replacement rules (MCDReplacements) 0

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 the is 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 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 (ie: terror) 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 random. 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
  • "STR_THE_ULTIMATE_THREAT: true" means the mission would only run if the player has researched the ultimate threat.
  • "STR_TLETH_TH_ALIEN_CITY: false" means the mission would only run if the player has not researched Tleth.

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? true

Guidelines/Tips

Relevant ruleset files for editing missions are for a terror type mission:

  • missionScripts.rul
  • alienMissions.rul
  • alienDeployments.rul
  • ufoTrajectories.rul
  • regions.rul
  • globe.rul

alienDeployments.rul defines the mission site details the globe defines the terrain (id:-3) which references the deployment directly, because this is a terror site terrain. The region defines a number of city-style "points" (meaning the min/max values are the same for lat/lon) which use that terrain/texture. The trajectory points to these "points" as the mission site targets. The alienMission provides the link between the trajectory and the region in its waves, which spawn the site directly instead of an actual UFO/USO and finally the missionScript invokes the AlienMission.

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. -
spriteFaceGroup Pixel color group in palette that will be replace in unit graphic by new color, range form 1-15 (its skip first group). Used by face recoloring based on nationality. example:
6
spriteFaceColor New colors index for face pixels. 8 values ordered by:
  • Male Blond
  • Female Blond
  • Male Brown
  • Female Brown
  • Male Asian
  • Female Asian
  • Male African
  • Female African

Other units use random position form table. Value 0 mean original value.

example: 
 - 96
 - 96
 - 96
 - 96
 - 160
 - 160
 - 163
 - 163
spriteHairGroup Pixel color group in palette that will be replace in unit graphic by new color, range form 1-15 (its skip first group). Used by hair recoloring based on nationality. example:
9
spriteHairColor New colors index for hair pixels. 8 values ordered by:
  • Male Blond
  • Female Blond
  • Male Brown
  • Female Brown
  • Male Asian
  • Female Asian
  • Male African
  • Female African

Other units use random position form table. Value 0 mean original value.

example: 
 - 144
 - 144
 - 164
 - 164
 - 245
 - 245
 - 166
 - 166
spriteUtileGroup Pixel color group in palette that will be replace in unit graphic by new color, range form 1-15 (its skip first group). -
spriteUtileColor New colors index for pixels. 8 values ordered by:
  • Male Blond
  • Female Blond
  • Male Brown
  • Female Brown
  • Male Asian
  • Female Asian
  • Male African
  • Female African

Other units use random position form table. Value 0 mean original value.

-
spriteRankGroup Pixel color group in palette that will be replace in unit graphic by new color, range form 1-15 (its skip first group). -
spriteRankColor New colors index for pixels. For solders 6 values ordered by:
  • STR_ROOKIE
  • STR_SQUADDIE
  • STR_SERGEANT
  • STR_CAPTAIN
  • STR_COLONEL
  • STR_COMMANDER

For aliens 7 values ordered by (alien unit rank property):

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

Civilians uses random position form 8 element table. Value 0 mean original value.

-
corpseBattle List of string IDs of the corpse items generated when a unit wearing this armor is killed (one per unit tile) on the Battlescape. -
corpseGeo String ID of the corpse item associated with this unit on the Geoscape. -
storeItem String ID of the item that represents this armor in Base Stores for equipping. -
weight Physical weight of the armor when worn 6
stats like soldier stats (see below) but these are treated as stat bonuses for wearing the specific armor. -
frontArmor Protection provided on the front of the unit. 0
sideArmor Protection provided on the sides of the unit. 0
rearArmor Protection provided on the rear of the unit. 0
underArmor Protection provided under the unit (eg. from explosions). 0
drawingRoutine Drawing routine used to put together the body parts in the unit's spriteSheet: 0
constantAnimation Set it to "true" for units that constantly show an animation, such as: Biodrone, Celatid, Silacoid. false
movementType Type of movement provided by this armor:
  • 0 = Walking
  • 1 = Flying
  • 2 = Sliding (no walking animation)

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

0
damageModifier List of decimal damage modifiers (1.0 = 100%) this armor applies to each damage type (see Items section) received. Modifiers must be specified for all damage types, in this order:
  • None
  • Armor Piercing
  • Incendiary
  • High Explosive
  • Laser
  • Plasma
  • Stun
  • Melee
  • Acid
  • Smoke

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

size Size of the unit wearing this armor, in Battlescape grid units. Every unit is square, so a size of 2 means 2x2. 1
loftempsSet List of LOFTEMPS IDs (one per unit tile, so a 1x1 unit has 1, a 2x2 unit has 4, etc.) used to represent a unit wearing this armor in 3D space. -
loftemps loftemps is a deprecated option that only works for 1x1 sized units. -
forcedTorso soldier sprites have female and male torsos. some armours reuse these sprites for flying/non flying torso without difference between genders. This can be controlled by the parameter: 0 = use genderrelated torso, 1 = use male torso, 2 = use female torso 0

Player Units (Soldiers)

Defines a soldier recruited by X-COM, listed in "soldiers:". Currently only one soldier unit type (XCOM) is supported.

Unit stats are represented as follows:

Value Description Default
type String ID of the soldier name. required
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. -
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
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:

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
floatHeight Distance between the bottom of this unit and the ground. 0
value Score this unit is worth. 0
deathSound Sound ID from BATTLE.CAT played when this unit dies. -1
aggroSound Sound ID from BATTLE.CAT played when this unit aggros. -1
moveSound Sound ID from BATTLE.CAT played when this unit moves. -1
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 assault. Less aggressive units tend to set up ambushes.

Vanilla values are:

  • 0 = mostly passive
  • 1 = balanced
  • 2 = mostly aggresive
 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 (eg. Zombies respawn as Chrysallids). -
livingWeapon Is this unit a living weapon? (only attacks with a fixedWeapon) false
female Is this unit a female? (used for TFTD civilian types) false
meleeWeapon If this unit has a built in weapon, what is it? this weapon does not go in an inventory slot. (must reference an item) -
builtInWeapons A list of weapons this unit comes pre-equipped with. these WILL appear in inventory slots (references items) -

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 (eg. race units + terrorist units), defined by a list of unit string IDs. Order here will define rank in terms of deployment. generally speaking the order is:
  • 0 - Commander
  • 1 - Leader
  • 2 - Engineer
  • 3 - Medic
  • 4 - Navigator
  • 5 - Soldier
  • 6 - Terrorist 1
  • 7 - Terrorist 2

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

-
retaliation retaliation enables/disables the race for retaliation missions. True

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
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
terrains list of string IDs of the terrain to choose from to generate this map. This is not used for UFO sites where the terrain comes from the Geoscape. -
shade Shade of the map (0-15, where 0 is full daytime and 15 is full nighttime). This is not used for UFO sites where the shade comes from the Geoscape. 0
nextStage String ID of the next deployment stage to use after this one, for multi-stage missions. -
race Sets the race to use in the next stage. ""
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. -
alert String ID to use when this mission spawns on the Geoscape. -
markerName String ID that identifies this mission on the Geoscape. -
durationMin

durationMax

Minimum and maximum duration of this mission on the Geoscape (in hours).

I think these are deprecated; you should use duration.

-
duration [min, max] -- Minimum and maximum duration of this mission on the Geoscape (in hours). -
script Reference to a mapScript. -
data List of deployment data for each alien rank on this mission (see below). -
briefing Information about the mission briefing (see below). -

Notes:

  • terrains can also be used with UFOs, with the game using instead the listed terrain rather than the location of the UFO on Geoscape.

Deployment Data

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. 0
highQty Minimum quantity of aliens to spawn on superhuman. (minimum quantity for veteran/genius is the median of this and the previous value) 0
dQty Delta in Quantity. ie: random number of aliens to spawn on top of the minimum (all difficulties). 0
extraQty functionally identical to dQty, spawns a random number of additional aliens. 0
percentageOutsideUfo Percentage (0-100%) of aliens to spawn outside in UFO sites. 0
itemSets Three lists (one for each alien technology level) of items (string IDs) for the aliens to equip. required

Briefing Data

Value Description Default
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. -
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
music The ID of the music to play. "GMDEFEND"
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
cutscene Sets the cutscene to play before the mission briefing. -

Objectives Data

Used to define tile types towards objectives. Used for Alien Base Control Modules (UFO & TFTD), Synomium Devices (TFTD) and Alien Brain/T'Leth (UFO/TFTD).

Value Description Default
objectiveType Defines which type of MCD to check for when tallying mission objectives. -
objectivesRequired How many of the previous tile types must be destroyed in order for the mission to be considered a success. -
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. [string, int]
objectiveFailed The string and score adjustment to be shown on the mission debriefing. [string, int]
despawnPenalty How many points the aliens will receive when this site despawns due to XCom negligence. -
points How many points the aliens will receive each half hour that the mission site stays active. Does not stack with despawnPenalty. -

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 (or item, if a lookup is defined). required
lookup String ID of the research project's display name and UFOPaedia article reference. -
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
needItem Does this project require an item of the same name? false
dependencies List of research projects that can unlock access to this one. If the full list is researched, or if one of the projects on the list "unlocks" this one, it becomes available. -
unlocks List of research projects unlocked, regardless of other dependencies, but not requirements, by completing this project (for example, any live alien unlocks "alien origins"). -
requires List of research projects unilaterally required before this project can be unlocked (for example, "the martian solution" will not even be considered for unlocking until AFTER "alien origins" is completed). -
getOneFree List of "bonus" research projects that may be granted when completing this project (for example, alien medics will give you information on other alien races). Used in Alien Navigators (gives random alien Mission), Medics (random alien interrogation or autopsy) or Engineers (gives UFO type). -
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. -

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 (and the item it produces). required
category String ID of the manufacturing project's 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 (on average) required per item. 0
cost Monetary deduction per item manufactured. 0
requiredItems List of items required and consumed per item manufactured. -
producedItems List of items produced per each item consumed. If not specified, defaults to 1 item with the same string ID as the manufacture. 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: 0
section String ID of the UFOpaedia section this article belongs in. -
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. 150
rect_stats Rectangle (x, y, width, height) of the stats text on the screen, only applicable to Craft articles. 0
rect_text Rectangle (x, y, width, height) of the description text on the screen, only applicable to Craft articles. 0
weapon String ID of the weapon, only applicable to HWP 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. 0
waypoints List of waypoints for the UFO to traverse, defined as [zone, altitude, speed].

zone: Globe zone where the waypoint is located.
altitude: UFO altitude after reaching this waypoint:

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

speed: UFO speed after reaching this waypoint, as a percentage (0-100%) of its maximum speed.

-

Alien Missions

Defines an alien 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
objective Missions are split by objective:
  • 0 = score (default if omitted)
  • 1 = infiltration
  • 2 = alien base
  • 3 = mission site (terror etc)
  • 4 = retaliation
  • 5 = supply
 0
spawnZone mission zone to use when spawning mission sites / alien bases. -
spawnUfo UFO to spawn for retaliation. -
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 List of UFO waves to spawn as this mission progresses, as described below. 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 seconds) 0
objective true Marks this wave as the one that carries out the mission objective. Only for mission site / supply missions. -

Alien Item Levels

This is a list of item level probabilities, with a number between 0 and 2 representing an item level from plasma pistols to heavy plasmas, as defined in the deployments, expressing a 10% probability for that item level being used.

0 = first set (plasma pistol/clip) 1 = second set (plasma rifle/clip) 2 = third set (heavy plasma/clip)

For example: [ 2, 0, 0, 0, 0, 0, 0, 1, 1, 1 ] would represent a 60% chance for pistols, 30% rifles, and 10% heavy weapons.
Note that the order does not matter, but the length DOES. each line MUST have 10 digits.

The above can be confusing. There are 10 fields; each number represents 10%.
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

Each line represents a month after the beginning of the game, and there is no limit to the number defined.
OpenXCom will use the most recently available item level in the event the game goes on forever.

Extra Sprites

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

Value Description Default
type Filename of the original/new image to modify. required
width

height

Size of the sprite(s) in pixels. 0

0

singleImage Is the image file just a single sprite (true) or a spritesheet (false)? false
subX

subY

Size of the subdivision in pixels. If a subdivision is specified, then the image file is divided into chunks to form the sprites (eg. spritesheets). 0

0

files List of the new sprites to add/replace, listed as spriteID: filename. -

Example: 

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

Extra Sounds

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

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

Example: 

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

Music

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

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, sans 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: Магазин к снайп. винтовке

Interfaces

Value Description Default
type ? -
elements ? -
id ? -
color ? -

StatStrings

Statstrings are used for automatically renaming soldiers. They are case sensitive and they are processed in the order in which they are specified.

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

psiSkill
bravery
strength
firing
reactions
stamina
tu
health
throwing

One or more stat ranges are ANDed together for success. Each range has a minVal and maxVal. Use YAML standard tilde (~) to indicate null. ((~) = 0 as minvalue; (~) =255 as maxvalue) -

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]

Font

Defines the font collection used by default.

Value Description Default
fontName Name of *.dat file, placed in Language folder, which describes used font collection. Font.dat

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 is cutscene is a video playlist
slideshow Info for playing a slideshow (see below). required if this is 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 faster by clicking. 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. The palette for the slide is taken from the image, so caption text color will be determined by the image palette. required
caption The string ID of the caption text. -
captionSize The size of the text box, in pixels, in which to display the caption. [320, 200]
captionPos The screen position at which to display the caption. [0, 0]
captionColor The palette index to use for the caption color. required

References

<references />

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