Editing Mod:Scripts

This tutorial shows the basics of scripting in ''[[Wikipedia 2197|The Sum]]''. To code dialogues, it is best to [[Mod:Create_a_dialogue#Scripting dialogue (advanced)|follow the steps in this tutorial]].
[[file:Ecran Scripts.jpg|thumb|Preview of the script page.]]

== Outils requis ==
[[file:Ecran Level Editor.jpg|thumb|This tutorial uses mainly the Level editor.]]
* [[Mod:Éditeurs#.C3.89diteur_de_niveaux_.28Level_editor.29|''Level editor''.]]

== Before You Begin ==
Please take some time to read the "Scripting" section of the [http://10projets.org/nousaurons/editor_readme.html#Levelsection7 readme file of the Fallout Tactics editor].

== Terms to learn ==
=== Entity ===
Character (''actor'') and/or object, an entity is an interactive element of the game. Most of the scripts concern and affect entities.

=== Player ===
Each entity (character or interactive object) is associated with a "player", whether controlled by the player or not. Each player is linked to a team, and several players can have the same team. There is an unlimited number of players.{{Idea|It is possible to assign special behaviors (AI) to each player, such as running away from the player.}}In ''[[Wikipedia 2197|The Sum]]'', the basic players are:
<ol start="0">
<li>'''Scenary :''' Everything that is part of the ''decor'' and does not have a particular behavior. '''Behavior:''' passive.</li>
<li>'''Joueur :''' Any entity controlled by the player.</li>
<li>'''Animaux :''' Animals on the map. '''Behavior:''' Friendly by default, hostile if the player skins an animal or has raw meat on them without bones to ''distract'' the animals.</li>
<li>'''Humains :''' Various entities. '''Behavior:''' Neutral by default, hostile if injured in the presence of the player.</li>
<li>'''Ennemis :''' Various entities. '''Behavior:''' Hostile by default, friendly under certain scripted circumstances.</li>
<li>'''Amis :''' Various entities. '''Behavior:''' Friendly by default, hostile if injured in the presence of the player.</li>
<li>'''Banque :''' Scripted Entities. '''Behavior:''' Never hostile.</li>
</ol>

=== Team ===
Each ''team'' determines the alignment (from hostile to friendly) of a ''player'' towards others teams. This alignment goes from -10 (complete hostility, red dot in the minimap) to 10 (complete friendliness, green dot in the minimap). 0 indicate the neutrality (gray dot in the minimap).

=== Quantity ===
''Quantity'' refers to a large list of possible conditions for entities, pretty much everything that is part of their entity file ('''.ent''') (e.g. Strength, Dexterity, Age, Sex, % of Life Points, Living or Dead, Perks, Electricity, etc.) can be checked (counted) in one of the conditions starting with: ''Quantity -''.

=== Waypoint ===
A ''waypoint'' is an invisible marker added to a location with the [[Mod:Editors#Level_editor|Level_editor]]. Each waypoint has a code name and an index, and several waypoints can share the same name. It is possible to program a movement of characters by programming a series of waypoints.

=== Zone ===
Areas are rectangular prisms (with a width, length and height) with a unique code name in a location. Several conditions determine the presence or characteristics of entities in zones. They are created and used in the [[Mod:Editors#Level_editor|Level_editor]].

=== Exit Grid ===
A green area at the edges of a location that allows, when walking in the middle of it, to leave the current location to access the [[The Sum:Worldmap|Worldmap]].

== Create a script ==
=== Open the location file (level editor) ===
# Open the folder ''Game''/ then ''FT Improver.EXE''.{{Warning|Use ''FT Tools.exe'' instead will result in an error.}}
# Pass the videos by clicking on them.
# Click on {{False button|MORE|color=black|button=yes}}.
# Click {{False button|LEVEL EDITOR|color=black|button=yes}}.
# Navigate to the {{False button|File|color=gray|border=black}} menu then {{False button|Open|color=gray3}}.
# Open the file of the place previously created which must end with '''.mis'''.

=== Accessing scripts ===
Scripts are stored and coded in the [[Mod:Editors#Level_editor|Level Editor]].
# Click on the {{False button|Level|color=black2}} tab.
# Click on the {{False button|Triggers...|color=gray|bord=black}} tab at the bottom left.

=== Add a script ===
In the[[Mod:Editors#Level_editor|Level Editor]], a script is a series of '''conditions''' leading (if they are '''all''' true) to a series of '''actions'''. <font color="red">Warning: There is no such thing as "or" (''or'') in the editor</font>. You can create as many scripts as you need, but they only work in the location in which they were added.{{Idea|For each script, add a short description that is easy to understand (example: ''ENEMY LEAK - 1 dead)''.}}

==== Conditions ====
There are 20 conditions. The ones that are not recommended to use are crossed out.
* '''Always:''' Default condition, it is always true. Useful when you want to produce an action that starts automatically, like assigning variables.
* '''Never:''' It is always false. Useful to disable a script temporarily.
* '''Speech Occured:''' A dialog window with the specified code name has opened. Can be triggered by scripts using the ''Force Speech'' action.
* '''Skill Use Occured:''' A character with the specified code name has used a [[Skill]].
* '''Variable:''' A specified variable has a specified value.
* '''Timer:''' A timer with the specified code name has reached a specified value.
* '''Quantity - Team:''' Number of elements (''<''' '''>''' or '''=''') of the same type in a specified ''team''.
* '''Quantity - Player:''' Number of elements ('''<''' '''>''' or '''=''') of the same type of a specified ''player''.
* '''Quantity - Player Kills:''' Comparaison, entre deux ''players'', du nombre de personnages tués.
* '''Quantity - Unit:''' Number of elements ('''<''' '''>''' or '''=''') of the same type of a specified entity.
* '''Object Script State:''' State ('''on''' or '''off''') of an interactive object, such as a switch or a door.
* <font color="grey"><s>'''WeaponMode is:''' These modes are not used in ''The Sum'</s></font>
* <font color="grey"><s>'''World mode of play is:''' The game mode of ''The Sum'' is '''CTB''' by default.</s></font>
* '''Gui Open:''' Game window opened by the player. '''Inv''' (Bag), <font color="grey"><s>'''Main'''</s></font>, '''Char''' (Char), '''Loot''' (Scavenge), '''Steal''' (Steal), '''Barter''' (Exchange), '''Options''' (Options), '''Skilldex''' (Do), '''Pipboy''' (GPSP) and <font color="grey"><s>'''Speech''' (Dialogue)</s></font>.
* <font color="grey"><s>'''Right Click on Tab:''' No use.</s></font>
* ''All Alive at Exit Grid:'' True if all characters still alive in the player's team are present in an ''Exit Grid'', the green areas at the edge of the location used to reach the game map.
* ''Can See:'' True if one ''player'' character is able to ''see'' one of another ''player'' characters. Characters who use the Skill ''Sneak'' do not trigger this condition.
* <font color="grey"><s>'''Brain Extraction Complete:''' No use.</s></font>
* <font color="grey"><s>'''MP - Game Timed Out:''' ''The Sum'' does not work in ''Multiplayer'' mode.</s></font>
* <font color="grey"><s>'''Main Actor Alive:''' Since the game ends when the main character dies, this condition is equivalent to ''Always''.</s></font>

==== Actions ====
There are 61 actions. The ones that are not recommended are crossed out.
* '''Center view:''' Center the view on a specified entity. The rest of the time, [[The_Sum:About/2#View|The view can be changed freely by the player]].
* '''Player Retreat Zone:''' Assigns a ''Retreat Zone'' to a ''player'' (area where a ''player's'' characters will go if severely injured).
* '''Player Move State - Deactivate:''' Deactivate a player. It disappears.
* '''Player Move State - Stationary:''' Out of combat, makes the characters of a ''player'' static. If disabled, they appear.
* '''Player Move State - Perimeter:''' Out of combat, assigns a zone to a ''player'' (zone in which the characters try to stay).
* '''Player Move State - Wander:''' Out of combat, assigns a zone to a ''player'' (area in which he wanders).
* '''Player Move State - Follow:''' Out of combat, assigns the code name of a character to a ''player''. The characters of this ''player'' try to follow them.
* '''Player Move State - WayPoint:''' Out of combat, assign the first ''WayPoint'' (index 0) of a specified name to the characters of a ''player''. They will walk (depending on their ''Priority'') to this first ''WayPoint'' and then other ''WayPoints'' of the same name if they exist.{{Warning|If the script is marked as {{False button|✔ Preserve|color=black2}}, the characters will never walk beyond the index 0.}}
* '''Player Move State - Flee:''' Instructs the characters of a ''player'' to run away to a specified zone.
* '''Player Priority - Move State:''' Chance that the characters of a ''player'' move when a script asks them. At 10, they drop everything and move. Above 8, they run instead of walking.
* '''Player Priority - Aggression:''' Chance that the characters of a ''player'' attack another when a script asks them.
* '''Player Priority - Communication:''' Distance at which the characters of the same ''player'' realize that another is attacked. At 0, they do not react, at 10, they ''communicate'' on the whole map.
* '''Player Priority - Mobility:''' Out of combat, how often the characters of a ''player'' move. At 1, they stop at every step or so, at 10, they are always moving.
* '''Player Priority - Kill Player:''' Chance that the characters of a ''player'' attack another ''player'' when a script asks them.
* '''Player Priority - Kill Unit:''' Chance that the characters of a ''player'' attack a specified entity when a script asks them.
* '''Set Variable:''' Assign a value (text) to a variable. It is possible to check the option {{False button|Campaign|color=gray}} so that the variable is read in other places.
* '''Set Timer:''' Sets and starts an ascending or descending timer (if the {{False button|Decending|color=gray}} box is checked.{{Warning|A timer left running when exiting a location can sometimes make the game crash.}}
* '''Stop Timer:''' Stops a specified timer.
* '''Show Timer:''' Show a specified timer at the top of the screen, visible to the player.

* '''Wait:''' Waits a specified number of seconds before performing the following actions in the list.{{Avertissement|''Wait'' works only when the {{False button|✔ Blocking|color=black2}} box is checked in the action settings.}}
* '''Add Objective:''' Adds a task (among the entries in the location ''.txt'' file) to the player's to-do list (screen ''GPSP''). If the {{False button|with popup box|color=gray}} box is checked, a task notification appears on the main screen.
* '''Complete Objective:''' Complete (changes to gray) a specified task (among the entries in the location's ''txt'' file) to the player's task list (screen ''GPSP'').
* <font color="grey"><s>'''Set Death Text:''' Not used.</s></font> 
* '''End Mission:''' Quit the game ({{Faux bouton|Main Menu|couleur=noir2}}), Open the [[Worldmap]] ({{Faux bouton|World Map|couleur=noir2}}), <font color="grey"><s>Kill the [[Main character|main character]] ({{Faux bouton|Death Screen|couleur=noir2}}), bring up the fail screen ({{Faux bouton|Fail Screen|couleur=noir2}}) or victory screen ({{Faux bouton|Win Screen|couleur=noir2}}).</s></font>
* '''Goto Mission:''' Instantly moves the player and all his characters to a location (specified by its code name).
* <font color="grey"><s>'''Toggle Exit Grids:''' The ''Exit Grids'' are always functional in ''The Sum''.</s></font> 
* '''Set Click Speech:''' Assigns a dialogue (added in the tab {{Fake Button|Level|color=black2}} and button {{Fake Button|Speech...|color=gray|border=black}}) to a specified entity. This one is triggered when the player clicks on it.{{Idea|Using ''Set Click Speech'' on a specified entity with the parameter "None" removes a dialog already programmed.}}
* ''Set Random Speech:'' Assigns a dialogue (added in the tab {{False button|Level|color=black2}} and button {{False button|Speech...|color=gray|border=black}}) floating above the head of a specified entity. This one is displayed from time to time.{{Idea|Using ''Set Random Speech'' on a specified entity with the parameter "None" removes an already programmed dialog.}}
* '''Play Wav:''' Plays a ''.wav'' file from the ''Game/core/sound/'' folder. The {{False button|Sound Id|color=gray}} must be unique. If the code name of an entity is specified, the sound can only be heard near this entity.
* '''Kill Entity:''' Instantly kill an entity in a specified way (''Normal'', ''Explode'', ''Cutinhalf'', ''Electrify'', ''Melt'', ''Fire'', ''Riddled'', ''Bighole'').
* '''Set object script state:''' Activates a specified interactive object. For example, if it is a door, it is possible to open or close it.
* '''Set Team Alignment Matrix:''' Determines the alignment of a ''team''. Affects all players of this team.
* '''Display World Text:''' Displays a text (among the entries in the file ''.txt'' of the place) in the form of a yellow window in the middle of the page. The window interrupts the game, you must press {{False button|OK|color=white|button=yes}} to continue.
* <font color="grey"><s>'''Start Combat Mode:''' Le mode de jeu de ''Nous Aurons'' est toujours ''CTB''.</s></font> 
* <font color="grey"><s>'''Add Reputation:''' Utilisé par les scripts généraux pour déterminer l'électricité disponible.</s></font> 
* '''Add Experience:''' Adds a specified number of [[Autonomy Points]] to the main character.
* '''Add Experience to Player:''' Adds a specified number of Autonomy Points to all characters in a specified player.
* '''Force Speech:''' Triggers the dialog (added in the {{False button|Level|color=black2}} tab and {{False button|Speech...|color=gray|edge=black}} button) of a specified entity and automatically centers the view on it.{{Avertissement|Specifying a non-existent entity will make the game crash.}}
* '''Change Team:''' Change the "team" of a specified "player".
* '''Change Player:''' Change the ''player'' of a specified ''Unit''.
* '''Move Unit:''' ''Teleport'' an entity to a specified waypoint.{{Warning|Moving a non-existent entity will crash the game.}}
* '''Give Item to NPC:''' Passes an item with the specified code name from the player characters to a character with the specified code name.{{Warning|When the player is too far away, nothing happens. When the character already has a copy of the item, nothing happens}}
* '''Give Item from NPC to Human:''' Passes an item with a specified code name from a character to the player with a specified code name. {{Warning|When the character is too far away, nothing happens. When the player already has a copy of the item, nothing happens}}
* '''Lock/Unlock Door:''' Lock ({{Faux bouton|LockState|couleur=gris}} coché) or unlock ({{Faux bouton|LockState|couleur=gris}} unchecked) a door with the specified code name.
* <font color="grey"><s>'''Jam/Unjam Minimap:''' Aready used by general scripts based on available electricity.</s></font> 
* '''Ping Minimap:''' Mark a specified location (code name of a ''waypoint'') in the minimap. The player must have enough portable electricity for this to work.
* <font color="grey"><s>'''Add text to Debrief text list:''' Used only at the end of the game.</s></font> 
* <font color="grey"><s>'''Display Debrief window and text:''' Used only at the end of the game.</s></font> 
* '''Zone of death:''' Instantly kills all entities in a specified zone and in a specified manner (''Normal'', ''Explode'', ''Cutinhalf'', ''Electrify'', ''Melt'', ''Fire'', ''Riddled'', ''Bighole''). By checking {{False button|Outside location|color=gray}}, it is possible to kill all entities outside the specified zone.
* '''Play Bink Movie:''' Start a ''.bik'' video (created with [[Mod:Editors#The_RAD_Video_Tools|The RAD Video Tools]]) and stored in ''Game/core/movie/''. The {{False button|Archive Title Key|color=gray}} is a code name (e.g.: ''movie_name_intro'') that must also be added to the files ''Game/core/locale/game/'''generic_mission.txt''''' and ''Game/NousAurons/locale/game/'''generic_mission.txt''''' under "// FILM NAME" in this way:<syntaxhighlight>
movie_name_intro = {Introduction}
</syntaxhighlight>
* '''Modify RecruitPool list:''' Calls an action to be applied to the list of companions available to the player, from a code name present in ''Game/core/campaigns/'''campaign.txt'''''. Usually, the action is to add a character.
* <font color="grey"><s>'''Add items to QuarterMaster list:''' Used by general scripts to put items in the cooler.</s></font> 
* '''Set Mission State:''' Hides ({{Fake Button|Covered|color=black2}}), reveals ({{Fake Button|UnCovered|color=black2}}), or shows the location ({{Fake Button|Visited|color=black2}}) of a specified location on the [[Worldmap]]
* <font color="grey"><s>'''Open Mission:''' Use {{False button|Set Mission State|color=black2}} instead.</s></font> 
* '''Mission Complete:''' Turns a location (specified by its code name) gray on the [[We'll:Map|Map]], indicating it as visited.
* '''Set Random Encounter Enable:''' Enables or disables (check {{False button|Enabled to|color=black2}} or not) a specified random encounter.
* <font color="grey"><s>'''Brain Extraction:''' Not used</s>
* <font color="grey"><s>'''MP - Team with the Most Wins:''' ''The Sum'' does not work in ''Multiplayer'' mode.</s></font> 
* <font color="grey"><s>'''MP - Team with the Least Wins:''' ''The Sum'' does not work in ''Multiplayer'' mode.</s></font> 
* <font color="grey"><s>'''MP - Team Meeting Condition Wins:''' ''The Sum'' does not work in ''Multiplayer'' mode.</s></font> 
* <font color="grey"><s>'''MP - Team Victory:''' ''The Sum'' does not work in ''Multiplayer'' mode.</s></font>{{Idea|Each set of actions can be executed only once, or each time the conditions are met. To do so, check {{False button|Preserve|color=black2}} to the right of {{False button|✔&nbsp;Conditions|color=black2}}{{False button|&nbsp;Actions|color=black2}}.}}