Scenario Scripts

Scenario scripts can control a general mission sequence or define specific features such as rejoins or special player placement. For documentation of the scripting language see C4Script.

The following callbacks are made to the scenario script. All callbacks except Initialize that are made to scenario script from the engine are also made to all goals, rules and environment objects in the game. Other scripts can access local variables of the scenario and call scenario functions with the global proplist Scenario. With the functions GameCall and GameCallEx, callbacks to the scenario script can be made from scripts.

Function	Parameter	Description
Initialize		Called when the round is started.
InitializePlayer	int player, int x, int y, object base, int team, id extra_data	Called after when a new player joins the game. At this point, the clonks, materials, structures etc. are already placed at the position given in the Scenario.txt. x and y specify the starting position of the player, base is the player's base (if any), team denotes the team of the player. For extra_data, see CreateScriptPlayer
InitializePlayers		Called after all initial players joined. Can be used e.g. to start intros.
RelaunchPlayer	int player, int killed_by_player	Called when a player is about to be eliminated because his last crew member died.
RemovePlayer	int player, int team	Called when a player is removed from the game.
RejectHostilityChange	int player1, int player2, bool hostile	When the hostility of two players is about to be changed, this function is called first. If it returns true, the hostility is not changed. See SetHostility.
OnHostilityChange	int player1, int player2, bool hostile, bool old_hostility	Called after the hostility of two players has been changed. See SetHostility.
RejectTeamSwitch	int player, int new_team	When the team of a player is about to be changed, this function is called first. If it returns true, the team of the player is not switched. See SetPlayerTeam
OnTeamSwitch	int player, int new_team, int old_team	Called after the team of a player has been changed. See SetPlayerTeam.
OnGameOver		Called if a round is ended through the game by player elimination, fulfillment of all goals (as defined in the Scenario.txt) or by the script command GameOver. It will not be called if the round was aborted.
OnWealthChanged	int player	Called when the wealth of a player has changed.
InitializeAmbience		Called on game initialization in Frame zero (i.e. not in savegames). To be used to create sound and music controller objects. If not defined and Objects.ocd is loaded, falls back to a global function defined in Ambience.ocd which creates the default ambience controller.

At the start of each round, before the players have joined, the engine calls the function "Initialize" in the scenario script, if defined. Within this function a scenario can perform special object placement or start the scenario scripting sequence.

func Initialize()
{
  Log("Hello"); 
  CreateObject(WindGenerator,250,200);
}

After joining a new player the engine calls the function InitializePlayer in the scenario script for that player. This function is called after the basic player objects as defined in Scenario.txt have been placed, so a preliminary starting position has been selected and the player's crew and starting material and buildings are present. In this function, you can now perform more special initial placement.

func InitializePlayer(int player)
{
  Log( "Player nr. %d has joined the game", player );
  Sound("Ding");
  // The first clonk of the player starts at a random position in the landscape
  GetCrew(player,0)->SetPosition( Random(LandscapeWidth()), Random(LandscapeHeight()));
}