Player controls

Player controls Player controls Since OC the engine allows to define control commands completely arbitrarily. Own keyboard commands can be added and modified. All supported input devices such as mouse, keyboard and gamepads can be mapped freely and commands can consist of any key combinations or sequences. PlayerControls.txt All control commands which a player can send to the game are defined in the file PlayerControls.txt. The standard keys as well as their standard mapping for various input devices are contained in the global definition file in the Systems.c4g folder. Object definitions and scenarios can add more keys or overload the parameters of existing commands in their local Systems.c4g folder**. Additional PlayerControls.txt files can be put in language packages to adapt the standard key mappings of different loaded languages to the keyboard of their respective country**. Section [ControlDefs] Definition of possible player commands. Not valid in language packages. Subordinated to this section: ValueData typeDescription Identifier String (max. 96 chars)Internally used name for identification of the command. The command is referenced by that name in standard mappings and it is predefined in script as CON_Name. The name should therefore be a valid identifier in script, i.e. only consist of letters, numbers and _. Especially there should be no space characters or German umlauts. To avoid conflicts the same rules as for object IDs apply for definitions local to a certain scenario or object. GUIName StringName which is shown to the player in the control configuration dialog and in control tooltips. Localized strings from the corresponding string table can be used ($Name$). GUIDesc StringInformative description which is displayed to the player in the control configuration dialog. Lokalisierte Zeichenketten koennen aus dem zugehoerigen StringTable refeenziert werden ($Name$). Global BooleanIf true this is a global definition, i.e. not assigned to a particular player. See Global definitions. Hold BooleanIf true this command is interpreted as a held command. Such a command remembers whether the control key is pressed and generates another scripting event when it is released. See Held keys. RepeatDelay IntegerOnly valid if Hold is true. If greater than 0 then this key generates additional scripting events while pressed every that many number of frames. See Key repeats. InitialRepeatDelay IntegerIf specified then the delay of the first key repeat event can be changed. See Key repeats. DefaultDisabled BooleanIf true then the command is deactivated in the normal case and needs to be activated by script first. This is useful for commands that are only required in special situations. See Deactivated commands. ExtraData C4IDOptional ID that is passed to the script function. See ExtraData. SendCursorPos BooleanIf true then the GUI mouse position at the time of triggering the command will be sent as a separate CON_CursorPos command. If the mouse is not activated then the cursor position in GUI coordinates is transmitted. Action StringAction to be executed for this command. Possible values:

ValueDescription None No action. Script Execution of the script function PlayerControl. See Script callbacks. (Default value) Menu Open the player menu (asynchronous command). MenuOK Confirmation of the selected item in the player menu (asynchronous command). MenuCancel Close the player menu (asynchronous command). MenuLeft / MenuUp / MenuRight / MenuDown Navigation in the player menu (asynchronous command).

Section [ControlSets] Definition of standard control mappings. ValueData typeDescription Name StringInternal name for identification of otherwise equal control mappings. The names of the standard mappings are Keyboard1, Keyboard1Classic, Keyboard2, Keyboard2Classic, Gamepad. By using placeholders (*) keys can directly be defined in multiple mappings**.

ValueData typeDescription Key StringSpecifies the key(s) of this mapping or a reference to another mapping. See Key mappings. ComboIsSequence BooleanIf true then multiple keys are taken as a sequence, i.e. they need to be pressed one after the other instead of all at the same time. See Key mappings. Control StringCommand that is combined with this mapping. The name should be equivalent to the Identifier of a command defined in a [ControlDef]. Priority IntegerPriority of the mapping. If more than once mapping is using the same keys then the key with the highest priority is executed first until a command is treated as handled. TriggerMode bitmaskTrigger mode of this mapping. Bitmask based on the following values:

ValueDescription Default valueNo particular action. Hold The key changes the state of the command linked to to be held even if the key itself is pressed only shortly. Only valid if the Hold attribute is set for the command. This state remains until a corresponding mapping with trigger mode Release is being pressed. See Held keys. Release The key removes the held state. A key can have both Hold and Release set to toggle between the two states. See Held keys. AlwaysUnhandled The key press is always passed to the mapping with the next lowest priority, independent of whether the previous command was executed successfully or not. ToggleUnhandled The keypress is passed to the mapping with the next lower priority only if the previous command was executed successfully. This can be used to define macros. ** OverrideAssignments The assignment overwrites all other assignments for the same control with the same press/release trigger mode.

Script callbacks To initialize the player control the script function InitializePlayerControl is called for each player. This call might be delayed by a few frames with respect to InitializePlayer since the initialization of the control needs to be transmitted in the network. When continuing savegames InitalizePlayerControl will be called again. The chosen control might be different from the original one. The same can happen if a player chooses to change its controls during the game.

global func InitializePlayerControl(int player, string control_name, bool has_keyboard, bool has_mouse, bool has_gamepad)
{
  // Hier bietet sich die Möglichkeit, spezielle Kontrollelemente wie ein Gamepad-Zielkreuz zu erzeugen
  // oder zu zerstören, falls die Kontrolle vom Gamepad weggeschaltet wurde
  return true;
}

most commands (except for asynchronous commands in the player menu) call a global script function:

global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated, bool release)

For an explanation of the parameters see PlayerControl. Amongst others, the function receives the calling player in player as well as the command to be executed in control. As a simple example let's assume that in the global PlayerControls.txt the following command has been defined:

[ControlDefs]
  [ControlDef]
  Identifier=Jump
  GUIName=Jump
  GUIDesc=Hoppin' around
  Repeat=5

[ControlSets]

  [ControlSet]
  Name=Keyboard1
  
    [Assignment]
    Key=W
    Control=Jump
    Priority=50

This defines a Jump key and the corresponding standard mapping on the keyboard for the first player. The following script is used to handle the control:

global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated, bool release)
{
  // Welches Kommando wurde ausgeloest?
  // Die Konstante CON_Jump wurde automatisch durch die Definition in PlayerControls.txt angelegt
  if (control == CON_Jump && !release)
  {
    // Sprungtaste gedrueckt. Der vom Spieler ausgewaehlte Clonk soll springen
    var player_clonk = GetCursor(player);
    if (player_clonk && player_clonk->Jump())
    {
      // Das Kommando wurde erfolgreich abgearbeitet
      return true;;
    }
  }
  // Unbekanntes Kommando
  return false;
}

ExtraData Since not every object definition is able to overload the global PlayerControl function the ExtraData field can be used to distribute commands. As an example consider the following definition:

[ControlDefs]
  [ControlDef]
  Identifier=Dig
  GUIName=Dig
  GUIDesc=Going underground
  ExtraData=Shovel

Let shovel be the ID of a shovel object. In the global script there could be the following, generic handling for unknown commands, for example:

global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated, bool release)
{
  // Behandlung bekannter Befehle
  // [...]
  // Befehl mit eigener Behandlung
  if (control_extra) return control_extra->PlayerControl(player, control, x, y, strength, repeat, release);
  // Unbekanntes Kommando
  return false;
}

And in the script of the shovel:

func PlayerControl(int player, int control, int x, int y, int strength, bool repeated, bool release)
{
  // Behandlung bekannter Befehle
  // Grabkommando direkt an die Schaufel
  if (control == CON_Dig)
  {
    // Nur, wenn ein Clonk ausgewaehlt ist, der graben kann
    var player_clonk = GetCursor(player);
    if (player_clonk && player_clonk->HasShovel())
    {
      return player_clonk->StartDig();
    }
  }
  // Unbekanntes Kommando
  return false;
}

Held keys If the Hold flag is set for a command then the engines saves the current key state for that key. These kind of keys have a few specialties:

When released they also generate PlayerControl calls in the script with the Release flag set.
Mappings can emulate permanent key presses using the Hold/Release flags.
Key repeats are generated.
The held state of the key can be queried in the script via GetPlayerControlState.

A good example for this functionality is a directional command:

  [ControlDef]
  Identifier=Left
  GUIName=Left
  GUIDesc=Walk left
  Hold=1

In the script the direction is transferred to the Clonk:

global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated, bool release)
{
  if (control == CON_Left) return UpdateControlDir(player);
  // ...
}

global func UpdateControlDir(int player)
{
  // Clonk ausgewaehlt?
  var player_clonk = GetCursor(player);
  if (player_clonk)
  {
    // Clonkrichtung aktualisieren
    var new_comdir = COMD_Stop;
    if (GetPlayerControlState(player, CON_Left)) new_comdir = COMD_Left;
    player_clonk->SetComDir(new_comdir);
    // Kommando behandelt
    return true;;
  }
  // Kommando behandelt
  return false;
}

To achieve the behaviour of classic controls a mapping can emulate the Hold state:

    [Assignment]
    Key=A
    Control=Left
    TriggerMode=Hold

    [Assignment]
    Key=S
    Control=Left
    TriggerMode=Release | AlwaysUnhandled

Global definitions ... Key repeats If a command has RepeatDelay defined then repeated commands are generated while the key is pressed. For example for a throwing command:

  [ControlDef]
  Identifier=Throw
  GUIName=Throw
  GUIDesc=Get rid of your selected inventory
  Hold=1
  RepeatDelay=5
  InitialRepeatDelay=35

In the example one could keep the key pressed after having it pressed for the first time. The Throw command then would be sent every 5 seconds automatically after an initial delay of 35 frames (about one second). Repeats are only generated when the command also has the Hold flag set. Deactivated commands** ... Keyboard shortcuts ... Priorities ... ** - not yet implemented Sven22009-06