From 22d689d56005338e9acb7cef60aa1ffaf4ff807b Mon Sep 17 00:00:00 2001 From: Sven Eberhardt Date: Tue, 9 Jun 2009 00:29:55 -0400 Subject: [PATCH] Moving controls to script: Docs --- docs/sdk/playercontrols.xml | 265 ++++++++++++++++++++++++++++++++++++ 1 file changed, 265 insertions(+) create mode 100644 docs/sdk/playercontrols.xml diff --git a/docs/sdk/playercontrols.xml b/docs/sdk/playercontrols.xml new file mode 100644 index 000000000..6ffdd37f9 --- /dev/null +++ b/docs/sdk/playercontrols.xml @@ -0,0 +1,265 @@ + + + + +Spielersteuerung +Spielersteuerung + +Ab OC erlaubt die Engine, Steuerungskommandos fuer Spieler komplett frei zu definieren. Eigene Tastaturkommandos koennen hinzugefuegt oder veraendert werden. Alle unterstuetzten Eingabegeraete wie Maus, Tastatur und Gamepads koennen frei belegt werden und Kommandos koennen aus beliebigen Tastenkombinationen oder Sequenzen bestehen. +PlayerControls.txt +Alle Steuerungsbefehle, die ein Spieler an das Spiel geben kann, werden in der Datei PlayerControls.txt definiert. Die Standardtasten sowie deren Standardbelegung fuer verschiedene Eingabegeraete befinden sich in der globalen Definitionsdatei in der System.c4g. Objektdefinitionen und Szenarien koennen weitere Tasten in ihrer lokalen System.c4g hinzufuegen oder die Parameter vorhandener Steuerkommandos ueberladen**. +Zusaetzliche Dateien PlayerControls.txt koennen in Sprachpaketen abgelegt werden, um die Standardbelegungen der Tasten bei verschiedenen, geladenen Sprachen an die Tastaturen des jeweiligen Landes anzupassen**. + + +Sektion [ControlDefs] +Definition der moeglichen Spielerkommandos. Nicht gueltig in Sprachpaketen. Dieser Sektion untergeordnet: + + + + Wert + Datentyp + Beschreibung + + + Identifier + Zeichenfolge (Max. 96 Zeichen) + Intern benutzter Name zur Identifikation des Kommandos. Das Kommando wird unter diesem Namen in Standardbelegungen referenziert und im Script als CON_Name-Konstante vordefiniert. Der Name sollte folglich im Script gueltig sein, d.h. nur aus Buchstaben, Zahlen sowie _ bestehen. Insbesondere sollten keine Leerzeichen oder deutsche Umlaute verwendet werden. Zur Vermeidung von Konflikten gelten in szenarienlokalen sowie Objektpaketlokalen Definitionen dieselben Benennungsregeln wie zur Vergabe von Objekt-IDs. + + + GUIName + Zeichenfolge + Name, der dem Spieler im Steuerungskonfigurationsdialog sowie in den Steuerungstooltips angezeigt wird. Lokalisierte Zeichenketten koennen aus dem zugehoerigen StringTable refeenziert werden ($Name$). + + + GUIDesc + Zeichenfolge + Erlaeuternde Beschreibung, die dem Spieler im Steuerungskonfigurationsdialog angezeigt wird. Lokalisierte Zeichenketten koennen aus dem zugehoerigen StringTable refeenziert werden ($Name$). + + + Global + Boolean + Wenn wahr, ist dies eine globale, d.h. keinem Spieler zugeordnete Definition. Siehe Globale Definitionen. + + + Hold + Boolean + Wenn wahr, wird das Kommando als ein gehaltenes Kommando interpretiert. Ein solches Kommando speichert, ob die Steuerungstaste gedrueckt ist und generiert beim Loslassen ein zusaetzliches Scriptereignis. Siehe Gehaltene Tasten. + + + RepeatDelay + Integer + Nur gueltig wenn Hold wahr. Wenn groesser 0, generiert die Taste im gehaltenen Zustand im angegebenen Abstand (in Frames) weitere Scriptereignisse. Siehe Tastenwiederholungen. + + + InitialRepeatDelay + Integer + Wenn angegeben, kann die Wartezeit fuer das erste Tastenwiederholungsereignis geaendert werden. Siehe Tastenwiederholungen. + + + DefaultDisabled + Boolean + Wenn wahr, ist das Kommando im Normalfall deaktiviert und muss erst per Script aktiviert werden. Nuetzlich fuer Kommandos, die nur in sehr speziellen Situationen benoetigt werden. Siehe Deaktivierte Kommandos. + + + ExtraData + C4ID + Optionale ID, die an die Scriptfunktion uebergeben wird. Siehe ExtraData. + + + Action + Zeichenfolge + Auszufuehrende Aktion bei diesem Kommando. Moegliche Werte: +
Beliebig viele Sektionen [ControlDef]
+ + Wert + Beschreibung + + + None + Keine Aktion. + + + Script (Standardwert) + Ausfuehrung des Scriptbefehls PlayerControl bzw. PlayerControlReleased. Siehe Script-Callbacks. + + + Menu + Oeffnen des Spielermenues (asynchrones Kommando). + + + MenuOK + Bestaetigen des ausgewaehlten Elementes im Spielermenue (asynchrones Kommando). + + + MenuCancel + Schliessen des Spielermenues (asynchrones Kommando). + + + MenuLeft / MenuUp / MenuRight / MenuDown + Navigation im Spielermenu (asynchrones Kommando). +
+ + + +Sektion [ControlSets] +Definition von Standard-Steuerungsbelegungen. + + + + Wert + Datentyp + Beschreibung + + + Name + Zeichenfolge + Interner Name zur Identifikation gleicher Steuerungsbelegungen. Die Namen der Standardbelegungen sind Keyboard1, Keyboard1Classic, Keyboard2, Keyboard2Classic, Gamepad +
Beliebig viele Sektionen [ControlSet]
+ + + + + Wert + Datentyp + Beschreibung + + + Key + Zeichenfolge + Taste(n) dieser Belegung oder Referenz auf eine andere Belegung. Siehe Tastenbelegungen. + + + Control + Zeichenfolge + Kommando, das mit dieser Belegung verknuepft wird. Der Name sollte dem Identifier eines in einer [ControlDef] definierten Kommandos entsprechen. + + + Priority + Integer + Prioritaet der Belegung. Nutzen mehrere Belegungen die gleichen Tasten, so wird zunaechst die Taste mit der hoeheren Prioritaet ausgefuehrt, bis ein Kommando als behandelt gilt. + + + TriggerMode + Bitmaske + Ausloesmodus dieser Belegung. Bitmaske aus folgenden Werten: +
Beliebig viele Sektionen [Assignment]
+ + Wert + Beschreibung + + + Default (Standardwert) + Keine besondere Aktion. + + + Hold + Die Taste versetzt das verlinkte Kommando in den gedrueckten Zustand, selbst wenn die Taste selbst nur angeschlagen wird. Nur gueltig, wenn das Kommando das Hold-Attribut gesetzt hat. Dieser Zustand bleibt erhalten, bis eine entsprechende Belegung mit Ausloesemodus Release gedrueckt wird. Siehe Gehaltene Tasten. + + + Release + Die Taste entfernt den gedrueckten Zustand. Eine Taste kann auch sowohl Hold als auch Release setzen, um zwischen den Zustaenden hin und her zu schalten. Siehe Gehaltene Tasten. + + + AlwaysUnhandled + Der Tastendruck wird immer an die Belegung mit der naechstniedrigen Prioritaet weitergereicht, unabhaengig davon, ob das vorherige Kommando erfolgreich ausgefuehrt wurde. + + + ToggleUnhandled + Der Tastendruck wird genau dann an die Belegung mit der naechstniedrigen Prioritaet weitergereicht, wenn das vorherige Kommando erfolgreich ausgefuehrt wurde. Hiermit lassen sich Makros definieren. ** +
+ + + + + + +Script-Callbacks +Die meisten Kommandos (abgesehen von asyrnchronen Kommandos im Spielermenue), rufen eine globale Scriptfunktion auf: +global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated) +Fuer eine Erlaeuterung der Parameter siehe PlayerControl. Die Funktion erhaelt unter anderem den aufrufenden Spieler in iPlr, sowie das ausgefuehrte Kommando in iControl. +Fuer ein einfaches Beispiel sei in der globalen PlayerControls.txt folgendes Kommando definiert: +[ControlDefs] + [ControlDef] + Identifier=Jump + GUIName=Jump + GUIDesc=Hoppin' around + Repeat=5 + +[ControlSets] + + [ControlSet] + Name=Keyboard1 + + [Assignment] + Key=W + Control=Jump + Priority=50 + +Dies definiert eine Sprungtaste und die zugehoerige Standardbelegung auf der Tastatur fuer den ersten Spieler. Dazu folgendes Script zur Behandlung: +global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated) +{ + // Welches Kommando wurde ausgeloest? + // Die Konstante CON_Jump wurde automatisch durch die Definition in PlayerControls.txt angelegt + if (control == CON_Jump) + { + // 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 +Da nicht jede Objektdefinition die globale PlayerControl-Funktion ueberladen kann, gibt es das ExtraData-Feld zum Verteilen von Kommandos. Zum Beispiel fuer folgende Definition: +[ControlDefs] + [ControlDef] + Identifier=Dig + GUIName=Dig + GUIDesc=Going underground + ExtraData=SHVL +Dabei sei SHVL die ID eines Schaufelobjektes. Im globalen Script kann zum Beispiel folgende, allgemeine Behandlung fuer unbekannte Kommandos stehen: +global func PlayerControl(int player, int control, C4ID control_extra, int x, int y, int strength, bool repeated) +{ + // Behandlung bekannter Befehle + // [...] + // Befehl mit eigener Behandlung + if (control_extra) return control_extra->PlayerControl(player, control, x, y, strength, repeat); + // Unbekanntes Kommando + return false; +} + +Und im Script der Schaufel: +func PlayerControl(int player, int control, int x, int y, int strength, bool repeated) +{ + // 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; +} + + +Gehaltene Tasten +Globale Definitionen +Tastenwiederholungen +Deaktivierte Kommandos +Tastenbelegungen +Prioritaeten + +** - noch nicht implementiert +Sven2Juni 2009 +