CreatingSubstitutions

Introduction

Substitutions are wildcard pieces of text that can be written into mission text and ship hails that get replaced with a separate piece of text before being displayed to the player. These substitutions must be in the form "<text>" where the < and > are required parts of the wildcard.

Certain substitutions are hardcoded; these can be found in the creating missions page. Beginning with v0.9.15, content creators are able to create custom substitutions.

The syntax for the definition of a custom substitution is:

substitutions
	<text> <replacement>
		[<condition set>]
	...

Substitution characteristics

A substitutions node can be defined in two places. The first place is as a child of a missions node, as described in creating missions. Substitutions defined in this way apply only to the mission they are defined within. The second way to define substitutions is with the substitutions node being a root node. Substitutions defined in this way are applied globally to all missions and ship hails.

The three types of substitutions, hardcoded, mission-specific, and global, have a specific precedence and order of execution to them. Global substitutions are replaced first, followed by mission-specific substitutions, and finally hardcoded substitutions. If a specific text-replacement is defined in more than one location, then the substitution that is executed later is the one that is used. For example, since <first> is a hardcoded substitution, this text replacement can never be used or modified by global or mission-specific substitutions. This order of execution can be taken advantage of to create text replacements that substitute into more text replacements. See the Examples section for how this can be done.

<text> <replacement>

Substitutions simply search for the text on the left and replace it with the text on the right whenever it is found within a piece of text. As mentioned above, multiple replacements of the same text can be defined, but whichever replacement is evaluated last is the one that gets used.

A substitutions node can define multiple text replacements at once.

<text> <replacement>
	[<condition set>]

Text replacement lines are able to define a condition set that determines whether the text replacement is used. This allows for certain text replacements to only be used under certain circumstances. Combining this with defining multiple replacements for the same piece of text, you can create a substitution that reacts to the player's actions or attributes.

Note that currently, the condition sets for substitutions are evaluated when the mission is instantiated. This means that actions taken during a mission can not change the outcome of any substitutions, as they have already made their text replacements. If you wish to change the outcome of text based on conditions that could have changed during the mission, then you should instead use branch or to display.

Examples

Using global substitutions

Global substitutions are defined by a substitutions root node. This node can be placed in any data file at any point, and the new replacements will be added to a global list by the game.

substitutions
	"<author>" "Michael Zahniser"

phrase "thank the author"
	word
		"Remember to thank the author, <author>!"

mission "Wow!"
	...
	on offer
		conversation
			`You walk into the spaceport and run into none other than <author>, the creator of the game!`
			...

The above substitution, phrase (should it be used as a ship hail), and mission would result in the hail, "Remember to thank the author, Michael Zahniser!" and the mission conversation, "You walk into the spaceport and run into none other than Michael Zahniser, the creator of the game!"

Using mission substitutions

Mission substitutions are defined by a substitutions node that is a child of a mission.

mission "Oh no"
	...
	landing
	substitutions
		"<nemesis>" "Blue"
	dialog
		`When you land, you walk within the line of sight of your nemesis <nemesis>, who challenges you to a duel. Do you accept?`

Substitutions will apply to all text generated by a mission (e.g. conversations, dialogs, mission description). The above would result in the dialog, "When you land, you walk within the line of sight of your nemesis Blue, who challenges you to a duel. Do you accept?"

Order of precedence

substitution
	"<greeting>" "Hello there"
	"<mission>" "destroy"
	"<planet>" "Luna"

mission "Destroy the Moon?"
	...
	destination "Earth"
	substitutions
		"<mission>" "travel to"
		"<planet>" "New Boston"
	on offer
		conversation
			`<greeting>. I want you to <mission> <planet>.`
			...

The above conversation would read, "Hello there. I want you to travel to Earth." The global substitution <greeting> is never overridden and thus gets used. The substitution <mission> is defined globally and within the mission, but the mission-specific substitution takes precedence over the global definition. The substitution <planet> is defined by all three sources, but the hardcoded replacement of the mission's destination planet takes precedence over the other two substitution sources.

Order of execution

substitution
	"<storage>" "<container> of <commodity>"

mission "Forrest Gump"
	...
	cargo "chocolates" 1
	substitutions
		"<container>" "a box"
	on offer
		dialog
			"You sit down on a bench next to Forrest Gump. He offers you <storage>."

The above dialog would read, "You sit down on a bench next to Forrest Gump. He offers you a box of chocolates." Since global substitutions are executed first, the sentence He offers you <storage>. becomes He offers you <container> of <commodity>. The <container> text is then replaced with "a box" by the mission substitutions, and <commodity> is replaced by "chocolates" from the hardcoded substitutions.

The same behavior would be observed if <storage> was defined above <container> within the mission substitutions. But if the order was reversed then the dialog would read, "He offers you <container> of chocolates," since the <container> replacement would have already been executed before the text "<container>" was added to the dialog.

Using condition sets on replacements

substitutions
	"<net worth>" "poor"
	"<net worth>" "rich"
		"net worth" >= 100000000

The above substitutions would replace <net worth> with "poor", unless the player's net worth condition is above 100m credits, in which case the replacement would become "rich". Should the player's net worth drop, then the "poor" replacement would be used again.

Since substitutions are evaluated in the order they are defined, one must be careful with how they order conditional substitutions. For example, if instead of defining the "poor" replacement first, the "rich" replacement were defined first, then the "poor" replacement would always overwrite the "rich" replacement, since an empty condition set is always true. Similarly, if there were some third replacement with a condition of "net worth" >= 1000000, then that would need to be defined between the two in the example, as if it were defined first then it would be overwritten by "poor," and if it were defined last then it would always overwrite "rich."

Changing substitutions through events

The global substitutions list can be added to through events.

substitutions
	"<title>" "Captain"

event "player warlord"
	substitutions
		"<title>" "Warlord"

mission "You are now a warlord"
	to offer
		"reputation: Pirate" > 100
		"reputation: Merchant" < 100
	on offer
		event "player warlord"
		fail

The above data would change the player's title replacement from "Captain" to "Warlord" after you get a high enough pirate reputation and a low enough merchant reputation. The distinction between using an event to make this change and defining the substitution like below is that the above data creates a permanent change, while the below data would change the player's title back to "Captain" if they improved their reputation with merchants or lost reputation with pirates.

substitutions
	"<title>" "Captain"
	"<title>" "Warlord"
		"reputation: Pirate" > 100
		"reputation: Merchant" < 100