DID YOU KNOW?
OpenXcom (and also OpenXcom Extended) have a ruleset syntax validation and auto-completion tool (a plugin for VSCode), which automatically finds and highlights all your syntax errors.
More info: https://openxcom.org/forum/index.php/topic,6552.0.html
Give it a try!
A reference of the customizable values of everything in a ruleset, according to the latest OpenXcom nightly.
IMPORTANT: The OpenXcom Extended (OXCE) ruleset is highlighted using light green background, just like the one used in this disclaimer. Anything marked green does not work with OpenXcom (OXC).
Some guidelines:
items: - &STR_LASER_RIFLE # Let's mark laser rifle info with an anchor type: STR_LASER_RIFLE size: 0.2 costSell: 36900 weight: 8 # # a million other attributes... # - type: STR_LASER_SNIPER_RIFLE refNode: *STR_LASER_RIFLE # First, let's inherit everything from the STR_LASER_RIFLE anchor. bigSprite: xxx # And now let's give it a new sprite, accuracyAimed: 160 # increase aimed shot accuracy tuAuto: 0 # and disable auto shot.
Defines the content of the base at the start of game.
If you don't define some of them, the default starting base will be used instead of the missing ones.
The default starting base will also be used for New Battle screen.
| Value | Description | Default |
|---|---|---|
| randomSoldiers | Determines number and type of starting X-Com soldiers.
If a mod contains more than one type of soldiers, this can also be specified with: randomSoldiers: STR_SOLDIER: 3 STR_ANOTHER_SOLDIER: 7 |
0 |
| scientists | Determines number of starting scientists. | 0 |
| engineers | Determines number of starting engineers. | 0 |
| facilities | List of starting base facilities and their position (x and y coordinates being 0-5). | - |
| items | List of starting items in the base, excluding items on crafts. | - |
| crafts | List of starting crafts in the base and items on board. | - |
OpenXcom uses the same format to define a starting base as for saving/loading a real base (except for randomSoldiers attribute). That means you can also define various other parameters in your mod, for example:
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 |
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 globe textures that determine the battlescape appearance of a certain place on the globe. | - |
| countryColor | Color of the country labels (0-255). | 239 |
| cityColor | Color of the city labels (0-255). | 138 |
| baseColor | Color of the xcom base labels (0-255). | 133 |
| lineColor | Border line color (0-255). | 162 |
| oceanPalette | Color range (defined as palette offset) of the "oceans", or better said of the "globe sections not covered by polygons" (0-15). | 12 |
| oceanShading | Whether ocean shading (32-color) should be used or not.
Notes:
|
true |
| Value | Description | Default |
|---|---|---|
| id | ID of the texture.
|
required |
| terrain | List of terrains (can be more than one) that correspond to each Geoscape texture.
Terrains can be restricted to certain areas on the globe with area: ([lon1, lon2, lat1, lat2]) and weight: NUMBER that gives their chance of appearance. These textures are primarily used for UFO landing/crash sites. Example 1: globe: textures: - id: 0 terrain: - name: FOREST area: [0, 360, -90, 0] - name: JUNGLE area: [0, 360, 0, 90] Example 2: globe: textures: - id: 11 terrain: - name: PIPES weight: 50 - name: SEABED weight: 25 - name: CORAL weight: 25 |
- |
| deployments | Defined by weighted alien deployments (can be more than one), which determine appearance for mission sites (e.g. terror sites, artifact sites, shipping lanes, etc.).
Example: globe: textures: - id: -4 deployments: STR_CARGO_SHIP_P1: 50 STR_CRUISE_SHIP_P1: 50 |
- |
| baseTerrain | In OXCE, the terrain-based textures can additionally have separate terrain defined for base defense missions.
This terrain can be used in map scripting to replace the generic "dirt" blocks with something more fitting (e.g. snow in the arctic or jungle near the equator). More info: https://openxcom.org/forum/index.php/topic,5108.0.html |
- |
| startingCondition | In OXCE, the textures can have their own starting conditions (with lower priority than deployment starting conditions). | - |
| fakeUnderwater | In OXCE, the (land) textures can also be flagged as fake underwater textures using this boolean attribute.
Such terrain can support underwater missions, underwater bases/facilities and have separate starting conditions. More info: https://openxcom.org/forum/index.php/topic,7374.msg116684.html#msg116684 |
false |
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 |
| labelColor | Color (0-255) of the country label. | 0 (not used) |
| areas | List of "rectangles" on the globe defined as [lon1 lon2 lat1 lat2]. Any activity within these areas counts towards the country's graph activity and affects their opinion of the player. | - |
| zoomLevel | Minimum globe zoom level at which this extra globe label becomes visible.
Note: doesn't work for countries. Only for extra globe labels. |
0 |
Defines one of the world regions, listed in "regions:". They're used for base placement, activity graphs and mission spawning.
| Value | Description | Default |
|---|---|---|
| type | String ID of the region name. | required |
| cost | Amount of money spent building an X-COM base in this region (first base is free). | 0 |
| areas | List of "rectangles" on the globe defined as [lon1, lon2, lat1, lat2]. Any activity within these areas counts towards the region's graph activity.
Example: regions: - type: STR_EUROPE areas: - [335, 60, -70, -35] |
- |
| regionWeight | Weight of this region when selecting regions for alien missions. | 0 |
| missionWeights | Weighted list of the different mission types for this region (eg. STR_ALIEN_RESEARCH: 14). | - |
| missionZones | List of mission zones. Mission zones are used for generating waypoints for UFO trajectories, and also for spawning mission sites and alien bases. Each mission zone itself is a list of "mission areas", where each mission area is defined by:
Zones used for mission site spawning additionally have:
Example: ([lon1, lon2, lat1, lat2, textureID, STR_CITY_NAME]). Important: Crossing the prime meridian in missionZones requires a different syntax! (lon2 cannot be smaller than lon1) Wrong example: [350, 8, 20, 30] Correct example: [350, 368, 20, 30] # 368 (=8+360) also represents 8 degrees, and satisfies the lon2 >= lon1 condition PS: This syntax exception does not apply to areas. |
- |
| missionRegion | Spawn mission in this region instead (used for regions without land). | - |
Defines one of the facilities that can be built in an X-COM base, listed in "facilities:".
| Value | Description | Default |
|---|---|---|
| type | String ID of the facility name. | required |
| fakeUnderwater | Defines whether the facility can be built in a standard base, fake underwater base (used by hybrid mods), or both.
Possible options:
|
-1 |
| requires | List of topics (string IDs) that must be researched to unlock this facility. If none are specified, this facility is unlocked from the start. | - |
| requiresBaseFunc | A list of services required to build this facility. | - |
| provideBaseFunc | A list of services this facility provides after being built. | - |
| forbiddenBaseFunc | A list of services that cannot be used anymore after this facility is built. | - |
| spriteShape | Sprite ID from BASEBITS.PCK used to draw the facility's outer shape in the Basescape and UFOpaedia. | -1 |
| spriteFacility | Sprite ID from BASEBITS.PCK used to draw the facility's contents in the Basescape and UFOpaedia. Drawn on top of spriteShape. Not required for buildings size 2 or larger. | -1 |
| missileAttraction | A weight (i.e. not a percentage) of how likely will alien missiles/bombardments hit this type of facility. | 100 |
| destroyedFacility | String ID of the destroyed version of this facility (must have the same size).
Note: destruction can happen either in Base Defense mission or via Alien missiles/bombardment. |
- |
| lift | Is this facility an Access Lift? All base facilities must be connected to the lift. | false |
| hyper | Is this facility a Hyperwave Decoder? Displays extra information for detected UFOs. Only valid for radar facilities. If "true", the radar detection chance will be taken from radarChance value. | false |
| mind | Is this facility a Mind Shield? Reduces the chance of UFOs finding your base. Does stack (detection chance is inversely proportional to the number of mind shields). | false |
| mindPower | The power of the mind shield provided by this facility. | 1 |
| grav | Is this facility a Grav Shield? Doubles the power of your base defenses. Does not stack. | false |
| size | Size of the facility, in grid units. Every facility is square, so a size of 1 means 1x1, 2 means 2x2, etc. Bigger facilities are made up of multiple sprites, for example a 2x2 facility will use 4 sprites for spriteShape and 4 sprites for spriteFacility (top-left, top-right, bottom-left, bottom-right). | 1 |
| buildCost | Amount of money spent to build this facility in the base. | 0 |
| refundValue | Amount of money refunded when the facility is dismantled. | 0 |
| buildCostItems | Items needed to build a facility and items "refunded" when the facility is dismantled.
- type: STR_MY_FACILITY buildCostItems: STR_ALIEN_ALLOYS: build: 100 refund: 75 STR_ALIEN_ENTERTAINMENT: build: 1 refund: 1 |
- |
| buildTime | Amount of days it takes for this facility to be built. | 0 |
| monthlyCost | Amount of money spent monthly for the maintenance of this facility. | 0 |
| storage | Amount of storage space (for items) this facility provides. See Base Stores. | 0 |
| storageTiles | A list of tile positions where to place items in this facility's storage. If empty, vanilla checkerboard pattern will be used. | - |
| personnel | Amount of personnel (soldiers, scientsts, engineers) these quarters can contain. | 0 |
| aliens | Amount of live aliens this facility can contain. Only checked if the storageLimitsEnforced option is enabled. | 0 |
| prisonType | What type of prisoners (aliens) can be held in this facility.
More info: https://openxcom.org/forum/index.php/topic,4830.msg69933.html#msg69933 |
0 |
| crafts | Amount of X-COM craft this facility can contain. | 0 |
| labs | Amount of lab space this facility provides for research projects. | 0 |
| workshops | Amount of workshop space this facility provides for manufacture projects. | 0 |
| psiLabs | Amount of soldier space this facility provides for psionic training. | 0 |
| trainingRooms | Amount of soldier space this facility provides for combat/martial training. | 0 |
| radarRange | Maximum radar detection range of this facility, in nautical miles. | 0 |
| radarChance | Chance (0-100%) of this radar detecting a UFO that enters its range. | 0 |
| defense | Offensive power provided by this base defense against attacking UFOs. | 0 |
| hitRatio | Chance (0-100) of the base defense hitting an attacking UFO. | 0 |
| fireSound | Sound ID from GEO.CAT played when the base defense fires. | 0 |
| hitSound | Sound ID from GEO.CAT played when the base defense hits a target. | 0 |
| mapName | Map associated to this facility in Battlescape base defenses. | - |
| verticalLevels | Can be used instead of mapName. Allows generating a base facility map as if it were an addBlock map script command.
More info: https://openxcom.org/forum/index.php/topic,5316.0.html |
- |
| maxAllowedPerBase | Maximum number of facilities of this type allowed to be built per base. | 0 (not used) |
| manaRecoveryPerDay | How much mana does the facility recover per day. The facility setting is NOT cumulative, more facilities don't provide more regen. If there are multiple facilities of different type with different regen rate, the best (highest) regen rate is used. | 0 |
| sickBayAbsoluteBonus sickBayRelativeBonus |
How much additional HP is healed per day.
- type: STR_FIELD_HOSPITAL sickBayAbsoluteBonus: 0.75 sickBayRelativeBonus: 0.0 - type: STR_SURGERY_ROOM sickBayAbsoluteBonus: 0.25 sickBayRelativeBonus: 1.0 - type: STR_REGENERATION_ROOM sickBayAbsoluteBonus: 0.0 sickBayRelativeBonus: 10.0 - type: STR_GOAULD_SARCOPHAGUS sickBayAbsoluteBonus: 90.0 sickBayRelativeBonus: 0.0 Examples, considering the ruleset above:
|
0.0 0.0 |
| leavesBehindOnSell | A facility to leave behind a dismantled facility (must be of the same size); or a list of 1x1 facilities to fill in the old facility's place. | - |
| removalTime | How long facilities left behind when this one is sold should take to build.
Possible options:
|
0 |
| canBeBuiltOver | Can this facility be built over? | false |
| buildOverFacilities | A list of other base facilities this one can be built over. If empty, it can be built over anything with canBeBuiltOver: true. | - |
| rightClickActionType | Which screen should open when R-clicking on this facility in the base view?
Possible options:
|
0 |
Defines one of the X-COM crafts that go on interception missions, listed in "crafts:".
| Value | Description | Default |
|---|---|---|
| type | String ID of the craft name. | required |
| requires | List of topics (string IDs) that must be researched to unlock this craft. If none are specified, this craft is unlocked from the start. | - |
| requiresBuyBaseFunc | A list of services required to buy this craft. | - |
| sprite | Sprite ID from BASEBITS.PCK used to draw this craft in the Basescape and from INTICON.PCK used to draw the damage indicator in dogfights.
Note that:
|
-1 |
| marker | Sprite ID from GlobeMarkers spritesheet, used for drawing craft icon on the globe. Usually 3x3 pixels, but can be modded to be bigger.
Note: if not modded, sprite id 1 is used (=vanilla craft marker) |
-1 |
| weapons | Amount of craft weapons this craft can equip. The UI can only display a max of 2 weapons.
In OXCE, you can have up to 4 weapons (or other accessories) |
0 |
| weaponTypes | A list defining compatible weapon types for this craft type. Up to 4 slots, and each slot can have up to 4 compatible weapon types.
Example: [0, [0, 1], [2,3], [0,2,4]] |
[0, 0, 0, 0] |
| weaponStrings | A list describing the craft's weapon slots (up to 4 slots). | [STR_WEAPON_ONE, STR_WEAPON_TWO] |
| soldiers | Amount of soldiers this craft can carry. | 0 |
| pilots | How many pilots are required to pilot this craft.
Notes:
|
0 |
| allowLanding | Should this craft be able to start a Battlescape mission?
Note: you may want to set false to your manned/piloted interceptors. |
true |
| vehicles | Amount of vehicles this craft can carry. | 0 |
| costBuy | Amount of money spent for purchasing this craft. If set to 0, the craft will not be available in the Purchase/Recruit screen. | 0 |
| costRent | Amount of money spent monthly for renting this craft. If set to 0, the craft is not on rental and won't count towards base maintenance. | 0 |
| costSell | Amount of money gained for selling this craft. | 0 |
| forceShowInMonthlyCosts | Forces this craft type to appear in Monthly Costs breakdown, even if not present at the base.
Note: Skyranger, Interceptor, Triton and Barracuda have this turned on (for backwards-compatibility). |
false |
| refuelItem | Item required for refueling this craft. If no item is specified, the craft uses human fuel. | 0 |
| repairRate | Amount of damage restored every hour while Repairing in base. | 1 |
| refuelRate | Amount of fuel restored every 30 mins while Refueling in base. If specified, a refuelItem is spent each time. | 1 |
| transferTime | Number of hours it takes to purchase/transfer this craft to a base. | 0 |
| score | Score lost when this craft is destroyed. | 0 |
| battlescapeTerrainData | Terrain associated to this craft in Battlescape missions. | - |
| craftInventoryTile | Coordinates [x, y, z] of the craft inventory tile (weapon's pile) in the craft. If not specified, tile occupied by the first soldier is used. | - |
| mapVisible | Should the craft map be visible at the beginning of the battle? Used for some funky effects (see W40k mod for examples). | true |
| deployment | Custom positions for the unit deployment in the craft, listed as: [x, y, z, facing]
If not specified, units are placed on empty spots from top-left to bottom-right facing top-right. |
- |
| keepCraftAfterFailedMission | Defines whether the craft should be lost after a failed mission or not. Useful for example to implement paratroopers; or any kind of troop deployment without a craft physically being on the map. | false |
| spacecraft | Can this craft go to Cydonia? | false |
| notifyWhenRefueled | Should a pop up window inform the player once this craft is fully refueled? | false |
| autoPatrol | Should this craft automatically return to its patrol destination after refueling? | false |
| maxAltitude | Maximum altitude (0-4) this craft can dogfight to. | -1 |
| maxItems | Amount of items this craft can carry. | 0 |
| shieldRechargedAtBase | How many shield points are recharged when landed at base per hour. | 1000 |
The following attributes define so called "craft stats". They are listed in a separate table, just for convenience... but are still part of the Craft ruleset.
Note: In OXCE, all these stats are dynamic, i.e. can be modified by equipping craft weapons/accessories.
| Value | Description | Default |
|---|---|---|
| fuelMax | Maximum amount of fuel this craft can carry. Crafts use up fuel based on their speed while traveling. | 0 |
| damageMax | Maximum amount of damage this craft can take. If this amount is exceeded, the craft is destroyed. | 0 |
| speedMax | Maximum speed in nautical miles. Crafts travel at max speed when flying and half speed when patrolling. | 0 |
| accel | Acceleration value shown in the UFOpaedia. | 0 |
| radarRange | Detection range of the craft's radar in nautical miles. Every craft radar has a detection chance dependent on its radarChance. | 672 |
| radarChance | Chance (0-100%) of this craft radar detecting a UFO that enters its range. | 100 |
| sightRange | Range at which the craft can detect alien bases in nautical miles. | 1696 |
| hitBonus | Flat bonus percentage to hit chances of all equipped weapons. | 0 |
| avoidBonus | Flat bonus percentage to dodge chances against enemy fire. | 0 |
| powerBonus | Multiplier for the power of craft weapons, e.g. 20 = weapons' power increased to 120% of their original power, -20 = decreased to 80%. | 0 |
| armor | Amount of blocked damage per hit. | 0 |
| shieldCapacity | Craft's maximum shield capacity. | 0 |
| shieldRecharge | Defines the percent chance of recharging a point of shielding per game second (GS) during a Dogfight. Values under 100 are the percent chance, for over 100, every +100 means an automatic +1 to shields per GS. Thus shieldRecharge: 250 means +2 shields/GS, with a 50% chance of +1 more. | 0 |
| shieldRechargeInGeoscape | Similar to shieldRecharge, but acts every 5 seconds in the Geoscape. Giving it a value of -1 means instant recharge as soon as 5 seconds pass! | 0 |
| shieldBleedThrough | Defines the percent of damage that passes the shield when it goes down. A value of 0 means that with even just 1 shield point, any single hit will be blocked, while 100 means 100% of the damage left after the shield blocks it will go on to damage the craft. | 0 |
Defines one of the weapons equipped by X-COM craft for shooting down UFOs, listed in "craftWeapons:".
| Value | Description | Default |
|---|---|---|
| type | String ID of the weapon name. | required |
| weaponType | A weapon's type/category. Used to limit certain weapons/accessories to certain craft weapon slots. | 0 |
| sprite | Sprite ID from BASEBITS.PCK used to draw the weapon in the Basescape and from INTICON.PCK used to draw the weapon in dogfights.
Note that:
|
-1 |
| sound | Sound ID from GEO.CAT played when this weapon fires. | -1 |
| stats | Contains the same set of attributes as Craft Stats. These dynamically increase/decrease the stats of a craft, when equipped.
Examples:
|
- |
| hidePediaInfo | Allows hiding the weapon's stats in the Ufopedia.
Note: this can be used for example when the craft weapon is not really a weapon, but only an equipment/booster (e.g. radar booster, extra fuel tank, etc.). |
false |
| damage | Amount of damage this weapon does to enemy UFOs. | 0 |
| shieldDamageModifier | Defines the percent of power that a weapon does to shields. | 100 |
| range | Maximum range of this weapon in dogfights (in kilometers). | 0 |
| accuracy | Chance (0-100%) of each shot hitting the enemy UFO. | 0 |
| reloadCautious | Time this weapon takes to fire between each shot in Cautious Mode. | 0 |
| reloadStandard | Time this weapon takes to fire between each shot in Standard Mode. | 0 |
| reloadAggressive | Time this weapon takes to fire between each shot in Aggressive Mode. | 0 |
| ammoMax | Maximum amount of ammo this weapon can carry. | 0 |
| rearmRate | Amount of ammo restored every hour while the craft is Rearming in base. If specified, clips are spent depending on their clipSize, and reamRate should be a multiple of clipSize. If the clipSize of the specified ammo is 0, no clips are spent. | 1 |
| projectileType | Type of the weapon projectile, used for the projectile sprite in dogfights:
|
2 |
| projectileSpeed | Speed of the weapon projectile in dogfights. | 0 |
| launcher | String ID of the item required to equip this weapon. | - |
| clip | String ID of the item required to rearm this weapon. | - |
| underwaterOnly | Is this craft weapon restricted to underwater use only? | false |
| tractorBeamPower | How much the weapon slows down the maximum speed of a UFO when it's in range and the weapon is active.
Note: Tractor beams allow you to effectively decrease the maximum speed of a UFO during interception, preventing their escape. If you have powerful enough beams targeting the UFO, you can even cause it to land or splash down in the water! |
0 |
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 |
| nameAsAmmo | Extension for the name of weapons loaded with this item as ammo. | - |
| battleType | Defines the weapon's behavior in the Battlescape:
|
0 |
| requires | List of topics (string IDs) that must be researched to unlock this item. If none are specified, this item is unlocked from the start. Soldiers can only use unlocked items in the Battlescape. | - |
| requiresBuy | A list of research topics required to be able to buy this item.
Note: you can use the item even if the requirements are not met... you just can't buy it. |
- |
| requiresBuyBaseFunc | A list of services (for a given base) required to be able to buy this item. | - |
| size | Space occupied by this item in Base Stores. Can be a decimal value. | 0.0 |
| costBuy | Amount of money spent for purchasing this item. If set to 0, this item will not be available in the Purchase/Recruit screen. | 0 |
| costSell | Amount of money gained for selling this item. | 0 |
| transferTime | Number of hours it takes to purchase/transfer this item to a base. | 24 |
| categories | A list of categories this item belongs to. | - |
| monthlyMaintenance | Monthly maintenance cost of items in Stores. For example your tanks could have a small monthly maintenance cost. | 0 |
| monthlySalary | Monthly salary of "other employees" (represented as items in Stores). This is practically identical to monthlyMaintenance, it just shows on a different place in the [Monthly costs] screen.
Note: the "other employees" can't do much (yet), but you could use them for example to increase your Stores capacity (by giving them negative size)... representing increased storage effectiveness by hiring specialized logistics personnel (or outsourcing storage completely). |
0 |
| Value | Description | Default |
|---|---|---|
| customItemPreviewIndex | Allows to have different icons for different types of Vehicles (HWP/SWS) on the [Craft Info] screen. Defined either as a single index into the CustomItemPreviews spritesheet, or as a list of indices (for bigger icons). | - |
| bigSprite | Sprite ID from BIGOBS.PCK used to draw this item in a soldier's inventory and UFOpaedia. | -1 |
| specialIconSprite | Sprite ID from SPICONS.DAT used to draw this item when used as specialWeapon (in Armor definition). | -1 |
| floorSprite | Sprite ID from FLOOROB.PCK used to draw this item on the floor of a Battlescape tile. | -1 |
| handSprite | Sprite ID from HANDOB.PCK used to draw this item on a soldier's hand in the Battlescape.
modders: each handobject needs 8 images (8 directions) define the extrasprites accordingly |
120 |
| bulletSprite | Sprite ID from BulletSprites.png used to draw this weapon's projectile on the Battlescape:
for modders: the bulletsprite needs to be put into the extraSprites type "Projectiles" the bulletsprite can contain up to 35 3x3 images. The corresponding file id is 35*[bulletSprite] |
-1 |
| bulletSpeed | How much faster (or slower, if you use a negative number) is a projectile fired from this weapon compared to the average. | 0 |
| explosionSpeed | How much faster (or slower, if you use a negative number) is an explosion animated compared to the average. | 0 |
| turretType | Sprite ID from TANKS.PCK of the turret to assign to this tank:
|
-1 |
| vaporColor | The color offset (0-3 in TFTD) to use for the vapor trail. | -1 |
| vaporDensity | The vapor cloud density (number of particles) for the vapor trail. | 0 |
| vaporProbability | The vapor cloud probability (0-100%) for the vapor trail. | 15 |
| Value | Description | Default |
|---|---|---|
| explosionHitSound | Sound ID from BATTLE.CAT played when explosion happens. Can be a list with multiple options. If not specified, default explosion sound is used. | - |
| reloadSound | Sound ID from BATTLE.CAT played when this weapon is reloaded. Can be a list with multiple options. If not specified, default reload sound is used. | - |
| fireSound | Sound ID from BATTLE.CAT played when this weapon fires. In OXCE, can be a list with multiple options. | -1 |
| hitSound | Sound ID from BATTLE.CAT played when this weapon hits a target. In OXCE, can be a list with multiple options. | -1 |
| psiSound | Sound ID from BATTLE.CAT played when this weapon performs a psi attack (only Panic/MindControl). Can be a list with multiple options. | - |
| hitMissSound | Sound ID from BATTLE.CAT played when this weapon misses a psi attack (Use/Panic/MindControl). Can be a list with multiple options. | - |
| psiMissSound | Sound ID from BATTLE.CAT played when this weapon misses a psi attack (only Panic/MindControl). Can be a list with multiple options. | - |
| meleeSound | Sound ID from BATTLE.CAT played when this weapon attacks a target with melee. In OXCE, can be a list with multiple options. | 39 |
| meleeHitSound | Sound ID from BATTLE.CAT played when this weapon hits a target with melee. In OXCE, can be a list with multiple options. | -1 |
| meleeMissSound | Sound ID from BATTLE.CAT played when this weapon misses a target with melee. Can be a list with multiple options. | - |
| hitAnimation | Sprite ID from SMOKE.PCK used to draw the weapon's "hit explosion". In OXCE, it applies also to Use action of psi weapons.
NOTE: Do not define this value for melee/psi weapons, they use HIT.PCK and therefore meleeAnimation instead. NOTE: Explosive style weapons (Damage type: smoke, incendiary, stun, & High Explosive) use X1.PCK and should always be set to the first above water sprite (spriteID for UFO, spriteID + 8 for TFTD). TFTD spritesheet should start with 8 underwater images, followed by 8 above water images. |
-1 |
| hitMissAnimation | Sprite ID from SMOKE.PCK used to draw the weapon's "miss explosion". Applies only to Use action of psi weapons. | -1 |
| meleeAnimation | Sprite ID from HIT.PCK played when this weapon hits a target with melee. | 0 |
| meleeMissAnimation | Sprite ID from HIT.PCK played when this weapon misses a target with melee. | -1 |
| psiAnimation | Sprite ID from HIT.PCK played when this weapon hits a target with psi attack (only Panic/MindControl). For Use action on psi weapons, define hitAnimation. | -1 |
| psiMissAnimation | Sprite ID from HIT.PCK played when this weapon misses a target with psi attack (only Panic/MindControl). For Use action on psi weapons, define hitMissAnimation. | -1 |
| Bullets (non-explosive) | Melee weapon (or gun-butt) | Psi weapon (panic/MC) | Psi weapon (Use) | |
|---|---|---|---|---|
| Hit sound | hitSound | meleeSound+meleeHitSound | psiSound > hitSound | hitSound |
| Miss sound | - | meleeMissSound > meleeSound | psiMissSound > hitMissSound > psiSound > hitSound | hitMissSound > hitSound |
| Hit animation | hitAnimation | meleeAnimation | psiAnimation > meleeAnimation | hitAnimation |
| Miss animation | - | meleeMissAnimation > meleeAnimation | psiMissAnimation > meleeMissAnimation > psiAnimation > meleeAnimation | hitMissAnimation > hitAnimation |
| Value | Description | Default |
|---|---|---|
| power | Weapon power. Usually corresponds to weapon's average damage. For some weapons/items, it determines the range (e.g. for incendiary or smoke). | 0 |
| hidePower | Allows hiding the weapon's power (and the entire ammo section) in the Ufopedia.
Note: this can be used for example when the weapon is mostly scripted and the damage info is more confusing than helpful. |
false |
| damageType | What type of damage does this weapon do:
Notes:
|
0 |
| blastRadius | Size of the projectile explosions. 0 for no explosion. -1 to automatically calculate based on weapon power and damage type (actual blastRadius currently is capped due Explosion calculations).
Note: blastRadius is deprecated in OXCE. Use damageAlter.FixRadius instead. If both are specified, FixRadius is taken. |
-1 |
| damageAlter | OpenXcom has 10 damage types and the mechanics of all 10 of them are completely hardcoded. In OXCE, you can use one of these hardcoded damage types as a starting point, but still be able to override all damage aspects for every item. To do this, you always use a pair of attributes for default and override:
Damage override has many attributes, which are all described in Item Damage Types. Small example: - type: STR_HWP_DISC_PLASMA_CANNON damageType: 5 damageAlter: RandomType: 6 IgnoreOverKill: false ToArmorPre: 0.05 ToStun: 0.75 RandomWound: false ToWound: 0.12 FireThreshold: 25.0 |
- |
| meleePower | Damage this weapon will do when using melee. This only applies to Firearms, and is only available as stun damage. For normal melee weapons, use regular power and damage types. | 0 |
| meleeType | Default damage type for secondary melee attack. Automatically set to damage type 7 (melee) for items with battleType = 3 (melee weapon). | - |
| meleeAlter | Damage type details for meleeType.
Damage override has many attributes, which are all described in Item Damage Types. |
- |
| strengthApplied | Add the attacking unit's strength to this weapon's damage.
Note: strengthApplied is deprecated in OXCE. Use damageBonus instead, which is also more configurable. If both are specified, damageBonus is taken. |
false |
| damageBonus | Formulae for additional weapon power bonus (not damage bonus!). Defined as a sum of polynomials of up to third degree with various unit stats as parameters :) If you didn't understand the previous sentence, don't be sad, just look at an example. FIXME: add more description and examples later.
Example: - type: STR_EXAMPLE_1 damageBonus: bravery: 2.5 flatHundred: -1.25 - type: STR_EXAMPLE_2 damageBonus: firing: [0.0, 0.01] In the first example the power bonus is "250% of soldier's bravery minus 125". In the second example the power bonus is "0% of firing accuracy plus 1% of firing accuracy squared". |
- |
| meleeBonus | Same as damageBonus, but applies to secondary melee attacks. | - |
| Value | Description | Default |
|---|---|---|
| noLOSAccuracyPenalty | The penalty (in percent) to accuracy applied when attacking a unit or a tile outside of LOS. Overrides global setting. | -1 |
| accuracyAimed accuracySnap accuracyAuto accuracyMelee |
The base accuracy (in percent) applied to a soldier's Firing Accuracy when firing an Aimed/Snap/Auto shot or doing a Melee attack.
Note: in OXCE, it doesn't need to be applied only to firing accuracy, a combination of many other attributes can be used instead, see accuracyMultiplier and meleeMultiplier. |
0 0 0 0 |
| accuracyPanic accuracyMindControl accuracyUse |
The accuracy bonus (in flat percent) applied during psi attacks (Panic/MindControl/Use). accuracyMultiplier is also used in the calculations. | 20 0 0 |
| accuracyThrow | The base accuracy (in percent) applied when throwing items. See also throwMultiplier. | 100 |
| accuracyCloseQuarters | The base accuracy (in percent) applied when checking CQC (close quarters combat) score. Overrides global setting. See also closeQuartersMultiplier. | -1 |
| blockBothHands | Does this weapon block both hands? If true, you cannot use this weapon while holding anything in the offhand. | false |
| twoHanded | Is this weapon two-handed? If true, incurs an accuracy penalty if used with both hands occupied. Note that the handsprite of a twoHanded item is also drawn at a slightly different position than a one handed item. | false |
| oneHandedPenalty | Override for the global one-handed penalty (which applies only to weapons marked as twoHanded). 20% penalty would be encoded as "80" (i.e. 100 minus 20), meaning you will use the weapon at 80% of its usual accuracy. | -1 |
| kneelBonus | Override for the global kneel bonus (which applies to all weapons). 15% bonus would be encoded as "115" (i.e. 100 + 15), meaning you will use the weapon at 115% of its usual accuracy. | -1 |
| skillApplied | Is melee accuracy skill applied to the accuracy of an attack made with this item? Only affects melee attacks.
Note: skillApplied is deprecated in OXCE. Use meleeMultiplier instead, which is also more configurable. If both are specified, meleeMultiplier is taken. |
true |
| accuracyMultiplier | Formulae defining the skills (i.e. various units stats) affecting the unit's accuracy when using this item in Aimed/Snap/Auto shots and in Psi attacks (Panic/MindControl/Use).
Example: - type: STR_EXAMPLE accuracyMultiplier: firing: 0.0 throwing: 0.5 melee: 0.5 In this example, the accuracy is based on 50% of unit's throwing skill and 50% of unit's melee skill... and 0% of unit's firing skill. |
- |
| meleeMultiplier | Same as accuracyMultiplier, but used for Melee attacks (primary and secondary). | - |
| throwMultiplier | Same as accuracyMultiplier, but used for Throwing. | - |
| closeQuartersMultiplier | Same as accuracyMultiplier, but used for CQC scoring. | - |
| Value | Description | Default |
|---|---|---|
| waypoints | Gives the integer number of waypoints the weapon can use. (eg. Blaster Launcher). Can also be used to make ammo items use the waypoint system. "-1" means unlimited waypoints. | 0 |
| sprayWaypoints | Waypoints for "spray shots", i.e. autoshots in multiple directions.
More info here: https://openxcom.org/forum/index.php/topic,6423.0.html |
0 |
| shotgunPellets | Number of projectiles fired per unit of ammunition. (note: due to engine limitations it is currently impossible to draw multiple projectiles in flight.) | 0 |
| shotgunBehavior shotgunSpread shotgunChoke |
Attributes affecting how shotguns work.
More info: https://openxcom.org/forum/index.php/topic,4834.0.html |
0 100 100 |
| maxRange | Maximum range at which this weapon can operate. | 200 |
| aimRange | Maximum effective range with this weapon before which range-based dropoff occurs. | 200 |
| snapRange | Maximum effective range with snap shot before which range-based dropoff occurs. (ufoextender accuracy only) | 15 |
| autoRange | Maximum effective range with auto shot before which range-based dropoff occurs. (ufoextender accuracy only) | 7 |
| minRange | Range-based dropoff will work in reverse for ranges below this. | 0 |
| dropoff | The value by which the accuracy lowers for each tile after (or before) the thresholds above. | 2 |
| powerRangeThreshold | Number of tiles defining the effective range (i.e. range with no power reduction). Beyond this range power reduction is applied. | 0 |
| powerRangeReduction | Weapon's power dropoff per tile beyond effective range. | 0 |
| Value | Description | Default |
|---|---|---|
| clipSize | The amount of ammo stored in each weapon clip. If -1 is specified, this weapon has infinite ammo. If specified for a HWP, clipSize determines the maximum amount of shots which can be loaded into the HWP weapon. Use clipsize -1 for melee weapons. | 0 |
| compatibleAmmo | List of string IDs of the ammo items that can be loaded on this weapon. If none are specified, the weapon doesn't need ammo. | - |
| tuLoad tuUnload |
Amount of Time Units required to load/unload this item.
Note: in OXCE, when loading a weapon, you need to additionally pay the cost of moving the ammo from its current inventory slot into a hand slot! Consider that when balancing reload costs. Update: since OXCE v6.2, the OXCE behavior is now turned off by default. It can be enabled using the extendedItemReloadCost setting. |
15 8 |
| ammo | In OXCE, you can load multiple different types of ammo into one gun at the same time. This allows you to create, for example, a rifle with a built-in grenade launcher. There are up to 4 ammo slots, which can be assigned to Aimed/Snap/Auto actions. Going back to the rifle with a grenade launcher example, you could have the rifle with Aimed and Snap and sacrifice the Auto action for implementing let's say a Snap shot for the grenade launcher.
Example: - type: STR_WEAPON_WITH_4_AMMO_SLOTS ammo: 0: compatibleAmmo: [ STR_AMMO_1, STR_AMMO_2 ] tuLoad: 5 tuUnload: 2 1: compatibleAmmo: [ STR_AMMO_3 ] tuLoad: 10 tuUnload: 4 2: compatibleAmmo: [ STR_AMMO_4, STR_AMMO_5 ] tuLoad: 10 tuUnload: 4 3: compatibleAmmo: [ STR_GRENADE_AMMO ] tuLoad: 20 tuUnload: 8 |
- |
| autoShots | How many auto shots does this weapon fire. | 3 |
| arcingShot | Does this weapon fire in an arc? | false |
| confAimed confSnap confAuto confMelee |
A mapping between actions and ammo slots (see above).
Example: - type: STR_RIFLE_WITH_A_GRENADE_LAUNCHER confAimed: shots: 1 name: STR_AIMED_SHOT ammoSlot: 0 arcing: false confSnap: shots: 2 name: STR_DOUBLE_SNAP_SHOT ammoSlot: 0 arcing: false confAuto: shots: 1 name: STR_LAUNCH_GRENADE ammoSlot: 3 arcing: true confMelee: name: STR_PUNCH_IN_THE_FACE |
- |
| psiAttackName | Besides panic attack and mind control, weapons of psi-amp type can have also a third type of attack, bound to "use" attributes (for example costUse). This attribute defines what should be the name of such attack in the action menu (e.g. Seduce, VooDoo spell, etc.). | - |
| primeActionName | Name of the prime action in the action menu. Default is STR_PRIME_GRENADE.
Tip: in OXCE more item battleTypes can be primed than in OpenXcom, for example also battleType 10 (Electro-flares). |
<= |
| primeActionMessage | Message for the player informing about the priming of an item. Default is STR_GRENADE_IS_ACTIVATED. | <= |
| unprimeActionName | Name of the un-prime action in the action menu. | - |
| unprimeActionMessage | Message for the player informing about the un-priming of an item. Default is STR_GRENADE_IS_DEACTIVATED. | <= |
| Value | Description | Default |
|---|---|---|
| tuAimed tuSnap tuAuto tuMelee |
The percentage (0-100%) of Time Units (from the soldier's total) required to fire an Aimed/Snap/Auto Shot or doing a Melee attack. If 0, the weapon does not have the corresponding attack. | 0 0 0 0 |
| tuUse | Amount of Time Units required to use this item (for non-offensive items). It's a flat rate if flatRate is true, otherwise it's a percentage (0-100%). | 0 |
| tuMindControl tuPanic |
Amount of Time Units required to use this item. If not specified, defaults to tuUse. | -1 -1 |
| tuThrow tuPrime tuUnprime |
Amount of Time Units required to throw/prime/unprime this item. | 25 50 25 |
| costAimed costSnap costAuto costMelee costUse costMindControl costPanic costThrow costPrime costUnprime |
Extended way of defining the cost of item use. Instead of spending only time units, you can also define to spend energy, morale, HP, mana and stun. All costXXX settings override tuXXX settings, for example costAimed overrides tuAimed, etc.
Example: - type: STR_FUNNY_WEAPON costAimed: time: 90 energy: 20 morale: 65 mana: 5 |
- |
| flatRate | If true, then TU costs for this weapon are a flat rate (instead of a percentage of unit TUs). | false |
| flatAimed flatSnap flatAuto flatMelee flatUse flatThrow flatPrime flatUnprime |
Extended way of defining if the cost of item use is flat or in percentage. You can now define it for various actions separately. If defined, the more specific setting (e.g. flatAimed) overrides the less specific setting (flatRate).
Example: - type: STR_FUNNY_WEAPON costAimed: time: 90 energy: 20 mana: 5 flatAimed: time: false # 90% of TU energy: true # 20 energy (flat) mana: true # 5 mana (flat) |
- |
| Value | Description | Default |
|---|---|---|
| experienceTrainingMode | Defines which skill(s) should improve when the soldiers gain experience by hitting enemy units (or healing fatal wounds of any units).
More info: https://openxcom.org/forum/index.php/topic,4230.0.html |
0 |
| manaExperience | How much mana experience points does the weapon provide.
manaExperience: 250 # this means 2 points + 50% chance for a 3rd point (on every hit on hostile unit) |
0 |
| recover | Is this item recoverable? (gets transported to the X-COM base on mission success) | true |
| recoverCorpse | Since the recover flag applies to both live body (prisoner capture) and dead body (corpse recovery) in OpenXcom, OXCE adds this new flag to allow recovery of a live body, but disable recovery of the corpse (used in mods mostly to ignore dead bodies of killed humans). | true |
| recoveryPoints | Score gained for recovering this alien artifact. | 0 |
| liveAlien | Does this item represent a live alien? (counts towards Alien Containment) | false |
| prisonType | What type of prison (alien containment) facility can accommodate a unit (marked as liveAlien) represented by this item.
More info: https://openxcom.org/forum/index.php/topic,4830.msg69933.html#msg69933 |
0 |
| specialType | MCD value in map files to which this item corresponds for mission recovery. | -1 |
| recoveryDividers | Definition how special items (with specialType > 1) should be recovered from the mission.
More info here: https://openxcom.org/forum/index.php/topic,6616.0.html |
- |
| recoveryTransformations | Allows recovering items as other items (for example alien weapons as alien weapon fragments).
More info here: https://openxcom.org/forum/index.php/topic,6868.0.html |
- |
| Value | Description | Default |
|---|---|---|
| medikitActionName | Name of the use action in the action menu. Default is STR_USE_MEDI_KIT. | <= |
| medikitType | Defines, which functions can this medikit perform. Possible options:
|
0 |
| allowSelfHeal | Deprecated. Use medikitTargetSelf instead. | false |
| medikitTargetSelf | Is it possible to use the medikit on oneself (true)? Or only on other units (false)? Ignores other settings. | false |
| medikitTargetImmune | Is it possible to use the medikit on units that cannot bleed (true)? Or only on other units (false)? | false |
| medikitTargetMatrix | Says what targets are allowed for a medikit item. It is a composite attribute (a bit map), individual parts:
So, for example:
|
63 |
| isConsumable | Will this medikit be automatically refilled at the base (false)? Or will it disappear after the mission, if used at least once (true)?
Note: If you use multiple medikits, they will use the same "combination" algorithm as the guns use for bullet recovery in OpenXcom. Using two medikits let's say just once will not make both of them disappear, because there will be enough "stuff" left to fully recover one of them. |
false |
| painKiller | Amount of painkillers contained in a Medi-Kit. | 0 |
| heal | Amount of heals contained in a Medi-Kit. | 0 |
| stimulant | Amount of stimulants contained in a Medi-Kit. | 0 |
| woundRecovery | Amount of Fatal Wounds treated by each heal of a Medi-Kit. | 0 |
| healthRecovery | Amount of Health recovered by each heal of a Medi-Kit. | 0 |
| stunRecovery | Amount of Stun removed by each stimulant of a Medi-Kit. | 0 |
| energyRecovery | Amount of Energy recovered by each stimulant of a Medi-Kit. | 0 |
| manaRecovery | Amount of Mana recovered by each stimulant of a Medi-Kit. | 0 |
| painKillerRecovery | Strength of the pain killers (1.0 = 100%). Linear factor affecting vanilla morale recovery (based on lost health). | 1.0 |
| moraleRecovery | Additional points of morale to restore when pain killers are used. Does not depend on lost health (or anything else). | 0 |
| medikitBackground | Sprite ID of the medikit background.
Tip: size and position of buttons can also be adjusted using Interface ruleset (but only globally for all medikit items). |
- |
| Value | Description | Default |
|---|---|---|
| weight | Weight occupied by this item in a soldier's inventory. | 3 |
| invWidth | Item width in a soldier's inventory (in grid units). | 1 |
| invHeight | Item height in a soldier's inventory (in grid units). | 1 |
| fixedWeapon | Is this weapon fixed (cannot be dropped from the Inventory)? (it's part of a unit, e.g. tanks and terrorist units) | false |
| fixedWeaponShow | Should the fixed weapon be drawn on the unit in the Battlescape or not? Normally, the weapon is not drawn (for example Reaper or Cyberdisc weapon... because it's a part of the unit itself), but in mods you may have for example fixed weapons on certain armors, which you want to display as normal "carried" weapons. | false |
| defaultInventorySlot | An inventory slot where a fixedWeapon should be placed when it is created. | - |
| defaultInvSlotX | A position within the inventory slot where a fixedWeapon should be placed when it is created. | 0 |
| defaultInvSlotY | A position within the inventory slot where a fixedWeapon should be placed when it is created. | 0 |
| supportedInventorySections | A list of inventory slots, where this item can be (manually) placed. If empty, all slots are OK. | - |
| ignoreInBaseDefense | Items marked with this flag will not appear in the Base Defense mission.
Note: mods, which have items used mostly in Geoscape (e.g. random resources used for manufacturing), but still recoverable from Battlescape should use this flag so that the ground inventory is not spammed by useless junk slowing the game down (significantly! if there are thousands of such items). |
false |
| ignoreInCraftEquip | Items marked with this flag will not appear in Craft Inventory Equipment screen.
Defaults:
|
<= |
| specialUseEmptyHand | Whether this specialWeapon is used when clicking on the empty hand slot in soldier's inventory. Used for punching/kicking with bare hands :) | false |
| Value | Description | Default |
|---|---|---|
| fuseType | Defines how item priming works.
Possible options:
Defaults:
|
<= |
| fuseTriggerEvents | Defines how fuse triggers work. Contains 5 sub-attributes:
Example/Defaults: fuseTriggerEvents: defaultBehavior: true throwTrigger: false throwExplode: false proximityTrigger: false proximityExplode: false |
<= |
| specialChance | The chance (0-100%) of special effects happening, including:
|
100 |
| isExplodingInHands | Does the item explode also when still in a unit's inventory? | false |
| hiddenOnMinimap | Is the item visible on the minimap?
Tip: use for example for mines hidden underground |
false |
| Value | Description | Default |
|---|---|---|
| isFireExtinguisher | Can this item be used to extinguish fire on units? | false |
| armor | How much damage is needed to destroy this item on the ground. | 20 |
| attraction | Represents how likely an alien is to pick up this item. Values below 5 will be ignored (by design). | 0 |
| LOSRequired | Does this item require line of sight? (only applies to mind probes and psi-amps) | false |
| psiRequired | Does using this item require psi skill > 0 ? Items of battleType=9 (psi-amps) have this flag set to true by default. | false |
| manaRequired | Does using this item require mana research unlocked? | false |
| underwaterOnly | Can this item only be used underwater? | false |
| landOnly | Can this item only be used on land? | false |
| zombieUnit | String ID of the unit used for zombification (eg. Chrysallids turn units into Zombies). | - |
| zombieUnitByArmorMale | Overrides zombieUnit. Based on armor worn by the victim. A list of String ID pairs. | - |
| zombieUnitByArmorFemale | Overrides zombieUnit. Based on armor worn by the victim. A list of String ID pairs. | - |
| zombieUnitByType | Overrides zombieUnit. Based on the victim soldier/unit type. A list of String ID pairs. | - |
| spawnUnit spawnUnitFaction |
Used for spawning units from items.
More info: https://openxcom.org/forum/index.php/topic,6535.0.html |
- -1 |
| ai.useDelay ai.meleeHitCount |
1/ Used to override AI delay defined by global settings.
2/ How many times should an AI unit try to perform a melee attack (in the single go)? In vanilla, the unit used the melee attack until the target was neutralized or until it ran out of TUs. This attribute gives you the option to perform "hit and run". ai: useDelay: 1 meleeHitCount: 15 |
-1 25 |
Defines some extra behavior (and list order) of item categories, listed in "itemCategories:".
| Value | Description | Default |
|---|---|---|
| type | String ID of the item category name. | required |
| hidden | Defines whether this category should be hidden in the filter on the [Craft Equipment] screen.
Note: categories not shown to the player are still useful for the modder sometimes. |
false |
| replaceBy | Defines mapping between item categories.
Note: this is useful when you are still experimenting with the item categorization. If you defined too many categories for example, you can group them together easily here, instead of having to redefine all the items. And if you change your mind later, you can easily ungroup them again. |
- |
These are the sub-attributes you can use within attributes damageAlter and meleeAlter. Listed separately for convenience.
| Value | Description | Default |
|---|---|---|
| FixRadius | A blast radius.
|
0 |
| RandomType | Defines how will be dice be rolled to determine damage based on power (primary damage calculation). Possible options:
|
0 |
| ResistType | A damage type, i.e. what resistance of the target unit's armor is applied. Same values like damageType. | 0 |
| FireBlastCalc | Vanilla fire/incendiary blast radius has a special formula. This option turns it on/off. | false |
| IgnoreDirection | Should the damage calculation ignore from which direction the projectile came? Used for example for smoke or fire. | false |
| IgnoreSelfDestruct | Killing using this damage prevents self-destruct (e.g. of Cyberdisc). Used for example on HE, Stun or Melee damage. | false |
| IgnorePainImmunity | Some units are immune to pain/stun (see painImmune on Armor). This allows you to ignore such immunity. Used for example on Stun damage. | false |
| IgnoreNormalMoraleLose | When units are hit, they lose morale. This option allows you to turn this effect on/off. | false |
| IgnoreOverKill | Disables overkill damage, i.e. units won't get vaporized/disintegrated when killed (by a hit doing a lot more damage than necessary to kill). | false |
| ArmorEffectiveness | How effective is a unit's front/side/rear/bottom armor against this damage. 1.0 is 100%. | 1.0 |
| RadiusEffectiveness | If FixRadius = -1, the blast radius is not fixed, but dynamically calculated from Power (incl. Power bonus). This is a factor for such calculation. | 0.0 |
| RadiusReduction | How much explosion Power decreases with distance from the center. | 10.0 |
| FireThreshold | How much damage is needed to set a unit or a tile on fire. | 1000 |
| SmokeThreshold | How much damage is needed to create smoke on a tile. | 1000 |
| ToArmorPre | How much of the primary damage (Power x RandomType) is applied to the unit's armor before armor is considered. | 0.0 |
| RandomArmorPre | Should the calculation above be randomized?
Example 1: Power = 100. Primary damage rolled = for example 140. ToArmorPre = 0.1. RandomArmorPre = false. Damage applied to a unit's armor will be 14. Example 2: Power = 100. Primary damage rolled = for example 140. ToArmorPre = 0.1. RandomArmorPre = true. Damage applied to a unit's armor will be a random value between 0 and 14. |
false |
| ToArmor | How much of the primary damage is applied to the unit's armor after armor is considered. | 0.1 |
| RandomArmor | Should the calculation above be randomized? | false |
| ToHealth | How much of the primary damage is applied to the unit's health. | 1.0 |
| RandomHealth | Should the calculation above be randomized? | false |
| ToStun | How much of the primary damage is applied to the unit's stun level. | 0.25 |
| RandomStun | Should the calculation above be randomized? | true |
| ToWound RandomWound |
Determines how many fatal wounds should be inflicted. Default settings equal to vanilla calculations. Formula is quite hard to describe in words, so here's the code:
if (damage > 0) { if (RandomWound) { if (RNG::generate(0, 10) < int(damage * ToWound)) { return RNG::generate(1,3); } } else { return (int)std::round(damage * ToWound); } } |
1.0 true |
| ToTime | How much of the primary damage is applied to the unit's TUs. | 0.0 |
| RandomTime | Should the calculation above be randomized? | false |
| ToEnergy | How much of the primary damage is applied to the unit's energy. | 0.0 |
| RandomEnergy | Should the calculation above be randomized? | false |
| ToMana | How much of the primary damage is applied to the unit's mana burn. | 0.0 |
| RandomMana | Should the calculation above be randomized? | false |
| ToMorale | How much of the primary damage is applied to the unit's morale. | 0.0 |
| RandomMorale | Should the calculation above be randomized? | false |
| ToItem | How much of the primary damage is applied to items. | 0.0 |
| RandomItem | Should the calculation above be randomized? | false |
| ToTile | How much of the primary damage is applied to the terrain. | 0.5 |
| RandomTile | Should the calculation above be randomized? | false |
| TileDamageMethod | Which tile damage method should be used?
|
1 |
| DT_NONE | DT_AP | DT_IN | DT_HE | DT_LASER | DT_PLASMA | DT_STUN | DT_MELEE | DT_ACID | DT_SMOKE | DT_10 ... DT_19 | |
|---|---|---|---|---|---|---|---|---|---|---|---|
| ResistType | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9 | 10 ... 19 | |
| FireBlastCalc | true | ||||||||||
| IgnoreOverKill | true | true | true | true | true | true | true | true | true | true | |
| IgnoreSelfDestruct | true | true | true | true | |||||||
| IgnorePainImmunity | true | ||||||||||
| IgnoreDirection | true | true | |||||||||
| FixRadius | -1 | -1 | -1 | -1 | |||||||
| RadiusEffectiveness | 0.03 | 0.05 | 0.05 | 0.05 | |||||||
| ArmorEffectiveness | 0.0 | 0.0 | |||||||||
| FireThreshold | 0 | ||||||||||
| SmokeThreshold | 0 | ||||||||||
| ToHealth | 1.0 | 0.0 | 0.0 | ||||||||
| ToArmor | 0.0 | 0.0 | 0.0 | ||||||||
| ToWound | 0.0 | 0.0 | 0.0 | ||||||||
| ToItem | 0.0 | 1.0 | 0.0 | 0.0 | |||||||
| ToTile | 0.0 | 0.0 | 0.0 | ||||||||
| ToStun | 0.0 | 1.0 | 1.0 | ||||||||
| RandomStun | false | ||||||||||
| TileDamageMethod | 2 | 2 | 2 | 2 |
Defines one of the UFOs that invade Earth, listed in "ufos:".
| Value | Description | Default |
|---|---|---|
| type | String ID of the UFO name. | required |
| size | String ID of the UFO size. | STR_VERY_SMALL |
| sprite | Sprite ID from INTERWIN.DAT used to draw this UFO in the dogfight view and UFOpaedia.
Note: don't try to add more images if you don't want to punch yourself in the face - use modSprite instead. |
-1 |
| modSprite | Filename used to draw this UFO in the dogfight view and UFOpaedia. | - |
| marker | Sprite ID from GlobeMarkers spritesheet, used for drawing flying UFO icon on the globe. Usually 3x3 pixels, but can be modded to be bigger.
Note: if not modded, sprite id 2 is used (=vanilla flying UFO marker). |
-1 |
| markerLand | Sprite ID from GlobeMarkers spritesheet, used for drawing landed UFO icon on the globe. Usually 3x3 pixels, but can be modded to be bigger.
Note: if not modded, sprite id 3 is used (=vanilla landed UFO marker). |
-1 |
| markerCrash | Sprite ID from GlobeMarkers spritesheet, used for drawing crashed UFO icon on the globe. Usually 3x3 pixels, but can be modded to be bigger.
Note: if not modded, sprite id 4 is used (=vanilla crashed UFO marker). |
-1 |
| power | Damage power of this UFO's weapon in dogfights. | 0 |
| range | Maximum range of this UFO's weapon in dogfights (in kilometers). | 0 |
| score | Score gained when this UFO is destroyed, or half this score if it crash lands. | 0 |
| reload | Time the UFO's weapon takes to fire between each shot. | 0 |
| breakOffTime | Minimum amount of time for the UFO to be able to break off of a dogfight. | 0 |
| missionScore | Negative points awarded each half hour the UFO is airborne, and twice this value when landed | 1 |
| battlescapeTerrainData | Terrain associated to this UFO in Battlescape missions. | required |
| hunterKillerPercentage | The chance (0-100%) to become a hunter-killer UFO upon spawning (unless overridden by mission wave).
Possible options:
|
0 |
| huntMode | Algorithm to use when prioritizing xcom targets (unless overridden by mission wave).
Possible options:
|
0 |
| huntBehavior | Algorithm to use when considering retreating from the dogfight (unless overridden by mission wave).
Possible options:
|
2 |
| huntSpeed | When hunter-killer finds a target, it will change speed to a percentage of its maximum speed.
Possible options:
|
100 |
| missilePower | Only relevant for retaliation UFOs. If not shot down during the base defense, it will destroy some base facilities or even the whole base (without ground mission!).
Possible options:
More info: https://openxcom.org/forum/index.php/topic,6668.0.html |
0 |
| fireSound | UFO's fire sound in the Dogfight, from GEO.CAT. | -1 |
| alertSound | Sound played when this type of UFO is detected, from GEO.CAT. | -1 |
| huntAlertSound | Sound played when this type of UFO starts hunting an XCOM craft, from GEO.CAT. | -1 |
| raceBonus | Modifies or overrides the UFO Stats per alien race.
You can use this to make the same type of UFO have different stats depending on the alien race. - type: STR_TERROR_SHIP raceBonus: STR_MUTON: hitBonus: 20 craftCustomDeploy: STR_MORE_SCARY_WEAPONS missionCustomDeploy: STR_TERROR_SITE_MUTONS STR_ETHEREAL: missionCustomDeploy: STR_END_OF_THE_WORLD |
- |
The following attributes define so called "ufo stats". They are listed in a separate table, just for convenience... but are still part of the UFO ruleset.
Note: In OXCE, all these stats are dynamic, i.e. can depend on the alien race piloting the UFOs.
| Value | Description | Default |
|---|---|---|
| damageMax | Maximum amount of damage this UFO can take. If the UFO takes 50% damage, it crash lands. If it takes 100% damage, it is destroyed. | 0 |
| speedMax | Maximum speed in nautical miles. | 0 |
| radarRange | Detection range of the UFO's radar in nautical miles. Relevant for hunter-killer UFOs. | 672 |
| radarChance | Chance (0-100%) of this UFO radar detecting a craft that enters its range. | 100 |
| sightRange | UFO's sight range (for detecting X-COM bases) in nautical miles. | 268 |
| hitBonus | Flat bonus percentage to hit chance. | 0 |
| avoidBonus | Flat bonus percentage to dodge chances against enemy fire. | 0 |
| powerBonus | Multiplier for the weapon power, e.g. 20 = weapon power increased to 120%, -20 = decreased to 80%. | 0 |
| armor | Amount of blocked damage per hit. | 0 |
| shieldCapacity | UFO's maximum shield capacity. | 0 |
| shieldRecharge | Defines the percent chance of recharging a point of shielding per game second (GS) during a Dogfight. Values under 100 are the percent chance, for over 100, every +100 means an automatic +1 to shields per GS. Thus shieldRecharge: 250 means +2 shields/GS, with a 50% chance of +1 more. | 0 |
| shieldRechargeInGeoscape | Similar to shieldRecharge, but acts every 5 seconds in the Geoscape. Giving it a value of -1 means instant recharge as soon as 5 seconds pass! | 0 |
| shieldBleedThrough | Defines the percent of damage that passes the shield when it goes down. A value of 0 means that with even just 1 shield point, any single hit will be blocked, while 100 means 100% of the damage left after the shield blocks it will go on to damage the UFO. | 0 |
| craftCustomDeploy | Overrides the deployment data used during the Battlescape generation, when the UFO crashes or lands. | - |
| missionCustomDeploy | Overrides the deployment data used during the Battlescape generation, when the UFO spawns a mission site. | - |
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). | - |
Defines one of the terrains used to generate a Battlescape map, listed in "terrains:".
| Value | Description | Default |
|---|---|---|
| name | String ID of the terrain name. | required |
| mapDataSets | List of filenames (each with matching MCD/PCK/TAB files) that contain the tiles of this terrain. | - |
| mapBlocks | List of map blocks (see below) that are used for generating a map. | - |
| addOnly | Normally, when loading mapBlocks, any map blocks loaded previously (e.g. from other mods) are deleted first and then new map blocks are added. If this attribute is true, the existing map blocks are not deleted and the new ones are added at the end of the list.
Note: does not apply to mapDataSets or anything else |
false |
| civilianTypes | List of units to use as civilians for this mission. | [MALE_CIVILIAN, FEMALE_CIVILIAN] |
| music | The list of musics this terrain can choose from (unless overridden by alienDeployment). | - |
| depth | Minimum and maximum possible depth, format is [minDepth, maxDepth]. Sets the battlescape depth (randomly, unless overridden by alienDeployment). | [0, 0] |
| ambience | The ambient sound effect. Sound ID from BATTLE.CAT. | -1 |
| ambientVolume | The volume of the ambient sound effect. | 0.5 |
| ambienceRandom | A list of ambient sound effects (IDs from BATTLE.CAT). Doesn't work when ambience is defined. Uses ambientVolume. A random sound effect is chosen each time a sound is played. | - |
| ambienceRandomDelay | The delay between random ambient sound effects in seconds. Chosen randomly between the defined min and max (after each sound played).
Note: the time passes only when the game is not "busy" (= when you see the map tiles animate). When the tiles don't animate, the timer for ambient sounds doesn't tick. |
[20, 60] |
| script | The map generation script name. | DEFAULT |
| enviroEffects | String ID of enviro effects for missions using this terrain.
Note: if enviro effects are defined both on terrain and on alien deployment, the deployment's enviro effects are used. |
- |
| 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 <IP_ADDRESS>), 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 <IP_ADDRESS>), 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. | - |
| fuseTimers | This attribute allows you to pre-prime the items placed on the map using the items attribute. It's a list of items and information about minimum and maximum fuse timer.
Example: items: STR_ELERIUM: - [0, 0, 0] STR_TIMEBOMB: - [2, 1, 0] - [6, 2, 0] fuseTimers: STR_TIMEBOMB: [0, 30] In this example 3 items are placed on the map block: 1 Elerium item and 2 Timebomb items. Both Timebomb items will be pre-primed with a random delay between 0 and 30 (each item will have a different delay). Elerium item will not be pre-primed :) |
- |
| randomizedItems | A list of additional items to add to this mapblock, using a more randomized approach. Does not support pre-priming of items.
Example: randomizedItems: - position: [12, 15, 2] amount: 3 mixed: true itemList: [STR_ITEM_1, STR_ITEM_2, STR_ITEM_3, STR_ITEM_3] In this example:
|
- |
FIXME Someone please document this...
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 | - |
| 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. | - |
| canBeSkipped | Only relevant for addUFO command with no label defined. Determines, whether an unsuccessful addUFO command can be skipped (and logged into the log file) or whether the game should crash.
Note: this attribute is more or less deprecated. Maybe useful for testing/debugging? |
true |
| craftName | String ID of the craft to be placed.
Note: this can be used to replace the craft you arrived with (e.g. Skyranger) with a new vehicle you used to make the last section of your journey. For example a small submarine for an underwater mission or an APC for a mission, where you couldn't land or didn't want to make too much noise :) |
- |
| terrain | String ID of an alternate terrain to be used for this command only. Used for example when you want to sneak in a few blocks from FOREST terrain into a map made predominantly using FARM terrain.
There is a special constant globeTerrain, which takes a random terrain corresponding to the globe texture, where the mission takes place. More info here: https://openxcom.org/forum/index.php/topic,7536.0.html There is also a special constant baseTerrain for base defense missions, which takes the terrain from the globe definition (see also baseDefenseMapFromLocation). More info: https://openxcom.org/forum/index.php/topic,5108.0.html |
- |
| verticalLevels | Allows using a set of map blocks (of various vertical sizes) stacked on top of each other... instead of just a single map block.
More info: https://openxcom.org/forum/index.php/topic,5316.0.html |
- |
Defines a Battlescape unit's armor as well as visual representation (so every unit has an armor), listed in "armors:".
| Value | Description | Default |
|---|---|---|
| type | String ID of the armor name. | required |
| requires | The research required to equip this armor.
Modding hint: it is possible to equip one "store item" as several different armors, e.g. as armor with or without a helmet. This option allows you to limit some of those options by a research topic. You could use this also for example to define different armor variants for each game difficulty level, e.g. make armor stronger for beginners and weaker for veterans. |
- |
| spriteSheet | Sprite sheet from UNITS used to draw a unit wearing this armor. | - |
| spriteInv | Sprite used for the Inventory Backgrounds of a unit wearing this armor. | - |
| layersDefaultPrefix layersSpecificPrefix layersDefinition | Alternative way of defining/creating inventory sprites (a.k.a. paperdolls), in layers.
More info: https://openxcom.org/forum/index.php/topic,6290.msg104464.html#msg104464 |
- - - |
| allowInv | Can the inventory of this armor be accessed or not? | true |
| corpseItem | Deprecated: use corpseGeo and corpseBattle instead. | - |
| corpseBattle | List of string IDs of the corpse items generated when a unit wearing this armor is killed/stunned (1 for 1x1 unit, 4 for 2x2 unit) on the Battlescape. | - |
| corpseGeo | String ID of the corpse item recovered in Debriefing. Defaults to corpseBattle if omitted.
Tip for modders: useful for example when you want to recover a "damaged" version of a soldier's armor. |
- |
| storeItem | String ID of the item that represents this armor in Base Stores for equipping. Set to STR_NONE to not require an item (eg. coveralls). | - |
| specialWeapon | Alternative method of defining a melee/psi weapon for aliens (and civilians); instead of defining it on the unit itself.
Note: in OXCE, this can be used also for Soldiers. It can be any type of weapon (not only melee/psi) and does not block the inventory. Instead it is accessed via a special icon. |
- |
| builtInWeapons | Alternative method of defining built-in weapons for aliens (and civilians); instead of defining them on the unit itself. Can be used also for Soldiers. | - |
| frontArmor | Protection provided on the front of the unit. | 0 |
| sideArmor | Protection provided on the sides of the unit. | 0 |
| leftArmorDiff | Used to define different armor values on the sides (left/right). If specified, left side armor = sideArmor + leftArmorDiff. | 0 |
| rearArmor | Protection provided on the rear of the unit. | 0 |
| underArmor | Protection provided under the unit (e.g. from explosions). | 0 |
| drawingRoutine | Drawing routine used to put together the body parts in the unit's spriteSheet:
|
0 |
| drawBubbles | Set to true for units that breathe underwater, e.g. humans and humanoid aliens.
Note: in vanilla this is set to true for all units using drawingRoutine 13 and 14. |
false |
| movementType | Type of movement provided by this armor:
it also defines the body of a tank (32-images) in your spriteSheet or the change in sprites while flying using a flying armor see: TANKS.PCK, XCOM_2.PCK |
0 |
| moveSound | Sound ID from BATTLE.CAT played when a unit wearing this armor moves (overrides unit's moveSound). | -1 |
| deathMale/deathFemale | Sound ID from BATTLE.CAT played when a unit wearing this armor dies. A list of sound IDs can be used too. | - |
| selectUnitMale/selectUnitFemale | Sound ID from BATTLE.CAT played when a unit wearing this armor is manually selected. A list of sound IDs can be used too. | - |
| startMovingMale/startMovingFemale | Sound ID from BATTLE.CAT played when a unit wearing this armor starts moving. A list of sound IDs can be used too. | - |
| selectWeaponMale/selectWeaponFemale | Sound ID from BATTLE.CAT played when a weapon of a unit wearing this armor is selected. A list of sound IDs can be used too. | - |
| annoyedMale/annoyedFemale | Sound ID from BATTLE.CAT played when a unit wearing this armor is repeatedly manually selected. A list of sound IDs can be used too. | - |
| size | Size of the unit wearing this armor, in Battlescape grid units. 1 means 1x1 unit, 2 means 2x2 unit, other sizes are not supported. | 1 |
| weight | Physical weight of the armor when worn. | 0 |
| visibilityAtDark | How far can the unit wearing this armor see during darkness. Default 0 uses 9 for X-Com, but for Aliens it uses the maxViewDistance variable (default 20). | 0 |
| visibilityAtDay | How far can the unit wearing this armor see during the day. Default 0 uses the maxViewDistance variable (default 20). Both of these variables only affect how far away units may be seen. Terrain revealed is always based on maxViewDistance, day or night. | 0 |
| personalLight | Intensity of the personal light for the unit wearing this armor. | 15 |
| camouflageAtDay | Makes the unit wearing this armor less visible during the day. Positive numbers set absolute distance (e.g. 7 means that unit is visible from 7 tiles away), negative numbers set relative distance (e.g. -10 means that unit is visible from a distance that is 10 tiles shorter than usual). Cannot decrease visibility below 1 tile. | 0 |
| camouflageAtDark | Makes the unit wearing this armor less visible during darkness. Positive or negative, same as above. | 0 |
| antiCamouflageAtDay | Cancels enemy camouflage by a specified amount (of tiles) during the day. Cannot increase visibility beyond the usual (e.g. camo = -5 and antiCamo = 7 still only evens out, it doesn't provide 2 additional tiles of visibility). | 0 |
| antiCamouflageAtDark | Cancels enemy camouflage by a specified amount (of tiles) during darkness. Cannot increase visibility beyond the usual. | 0 |
| heatVision | Allows seeing better through smoke. Percentage (0-100%) value defining how much smoke is ignored. | 0 |
| psiVision | Allow "seeing" through walls. Units with this armor can sense enemies that are 'psiVision' tiles (or less) away, in any direction.
Note: cannot sense enemies that are fearImmune. |
0 |
| stats | Like soldier stats (see below) but these are treated as stat bonuses while wearing a given type of armor. | - |
| damageModifier | List of decimal damage modifiers (1.0 = 100%) this armor applies to each damage type (see Items section) received. Modifiers must be specified for all damage types, in this order:
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: use loftempsSet instead. | - |
| deathFrames | Number of "death frames" = sprites in the death animation sequence. | 3 |
| overKill | Defines how much damage (over the maximum HP) is needed to vaporize/disintegrate a unit upon hit. Defined as percentage, e.g. 0.6 = 60% of maximum HP.
Notes:
|
0.5 |
| constantAnimation | Set it to "true" for units that constantly show an animation, such as: Biodrone, Celatid, Silacoid. | false |
| forcedTorso | Soldier sprites have female and male torsos. Some armors reuse these sprites for flying/non flying torso without difference between genders. This can be controlled by the parameter:
|
0 |
| 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. | <= |
| meleeDodgeBackPenalty | Defines the penalty to unit's melee dodge ability (see meleeDodge) when attacked from behind. Defined as percentage, e.g. 0.7 = 70%.
Note: The full penalty applies from behind, from sides the penalty is adjusted accordingly. There is no penalty for frontal assault. |
0.0 |
The following group of attributes has rather complicated definition (listed in a separate table just for convenience).
| Value | Description | Default |
|---|---|---|
| psiDefence | Formulae for psi defense value. | vanilla |
| meleeDodge | Formulae for melee dodge chance. | 0 |
| recovery.time | Formulae for TU recovery at the beginning of a new turn.
Note: this and all attributes below are defined under parent attribute recovery and a child attribute (time, energy, morale, etc.) |
vanilla |
| recovery.energy | Formulae for Energy recovery at the beginning of a new turn. | vanilla |
| recovery.morale | Formulae for Morale recovery at the beginning of a new turn. | 0 |
| recovery.health | Formulae for HP recovery at the beginning of a new turn. | 0 |
| recovery.stun | Formulae for Stun Level recovery at the beginning of a new turn. | vanilla |
| recovery.mana | Formulae for mana recovery at the beginning of a new turn. | 0 |
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:
FIXME: describe what each keyword means
Defines a soldier recruited by X-COM, listed in "soldiers:".
Unit stats are represented as follows:
| Value | Description | Default |
|---|---|---|
| type | String ID of the soldier type. | required |
| requires | List of topics (string IDs) that must be researched to unlock this soldier type. If none are specified, this soldier type is unlocked from the start. | - |
| requiresBuyBaseFunc | A list of services (for a given base) required to be able to hire this soldier type. | - |
| minStats | Minimum values used to generate the soldier's Starting Stats. In this case, psiSkill is treated as the initial stat (not generated). | - |
| maxStats | Maximum values used to generate the soldier's Starting Stats. In this case, psiSkill is treated as the minimum value for the first month of psi training (actual value is 100%-150%). | - |
| statCaps | Maximum stats this soldier can gain through Experience. NOTE: A stat will still go over the limit once, and then will no longer increase (see Regarding Caps). | - |
| trainingStatCaps | Maximum stats this soldier can gain through combat/martial training in the base. | statCaps |
| dogfightExperience | A list of probabilities (0-100%) to improve a stat (only bravery, firing or reactions) after a successful Dogfight.
- type: STR_SOLDIER dogfightExperience: bravery: 20 # 20% chance of improvement by 10 reactions: 50 # 50% chance to improve by 1 firing: 100 # guaranteed to improve by 1 |
- |
| armor | String ID of the armor this soldier uses by default. | - |
| armorForAvatar | When avatar display is activated in the Battlescape UI (instead of rank display)... which armor should the unit be wearing?
Note: things like Power/Flying Armor don't show the soldier's face, so you'd want to use Jumpsuits or Personal Armor. |
- |
| avatarOffsetX | Horizontal offset (in pixels) in the inventory sprite used for avatar display. | 67 |
| avatarOffsetY | Vertical offset (in pixels) in the inventory sprite used for avatar display. | 48 |
| flagOffset | Offset in the flag sprite collection to use for this soldier type.
Note: OXCE supports flag display per "nationality" (or better said per name pool file). |
0 |
| allowPromotion | Does this soldier type support promotion? Hint: combat dogs don't need a military hierarchy :) | true |
| allowPiloting | Is this soldier type capable of piloting a craft? Sorry, no doggies piloting a Skyranger. | true |
| costBuy | Amount of money spent for hiring this soldier type. If set to 0, the soldier type will not be available in the Purchase/Recruit screen. | 0 |
| costSalary | Amount of money spent monthly for employing this soldier type. | 0 |
| costSalarySquaddie | Bonus to a salary for a Squaddie. | 0 |
| costSalarySergeant | Bonus to a salary for a Sergeant. | 0 |
| costSalaryCaptain | Bonus to a salary for a Captain. | 0 |
| costSalaryColonel | Bonus to a salary for a Colonel. | 0 |
| costSalaryCommander | Bonus to a salary for a Commander. | 0 |
| standHeight | Height of this soldier when standing. | 0 |
| kneelHeight | Height of this soldier when kneeling. | 0 |
| floatHeight | Distance between the bottom of this unit and the ground. | 0 |
| femaleFrequency | The probability that a female soldier is hired. | 50 |
| value | The soldier's base value, without experience modifiers. Used for scoring in Debriefing. | 20 |
| transferTime | The amount of time (in hours) it takes for new recruits of this soldier type to arrive at a base. If 0, global personnel transfer time is used instead. | 0 |
| moraleLossWhenKilled | Percentage modifier for morale loss when this unit is killed.
Hint: set 0% for xcom security cameras and 500% for doggies. |
100 |
| deathMale | Death sound(s) for male soldiers. Either a single sound ID or a list of sound IDs from BATTLE.CAT. | - |
| deathFemale | Death sound(s) for female soldiers. Either a single sound ID or a list of sound IDs from BATTLE.CAT. | - |
| selectUnitMale/selectUnitFemale | Sound ID from BATTLE.CAT played when this soldier is manually selected. A list of sound IDs can be used too. | - |
| startMovingMale/startMovingFemale | Sound ID from BATTLE.CAT played when this soldier starts moving. A list of sound IDs can be used too. | - |
| selectWeaponMale/selectWeaponFemale | Sound ID from BATTLE.CAT played when this soldier's weapon is selected. A list of sound IDs can be used too. | - |
| annoyedMale/annoyedFemale | Sound ID from BATTLE.CAT played when this soldier is repeatedly manually selected. A list of sound IDs can be used too. | - |
| panicMale | Panic sound(s) for male soldiers. Either a single sound ID or a list of sound IDs from BATTLE.CAT. | - |
| panicFemale | Panic sound(s) for female soldiers. Either a single sound ID or a list of sound IDs from BATTLE.CAT. | - |
| berserkMale | Berserk sound(s) for male soldiers. Either a single sound ID or a list of sound IDs from BATTLE.CAT. | - |
| berserkFemale | Berserk sound(s) for female soldiers. Either a single sound ID or a list of sound IDs from BATTLE.CAT. | - |
| soldierNames | List of soldier name files/paths. Use delete to clear previously-loaded names. | - |
| statStrings | Override of global stat strings for this soldier type. | - |
| rankStrings | Override for classic xcom ranks. You can have for example only Rookies and Veterans for a certain soldier type. | - |
| rankSprite | Offset for rank sprites for this soldier type in BASEBITS.PCK | 42 |
| rankBattleSprite | Offset for rank sprites for this soldier type in SMOKE.PCK | 20 |
| rankTinySprite | Offset for rank sprites for this soldier type in TinyRanks | 0 |
Allows doing things like:
More info: https://openxcom.org/forum/index.php/topic,6331.0.html
| Value | Description | Default |
|---|---|---|
| name | String ID of the soldier transformation type. | required |
| requires | A list of research projects required before this project appears in the list of available transformations, the default empty list means this project is available from the beginning of the game. | - |
| requiresBaseFunc | A list of services required at a base in order to do this project, the default empty list means no special services are required. | - |
| producedItem | The item a soldier should be transformed into. The soldier is completely removed from the game.
Modding tips: sacrifices for special resources/weapons, transform specialists into resources needed to build special facilities, etc. |
- |
| producedSoldierType | The type of soldier produced by this project - any soldier undergoing this transformation will be switched to this type. If left empty, the soldier type does not change. | - |
| producedSoldierArmor | The armor the soldier will have when the project finishes, only used when keepSoldierArmor is false. Leaving it empty will give the soldier the default armor for the correspondiing soldier type. | - |
| keepSoldierArmor | Determines whether or not the soldier will keep the armor they're wearing through this transformation. | false |
| createsClone | Determines whether the selected soldier has the transformation done to them or a new soldier is created that is a copy of the original and the transformation is done to the new soldier. | false |
| needsCorpseRecovered | If your project allows dead soldiers, this determines whether or not you needed to have a corpse item available at the end of the battle in which the soldier died. This does not mean you need the corpse item in your stores, just that it would have been recovered if recover: true was set on the item. | true |
| allowsDeadSoldiers | Can dead soldiers undergo this transformation? If so, they are brought back to life at the base you started this project in. | false |
| allowsLiveSoldiers | Can live, non-wounded soldiers undergo this transformation? | false |
| allowsWoundedSoldiers | Can wounded soldiers undergo this transformation? | false |
| allowedSoldierTypes | This list determines which soldier types can undergo this transformation, the default empty list means nobody can have this project done to them. | required |
| requiredPreviousTransformations | A list of transformation projects that must be done to a soldier before they're eligible for this project, the default empty list means no previous projects are required. | - |
| forbiddenPreviousTransformations | A list of transformation projects that a soldier cannot have undergone in order to be eligible for this project, the default empty list means no previous projects are forbidden. | - |
| minRank | The minimum rank a soldier must have in order to be eligible for this project, from 0=rookie to 5=commander. | 0 |
| requiredMinStats | The minimum stats a soldier must have in order to be eligible for this project, defaults to all 0 so any soldier is eligible. | - |
| requiredItems | A list of items that must be consumed from the base's stores in which you start this project, the default empty list means no items are used. | - |
| requiredCommendations | A list of commendations (with a minimum decoration level) required to start this project. The default empty list means no commendations are required.
Example: https://openxcom.org/forum/index.php/topic,7405.msg117870.html#msg117870 |
- |
| cost | The cost of the project in dollars. | 0 |
| transferTime | Soldiers can be put in a transfer back to the base where they started if this parameter is greater than the default of 0 hours. New clones or resurrected soldiers are automatically given a transfer to the base with a default of 24 hours. | 0 |
| recoveryTime | The amount of wound recovery time a soldier is given after this project completes and the transfer, if any, is completed. The default value is 0 days. | 0 |
| flatOverallStatChange | A direct change to the soldier's overall stats when undergoing this project, can be positive or negative - tu: 5 means the soldier will gain 5 max time units, while tu: -5 means the soldier will lose 5 max time units. The default of 0 means no change. | - |
| flatMin flatMax |
Similar to flatOverallStatChange, but allows to specify a range from which the game chooses randomly.
More info: https://openxcom.org/forum/index.php/topic,7196.msg117768.html#msg117768 |
- |
| percentOverallStatChange | A percent change to the soldier's overall stats when undergoing this project, can be positive or negative - tu: 5 means the soldier will gain an extra 5% of their max time units, while tu: -5 means the soldier will lose 5% of their max time units. The default of 0 means no change. | - |
| percentMin percentMax |
Similar to percentOverallStatChange, but allows to specify a range from which the game chooses randomly. | - |
| percentGainedStatChange | A percent change to the soldier's stats, but instead of taking a portion of the overall stats, this only applies to the stats they've trained up from their initial values, can be positive or negative - firing: -100 means the soldier will lose all of the firing accuracy they trained since joining, while firing: 10 means they gain 10% of the amount they trained over their initial values. The default of 0 means no change. | - |
| percentGainedMin percentGainedMax |
Similar to percentGainedStatChange, but allows to specify a range from which the game chooses randomly. | - |
| showMinMax | If enabled, the GUI will show random improvement as min/max range. If disabled, it will show just a question mark. | false |
| rerollStats | This attribute allows you to specify, which stats should be completely re-rolled.
More info: https://openxcom.org/forum/index.php/topic,7196.msg117767.html#msg117767 |
false |
| lowerBoundAtMinStats | Determines whether or not any changes in stats from this project should go below the minStats defined on the new soldier type. | true |
| upperBoundAtMaxStats | Determines whether or not any changes in stats from this project should go above the maxStats defined on the new soldier type. | false |
| upperBoundAtStatCaps | Determines whether or not any changes in stats from this project should go above the statCaps defined on the new soldier type. | false
|
| reset | The reset flag can be used to clear the bonuses gained by previous transformations. It also clears the list of previously performed transformations.
For example: 1. you train karate and gain a bonus 2. then you transform the guy into a MEC and want to lose all the previous bonuses (since MECs can't benefit from karate training... I hope) Note: stats gained by "classic" transformations (i.e. those that are NOT bonuses) will NOT be reset; only bonuses can be reset |
false |
| soldierBonusType | ID of a soldier bonus applied to a soldier undergoing this transformation. | - |
Defines rules for soldier bonuses, listed in "soldierBonuses:".
Bonuses can be manually awarded by the player via soldier transformations; or automatically awarded together with a soldier commendations/medals.
More info: https://openxcom.org/forum/index.php/topic,7405.0.html
| Value | Description | Default |
|---|---|---|
| name | String ID of the soldier bonus type. | required |
| visibilityAtDark | Defines the bonus to night vision (in tiles). Cannot go beyond global maximum view distance. | 0 |
| stats | Defines the bonus to soldier's stats (same way as the armor can). Can go even beyond any cap/maximum. | - |
| recovery | Defines the bonus to soldier's resource recovery every turn (same way as the armor can). Affects time units, energy, health, stun, morale and mana. | - |
FIXME Someone please document this...
In OXCE, you can also use soldier commendations to assign soldier bonuses (see above). Bonuses are defined per decoration level. You don't need to define all decoration levels... if a soldier has a higher decoration level than defined, the highest available is used.
More info: https://openxcom.org/forum/index.php/topic,7405.msg116840.html#msg116840
Example:
commendations:
- type: STR_MEDAL_ALIENS_KILLED
description: STR_MEDAL_ALIENS_KILLED_DESCRIPTION
sprite: 1
soldierBonusTypes: [STR_KILL1, STR_KILL2, STR_KILL3, STR_KILL4] # various bonuses for various decoration levels
criteria:
killsWithCriteriaCareer: [1, 2, 3, 4, 5, 6, 7, 8, 9, 10]
killCriteria:
-
- [1, ["STATUS_DEAD", "FACTION_HOSTILE"]]
Defines an alien (enemy) or civilian (neutral) unit, listed in "units:". Every different alien rank is a different unit, since they have completely different stats. Unit stats are represented as follows:
| Value | Description | Default |
|---|---|---|
| type | String ID of the unit name. | required |
| race | String ID of the unit race (for alien units). | - |
| rank | String ID of the unit rank (for alien units). | - |
| spotter | The spotter score. Determines how many turns sniper AI units can act on this unit seeing your troops. | 0 |
| sniper | The sniper score. Determines the chances of firing from out of LOS on spotted units. | 0 |
| stats | Battlescape stats of this unit. | - |
| armor | String ID of the armor this unit uses by default. | - |
| standHeight | Height of this unit when standing. | 0 |
| kneelHeight | Height of this unit when kneeling. Not supported in OpenXcom yet, for future use? | 0 |
| floatHeight | Distance between the bottom of this unit and the ground. | 0 |
| value | Score this unit is worth. | 0 |
| civilianRecoveryType | Gets the type of staff (soldier/engineer/scientists) or type of item to be recovered when a civilian is saved. | - |
| intelligence | Intelligence of this unit's AI. The higher the value, the longer this unit remembers player troops between turns. | 0 |
| waitIfOutsideWeaponRange | Should the unit get "stuck" trying to fire from outside of weapon range? OXC bug, that may serve as "feature" in rare cases.
Note: the default value is to fix the OXC bug. |
false |
| canSurrender | Can this unit surrender? | false |
| autoSurrender | Does this unit surrender automatically, if all other units surrendered too? | false |
| aggression | Aggression of this unit's AI. The higher the value, the more ruthless the unit, the more likely to make a frontal/melee assault. Less aggressive units tend to set up ambushes.
Possible values are:
|
0 |
| isLeeroyJenkins | Unit marked as "leeroy" must have a melee weapon (and be able to use it). It will completely ignore vanilla AI "decision making" and run around (using vanilla patrol routine) until it spots someone and then charge at the nearest target (if multiple spotted).
Charge is mostly vanilla/OXCE, with the following differences:
|
false |
| energyRecovery | Energy recovered by the unit each turn. | 30 |
| specab | Special ability of this unit:
|
0 |
| spawnUnit | String ID of the unit used to respawn on death (e.g. Zombies respawn as Chrysallids). | - |
| livingWeapon | Is this unit a living weapon?
If yes, it ignores any weapon loadout associated with its rank in the alien deployment and only attacks with a weapon derived from its name (must be marked as fixedWeapon). The weapon's name is the unit's type without the first 4 letters (STR_) and with a suffix (_WEAPON). For example: STR_REAPER => REAPER_WEAPON. |
false |
| meleeWeapon | This unit's built-in melee weapon (e.g. Lobsterman's Claws). Does not appear in the inventory. | - |
| psiWeapon | This unit's built-in psi weapon. Ignored if the unit doesn't have any psi skill. Does not appear in the inventory. | ALIEN_PSI_WEAPON |
| capturable | Can this unit be captured alive?
Note: units which cannot be captured alive are insta-killed when they fall unconscious. |
true |
| builtInWeaponSets | A set of lists of weapons this unit can come pre-equipped with. Game will pick one set "at random" (randomness comes from the current alien tech level definition). These weapons WILL appear in inventory slots (references items). | - |
| builtInWeapons | Deprecated: use builtInWeaponSets instead. | - |
| moraleLossWhenKilled | Percentage modifier for morale loss when this unit is killed.
Tip: set for example 50% for cannon fodder and 300% for VIPs. |
100 |
| deathSound | Sound ID from BATTLE.CAT played when this unit dies. No value means no sound upon death. A list of sound IDs can be used too, the game then chooses one randomly each time. | - |
| selectUnitSound | Sound ID from BATTLE.CAT played when this unit is manually selected. A list of sound IDs can be used too. | - |
| startMovingSound | Sound ID from BATTLE.CAT played when this unit starts moving. A list of sound IDs can be used too. | - |
| selectWeaponSound | Sound ID from BATTLE.CAT played when this unit's weapon is selected. A list of sound IDs can be used too. | - |
| annoyedSound | Sound ID from BATTLE.CAT played when this unit is repeatedly manually selected. A list of sound IDs can be used too. | - |
| panicSound | Sound ID from BATTLE.CAT played when this unit panics. A list of sound IDs can be used too. | - |
| berserkSound | Sound ID from BATTLE.CAT played when this unit berserks. A list of sound IDs can be used too. | - |
| aggroSound | Sound ID from BATTLE.CAT played when this unit aggros. | -1 |
| moveSound | Sound ID from BATTLE.CAT played when this unit moves. | -1 |
| showFullNameInAlienInventory | Defines whether the [Alien Inventory] screen (accessible via middle-click on a unit) should display a unit's type/name or just a unit's race.
Possible options:
|
-1 |
| pickUpWeaponsMoreActively | Allows AI to pick up weapons more actively. More info: https://openxcom.org/forum/index.php/topic,6882.0.html
Possible options:
|
-1 |
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. |
- |
Defines a Battlescape deployment data used in Alien Missions (such as alien and map configurations), listed in "alienDeployments:".
| Value | Description | Default |
|---|---|---|
| type | String ID of the deployment name. | required |
| isHidden | If enabled, the mission will not appear in the mission list in New Battle GUI. Doesn't work when debug is enabled in options.cfg. | false |
| customUfo | String ID of a UFO to be used in mapscripts in addUFO command. This allows to reuse the same script for many deployments.
More info: https://openxcom.org/forum/index.php/topic,7631.0.html |
- |
| startingCondition | String ID of a starting condition for missions using this deployment.
Note: overrides any globe texture starting condition. |
- |
| enviroEffects | String ID of enviro effects for missions using this deployment.
Note: overrides any mission terrain enviro effects. |
- |
| data | List of deployment data for each alien rank on this mission (see below). | - |
| width | Width of the Battlescape map in grid units. | 0 |
| length | Length of the Battlescape map in grid units. | 0 |
| height | Vertical height of the Battlescape map in grid units. | 0 |
| civilians | Maximum number of civilians to spawn. The actual number of civilians spawned will be between 50-100% of the specified maximum. | 0 |
| civilianSpawnNodeRank | Map node rank to spawn civilians on.
More info: https://openxcom.org/forum/index.php/topic,6477.0.html |
0 |
| civiliansByType | A list of additional civilians to spawn, each list item is defined by a civilian type ID and a maximum number (type: number). The actual number of civilians spawned will be again between 50-100% of the specified maximum, but this time the 50% is rounded up (for civilians attribute it is rounded down). | - |
| terrains | List of string IDs of the terrains to choose from when generating the map. Not used for UFO land/crash sites, terrain comes from the Geoscape globe texture. | - |
| shade | Shade of the map (0-15, where 0 is full daytime and 15 is full nighttime). If not specified (e.g. for UFO land/crash sites), the shade comes from the Geoscape globe. | -1 |
| minShade | Minimum shade of the map (0-15). Used only when shade is not set, to adjust the shade coming from the Geoscape globe. | -1 |
| maxShade | Maximum shade of the map (0-15). Used only when shade is not set, to adjust the shade coming from the Geoscape globe. | -1 |
| nextStage | String ID of the next deployment stage to use after this one, for multi-stage missions. | - |
| race | Sets (overrides) the alien race to use when generating the map. | - |
| randomRace | Sets (overrides) the alien race to use when generating the map. Unlike race attribute, this is a list of multiple possible races; one is chosen randomly at runtime. | - |
| finalDestination | Sets whether this mission is where you send your uber-craft to win the game. | false |
| winCutscene | Sets the cutscene to play when you win the mission. If set to "winGame" or "loseGame", the player will be returned to the main menu after the cutscene plays. | - |
| loseCutscene | Sets the cutscene to play when you lose the mission. If set to "winGame" or "loseGame", the player will be returned to the main menu after the cutscene plays. | - |
| abortCutscene | Sets the cutscene to play when you abort the mission. If set to "winGame" or "loseGame", the player will be returned to the main menu after the cutscene plays. | - |
| script | Map script used to generate the map (overrides the map script from terrain definition). | - |
| alert | String ID of the message to display in the alert popup when this mission spawns on the Geoscape. | STR_ALIENS_TERRORISE |
| alertBackground | String ID of the background image to use in the alert popup when this mission spawns on the Geoscape. | BACK03.SCR |
| alertDescription | String ID of the additional mission description (displayed when clicking on the [Info] button on the [Target Info] screen). | - |
| alertSound | Sound ID from GEO.CAT to be played when the [Mission Detected] screen pops up. | -1 |
| briefing | Data for the mission briefing (see below). | - |
| markerName | String ID that identifies this mission type on the Geoscape. | STR_TERROR_SITE |
| markerIcon | What icon should be used to represent this base/site (taken from GlobeMarkers section in extraSprites) | -1 |
| depth | [min, max] -- Defines the depth range to randomly choose from for this mission. | [0, 0] |
| duration | [min, max] -- Minimum and maximum duration of this mission on the Geoscape (in hours).
Important: mission duration should be at least 2 hours... if it's just 1 hour and it spawns at the whole hour, it also despawns at the same moment... and crashes the game! |
[0, 0] |
| music | The list of musics this mission can choose from (if not specified, the music is taken from the terrain). | - |
| points | Negative score applied for each day this mission is active (applied daily for bases, or every half hour for mission sites) | 0 |
| unlockedResearch | String ID of a research topic that will be granted for free (only if the mission is finished successfully).
Note: there will be no Ufopaedia article shown nor any other related effect; the research will just be silently added into the list of finished research projects. |
- |
| missionBountyItem | String ID of an item that will be added to base stores for free (only if the mission is finished successfully).
Note: the player will be informed in the Debriefing screen. |
- |
| bughuntMinTurn | Possibility to override global bug hunt minimum turn for this alien deployment only (usually to set a higher number for longer missions). | 0 (no change) |
The following group of attributes is related only to alien bases (listed in a separate table just for convenience).
| Value | Description | Default |
|---|---|---|
| alienBase | Does this deployment correspond to an alien base assault? Used only in New Battle mode. | false |
| genMission | Which alien mission should this base generate?
Usually supply mission - can be used to generate any mission type except Mission Sites (UFO will be generated, but the site will never appear) |
- |
| genMissionFreq | Daily chance for the base mission to be generated. | 0 |
| genMissionLimit | Maximum number of times the genMission can be generated. | 1000 |
| baseSelfDestructCode | Discovering this research topic destroys all corresponding alien bases immediately. | - |
| baseDetectionRange | Radar detection range (in nautical miles) for an alien base. If more than 0, the base actively scans for xcom craft and generates xcom craft hunt missions. | 0 |
| baseDetectionChance | Chance (0-100%) of the base radar detecting a craft that enters its range. | 100 |
| huntMissionMaxFrequency | The maximum frequency (in minutes) of hunt missions generated by an alien base. | 60 |
| huntMissionWeights | A weighted list of hunt missions a base can generate, listed by "number of months passed". | - |
| alienBaseUpgrades | A weighted list of alien base upgrades, listed by "number of months passed". | - |
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 |
| abortPenalty | How many points the xcom will lose when this mission is aborted. | 0 |
| cheatTurn | When the aliens became aware of all your units (in vanilla it was after turn 20) | 20 |
| turnLimit | The amount of turns before the mission ends automatically. | 0 (no limit) |
| chronoTrigger | What happens when the timer reaches 0. Possible values:
|
0 |
| escapeType | Which type of tiles can be used for escape. Possible values:
|
0 |
| keepCraftAfterFailedMission | Defines whether the craft should be lost after a failed mission or not. Useful for example for timed missions where the craft doesn't wait for you (e.g. escape/extraction missions). | false |
Notes:
| Value | Description | Default |
|---|---|---|
| alienRank | Rank associated with this deployment data, as defined by the order of the race in question (see above) | required |
| lowQty | Minimum quantity of aliens to spawn on beginner/experienced. | required |
| highQty | Minimum quantity of aliens to spawn on superhuman. (minimum quantity for veteran/genius is the median of this and the previous value) | required |
| dQty | Delta in Quantity, i.e. random number of aliens to spawn on top of the minimum (all difficulties). | required |
| extraQty | Functionally identical to dQty, spawns a random number of additional aliens. | 0 |
| percentageOutsideUfo | Percentage (0-100%) of aliens to spawn outside of the UFO (in UFO land/crash sites). | required |
| itemSets | Three lists (one for each alien technology level) of items (string IDs) for the aliens to equip. | required |
| extraRandomItems | One or more item lists with extra equipment. One item will be chosen from each list randomly.
More info: https://openxcom.org/forum/index.php/topic,7055.msg111746.html#msg111746 |
- |
| 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 |
Starting conditions can be defined on alien deployments only (not on terrains):
| Value | Description | Default |
|---|---|---|
| type | String ID of the starting condition. | required |
| defaultArmor | If a soldier's armor is not permitted on a mission (see allowedArmors and forbiddenArmors below), it will be replaced by a default armor. Default armor is defined for each soldier type separately as a weighted list of possible armor replacements. There is also a special armor ID "noChange" representing no change needed (i.e. giving you a chance to keep the original armor even if it is not allowed... don't ask me why, ask modders!) | - |
| allowedArmors forbiddenArmors | A list of allowed/forbidden armors for a mission. Only one of these two attributes can be used. | - |
| allowedVehicles forbiddenVehicles | A list of allowed/forbidden vehicles (HWP/SWS) for a mission. Not permitted vehicles will stay at the base. Only one of these two attributes can be used. | - |
| allowedItems forbiddenItems | A list of allowed/forbidden items (weapons, equipment, etc.) for a mission. Not permitted items will stay at the base. Only one of these two attributes can be used. | - |
| allowedItemCategories forbiddenItemCategories | A list of allowed/forbidden item categories (categories are freely definable by modders) for a mission. This is used to simplify/shorten the definition of allowed/forbidden items. Only one of these two attributes can be used. | - |
| allowedCraft forbiddenCraft | A list of allowed/forbidden craft for a mission. Not permitted craft cannot target the mission destination at all. Only one of these two attributes can be used. | - |
| allowedSoldierTypes forbiddenSoldierTypes | A list of allowed/forbidden soldier types for a mission. If there are any not permitted soldier types onboard a craft, it won't be able to target the mission destination at all. Only one of these two attributes can be used. | - |
| requiredItems | A list of items (and their quantities) required for a mission (e.g. a skeleton key from EU2012). | - |
| destroyRequiredItems | Defines whether required items should be destroyed or not (when craft landing is confirmed). | false |
Enviro effects can be defined on alien deployments and on terrains. If both are defined, deployment's enviro effects will be used.
| Value | Description | Default |
|---|---|---|
| type | String ID of the enviro effects. | required |
| paletteTransformations | A list of palette transformations (oldPaletteName: newPaletteName) to apply during the mission (or mission stage). New palettes should be similar to original palettes, they should only convey visual effects like pollution, underwater environment, etc. For UFO-based mods only one palette (PAL_BATTLESCAPE) needs to be changed, for TFTD-based mods up to 4 palettes (for each depth). | - |
| environmentalConditions | A set of environmental conditions (one for each faction: STR_FRIENDLY, STR_HOSTILE or STR_NEUTRAL), see below. Environmental conditions define a special effect applied to each unit of a given faction at the beginning of their turn. This can be for example damage in toxic environment, stun in harsh environment, morale decrease in tough battles, etc.
Note: the player is informed about the effects applied on the [Next Turn] screen. |
- |
| armorTransformations | A list of armor transformations (oldArmorName: newArmorName) to apply during the mission (or mission stage). This can be only visual (e.g. replace helmetless armors with armors with a helmet when going underwater or in space) or also functional (effectively changing unit's stats and armor properties). The change is only temporary and reverted to original armor when the mission ends.
Note: if the armor is transformed, it is not checked if it is allowed or not and it is not replaced with default armor either. |
- |
| mapBackgroundColor | Possibility to change the color of the background outside of the map boundaries. Used for example to visually indicate the type of environment. | 15 |
| inventoryShockIndicator | String ID of the shock indicator sprite (in the inventory). Used to override the global one, for example in normal environment it can indicate body shock, in underwater environment drowning and in space suffocating. | - |
| mapShockIndicator | String ID of the shock indicator sprite (on the map). Used to override the global one. | - |
| Value | Description | Default |
|---|---|---|
| globalChance | Chance (0-100%) that this environmental condition will be turned on. Dice roll is performed only once, when the battle starts. | 100 |
| chancePerTurn | Chance (0-100%) that a unit will be affected. Dice roll is performed each turn, for each unit separately. | 0 |
| firstTurn | When should the environmental condition start affecting the units. XCOM units cannot be affected before their first turn (aliens and civilians can). | 1 |
| lastTurn | When should the environmental condition stop affecting the units. | 1000 |
| message | String ID of the message displayed on the [Next Turn] screen, explaining to the player what is happening. | - |
| color | Color (0-255) of the above message. | 29 |
| weaponOrAmmo | The item (a weapon or ammo) that defines the actual effect. Compared to normal weapons, there are some limitations. See notes below. | - |
| side | The unit side where the effect is applied. Possible options:
|
-1 |
| bodyPart | The unit body part where the effect is applied. Possible options:
|
-1 |
Note: there are limitations to what the effect can do, since we're not using a projectile and nobody is actually shooting
These palettes can:
| Value | Description | Default |
|---|---|---|
| type | String ID of the custom palette. | required |
| target | String ID of the target palette:
|
- |
| file | Path to a file containing the palette definition, in JASC format. | - |
| palette | Alternative to file. You can specify the palette directly in the ruleset using a list of RGB values. Using this method, you don't have to specify all 256 colors; you can also use it to just change a few colors and leave the rest unchanged. | - |
Defines a research topic that X-COM scientists can investigate, listed in "research:".
| Value | Description | Default |
|---|---|---|
| name | String ID of the research project's name. | required |
| lookup | String ID of the research project's display result (used when multiple projects give the same result, e.g. researching Sectoid Engineer and Sectoid Navigator both give the same live Sectoid info in the Ufopaedia). | - |
| cutscene | The name of the cutscene to play when this project is completed. If the cutscene is "wingame" or "losegame", the player is returned to the main menu after the cutscene plays. | - |
| spawnedItem | Item to be added to base stores, when the research is completed.
Tip: allows you to create unique items in limited quantities (e.g. special weapons, keys to special missions, etc.). Don't forget to inform the player in the pedia article! |
- |
| cost | Number of man-days (on average, the final time will be 50-150% this value) required to complete this project. | 0 |
| points | Score earned for completing this project. | 0 |
| dependencies | List of research projects that can unlock access to this one. If the full list is researched, or if one of the projects on the list "unlocks" this one, it becomes available. | - |
| unlocks | List of research projects unlocked, regardless of other dependencies, but not requirements, by completing this project (for example, any live alien unlocks "Alien Origins"). | - |
| disables | A list of research projects disabled by completing this project.
Notes:
|
- |
| getOneFree | List of "bonus" research projects that may be granted when completing this project. Examples: alien navigators (give random alien mission info), medics (give random alien interrogation or autopsy), engineers (give random UFO type info). | - |
| getOneFreeProtected | A list of additional "bonus" research projects that may be granted when completing this project. Each topic in the list is "protected" by another topic, which allows you finer control over when the player gets the bonus.
For example: you could divide the topics into early-game, mid-game and late-game and protect each group by some "gateway topic". |
- |
| sequentialGetOneFree | Should the topics from getOneFree and getOneFreeProtected be given randomly (false) or sequentially (true). | false |
| requires | List of research projects absolutely required before this project can be unlocked. For example, "The Martian Solution" will not even be considered for unlocking until AFTER "Alien Origins" is completed. | - |
| requiresBaseFunc | A list of services (for a given base) required to start this project. | - |
| needItem | Does this project require an item of the same name? | false |
| destroyItem | Will this item be destroyed (removed from stores) after research is finished? | false |
| unlockFinalMission | If true, this research topic allows to send a spacecraft to the final mission. | false |
Defines a manufacture project that X-COM engineers can produce, listed in "manufacture:".
| Value | Description | Default |
|---|---|---|
| name | String ID of the manufacturing project's name. | required |
| category | String ID of the manufacturing project's category.
Important: craft manufacturing projects MUST be defined in the STR_CRAFT category. |
- |
| requires | List of topics (string IDs) that must be researched to unlock this project. If none are specified, this project is unlocked from the start. | - |
| requiresBaseFunc | A list of services required (in the given base) to be able to start this project. | - |
| space | Amount of Workshop space required to begin this project. | 0 |
| time | Number of man-hours required per production. | 0 |
| cost | Monetary deduction per production. | 0 |
| refund | Whether the resources needed for a project should be refunded when a project is cancelled before completion.
Notes:
|
false |
| requiredItems | List of items required and consumed per production. | - |
| producedItems | List of items manufactured per production. If not specified, defaults to 1 item with the same string ID as the manufacture project. | name: 1 |