Scenario system

2019-10-14T13:53:16Z

Wheybags: Added section on packaging a scenario as a mod

{{Languages}}

The scenario system allows save-based mods to be created, so that installing mods separately is not necessary. This allows for server side scripting, or to provide a separate objective than the vanilla freeplay (which is actually a scenario, just like the [[campaign]]).

== Creation ==

Creation of a scenario starts in the world editor. The world editor allows an author to save a world that they have created as a scenario. This allows players to add special scripting to the scenario.

There are two ways to create a scenario:

* Via the [[Map editor]].
* Creating a new folder in the scenarios folder, and adding a control.lua.

== Differences between scenarios, saves, and mods ==

There are a few differences between a scenario, a save, and a mod. In a way, a scenario takes parts from both.

* Scenarios, unlike mods, cannot add anything to the game. The only type of scripting allowed in a scenario is scripting that would occur in control.lua.
* Scenarios can have premade maps, such as the supply scenario, or can have maps made with the world generator, such as freeplay.
* Scenarios do not need to be installed client side, unlike mods. This allows servers to implement small changes to gameplay on their end, such as displaying a MOTD to joining players.
* Scenarios, unlike normal saves, are stored in a different folder.
* Scenarios can be used to create a bit of a story, as the campaign does.

== Limitations of Scenarios ==

* Scenarios must be packaged into a mod to be distributed on the mod portal.
* Scenarios cannot add anything to the game (Namely, they may not make calls to data:extend()).
* Scenarios count as mods for the purpose of isolating [[achievements]].

== Playing a scenario ==

There are several scenarios included into the game by default. To play a scenario, click Play->Scenarios, and choose either a user scenario, or a scenario from the base game or mod. The Freeplay scenario is the same as the basic game, where the objective is to launch a rocket.

Upon choosing a scenario to play and saving the game, a normal save will be created that encompasses the map itself, and the control.Lua scripting that was provided by the scenario. This can be removed by deleting the script.dat and control.Lua files from the save, turning it into a normal save. Do this at your own risk, as it may break the save depending on how intertwined the scenario is with the save.

== Installing scenarios ==

Scenarios made by other players can be installed into a folder called scenarios in the player's [[application directory#User_data_directory|user data directory]]. It can then be played from the scenarios menu.

Scenarios added by mods are also shown in the Scenarios menu.

== Packaging a scenario as a mod ==
Create an empty mod, as described in [[Tutorial:Mod_structure]]. Then, simply add a "scenarios" folder, and copy your scenario into that folder. If you created a scenario with the map editor, you can find it in the scenarios folder in your [[application directory#User_data_directory|user data directory]].

== See also ==

* [[Campaign]]
* [[Map editor]]
* [[World generator]]

Tutorial:Localisation

2019-06-27T16:13:13Z

Wheybags: Add section about alternate input names

{{Languages}}Mods should define human readable names for prototypes that they add. They can also define descriptions for items or custom strings for usage in GUIs etc. This is called '''localisation'''.

== Format ==
Translations are stored as .cfg files, with the following format:

<pre>welcome-message=Hello world
[category]
title=Category related title</pre>
Any whitespace after or before <code>=</code> is included in the key or string, so <code>title =Category related title</code> will give an unknown key error if you are looking for the <code>title</code> key, since it is the <code>title </code> key.

These files are located within the language suffix of the language in the locale folder of the mod, so as an English example <code>__mod__/locale/en/any_name_here.cfg</code>. There can be more than 1 file per language, all of them will be read.

== Usage ==
=== Localising simple strings ===
The simplest localisation is of items, entities etc. If we say the item is <code>iron-plate</code>, the game will then search all loaded locale files for <code>item-name.iron-plate</code> and <code>item-description.iron-plate</code>, which in the locale file looks like this:

<pre>[item-name]
iron-plate=Iron plate
[item-description]
iron-plate=A plate made of iron.</pre>
If found in the locale, the label is set to this string. If not found, the game will instead show: <code>Unknown key: "item-name.iron-plate"</code>

In script, the localised string is formatted as <code>{"category.name"}</code>, so <code>game.print({"item-name.iron-plate"})</code> prints ''Iron plate''.

=== Localising with parameters ===
For more complex strings, localisation parameters can be used. For instance we want to show ''Time left: 10 minutes.''

So a key with a placeholder is defined, which is replaced by the first parameter after the locale key.:

<pre>time-left=Time left: __1__ minutes.</pre>
So it is used like this:

<source lang="lua">game.print({"time-left", 10})</source>
It also works with multiple parameters:

<source lang="lua">game.print({"time-left", 10, 45})</source>
<pre>time-left=Time left: __1__ minutes and __2__ seconds.</pre>
Which results in ''Time left: 10 minutes and 45 seconds.''

==== Built-in parameters ====
For some situations, we use localisation to show control schemes. For instance we want to say:

<pre>technology-prompt=Use T to open the technology screen</pre>
However the player may have rebound the key, but we can’t figure out which key as it would not be deterministic. So instead we use the built-in replacement functionality

<pre>technology-prompt=Use __CONTROL__open-technology-gui__ to open the technology screen.</pre>
We can also use this for items and entities etc.:

<pre>big-iron-plate=Big __ITEM__iron-plate__</pre>

==== Plurals ====
Pluralization can be used in any string that uses a parameter (e.g. __1__) that is numeric, so something like an amount of minutes. It can be used multiple times per string.

<pre>format-days=__1__ __plural_for_parameter_1_{1=day|rest=days}__</pre>
This results in "1 day" and "2 days" / "500 days" etc.

The number after <code>__plural_for_parameter_</code> denotes which parameter is used to determine the plural. This is the parameter 1 in the above example. Anything inside the {} is used to make the plural. Each plural form is separated by a |.
The text in front of the = determines for what the plural form is used. Options for this are:
* a simple number, e.g. "1".
* Multiple numbers, e.g. "2,3,4".
* What the number ends with, e.g. "ends in 11" or "ends in 1"
* Multiple ends with, e.g. "ends in 1,ends in 2,ends in 12".
* "rest" to give the default plural.

Plural forms may be empty or contain other keys such as __1__ or spaces. This allows rather large plural forms:

<pre>__plural_for_parameter_1_{1=__1__ player is|rest=__1__ players are}__ connecting</pre>

The system chooses the first fitting plural that it encounters when multiple would fit:
<pre>__plural_for_parameter_1_{ends in 12=option 1|ends in 2=option 2|rest=option 3}__</pre>
This will result in "option 1" for 12 and in "option 2" for 22 and in "option 3" for numbers not ending with 2.

=== Concatenating localised strings ===
The special locale key: <code>""</code> is used to concatenate, as the table format does not support concatenation:

<source lang="lua">game.print({"", {"item-name.iron-plate"}, ": ", 60})</source>
Will result in: ''Iron plate: 60''

=== Localising alternate input names ===
'''NOTE: This system is not released in a public version of the game yet, but will be soon. This note will be removed then.'''

In the introduction campaign, a special locale system is used for informing players how to do certain actions with their mouse.
The normal form is to use eg:
<pre>how-to-build=Use __CONTROL__build__ to place a building</pre>
which results in "Use Left mouse button to place a building". A more natural phrasing would be "Left click to place a building", which can be achieved by using the following:
<pre>how-to-build=__ALT_CONTROL__1__build__ to place a building</pre>

These "alt" versions are controlled by a few special locale keys, mouse-button-X-alt-1 and mouse-button-X-alt-2. In English, form 1 produces eg "Left click", and form 2 produces eg "left clicking". Only two alt forms ("1" and "2") are available at the moment, but if this a problem for some languages, we can add more.
Extra mouse buttons are handled through the mouse-button-n-alt-1/2 keys, which just take the normal name and prepend something like "Press" or "Pressing".

When translating to another language, you can use whatever forms you want here, but the important part is that you are consistent when you use the alt-forms everywhere else. It does not necessarily make sense to just copy the usages of alt forms from the English locale, and for some languages it may be more natural to simply not use this system at all.

Official Factorio Wiki - User contributions [en]

Scenario system

Tutorial:Localisation