Enhanced SitRep Mod

Folders and Files

Let's take a closer look at each of those things...

 audio, multiplay, skirmish and wrf

These are all standard Warzone folders - places where Warzone is expecting to find its Config files (Stats) and other resources such as audio and scripts.

 sitrepmod

This is a custom folder to store audio files that are specific to the Enhanced SitRep Mod - it just keeps them together and separate from Warzone (or other mods) audio files.

To ensure filenames were unique, each audio file is prefixed with "sit-". You can see a list of the files and download them from sitrepmod.

The audio files were created using Audacity, a free open source audio editor that has native support for OGG audio files.

It was desirable to use the same female voice that's used for other in-game messages and mission briefings for these new audio files. In order to do that, segments of existing audio files (see Audio Directory) were spliced together in Audacity and then saved as new .ogg files.

 Tip: You can use the search box on this wiki to locate audio files based on the words spoken in them (we've transcribed every single audio file!) to save time when looking for specific words.

There's also lots of voice audio in the Video Directory, however don't load video .ogg files in to Adacity as it tends to crash horribly - you'll have to somehow extract the audio track from the files (I used an audio recorder app to record the audio while the video was playing to achieve this).

 audio.cfg ()

This is one of Warzone's Config files (Stats) - it defines the volume and several other properties for each of the custom audio files included in the mod:

For more information on configuring this file, see audio.cfg.

 audio.wrf ()

This is one of Warzone's Config files (Stats) - it defines the location of the custom audio files included in the mod using their relative folder path from the mod's "Enhanced_SitRep_Mod" folder:

For more information on configuring this file, see audio.wrf.

 rules.js ()

This is one of Warzone's Config files (Stats) - it initialises players when the game starts, checks victory conditions and a bunch of other stuff.

In true modding style, it was decided to rewrite rules.js from scratch.  Here's the version of the file at the time of writing this guide for reference: rules.js

To interact with Warzone, the script uses the Warzone Javascript API and various standard Javascript Coding techniques. If you've developed Javascript for web browsers, then you pretty much know what to expect.

Includes

To avoid the file getting too big it was decided to split out key chunks of functionality in to external .js files. At the start of the file, the include() function is used to include the three resulting files (which are described later on this page).

Constants

Next, a few constants are set-up - these are read-only variables that can't be changed after they've been defined. Note that the constants don't follow the usual convention of using ALL_UPPERCASE - not sure why. You can find some coding conventions on the JS API's Introduction page.

The "teams" constant keeps track of whether the game is running in "Fixed Teams" alliance mode - while it's a simple check, using the alliancesType global and ALLIANCES_TEAMS constant, it's going to be done regularly (in the checkPlayers() function described later) hence us storing the result in a constant.

The "humanPlayer" constant is set to selectedPlayer to remember which player ID corresponds to the human player that rules.js is monitoring. It's impossible for the human player to switch to another player ID at this point in the game (while the game is still initialising) so this can't be circumvented. Knowing this helps when it comes to checking events relating to the construction and destruction of the HQ.

Player initialisation

The eventGameInit() event is then used to initialise all the players, The event is called once at the start of the game, as soon as the game environment is ready for interaction with scripts.

When altering player settings, you need to first hackNetOff() and then later hackNetOn() to avoid desynch between players. A loop goes through each player in turn and initialises them by calling functions that are in the rules.js.init.js file. Because structure limits have been defined, the applyLimitSet() function is called to merge them with the default structure limits.

Next we enable or disable the design mode (setDesign()) and mini map (setMiniMap()) depending on whether the player has (enumStruct()) a HQ or not. This is just the standard rule with Warzone and you'll get shouted at if you change it without good reason! The enableTemplate() function is used to ensure that the player can produce construction trucks regardless of whether the unit designer is enabled or not.

Backwards while loops

I'm addicted to backwards "while" loops - you'll see them regularly in any script that I work on!

This will iterate from "length-1" to "0", so it's obviously only useful if you don't care about iterating backwards through the array. There's no real benefit to doing this - you could use a "for" loop or several other approaches. I just thought I'd mention the backwards while loop as many people haven't seen it before for some reason?!

Game initialisation

Because we want to keep track of player statuses, so we can work out when they are defeated or revived, a "playerLiving" array is set up - it will be initialised later.

It's really important to define as few globals as possible and keep their contents simple due to the way that Warzone saves games - for more information, see Saved game files and Common Mistakes.

The isPlayerAlive() function works out if a player is still alive or defeated. In standard Warzone game rules, a player is considered dead if the don't have any factories or units left - because at that point they can't really engage in war any more.

The eventStartLevel() event is used is then used to initialise the game, it's called just once when the game starts. In this event:

• We initialise the playerLiving array by looping through all players (maxPlayers) and checking if they are alive

• A timer is set (setTimer()) that periodically checks player states via the checkPlayers() function

• The reporting API (in rules.report.js) is called to welcome the player to the game

Victory conditions

As mentioned above, the checkPlayers() function is called periodically to determine if the game is won or lost. In standard Warzone game rules:

• The player wins if they have no enemies left

• The player loses if they are dead, unless they are part of a fixed team in which case they only lose when all of their team is also dead

The checkPlayers() function goes through each player in turn to work out who's alive and who's dead. It keeps track of how many allies, team members and enemies are alive with respect to the player. The allianceExistsBetween() function determines if two players are allied with each other.

Using the playerLiving array, it's possible to detect when a player dies or gets revived (by an ally giving them a truck or other unit) and thus report on the situation.

After checking each player status and tallying the number of living allies, team mates and enemies, the victory conditions are then checked at the bottom of the checkPlayers() function. the gameOverMessage() function is called if the game is won or lost, and the "checkPlayers" timer is removed (removeTimer()) to prevent further calls to checkPlayers().

HQ monitoring