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.

Callbacks overview

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.

Sequential scripting

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()
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 );
  // The first clonk of the player starts at a random position in the landscape
  GetCrew(player,0)->SetPosition( Random(LandscapeWidth()), Random(LandscapeHeight()));
Sven2, 2002-04