Environment Sequences

New Game

When the player starts a new game the following sequence occurs:

1. Player starts a new game (multiplayer, skirmish, challenge, etc)
2. Loading screen appears
3. Map is loaded and initialised but not yet displayed
4. JS Environment is set up for each player
5. Applicable Player Scripts are loaded in to the environment for each player
6. The player scripts define their constants, functions, object classes, etc., and do any basic initialisation they require
7. When all players and their associated player scripts are ready, eventGameInit() is fired
8. Player Initialisation is trigged in rules.js.
9. After all eventGameInit() handlers have finished, eventStartLevel() is fired
10. After all eventStartLevel() handlers have finished, the game begins
11. Loading screen disappears, map interface is shown to all human players
12. Game objects can now be given instructions (eg. produce droids at factories, research at labs, etc).
13. From this point onwards, other Events will be fired (including custom events such as timers)

Notes

The eventGameInit() is only ever triggered once, at the start of a new game. It is not triggered when a game is loaded.

The eventStartLevel() is triggered once at the start of a new game, and again should a new level be loaded (see "New Level" section below). It is not triggered when a game is loaded.

All other events, including custom events (timers, etc), are disabled until eventStartLevel() has finished processing.

Prior to eventStartLevel(), Game objects can be queried (eg. using enum*() functions) but cannot be given orders. For example, you can't tell a factory to start making droids. You should only start instructing game objects to do stuff after eventStartLevel().

Commonly, eventGameInit() is used to initialise variables (and game settings in the case of rules.js) and eventStartLevel() is used to set a number of timers and/or queued function calls.

New Level

This only applies to Campaign mode, where the player might need to hop in a transport and set off to some other part of the world (a different map) – this is called a "new level" within the current game. As such, the initialisation sequence of a New Game (as listed above) will already have taken place.

When the new level starts:

1. <not sure what happens while the level is loading>
2. <not sure what happens with player scripts - are new ones loaded?>
3. eventStartLevel() will be triggered indicating that the new level has started
4. Game objects can now be given instructions (eg. produce droids at factories, research at labs, etc).
5. From this point onwards, other Events will be fired (including custom events such as timers)

Notes

During an away mission, you can use enumStructOffWorld() to query structures on the previous map.

<probably a bunch of other stuff worth noting, but I've not got any experience of campaign scripting – any help greatly appreciated!>

Saving a Game

Note: In Warzone 3.1, there are no events that indicate when a game is being saved or has been saved. New events were added in Warzone 3.2 to resolve this issue.

When a user saves a game, the following sequence occurs:

• On Warzone 3.2 and above, eventGameSaving() is fired
• The map and all events (including custom events) are frozen
• Warzone persists the game data - including map objects and global script variables
• On Warzone 2.3 and above, eventGameSaved() is fired
• The game and events are resumed after the save game process is completed

Loaded Game

When a game is loaded, it basically continues from where it was prior to being saved.

As such, the eventGameInit() and eventStartLevel() events are not fired. The reason your scripts keep working is because custom events are persisted in the save game file (that's why they require the function name parameter to be a string!) and standard game events will be triggered once the action resumes on the map.

When a user loads a game, the following sequence occurs:

1. Player loads a saved game (skirmish, campaign, challenge)
2. Loading screen appears
3. Map is loaded and initialised but not yet displayed
4. JS Environment is set up for each player
5. Applicable Player Scripts are loaded in to the environment for each player
6. The player scripts define their constants, functions, object classes, etc., and do any basic initialisation they require
7. On Warzone 3.2 or above:
   
   1. When all players and their associated player scripts are ready, eventGameLoaded() is fired
   2. After all eventGameLoaded() handlers have finished processing, the game begins
8. Loading screen disappears, map interface is shown to all human players
9. Game objects can now be given instructions (eg. produce droids at factories, research at labs, etc).
10. From this point onwards, other Events will be fired (including custom events such as timers)

Using Warzone 3.1? If you need an event when a game loads, check out the Process API script – it generates a custom eventGameLoaded() when it detects that a saved game has just been loaded.

Mission Won or Lost

If you are using missions (see Missions / Campaign), the eventMissionTimeout() event will be fired if the mission is not completed within the allotted amount of time. There is no event to indicate a mission being won – your code will have to determine when a mission is complete and stop the timer.

<probably a bunch of other stuff worth noting, but I've not got any experience of campaign scripting – any help greatly appreciated!>

Game Won or Lost

In multiplayer, skirmish and challenge games, the Victory Conditions determine when a game is won or lost. However, this check is done in rules.js (see also: Game Rules & SitRep) so if you want your script to be aware of this you will need to incorporate similar code.