Rulesets (OpenXcom) - Revision history

Hobbes: Undo revision 126446 by Hobbes (talk)

2026-03-10T14:56:01Z

Undo revision 126446 by Hobbes (talk)

← Older revision		Revision as of 14:56, 10 March 2026
Line 1:		Line 1:
	#~~REDIRECT~~ [[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)==
			[[Image:OpenXcomNotepadYaml.png\|right\|thumb\|Notepad++ Settings for editing OpenXcom YAML files]]

			OpenXcom exposes its inner workings to users and modders in the form of [[:Wikipedia:YAML\|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. Make sure you use UTF-8 encoding! (this is important for when you add strings and translations)

			===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. There's also [http://yaml-online-parser.appspot.com/ online YAML validators].

			*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)==
			# Open the ''Data\Ruleset\Xcom1Ruleset.rul'' file in your YAML editor.
			# Collapse everything (Alt-0 in Notepad++) and then open (uncollapse) the "facilities:" section.
			# Open "- type: STR_LIVING_QUARTERS"
			# change "personnel: 50" to "personnel: 500"
			# 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 - <i>shoot down Supply Ships and Large Scouts without getting hit</i>, 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 those 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"
			* Finally if you want to be able to equip blasters to your squad and use them you will have to remove the tech requirement. Go back to "items:" and completely remove the section for tech requirements from both blasters and bombs.
			:Start a new game, load up blasters on your sky-ranger, 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.

			== Modular Rulesets ==

			However, editing the main ''Xcom1Ruleset.rul'' is bad practice, as your changes will be wiped by any new versions, and it makes it a pain to keep updating and combining different rulesets. Instead you should make it modular, by making your own ruleset file (saved in ''data\Ruleset'') with only the changes it makes to the base game, for example a ''BiggerQuarters.rul'':

			facilities:
			- type: STR_LIVING_QUARTERS
			personnel: 500

			Then to load your extra ruleset into the game, you just go in your ''[[Options (OpenXcom)\|options.cfg]]'' file and add it like so:

			rulesets:
			- Xcom1Ruleset
			- BiggerQuarters

			Now when you start up the game, it'll automatically combine all the rulesets listed in the ''options.cfg''. Note that the order is important, as subsequent rulesets will modify the contents of previous ones (if the '''type''' is the same), so in this case ''BiggerQuarters'' will modify the STR_LIVING_QUARTERS of ''Xcom1Ruleset'', which is what you want. Normally you always want ''Xcom1Ruleset'' to come first. Note that you can also specify the order of your rulesets when starting your game by selecting the rulesets in the order you would like to have them applied.

			If you need to specifically erase a field, for example to clear requirements for something (like making an item or research available from the start of the game), you can use "" for an empty string, [] for an empty list and {} for an empty map. For example:

			requires: []

			If you want to remove an entire entry from a previous ruleset, you just need to specify "delete: STR_ID", for example:

			facilities:
			- delete: STR_LIVING_QUARTERS

			But be careful, as this will break any saves already using that item. If you want people to be able to use your new ruleset on existing saves, it's safer to just disable it, like adding a requirement that can not be met. For example, if you want to make the Heavy Plasma unavailable for the player, you can add an otherwise non-existing research topic (for example "STR_ALIENS_ONLY", so it can be easily identified for later modifications...). this would have to be researched in order to use the weapon, but since it isn't defined anywhere else, it effectively disables the weapon for the player:

			- type: STR_HEAVY_PLASMA
			requires:
			- STR_ALIENS_ONLY

			== See Also ==

			* [[Ruleset Reference (OpenXcom)\|Ruleset Reference]]
			* [http://openxcom.org/forum/index.php/board,8.0.html Modding forum]

			[[Category:OpenXcom]]

Hobbes: Protected "Rulesets (OpenXcom)" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

2026-03-10T14:01:11Z

Protected "Rulesets (OpenXcom)" ([Edit=Allow only administrators] (indefinite) [Move=Allow only administrators] (indefinite))

← Older revision		Revision as of 14:01, 10 March 2026
(No difference)

Hobbes: Redirected page to OpenXcom

2026-03-10T14:00:54Z

Redirected page to OpenXcom

← Older revision		Revision as of 14:00, 10 March 2026
Line 1:		Line 1:
	~~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:~~		#REDIRECT [[OpenXcom]]
	*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)==~~
	~~[[Image:OpenXcomNotepadYaml.png\|right\|thumb\|Notepad++ Settings for editing OpenXcom YAML files]]~~

	OpenXcom exposes its inner workings to users and modders in the form of [[:Wikipedia:YAML\|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. Make sure you use UTF-8 encoding! (this is important for when you add strings and translations)

	~~===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. There's also [http://yaml-online-parser.appspot.com/ online YAML validators].

	*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)==~~
	~~# Open the ''Data\Ruleset\Xcom1Ruleset.rul'' file in your YAML editor.~~
	~~# Collapse everything (Alt-0 in Notepad++) and then open (uncollapse) the "facilities:" section.~~
	~~# Open "- type: STR_LIVING_QUARTERS"~~
	~~# change "personnel: 50" to "personnel: 500"~~
	# ~~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 - <i>shoot down Supply Ships and Large Scouts without getting hit</i>, 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 those 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"
	* Finally if you want to be able to equip blasters to your squad and use them you will have to remove the tech requirement. Go back to "items:" and completely remove the section for tech requirements from both blasters and bombs.
	:Start a new game, load up blasters on your sky-ranger, 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.

	~~== Modular Rulesets ==~~

	However, editing the main ''Xcom1Ruleset.rul'' is bad practice, as your changes will be wiped by any new versions, and it makes it a pain to keep updating and combining different rulesets. Instead you should make it modular, by making your own ruleset file (saved in ''data\Ruleset'') with only the changes it makes to the base game, for example a ''BiggerQuarters.rul'':

	~~facilities:~~
	~~- type: STR_LIVING_QUARTERS~~
	~~personnel: 500~~

	~~Then to load your extra ruleset into the game, you just go in your ''[[Options (OpenXcom)\|options.cfg]]'' file and add it like so:~~

	~~rulesets:~~
	~~- Xcom1Ruleset~~
	~~- BiggerQuarters~~

	Now when you start up the game, it'll automatically combine all the rulesets listed in the ''options.cfg''. Note that the order is important, as subsequent rulesets will modify the contents of previous ones (if the '''type''' is the same), so in this case ''BiggerQuarters'' will modify the STR_LIVING_QUARTERS of ''Xcom1Ruleset'', which is what you want. Normally you always want ''Xcom1Ruleset'' to come first. Note that you can also specify the order of your rulesets when starting your game by selecting the rulesets in the order you would like to have them applied.

	If you need to specifically erase a field, for example to clear requirements for something (like making an item or research available from the start of the game), you can use "" for an empty string, [] for an empty list and {} for an empty map. For example:

	~~requires: []~~

	~~If you want to remove an entire entry from a previous ruleset, you just need to specify "delete: STR_ID", for example:~~

	~~facilities:~~
	~~- delete: STR_LIVING_QUARTERS~~

	But be careful, as this will break any saves already using that item. If you want people to be able to use your new ruleset on existing saves, it's safer to just disable it, like adding a requirement that can not be met. For example, if you want to make the Heavy Plasma unavailable for the player, you can add an otherwise non-existing research topic (for example "STR_ALIENS_ONLY", so it can be easily identified for later modifications...). this would have to be researched in order to use the weapon, but since it isn't defined anywhere else, it effectively disables the weapon for the player:

	~~- type: STR_HEAVY_PLASMA~~
	~~requires:~~
	~~- STR_ALIENS_ONLY~~

	~~== See Also ==~~

	* [[Ruleset Reference (OpenXcom)\|Ruleset Reference]]
	* [http://openxcom.org/forum/index.php/board,8.0.html Modding forum]

	[[~~Category:~~OpenXcom]]

IvanDogovich: /* Modular Rulesets */ ordering rulesets

2015-02-13T22:53:34Z

Modular Rulesets: ordering rulesets

← Older revision		Revision as of 22:53, 13 February 2015
Line 68:		Line 68:
	- BiggerQuarters		- BiggerQuarters

	Now when you start up the game, it'll automatically combine all the rulesets listed in the ''options.cfg''. Note that the order is important, as subsequent rulesets will modify the contents of previous ones (if the '''type''' is the same), so in this case ''BiggerQuarters'' will modify the STR_LIVING_QUARTERS of ''Xcom1Ruleset'', which is what you want. Normally you always want ''Xcom1Ruleset'' to come first.		Now when you start up the game, it'll automatically combine all the rulesets listed in the ''options.cfg''. Note that the order is important, as subsequent rulesets will modify the contents of previous ones (if the '''type''' is the same), so in this case ''BiggerQuarters'' will modify the STR_LIVING_QUARTERS of ''Xcom1Ruleset'', which is what you want. Normally you always want ''Xcom1Ruleset'' to come first. Note that you can also specify the order of your rulesets when starting your game by selecting the rulesets in the order you would like to have them applied.

	If you need to specifically erase a field, for example to clear requirements for something (like making an item or research available from the start of the game), you can use "" for an empty string, [] for an empty list and {} for an empty map. For example:		If you need to specifically erase a field, for example to clear requirements for something (like making an item or research available from the start of the game), you can use "" for an empty string, [] for an empty list and {} for an empty map. For example:

SupSuper at 13:00, 2 June 2014

2014-06-02T13:00:41Z

← Older revision		Revision as of 13:00, 2 June 2014
Line 11:		Line 11:
	[[Image:OpenXcomNotepadYaml.png\|right\|thumb\|Notepad++ Settings for editing OpenXcom YAML files]]		[[Image:OpenXcomNotepadYaml.png\|right\|thumb\|Notepad++ Settings for editing OpenXcom YAML files]]

	OpenXcom exposes its inner workings to users and modders in the form of [[:Wikipedia:YAML\|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.		OpenXcom exposes its inner workings to users and modders in the form of [[:Wikipedia:YAML\|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. Make sure you use UTF-8 encoding! (this is important for when you add strings and translations)

	===Notepad++===		===Notepad++===
Line 17:		Line 17:

	===Can't Notepad++?===		===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.		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. There's also [http://yaml-online-parser.appspot.com/ online YAML validators].

	*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.		*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.

SupSuper at 00:41, 28 May 2014

2014-05-28T00:41:00Z

← Older revision		Revision as of 00:41, 28 May 2014
Line 62:		Line 62:
	personnel: 500		personnel: 500

	Then to load your extra ruleset into the game, you just go in your ''[[~~Customizing~~ (OpenXcom)\|options.cfg]]'' file and add it like so:		Then to load your extra ruleset into the game, you just go in your ''[[Options (OpenXcom)\|options.cfg]]'' file and add it like so:

	rulesets:		rulesets:

SupSuper: Moved reference to a separate page

2013-10-29T15:32:12Z

Moved reference to a separate page

Show changes

SupSuper: /* Modular Rulesets */

2013-10-29T15:24:35Z

Modular Rulesets

← Older revision		Revision as of 15:24, 29 October 2013
Line 70:		Line 70:
	Now when you start up the game, it'll automatically combine all the rulesets listed in the ''options.cfg''. Note that the order is important, as subsequent rulesets will modify the contents of previous ones (if the '''type''' is the same), so in this case ''BiggerQuarters'' will modify the STR_LIVING_QUARTERS of ''Xcom1Ruleset'', which is what you want. Normally you always want ''Xcom1Ruleset'' to come first.		Now when you start up the game, it'll automatically combine all the rulesets listed in the ''options.cfg''. Note that the order is important, as subsequent rulesets will modify the contents of previous ones (if the '''type''' is the same), so in this case ''BiggerQuarters'' will modify the STR_LIVING_QUARTERS of ''Xcom1Ruleset'', which is what you want. Normally you always want ''Xcom1Ruleset'' to come first.

			If you need to specifically erase a field, for example to clear requirements for something (like making an item or research available from the start of the game), you can use "" for an empty string, [] for an empty list and {} for an empty map. For example:

	If you want to completely erase requirements for something (like making an item or research available from the start of the game), you need to define a new "requirement" or "dependencies" entry that reads "[]~~", for example:~~		requires: []

	~~requires~~: []		If you want to remove an entire entry from a previous ruleset, you just need to specify "delete: STR_ID", for example:

			facilities:
			- delete: STR_LIVING_QUARTERS

	If you want to disable ~~something~~, ~~the best way is to add~~ a requirement that can not be met. For example, if you want to make the Heavy Plasma unavailable for the player, you can add an otherwise non-existing research topic (for example "STR_ALIENS_ONLY", so it can be easily identified for later modifications...). this would have to be researched in order to use the weapon, but since it isn't defined anywhere else, it effectively disables the weapon for the player:		But be careful, as this will break any saves already using that item. If you want people to be able to use your new ruleset on existing saves, it's safer to just disable it, like adding a requirement that can not be met. For example, if you want to make the Heavy Plasma unavailable for the player, you can add an otherwise non-existing research topic (for example "STR_ALIENS_ONLY", so it can be easily identified for later modifications...). this would have to be researched in order to use the weapon, but since it isn't defined anywhere else, it effectively disables the weapon for the player:

	- type: STR_HEAVY_PLASMA		- type: STR_HEAVY_PLASMA

Warboy1982: /* Armor */

2013-10-14T08:59:11Z

Armor

← Older revision		Revision as of 08:59, 14 October 2013
Line 925:		Line 925:
	\| Physical weight of the armor when worn		\| Physical weight of the armor when worn
	\| 6		\| 6
			\|-
			\| '''stats'''
			\| like soldier stats (see below) but these are treated as stat bonuses for wearing the specific armor.
			\| -
	\|-		\|-
	\| '''frontArmor'''		\| '''frontArmor'''

Warboy1982: /* Armor */

2013-10-14T04:44:09Z

Armor

← Older revision		Revision as of 04:44, 14 October 2013
Line 921:		Line 921:
	\| String ID of the [[#Items\|item]] that represents this armor in [[Base Stores]].		\| String ID of the [[#Items\|item]] that represents this armor in [[Base Stores]].
	\| -		\| -
			\|-
			\| '''weight'''
			\| Physical weight of the armor when worn
			\| 6
	\|-		\|-
	\| '''frontArmor'''		\| '''frontArmor'''