Actions (Extensions)

**Actions** are a core element of Extensions.

## Description

Actions can be triggered by specific conditions:

* Missions: `missionStart` and `missionEnd` functions
* Factions: reaching a specific rank and/or unlocking a specific flag
* Conditional action sets

## File structure

The action file is defined by the `<ConditionalActions> </ConditionalActions>` tags.

Conditional actions require a specific condition upon which the actions will trigger., e.g. `<Instantly> </Instantly>`.

Then, actions can be defined inside the condition.

Here is the most basic conditional action file:

```
<ConditionalActions>

<Instantly>
 <RunFunction FunctionName="addFlags:testFlag" />
</Instantly>

</ConditionalActions>

```

## Conditions

Below is a list of all available conditions.

### `Instantly`

The following actions will trigger instantly as soon as the file is loaded in.

Usage:

```
<Instantly needsMissionComplete="true">
 <!-- Actions here -->
</Instantly>

```

* `needsMissionComplete` attribute, if set to `true`, will launch the actions only if the mission has been completed after the action file was loaded in.

### `OnConnect`

The following actions will trigger upon connecting to the target node.

Usage:

```
<OnConnect target="ExampleNode" needsMissionComplete="false" requiredFlags="testFlag">
 <!-- Actions here -->
</OnConnect>

```

* `needsMissionComplete` attribute, if set to `true`, will launch the actions only if the mission has been completed after the action file was loaded in.

* `requiredFlags` attribute defines a flag that must be set before the actions execute.

### `OnAdminGained`

The following actions will trigger upon getting admin access to the target node.

Usage:

```
<OnAdminGained target="ExampleNode">
 <!-- Actions here -->
</OnAdminGained>

```

### `OnDisconnect`

The following actions will trigger upon disconnecting from the target node.

Usage:

```
<OnDisconnect target="ExampleNode">
 <!--Actions here-->
</OnDisconnect>

```

### `HasFlags`

The following actions will trigger upon getting required flag(s).

Usage:

```
<HasFlags requiredFlags="flag1,flag2">
 <!-- Actions here -->
</HasFlags>

```

### `DoesNotHaveFlags`

*Note: the following condition does not work.*

```
<DoesNotHaveFlags Flags="flag1,flag2">
 <!-- Actions here -->
</DoesNotHaveFlags>

```

## Actions

Below is a list of all available actions.

Most actions allow delay attributes: `DelayHost` and `Delay`

* `DelayHost` is a node that hosts delayable actions. This node must have either of these daemons: `FastActionHost`, `IRCDaemon` or `DHSDaemon`.
* `Delay` is time (in seconds) the action is delayed for.

The following actions cannot be delayed:

* `LoadMission`
* `AddMissionToHubServer`
* `RemoveMissionFromHubServer`
* `AddThreadToMissionBoard`
* `AddAsset`
* `CopyAsset`

`AddIRCMessage` has a delay attribute by default and does not need a delay host.

An example of an action with a delay host:

```
<AddConditionalActions Filepath="Actions/ExampleActions.xml" DelayHost="ExampleNode" Delay="10.5" />
```

### `RunFunction`

The following action runs the following mission functions

Usage:

```
<RunFunction FunctionName="changeSong" FunctionValue="1" />
```

*Note: `FunctionValue` attribute is used to pass integer value to the function. Only the first four functions (five with the DLC) require this attribute.*
* `changeSong` - changes the song to the specific one
	+ `FunctionValue="1"` - Revolve (Cinematrik - "Revolve")
	+ `FunctionValue="2"` - The\_Quickening (Cinematrik - "The Quickening")
	+ `FunctionValue="3"` - TheAlgorithm (The Algorithm - "Malware Injection")
	+ `FunctionValue="4"` - Ryan3 (Ryan Burge - "Recursion")
	+ `FunctionValue="5"` - Bit(Ending) (Chris Larkin & Matt Trobbiani - "Bit")
	+ `FunctionValue="6"` - Rico\_Puestel-Roja\_Drifts\_By (Rico Puestel - "Roja Drifts By")
	+ `FunctionValue="7"` - out\_run\_the\_wolves (feeding | ear - "Outrun the Wolves")
	+ `FunctionValue="8"` - Irritations (Tonspender - "Irritations")
	+ `FunctionValue="9"` - Broken Boy (Tonspender - "Broken Boy")
	+ `FunctionValue="10"` - Ryan10 (Ryan Burge - "Phase of the Moon")
	+ `FunctionValue="11"` - Tetrameth (Sean Gillespie - "Tetrameth")
* `addRank` - changes the player's rank and sends a faction e-mail
	+ `FunctionValue` allows to set specific rank, e.g. value "10" will rank the player 90 out of 100.
* `addRankSilent` - changes the player's rank without sending a faction e-mail
	+ `FunctionValue` allows to set specific rank
* `addRankFaction:FACTION_ID` - changes the player's rank in the specific faction
	+ `FunctionValue` allows to set specific rank
* `setFaction:FACTION_ID` - assigns a faction to the player
* `setHubServer:NODE_ID` - sets the specific server to be a hub server. Marked with a circle on the netmap.
* `setAssetServer:NODE_ID` - sets the specific server to be an asset server. Marked with a star on the netmap.
* `addFlags:flag1,flag2` - adds specific flag(s)
* `removeFlags:flag1,flag2` - adds specific flag(s)
* `loadConditionalActions:Actions/ExampleActions.xml` - loads in a specific action file
* `playCustomSong:PATH_TO_SONG` - plays a custom song
* `playCustomSongImmediatley:PATH_TO_SONG` - plays a custom song without the fade-in

Labyrinths
* `changeSongDLC` - changes the song to the specific one from the *Labyrinths*
	+ `FunctionValue="1"` - Remi2 (The Algorithm - "ClearText")
	+ `FunctionValue="2"` - snidelyWhiplash (OGRE - "snidleyWhiplash")
	+ `FunctionValue="3"` - Slow\_Motion (Tonspender - "Slow Motion")
	+ `FunctionValue="4"` - World\_Chase (Cinematrik - "World Chase")
	+ `FunctionValue="5"` - HOME\_Resonance (Home - "Resonance")
	+ `FunctionValue="6"` - Remi\_Finale (The Algorithm - "Sabotage")
	+ `FunctionValue="7"` - RemiDrone
	+ `FunctionValue="8"` - DreamHead (HOME - "Dream Head")
	+ `FunctionValue="9"` - Userspacelike (The Algorithm - "Payload")
	+ `FunctionValue="10"` - CrashTrack

#### Special functions

The following functions are used only in some missions of the original game and are not intended to be used in Extensions.

Labyrinths
* `demoFinalMissionEndDLC`
* `activateAircraftStatusOverlay`
* `activateAircraftStatusOverlayLabyrinthsMonitoring`
* `playAirlineCrashSongSequence`
* `defAttackAircraft`
* `flashUI`

### `AddConditionalActions`

Loads in a specific action set.

Usage:

```
<AddConditionalActions Filepath="Actions/ExampleActions.xml" />
```

### `SaveGame`

Saves the game.

Usage:

```
<SaveGame />
```

### `LoadMission`

Loads in a specific mission and overrides the current one.

Usage:

```
<LoadMission MissionName="Missions/ExampleMission.xml" />
```

### `AddAsset`

Creates a file with specific contents in a specific folder

Usage:

```
<AddAsset FileName="SSHCrack.exe" FileContents="#SSH_CRACK#" TargetComp="ExampleNode" TargetFolderpath="bin" />
```

`FileContents` does not support newlines. Use this action to create programs or other small files.

### `CopyAsset`

Copies a file from one node to another.

Usage:

```
<CopyAsset DestFilePath="home" DestComp="Dest_Node" SourceComp="Source_Node" SourceFileName="Example_file.txt" SourceFilePath="home" />
```

The `Source` attributes define the computer the file is copied *from*, the `Dest` attributes define the computer the file is copied *to*.

This action can copy any types of files (custom themes, encrypted files, memory dumps, etc.)

### `DeleteFile`

Deletes a file from the target node. If the file does not exists, the action does nothing.

Usage:

```
<DeleteFile TargetComp="ExampleNode" FilePath="home" FileName="Example_file.txt" />
```

### `AppendToFile`

Appends a specific content to the target file.

Usage:

```
<AppendToFile TargetComp="ExampleWhitelist" TargetFolderpath="Whitelist" TargetFilename="list.txt">#PLAYER_IP#</AppendToFile>
```

The example above adds the player's IP to the whitelist, letting them connect to the whitelisted server.

### `AddMissionToHubServer`

Adds a specific mission to the hub server: `variableMissionListingServer`, `missionHubServer` and `DHSDaemon` (*Labyrinths* only).

Usage:

```
<AddMissionToHubServer MissionFilepath="Missions/ExampleMission.xml" TargetComp="Hub_Server" AssignmentTag="Kaguya"/>
```

* `AssignmentTag` is used for the `DHSDaemon` to assign the mission to the specific character. The player will not be able to start this mission if the assignement tag exists.
* For `variableMissionListingServer` and `missionHubServer`, the `AssignmentTag` can be set to `top` to place the mission to the top of the list.

### `RemoveMissionFromHubServer`

Removes a specific mission from any of the hub servers.

Usage:

```
<RemoveMissionFromHubServer MissionFilepath="Missions/ExampleMission.xml" TargetComp="Hub_Server" />
```

### `AddThreadToMissionBoard`

Adds a thread to the node with the `messageBoard` daemon.

Usage:

```
<AddThreadToMissionBoard ThreadFilepath="Docs/ExampleThread.txt" TargetComp="Example_Comp" />
```

### `AddIRCMessage`

Adds an IRC message to the node with the `IRCDaemon` or the `DHSDaemon` daemons.

Usage:

```
<AddIRCMessage Author="Kaguya" TargetComp="DHS_Hub" Delay="3.0">Hello @#PLAYERNAME#, welcome to our IRC!</AddIRCMessage>
```

`Delay` is the delay since the action set has been loaded in. In the following example the first message will appear in 3 seconds, and the second message will appear in 7 seconds, thus making a delay between both messages 4 seconds:

```
<AddIRCMessage Author="Kaguya" TargetComp="DHS_Hub" Delay="3.0">Hello @#PLAYERNAME#, welcome to our IRC!</AddIRCMessage>
<AddIRCMessage Author="Kaguya" TargetComp="DHS_Hub" Delay="7.0">A new mission is available for you.</AddIRCMessage>

```

If the alert icon is changed to `irc` or `irchub`, the player can be pinged:

* `@#PLAYERNAME#`
* `@channel`

IRC messages can also contain alerts, notes, links and account details:

* Alert: `!ANNOUNCEMENT!`
* Note: `!ATTACHMENT:note#%#Note Title#%#Note Content
Second line
Third line, etc.`
* Link: `!ATTACHMENT:link#%#Computer_Name#%#127.0.0.1`
* Account: `!ATTACHMENT:account#%#Computer_Name#%#127.0.0.1#%#admin#%#password`

### `CrashComputer`

Crashes (forkbombs) a target node. Setting a `TargetComp` to be a `playerComp` bluescreens it instantly.

Usage:

```
<CrashComputer TargetComp="TargetNode" CrashSource="ExampleNode" />
```

### `ChangeIP`

Changes the target node's IP to the specific one.

Usage:

```
<ChangeIP TargetComp="ExampleNode" NewIP="192.168.0.1" />
```

* `NewIP="#RANDOM_IP#"` will randomize the IP.

### `ShowNode`

Shows a specific node on the netmap.

Usage:

```
<ShowNode Target="ExampleNode" />
```

### `HideNode`

Hides a specific node from the netmap.

Usage:

```
<HideNode TargetComp="ExampleNode" />
```

### `HideAllNodes`

Hides all nodes (including player's computer) from the netmap.

Usage:

```
<HideAllNodes />
```

### `LaunchHackScript`

Launches a specific hacker script.

Usage:

```
<LaunchHackScript Filepath="HackerScripts/ExampleHack.txt" SourceComp="ExampleNode" TargetComp="playerComp" RequireLogsOnSource="false" RequireSourceIntact="true"/>
```

* `SourceComp` is the node that attacks the `TargetComp` (in this case, the target is the player's computer).
* `RequireLogsOnSource`, if set to `true`, lets the hacker script execute only if the player leaves logs on the source computer deleting, moving or downloading a file.
* `RequireSourceIntact`, if set to `true`, lets the hacker script execute only if the `~/sys` files on the source comp are intact.

### `SwitchToTheme`

Switches to a specific theme.

Usage:

```
<SwitchToTheme ThemePathOrName="Themes/ExampleTheme.xml" FlickerInDuration="3.0" />
```

* `FlickerInDuration` is the time it takes for the background to flicker in.
* Default themes can also be used.

### `StartScreenBleedEffect`

Starts a screen bleed effect similar to the one from the "Bit -- Termination" mission.

Usage:

```
<StartScreenBleedEffect AlertTitle="TITLE" CompleteAction="Actions/ExampleActions.xml" TotalDurationSeconds="60.0">Line one
Line two
Line three</StartScreenBleedEffect>
```

* `AlertTitle` is the title that appears in the bottom left corner of the screen. `Line one`, `Line two` and `Line three` appear below the title in the smaller font.
* `CompleteAction` is the action set that is loaded in once the screenbleed hits the bottom.
* `TotalDurationSeconds` is the time it takes for the screenbleed to hit the bottom.

### `CancelScreenBleedEffect`

Cancels a screen bleed effect.

Usage:

```
<CancelScreenBleedEffect />
```

### `KillExe`

Kills specific executables.

Usage:

* Kills all executables that contain `s` in their name (e.g. `SSHCrack`, `Shell`, etc.).

```
<KillExe ExeName="s" />
```

* Kills all player's shells.

```
<KillExe ExeName="shell" />
```

* Kills `ESequencer.exe`.

```
<KillExe ExeName="esequencer" />
```

### `GivePlayerUserAccount`

Reveals the target user account for the player when they attempt to log in.

Usage:

```
<GivePlayerUserAccount TargetComp="ExampleNode" Username="admin" />
```

### `SetLock`

Locks and/or hides a specific interface module.

Usage:

```
<SetLock Module="terminal" IsLocked="true" IsHidden="false" />
```

* `Module` attributes:
	+ `terminal`
	+ `ram`
	+ `netmap`
	+ `display`

### `ChangeNetmapSortMethod`

Changes the way the nodes are organized on the netmap. Functions similarly to `NetmapOrganizer.exe`.

Usage:

```
<ChangeNetmapSortMethod Method="grid" />
```

* `scatter` - nodes are scattered chaotically.
* `grid` - nodes are organized in small groups.
* `seqgrid` - nodes are sorted in order.
* `CHAOS` - nodes are moving chaotically all over the netmap.

### `ChangeAlertIcon`

*Note:* Labyrinths *only*
Changes the alert icon that points to the target node.

Usage:

```
<ChangeAlertIcon Target="ExampleNode" Type="irc" />
```

Available `Types`:

* `mail` - for the nodes with the `mailServer` daemon. Must also contain the account for the player.
* `board` - for the nodes with the `messageBoard` daemon
* `irc` - for the nodes with the `IRCDaemon` daemon
* `irchub` - for the nodes with the `DHSDaemon` daemon

## References

1. ↑ https://trello.com/c/fCoQsXop/299-several-actions-do-not-support-delays