Rulesets (OpenXcom)

In OpenXcom a ruleset is an easy to edit text file that contains settings (rules) that describe almost everything about how the game operates. Here are just some of the things that are in the ruleset:

• The costs, stats and characteristics of all items, units, facilities, X-COM craft and UFOs
• Dependencies and costs for research, manufacture and UFOpedia
• Your starting base
• The costs of personnel and transfer time.
• The stats of the funding countries and regions of the world.

You can find the rulesets in your Data\Ruleset folder.

Editing Rulesets (YAML)

Notepad++ Settings for editing OpenXcom YAML files

OpenXcom exposes its inner workings to users and modders in the form of YAML text files. Although YAML can be edited with any text editor, such as Notepad, it is much easier to use a dedicated YAML editor. YAML has a special syntax so any incorrect whitespace or character can cause an error, but it's a simple human-readable format so you should be able to figure it out by looking at the existing rulesets.

Notepad++

You can open any rulesets (or savegame files) in Notepad++ and select Language>YAML. This will help you keep the proper tabbing structure and also allow you to collapse large regions. You can set Notepad++ to recognize *.rul, *.sav and *.cfg files as YAML file extensions under preferences so that you don't have to set the language every time you edit one of OpenXcom's files.

Can't Notepad++?

Alternatively you could conjure up a Google search and look for YAML editors that are compatible with your OS. There are YAML plugins for both Visual Studio and Eclipse. Yedit for Eclipse is popular.

• Note: You should be able to collapse regions in whatever YAML editor you use. If not, you're in for a lot of scrolling as the files are quite large.

Your First Edit (Cheat)

1. Open the Data\Ruleset\Xcom1Ruleset.rul file in your YAML editor.
2. Collapse everything (Alt-0 in Notepad++) and then open (uncollapse) the "facilities:" section.
3. Open "- type: STR_LIVING_QUARTERS"
4. change "personnel: 50" to "personnel: 500"
5. Congratulations! You can now have 500 personal per living quarters.

A couple other examples

1. Fusion Ball Launcher balance update: Let's make something other than plasma cannons useful

• change "craftWeapons:" -> "type: STR_FUSION_BALL_UC>" -> "ammoMax: 2" to "ammoMax: 6"
• change "craftWeapons:" -> "type: STR_PLASMA_BEAM_UC>" -> "range: 52" to "range: 40" (just inside a terror-ships range)
• set the range for Laser Cannons to 34 (same as large scout) and set Stingray and avalanche ranges even shorter

Now there's a reason to build Fusion-Ball Launchers - shoot down Battleships and Terrorships, there's also a reason for Plasma Beams - shoot down Supply Ships and Large Scouts without getting hit, and a reason for Laser Cannons - shoot down Harvesters or Abductors safely and shoot down Large Scouts at equal range.

2. Sectopod Buff: It's time to put the fear of Sectopod in those power-suit/hovertank squads that think Ethereal Terrorsites are some kind of joke!

• "units:" -> "- type: STR_SECTOPOD_TERRORIST" -> "stats:" set TUs to 110, stamina to 125, Firing Accuracy to 100, Psi-Strength to 160 and health to 135.
• Note the field "armor: SECTOPOD_ARMOR". So close "units:" and open "armors:" -> "type: SECTOPOD_ARMOR"
• Set rear armor to 130 (a sectopod has a finely armored buttox, thankyou).
• Open "damageModifier:" (its part of the armor) and find a "- 1.5" and a "- 0.8" just below it. These are the values for how much damage a unit wearing sectopod armor takes from laser(1.5x) and plasma(0.8x). Increase the laser bonus to 1.8 and reduce the plasma further to 0.65 (it's now actually worth it to bring laser weapons just for the sectopods)
• Close "armors:" and open "items:" -> "type: SECTOPOD_WEAPON" and let's give it a good 145 weapon power. No need to adjust the weapon accuracy since we already increased the stat.

Now you can go back to having nightmares about Sectopods, just like you did when you were a young child who got in trouble for playing X-COM on the family computer after bed-time when you hadn't even done your homework.

3. Early Blaster: The best time to have a Blaster Launcher is in the back of a Skyranger full of rookies.

• Go to "items:" and pick anything that's purchasable. Copy the line with "costBuy:" and a number. Make sure you copy the tabs before "costBuy:". The best way to do this is to put the cursor at the end of the line above it, shift-down-arrow and shift-end to select the entire line and the line-break characters.
• Go to "type: STR_BLASTER_LAUNCHER" and add the "costBuy:" line. If the new line your adding doesn't look like the other lines in your YAML editor (like if it's red or black text instead of blue) then it's probably wrong and you probably have incorrect tab or line-break characters in it.
• Remove the section "required:"
• Do the last two things for Blaster Bombs as well.
• Open "startingBase:" -> "lon: 0.0" -> "items:" and replace "STR_CANNON" and "STR_CANNON_ROUNDS_X50" with "STR_BLASTER_BOMB" and "STR_BLASTER_LAUNCHER"

Start a new game, load up blasters on your skyranger, and land by a medium scout. Now hit the side of the medium scout with one shot to make a hole, hit that silly glowy thing in the middle with the second shot. Voilà, that rookie killing death-trap is now just like a crash-site, except with even less live aliens inside.

External Links

• Modding forum

Reference

A reference of all the customizable values of everything in a ruleset. Some guidelines:

• If a value is omitted from the ruleset, the default is used. You cannot omit required values.
• Text strings (eg. names) are represented by string IDs from the language files
• Numerical IDs (used for sprites, sounds, etc.) start at 0, not 1.
• Boolean (yes/no) values are represented by true/false.
• World coordinates are represented in degrees (see WORLD.DAT).
• Money amounts (prices, costs, etc.) are represented in dollars.

Countries

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

Value	Description	Default
type	String ID of the country name.	required
fundingBase	Country's base funding, in thousands. The starting funding can be anywhere between 1x and 2x the base funding.	0
fundingCap	Country's funding cap, in thousands. Once a country reaches this maximum, it will no longer increase its funding.	0
labelLon labelLat	Longitude and latitude coordinates of the country's label on the globe. This label is only shown when the globe is zoomed in and "detail" is turned on.	0.0 0.0
areas	A list of "square areas" on the globe defined as [lon1 lat1 lon2 lat2]. Any activity within these areas counts towards the country's graph activity and affects their opinion of the player.	-

Regions

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

Value	Description	Default
type	String ID of the region name.	required
cost	Amount of money spent building an X-COM base in this region (first base is free).	0
areas	A list of "square areas" on the globe defined as [lon1, lat1, lon2, lat2]. Any activity within these areas counts towards the region's graph activity.	-
cities	A list of cities belonging to this region. They will be displayed on the globe and used for terror site missions. Each city is defined by their lon and lat coordinates and a name string ID.	-
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 square areas ([lon1, lat1, lon2, lat2]) defining the mission zones for this region.	-
missionRegion	Spawn mission in this region instead (used for regions without land).	-

Base Facilities

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

Value	Description	Default
type	String ID of the facility name.	required
requires	List of topics (string IDs) that must be researched to unlock this facility. If none are specified, this facility is unlocked from the start.	-
spriteShape	Sprite ID from BASEBITS.PCK used to draw the facility's outer shape in the Basescape and UFOpaedia.	-1
spriteFacility	Sprite ID from BASEBITS.PCK used to draw the facility's contents in the Basescape and UFOpaedia. Drawn on top of spriteShape.	-1
lift	Is this facility an Access Lift? All base facilities must be connected to the lift.	false
hyper	Is this facility a Hyperwave Decoder? Displays extra information for detected UFOs. Only valid for radar facilities.	false
mind	Is this facility a Mind Shield? Reduces the chance of UFOs finding your base. Does not stack.	false
grav	Is this facility a Grav Shield? Doubles the power of your base defenses. Does not stack.	false
size	Size of the facility, in grid units. Every facility is square, so a size of 1 means 1x1, 2 means 2x2, etc. Bigger facilities are made up of multiple sprites, for example a 2x2 facility will use 4 sprites for spriteShape and 4 sprites for spriteFacility (top-left, top-right, bottom-left, bottom-right).	1
buildCost	Amount of money spent to build this facility in the base.	0
buildTime	Amount of days it takes for this facility to be built.	0
monthlyCost	Amount of money spent monthly for the maintenance of this facility.	0
storage	Amount of storage space (for items) this facility provides. See Base Stores.	0
personnel	Amount of personnel (soldiers, scientsts, engineers) these quarters can contain.	0
aliens	Amount of live aliens this facility can contain. Only checked if the alienContainmentLimitEnforced option is enabled.	0
crafts	Amount of X-COM craft this facility can contain.	0
labs	Amount of lab space this facility provides for research projects.	0
workshops	Amount of workshop space this facility provides for manufacture projects.	0
psiLabs	Amount of soldier space this facility provides for psionic training.	0
radarRange	Maximum radar detection range of this facility, in nautical miles.	0
radarChance	Chance (0-100%) of this radar detecting a UFO that enters its range.	0
defense	Offensive power provided by this base defense against attacking UFOs.	0
hitRatio	Chance (0-100) of the base defense hitting an attacking UFO.	0
fireSound	Sound ID from SAMPLE.CAT played when the base defense fires.	-1
hitSound	Sound ID from SAMPLE.CAT played when the base defense hits a target.	-1
mapName	Map associated to this facility in Battlescape base defenses.

Crafts

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

Value	Description	Default
type	String ID of the craft name.	required
requires	List of topics (string IDs) that must be researched to unlock this craft. If none are specified, this craft is unlocked from the start.	-
sprite	Sprite ID from BASEBITS.PCK used to draw this craft in the Basescape and from INTICON.PCK used to draw the damage indicator in dogfights.	-1
fuelMax	Maximum amount of fuel this craft can carry. Crafts use up fuel based on their speed while travelling.	0
damageMax	Maximum amount of damage this craft can take. If this amount is exceeded, the craft is destroyed.	0
speedMax	Maximum speed in nautical miles. Crafts travel at max speed when flying and half speed when patrolling.	0
accel	Aceeleration value shown in the UFOpaedia.	0
weapons	Amount of craft weapons this craft can equip. The UI can only display a max of 2 weapons.	0
soldiers	Amount of soldiers this craft can carry.	0
vehicles	Amount of vehicles this craft can carry.	0
costBuy	Amount of money spent for purchasing this craft. If set to 0, the craft will not be available in the Purchase/Recruit screen.	0
costRent	Amount of money spent monthly for renting this craft. If set to 0, the craft is not on rental and won't count towards base maintenance.	0
costSell	Amount of money gained for selling this craft.	0
refuelItem	Item required for refuelling this craft. If no item is specified, the craft uses human fuel.	0
repairRate	Amount of damage restored every hour while Repairing in base.	1
refuelRate	Amount of fuel restored every 30 mins while Refueling in base. If specified, a refuelItem is spent each time.	1
radarRange	Detection range of the craft's radar in nautical miles. Every craft radar has a 100% detection chance.	600
transferTime	Number of hours it takes to purchase/transfer this craft to a base.	0
score	Score lost when this craft is destroyed.	0
spacecraft	Can this craft go to Cydonia?	false
battlescapeTerrainData	Map associated to this craft in Battlescape missions.

Craft Weapons

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

Value	Description	Default
type	String ID of the weapon name.	required
sprite	Sprite ID from BASEBITS.PCK used to draw the weapon in the Basescape and from INTICON.PCK used to draw the weapon in dogfights.	-1
sound	Sound ID from SAMPLE.CAT played when this weapon fires.	-1
damage	Amount of damage this weapon does to enemy UFOs.	0
range	Maximum range of this weapon in dogfights (in meters).	0
accuracy	Chance (0-100%) of each shot hitting the enemy UFO.	0
reloadCautious	Time this weapon takes to fire between each shot in Cautious Mode.	0
reloadStandard	Time this weapon takes to fire between each shot in Standard Mode.	0
reloadAggressive	Time this weapon takes to fire between each shot in Aggressive Mode.	0
ammoMax	Maximum amount of ammo this weapon can carry.	0
rearmRate	Amount of ammo restored every 30 mins while the craft is Rearming in base. If specified, a clip is spent each time.	1
projectileType	Type of the weapon projectile, used for the projectile sprite in dogfights: 0 - Stingray 1 - Avalanche 2 - Cannon 3 - Fusion Ball 4 - Laser Cannon 5 - Plasma Beam	2
projectileSpeed	Speed of the weapon projectile in dogfights.	0
launcher	String ID of the item required to equip this weapon.	-
clip	String ID of the item required to rearm this weapon.	-

Items

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

Value	Description	Default
type	String ID of the internal item name.	required
name	String ID of the displayed item name, for cases where it's different from the internal name. If omitted, type is used.	-
requires	List of topics (string IDs) that must be researched to unlock this item. If none are specified, this item is unlocked from the start. Soldiers can only use unlocked items in the Battlescape.	-
size	Space occupied by this item in Base Stores. Can be a decimal value.	0.0
costBuy	Amount of money spent for purchasing this item. If set to 0, this item will not be available in the Purchase/Recruit screen.	0
costSell	Amount of money gained for selling this item.	0
transferTime	Number of hours it takes to purchase/transfer this item to a base.	24
weight	Weight occupied by this item in a soldier's inventory.	999
bigSprite	Sprite ID from BIGOBS.PCK used to draw this item in a soldier's inventory and UFOpaedia.	-1
floorSprite	Sprite ID from FLOOROB.PCK used to draw this item on the floor of a Battlescape tile.	-1
handSprite	Sprite ID from HANDOB.PCK used to draw this item on a soldier's hand in the Battlescape.	120
bulletSprite	Sprite ID from BulletSprites.png used to draw this weapon's projectile on the Battlescape: 0 - Rocket Launcher 1 - Pistol 2 - Rifle 3 - Auto Cannon 4 - Heavy Cannon 5 - Laser Pistol 6 - Laser Rifle 7 - Heavy Laser 8 - Plasma 9 - Small Launcher 10 - Blaster Launcher	-1
fireSound	Sound ID from SAMPLE2.CAT played when this weapon fires.	-1
hitSound	Sound ID from SAMPLE2.CAT played when this weapon hits a target.	-1
hitAnimation	Sprite ID from SMOKE.PCK used to draw the weapon's "hit explosion". NOTE: Do not define this value for melee/psi weapons, they use HIT.PCK instead.	0
power	Average damage of the weapon, in most cases it will be +-50% this value.	0
compatibleAmmo	List of string IDs of the ammo items that can be loaded on this weapon. If none are specified, the weapon doesn't need ammo.	-
damageType	What type of damage does this weapon do: 0 - None 1 - Armor Piercing 2 - Incendiary 3 - High Explosive 4 - Laser 5 - Plasma 6 - Stun 7 - Melee 8 - Acid 9 - Smoke	0
tuAuto accuracyAuto	The percentage (0-100%) of Time Units required and base accuracy for firing an Auto Shot. If tuAuto is 0, the weapon does not have an Auto Shot.	0 0
tuSnap accuracySnap	Percentage (0-100%) of Time Units required and base accuracy for firing a Snap Shot. If tuSnap is 0, the weapon does not have a Snap Shot.	0 0
tuAimed accuracyAimed	Percentage (0-100%) of Time Units required and base accuracy for firing an Aimed Shot. If tuAimed is 0, the weapon does not have an Aimed Shot.	0 0
tuMelee accuracyMelee	Percentage (0-100%) of Time Units required and base accuracy for doing a melee attack (Hit). If tuMelee is 0, the weapon does not have a Melee Attack.	0 0
clipSize	The amount of ammo stored in each weapon clip. If -1 is specified, this weapon has infinite ammo.	0
battleType	Defines the weapon's behavior in the Battlescape: 0 - None (Geoscape-only item) 1 - Firearm 2 - Ammo 3 - Melee 4 - Grenade 5 - Proximity Grenade 6 - Medi-Kit 7 - Motion Scanner 8 - Mind Probe 9 - Electro-flare 10 - Corpse	0
twoHanded	Is this weapon two-handed? (incurs an accuracy penalty if used with both hands occupied)	false
waypoint	Does this weapon use waypoints? (eg. Blaster Launcher)	false
fixedWeapon	Is this weapon fixed? (it's part of a unit, eg. tanks and terrorist units)	false
invWidth	Item width in a soldier's inventory (in grid units).	1
invHeight	Item height in a soldier's inventory (in grid units).	1
painKiller	Amount of painkillers contained in a Medi-Kit.	0
heal	Amount of heal's contained in a Medi-Kit.	0
stimulant	Amount of stimulants contained in a Medi-Kit.	0
healAmount	Amount of fatal wounds treated by each heal of a Medi-Kit.	0
healthAmount	Amount of health recovered by each heal of a Medi-Kit.	0
stun	Amount of stun removed by each stimulant of a Medi-Kit.	0
energy	Amount of energy recovered by each stimulant of a Medi-Kit.	0
tuUse	Amount of Time Units required to use this item (for non-offensive items). It's a flat rate if flatRate is true, otherwise it's a percentage (0-100%).	0
recoveryPoints	Score gained for recovering this alien artifact.	0
armor	How much damage is needed to destroy this item on the ground.	20
recover	Is this item recoverable? (gets transported to the X-COM base on mission success)	false
turretType	Sprite ID from TANKS.PCK of the turret to assign to this tank: 0 - Tank/Cannon 1 - Tank/Rocket Launcher 2 - Tank/Laser Cannon 3 - Hovertank/Plasma 4 - Hovertank/Launcher	-1
liveAlien	Does this item represent a live alien? (counts towards Alien Containment)	false
blastRadius	Size of the projectile explosions. 0 for no explosion. -1 to automatically calculate based on weapon power and damage type.	-1
flatRate	Is tuUse a flat rate (true) or a percentage (false)?	false
arcingShot	Does this weapon fire in an arc?	false
attraction	Represents how likely an alien is to pick up this item. Values below 5 will be ignored (by design).	0
maxRange	Maximum range at which this weapon can operate (0 for infinite range).	0
bulletSpeed	How much faster (or slower, if you use a negative number) is a projectile fired from this weapon compared to the average.	0

UFOs

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

Value	Description	Default
type	String ID of the UFO name.	required
size	String ID of the UFO size.	STR_VERY_SMALL
sprite	Sprite ID from INTERWIN.DAT used to draw this UFO in the dogfight view and UFOpaedia.	-1
damageMax	Maximum amount of damage this UFO can take. If the UFO takes 50% damage, it crash lands. If it takes 100% damage, it is destroyed.	0
speedMax	Maximum speed in nautical miles.	0
accel	Aceeleration value shown in the UFOpaedia.	0
power	Damage power of this UFO's weapon in dogfights.	0
range	Maximum range of this UFO's weapon in dogfights (in meters).	0
score	Score gained when this UFO is destroyed, or half this score if it crash lands.	0
reload	Time the UFO's weapon takes to fire between each shot.	0
breakOffTime	Minimum amount of time for the UFO to be able to break off of a dogfight.	0
battlescapeTerrainData	Map associated to this UFO in Battlescape missions.

Inventory Sections

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

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

Terrains

Value	Description	Default
type	String ID of the region name.	required

Armor

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

Value	Description	Default
type	String ID of the armor name.	required
spriteSheet	Sprite sheet from UNITS used to draw a unit wearing this armor.	-
spriteInv	Sprite used for the Inventory Backgrounds of a unit wearing this armor.	-
corpseItem	String ID of the corpse item generated when a unit wearing this armor is killed.	-
storeItem	String ID of the item that represents this armor in Base Stores.	-
frontArmor	Protection provided on the front of the unit.	0
sideArmor	Protection provided on the sides of the unit.	0
rearArmor	Protection provided on the rear of the unit.	0
underArmor	Protection provided under the unit (eg. from explosions).	0
drawingRoutine	Drawing routine used to put together the body parts in the unit's spriteSheet: 0 = Soldier, Sectoid, Muton 1 = Floater 2 = HWP 3 = Cyberdisk 4 = Civilian, Ethereal 5 = Sectopod, Reaper 6 = Snakeman 7 = Chryssalid 8 = Silacoid 9 = Celatid	0
movementType	Type of movement provided by this armor: 0 = Walking 1 = Flying 2 = Sliding (no walking animation)	0
size	Size of the unit wearing this armor, in Battlescape grid units. Every unit is square, so a size of 2 means 2x2.	1
loftemps	LOFTEMPS ID used to represent a unit wearing this armor in 3D space.	0
loftempsSet	Set of LOFTEMPS IDs (one for each unit tile) used to represent a unit wearing this armor in 3D space.	-

Soldiers (X-COM Units)

Value	Description	Default
type	String ID of the region name.	required

Enemy / Neutral Units

Value	Description	Default
type	String ID of the region name.	required

Alien Races

Value	Description	Default
type	String ID of the region name.	required

Alien Deployments

Value	Description	Default
type	String ID of the region name.	required

Research

Value	Description	Default
type	String ID of the region name.	required

Manufacture

Value	Description	Default
type	String ID of the region name.	required

UFOpaedia Entry

Value	Description	Default
type	String ID of the region name.	required

UFO Trajectories

Value	Description	Default
type	String ID of the region name.	required

Alien Missions

Value	Description	Default
type	String ID of the region name.	required

Alien Item Levels

Value	Description	Default
type	String ID of the region name.	required