<?xml version="1.0" encoding="UTF-8" standalone="yes"?>
<!DOCTYPE doc
  SYSTEM '../../clonk.dtd'>
<?xml-stylesheet type="text/xsl" href="../../clonk.xsl"?>
<doc>
  <title>Scenario Scripts</title>
  <h>Scenario Scripts</h>
  <part>
     <text>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 <emlink href="script/index.html">C4Script</emlink>.</text>
    <h id="Callbacks">Callbacks overview</h>
	<text>The following callbacks are made to the scenario script. All callbacks except <code>Initialize</code> 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 <code>Scenario</code>. With the functions <funclink>GameCall</funclink> and <funclink>GameCallEx</funclink>, callbacks to the scenario script can be made from scripts.</text>
	<text>
      <table>
        <rowh>
          <col>Function</col>
          <col>Parameter</col>
          <col>Description</col>
        </rowh>
        <row id="Initialize">
          <literal_col>Initialize</literal_col>
          <col></col>
          <col>Called when the round is started.</col>
        </row>
		
        <row id="InitializePlayer">
          <literal_col>InitializePlayer</literal_col>
          <col>int player, int x, int y, object base, int team, id extra_data</col>
          <col>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 <emlink href="scenario/scenario.html#SektionenPlayer1Player2Player3Player4">Scenario.txt</emlink>. <code>x</code> and <code>y</code> specify the starting position of the player, <code>base</code> is the player's base (if any), <code>team</code> denotes the team of the player. For <code>extra_data</code>, see <funclink>CreateScriptPlayer</funclink></col>
        </row>
        <row id="InitializePlayers">
          <literal_col>InitializePlayers</literal_col>
          <col></col>
          <col>Called after all initial players joined. Can be used e.g. to start intros.</col>
        </row>
        <row id="RelaunchPlayer">
          <literal_col>RelaunchPlayer</literal_col>
          <col>int player, int killed_by_player</col>
          <col>Called when a player is about to be eliminated because his last crew member died.</col>
        </row>
        <row id="RemovePlayer">
          <literal_col>RemovePlayer</literal_col>
          <col>int player, int team</col>
          <col>Called when a player is removed from the game.</col>
        </row>
		
        <row id="RejectHostilityChange">
          <literal_col>RejectHostilityChange</literal_col>
          <col>int player1, int player2, bool hostile</col>
          <col>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 <funclink>SetHostility</funclink>.</col>
        </row>
        <row id="OnHostilityChange">
          <literal_col>OnHostilityChange</literal_col>
          <col>int player1, int player2, bool hostile, bool old_hostility</col>
          <col>Called after the hostility of two players has been changed. See <funclink>SetHostility</funclink>.</col>
        </row>
		
        <row id="RejectTeamSwitch">
          <literal_col>RejectTeamSwitch</literal_col>
          <col>int player, int new_team</col>
          <col>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 <funclink>SetPlayerTeam</funclink></col>
        </row>
        <row id="OnTeamSwitch">
          <literal_col>OnTeamSwitch</literal_col>
          <col>int player, int new_team, int old_team</col>
          <col>Called after the team of a player has been changed. See <funclink>SetPlayerTeam</funclink>.</col>
        </row>
		
        <row id="OnGameOver">
          <literal_col>OnGameOver</literal_col>
          <col></col>
          <col>Called if a round is ended through the game by player elimination, fulfillment of all goals (as defined in the <emlink href="scenario/scenario.html#SektionGame">Scenario.txt</emlink>) or by the script command <funclink>GameOver</funclink>. It will not be called if the round was aborted.</col>
        </row>

        <row id="OnWealthChanged">
          <literal_col>OnWealthChanged</literal_col>
          <col>int player</col>
          <col>Called when the wealth of a player has changed.</col>
        </row>

        <row id="InitializeAmbience">
          <literal_col>InitializeAmbience</literal_col>
          <col></col>
          <col>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.</col>
        </row>
      </table>
	</text>

    <h id="Sequential">Sequential scripting</h>
    <text>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.</text>
    <code>func Initialize()
{
  <funclink>Log</funclink>(&quot;Hello&quot;); 
  <funclink>CreateObject</funclink>(WindGenerator,250,200);
}</code>
    <text>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.</text>
    <code>func InitializePlayer(int player)
{
  <funclink>Log</funclink>( &quot;Player nr. %d has joined the game&quot;, player );
  <funclink>Sound</funclink>(&quot;Ding&quot;);
  // The first clonk of the player starts at a random position in the landscape
  <funclink>GetCrew</funclink>(player,0)-&gt;<funclink>SetPosition</funclink>( <funclink>Random</funclink>(<funclink>LandscapeWidth</funclink>()), <funclink>Random</funclink>(<funclink>LandscapeHeight</funclink>()));
}</code>
  </part>
  <author>Sven2</author><date>2002-04</date>
</doc>
