Script Player


It is possible to create non-human players by script. These players have all the properties of normal players. They have a crew, wealth, build knowledge, home base material, hostility, teams, etc. However, script players do not have a game view port and they can not be controlled by human users.
Script players can be used to create AI controlled opponent teams in special scenarios.

Runtime join

For creating an AI player at run time - e.g. a new deathmatch opponent - you can use CreateScriptPlayer. This call will be followed (possibly with a little delay) by a InitializePlayer callback for the new player.
/* Script of a game rule named "Create AI" */

func Activate(int player)
  // The player selected the rule. Create a AI enemy.
  return CreateScriptPlayer("Computer", 0x7f7f7f);
func InitializePlayer(int player)
  // A player has joined. This call is issed to both the scenario script and all game rules, goals and 
  // environment objects
  // Is it a script player?
  if (GetPlayerType(player) == C4PT_Script)
    // Then take over the controls for all clonks!
    var crew_counter, crew;
    while (crew = GetCrew(player, crew_counter++))
      AddEffect("Int_EAI", crew, 1, 100, this);
func FxInt_EAITimer(object crew, effect, int time)
  // attack next enemy
  var enemy = FindObject(Find_Hostile(GetOwner(crew)), Find_OCF(OCF_Alive), Sort_Distance());
  if (enemy) crew->SetCommand("Attack", enemy);
  return FX_OK;
This script for a sample rule object allows the user to create AI opponents at runtime. Also, it will order all clonks of the AI players to attack. Notice: this sample script only handles those clonks automatically created through the scenario settings. Additional clonks placed by specialized scripting are not handled.
For internet games you can set MaxScriptPlayers in Teams.txt to a value greater than 0. This will enable the option to have script players join in the game lobby.

Default join

If scripted players should be present in the scenario right from the beginning (comparable to objects created via Objects.txt) then you should create them via the SavePlayerInfos.txt component:


This method effectively performs a player restore, similar to a regular player restore in a savegame resume. Consequently, no InitializePlayer is called for this player and no startup material or crew is created. A crew for this player should be created in the scenario script. Alternatively, a crew may be present in the Objects.txt. Otherwise, the script player will be eliminated shortly after game start.
Contrary to regular players, script players are saved if you perform "Save as scenario" in developer mode. This way, you can automatically generate the correct SavePlayerInfos.txt and an according crew in the Objects.txt of the scenario. In order to do this, simply execute CreateScriptPlayer from the console and create some Clonks for the newly created script player. Then save the game as scenario. The script player Clonks will automatically be restored with the correct owner and in the crew of the script player.

Specialized Players

Sometimes it can be desirable to create a script player at runtime, but still execute a specialized initialization instead of the default crew and base material creation. For example, a Hazard deathmatch scenario may provide a specialized alien enemy.
By passing a parameter to CreateScriptPlayer, scenario initialization can be prevented, i.e. no creation of start materials, no setting of player parameters such as homebase material by the according presets and no InitializePlayer-calls are done. Instead, a single CreateScriptPlayer-callback is done to the definition passed as idExtraData. Example:
/* Script of a rule named "Create aliens" */

func Activate(int player)
  // The player selected the game rule. Create an alien enemy!
  return CreateScriptPlayer("Aliens", 0x00ff00, 0, CSPF_FixedAttributes | CSPF_NoScenarioInit, GetID());
func InitializeScriptPlayer(int player, int idTeam)
  // An alien player has joined
  // since no scenario initialization has been executed, a crew for this player has to be created in this callback
  // create a green clonk. A real scenario should of course have it's own aliens :-)
  var alien = CreateObject(Clonk, LandscapeWidth()/2, -1, player);
  MakeCrewMember(alien, player);
  SetClrModulation(0x7fff7f, alien);
  // and attack
  AddEffect("Int_EAI", alien, 1, 100, 0, GetID());
func FxInt_EAITimer(object crew, effect, int time)
  // Attack next enemy
  var enemy = FindObject(Find_Hostile(GetOwner(crew)), Find_OCF(OCF_Alive), Sort_Distance());
  if (enemy) crew->SetCommand("Attack", enemy);
  return FX_OK;
Sven2, 2007-12