Das XR-Action-Mapping

Godot verfügt über ein Action Mapping-Feature als Teil des XR-Systems. Zum jetzigen Zeitpunkt ist dieses System Teil des OpenXR-Moduls. Es gibt Pläne, WebXR in naher Zukunft in dieses System einzubinden, daher nennen wir es in diesem Dokument das XR-Action Map-System. Es implementiert das Built-in-Action-Map-System von OpenXR weitgehend genau so, wie es angeboten wird.

Das XR-Action-Map-System macht Eingaben, Positionsdaten und Ausgaben für XR-Controller für Ihr Spiel/Ihre Anwendung verfügbar. Dies geschieht durch benannte Aktionen, die auf Ihr Spiel/Ihre Anwendung zugeschnitten werden können, und deren Bindung an die tatsächlichen Ein- und Ausgänge Ihrer XR-Geräte.

Da die XR-Action-Map derzeit Teil des OpenXR-Moduls ist, muss OpenXR in den Projekteinstellungen aktiviert sein, um sie zugängig zu machen:

Im unteren Teil des Bildschirms finden Sie dann das XR Action Map-Interface:

Bemerkung

Das in Godot integrierte Eingabesystem hat viele Gemeinsamkeiten mit dem Action-Map-System von XR. Unsere ursprüngliche Idee war es, das bestehende Eingabesystem um Funktionen zu erweitern und die Daten in das OpenXR Action-Map-System einzubinden. Vielleicht werden wir diese Idee irgendwann wieder aufgreifen, aber wie sich herausstellte, gab es einfach zu viele Probleme zu überwinden. Um nur ein paar zu nennen:

• Das Eingabesystem von Godot konzentriert sich hauptsächlich auf Tasteneingaben, XR fügt Auslöser, Achsen, Posen und Haptik (Ausgabe) hinzu. Dies würde das Eingabesystem stark verkomplizieren, mit Features, die bei normalen Controllern nicht funktionieren oder im Gegensatz zum aktuellen Ansatz stehen. Man war der Meinung, dass dies bei der Mehrheit der Godot-Benutzer zu Verwirrung führen würde.

• Das Eingabesystem von Godot arbeitet mit rohen Eingabedaten, die geparst werden und Aktionen auslösen. Diese Eingabedaten werden dem Endbenutzer zur Verfügung gestellt. OpenXR verbirgt die Rohdaten vollständig und übernimmt das Parsing für uns, wir erhalten nur Zugang zu den bereits geparsten Aktionsdaten. Diese Inkonsistenz wird wahrscheinlich zu Fehlern führen, wenn ein argloser Benutzer versucht, ein XR-Gerät als normales Eingabegerät zu verwenden.

• Das Eingabesystem von Godot erlaubt es, zur Laufzeit zu ändern, welche Eingaben an Aktionen gebunden sind, OpenXR nicht.

• Das Eingabesystem von Godot basiert auf Geräte-IDs, die in OpenXR bedeutungslos sind.

Dies bedeutet, dass ein Spiel/eine Anwendung, die traditionelle Eingaben mit XR-Controllern mischt, eine Trennung aufweist. Bei den meisten Anwendungen wird entweder das eine oder das andere verwendet und dies wird nicht als Problem angesehen. Letztendlich ist es eine Einschränkung des Systems.

Die Default-Action-Map

Godot erstellt automatisch eine Default-Action-Map, wenn keine Action-Map-Datei gefunden wird.

Warnung

Diese Default-Map wurde entwickelt, um Entwicklern zu helfen, ihre XR-Spiele/Anwendungen von Godot 3 auf Godot 4 zu portieren. Infolgedessen bindet diese Map im Wesentlichen alle bekannten Eingaben auf allen standardmäßig unterstützten Controllern an Aktionen, und zwar eins zu eins. Dies ist kein gutes Beispiel für das Einrichten einer Action-Map. Es ermöglicht einem neuen Entwickler, einen Ausgangspunkt zu haben, wenn er sich mit Godot XR vertraut machen will. Es verhindert, dass sie zuerst eine richtige Action-Map für ihr Spiel/ihre Anwendung entwerfen müssen.

For this walkthrough we're going to start with a blank action map. You can delete the "Godot action set" entry at the top by pressing the trash can icon. This will clear out all actions. You might also want to remove the controllers that you do not wish to setup, more on this later.

Aktions-Sets

Bemerkung

Bevor wir eintauchen, werden Sie in diesem Dokument den Begriff XR-Runtime verwenden. Mit XR-Runtime meinen wir die Software, die das AR- oder VR-Headset steuert und mit ihm interagiert. Die XR-Runtime stellt uns dies dann über eine API wie OpenXR zur Verfügung. Also:

• für Steam ist das SteamVR,

• für Meta auf dem Desktop ist dies der Oculus-Client (auch bei Verwendung des Quest-Links),

• für Meta auf Quest ist dies der native OpenXR-Client von Quest,

• unter Linux könnte dies Monado, etc sein.

Die Action-Map ermöglicht es uns, unsere Aktionen in Gruppen zu organisieren. Jedes Set kann für sich aktiviert oder deaktiviert werden.

Das Konzept hier ist, dass Sie verschiedene Sets haben könnten, die Bindings in verschiedenen Szenarien bieten. Sie könnten haben:

• eine Charakter-Control-Set für die Zeit, in der Sie herumlaufen,

• eine Fahrzeug-Control-Set für die Zeit, in der Sie ein Fahrzeug bedienen,

• ein Menü-Set für die Zeit, in der ein Menü geöffnet ist.

Nur das Action Set, das für den aktuellen Zustand Ihres Spiels/Ihrer Anwendung gilt, kann dann aktiviert werden.

Dies ist besonders wichtig, wenn Sie dieselbe Eingabe auf einem Controller an eine andere Aktion binden möchten. Zum Beispiel:

• in Ihrem Charakter-Control haben Sie vielleicht eine Aktion Springen,

• in Ihrem Fahrzeug-Control haben Sie vielleicht eine Aktion Beschleunigen,

• in Ihrem Menü-Set haben Sie vielleicht eine Aktion Auswählen.

Alle sind an den Trigger Ihres Controller gebunden.

OpenXR bindet einen Eingang oder Ausgang nur an eine einzige Aktion. Wenn derselbe Eingang oder Ausgang an mehrere Aktionen gebunden ist, wird diejenige im aktiven Action Set mit der höchsten Priorität aktualisiert/verwendet. In unserem obigen Beispiel ist es also wichtig, dass nur ein Action Set aktiv ist.

Für Ihr erstes XR-Spiel bzw. Ihre erste XR-Anwendung empfehlen wir Ihnen, mit einem einzigen Action Set zu beginnen und die Dinge nicht zu sehr zu verkomplizieren.

Für unser Beispiel in diesem Dokument werden wir daher ein einzelnes Action Set mit dem Namen my_first_action_set erstellen. Wir tun dies, indem wir auf den Button Action Set hinzufügen klicken:

Die Spalten in unserer Tabelle lauten wie folgt:

Farbe	Wert	Beschreibung
1	my_first_action_set	Dies ist der interne Name des Action Sets. OpenXR gibt für diesen Namen außer der Größe keine besonderen Beschränkungen vor, allerdings mögen einige XR-Runtimes keine Leerzeichen oder Sonderzeichen.
2	Mein erstes Action Set	Dies ist ein für Menschen lesbarer Name für das Action Set. Einige XR-Runtimes zeigen dem Endbenutzer diesen Namen an, zum Beispiel in Konfigurationsdialogen.
3	0	Dies ist die Priorität des Action Sets. Wenn mehrere aktive Action Sets mit Aktionen an dieselben Controller-Eingänge oder -Ausgänge gebunden sind, bestimmt das Action Set mit dem höchsten Prioritätswert die Aktion, die aktualisiert wird.

Aktionen

In der XR Action-Map sind Aktionen die Entitäten, mit denen Ihr Spiel/Ihre Anwendung interagieren wird. Zum Beispiel können wir eine Aktion Shoot definieren und die Eingabe, die an diese Aktion gebunden ist, wird das Signal button_pressed auf dem entsprechenden XRController3D-Node in Ihrer Szene mit Shoot als name-Parameter des Signals auslösen.

Man kann auch den aktuellen Zustand einer Aktion per Polling abfragen. XRController3D zum Beispiel hat eine is_button_pressed Methode.

Aktionen können sowohl für die Eingabe als auch für die Ausgabe verwendet werden, und jede Aktion hat einen Typ, der ihr Verhalten definiert.

• Der Typ Bool wird für diskrete Eingaben wie Buttons verwendet.

• Der Typ Float wird für analoge Eingänge wie Trigger verwendet.

Diese beiden sind besonders, da sie die einzigen sind, die austauschbar sind. OpenXR wird Konvertierungen zwischen Bool und Float-Eingaben und Aktionen behandeln. Sie können den Wert einer Aktion vom Typ Float erhalten, indem Sie die Methode get_float auf Ihrem XRController3D-Node aufrufen. Sie gibt das Signal input_float_changed aus, wenn sie geändert wird.

Bemerkung

Bei der Abfrage von Analogeingängen als Tasten wird ein Schwellenwert angewendet. Dieser Schwellenwert wird derzeit ausschließlich von der XR-Runtime verwaltet. Es ist geplant, Godot zu erweitern, um in Zukunft ein gewisses Maß an Kontrolle über diese Schwellenwerte zu ermöglichen.

Der Typ Vector2 definiert die Eingabe als Achseneingabe. Touchpads, Thumbsticks und ähnliche Eingaben werden als Vektoren dargestellt. Sie können den Wert einer Aktion vom Typ Vector2 erhalten, indem Sie die Methode get_vector2 auf Ihrem XRController3D-Node aufrufen. Er gibt das Signal input_vector2_changed aus, wenn er geändert wird.

Der Typ Pose definiert eine räumlich getrackte Eingabe. Mehrere "Pose"-Eingaben sind in OpenXR verfügbar: aim, grip und palm. Ihr XRController3D-Node wird automatisch positioniert, basierend auf der Pose-Aktion, die der Pose-Property dieser Nodes zugeordnet ist. Mehr über Posen später.

Bemerkung

Die OpenXR-Implementierung in Godot stellt auch eine spezielle Pose namens Skelett zur Verfügung. Diese ist Teil der Hand-Tracking-Implementierung. Diese Pose wird durch die Aktion Skelett dargestellt, die außerhalb des Action-Map-Systems unterstützt wird. Sie ist also immer vorhanden, wenn die Handverfolgung unterstützt wird. Man muss keine Aktionen an diese Pose binden, um sie zu benutzen.

Schließlich ist der einzige Ausgabetyp Haptic und erlaubt es uns, die Intensität des haptischen Feedbacks, wie z.B. die Vibration des Controllers, einzustellen. Controller können mehrere haptische Ausgänge haben und Unterstützung für haptische Westen ist für OpenXR geplant.

Fügen wir also eine Aktion für unsere Zielpose hinzu, indem wir auf den +-Button für unser Action Set klicken:

Die Spalten in unserer Tabelle lauten wie folgt:

Farbe	Wert	Beschreibung
1	aim_pose	Dies ist der interne Name der Aktion. OpenXR gibt für diesen Namen außer der Größe keine besonderen Beschränkungen vor, allerdings mögen einige XR-Runtimes keine Leerzeichen oder Sonderzeichen.
2	Ziel-Pose	Dies ist ein von Menschen lesbarer Name für die Aktion. Einige XR-Runtimes zeigen dem Endbenutzer diesen Namen an, zum Beispiel in Konfigurationsdialogen.
3	Pose	Der Typ dieser Aktion.

OpenXR definiert eine Reihe von Binding-fähigen Eingabeposen, die für Controller allgemein verfügbar sind. Es gibt keine Regeln dafür, welche Posen für verschiedene Controller unterstützt werden. Die Posen, die OpenXR derzeit definiert, sind:

• Bei den meisten Controllern ist die "Zielen"-Pose leicht vor dem Controller positioniert und zielt nach vorne. Dies ist eine großartige Pose für Laserpointer oder zum Ausrichten der Mündung einer Waffe.

• Bei den meisten Controllern befindet sich die Griffhaltung an der Stelle, an der sich die Grifftaste auf dem Controller befindet. Die Ausrichtung dieser Pose ist von Controller zu Controller unterschiedlich und kann für denselben Controller bei verschiedenen XR-Runtimes unterschiedlich sein.

• Die Handflächen-Pose wird bei den meisten Controllern in der Mitte der Handfläche der Hand positioniert, die den Controller hält. Dies ist eine neue Pose, die nicht in allen XR-Runtimes verfügbar ist.

Bemerkung

Wenn Handtracking verwendet wird, gibt es derzeit große Unterschiede in den Implementierungen zwischen den verschiedenen XR Runtimes. Daher ist die Action-Map derzeit nicht für die Handverfolgung geeignet. Daran wird gearbeitet, also bleiben Sie dran.

Vervollständigen wir unsere Liste der Aktionen für einen sehr einfaches Shooter/eine einfache Anwendung:

Wir haben folgende Aktionen hinzugefügt:

• Bewegung, die es dem Benutzer ermöglicht, sich außerhalb des normalen Raum-Trackings zu bewegen.

• Greifen, das erkennt, dass der Benutzer etwas festhalten möchte.

• Schießen, das erkennt, dass der Benutzer die Waffe, die er in der Hand hält, abfeuern möchte.

• Haptisch, was uns ermöglicht, haptisches Feedback auszugeben.

Beachten Sie nun, dass wir nicht zwischen der linken und der rechten Hand unterscheiden. Das wird erst in der nächsten Phase festgelegt. Wir haben das Action-System so implementiert, dass man die gleiche Aktion an beide Hände binden kann. Der entsprechende XRController3D-Node wird das Signal ausgeben.

Warnung

Sowohl für Greifen als auch für Schießen haben wir den Typ Bool verwendet. Wie bereits erwähnt, führt OpenXR automatische Konvertierungen von analogen Controls durch, jedoch wenden derzeit nicht alle XR Runtimes sinnvolle Schwellenwerte an.

Wir empfehlen als Workaround, den Typ Float zu verwenden, wenn Sie mit Triggern und Grip-Buttons interagieren und Ihren eigenen Schwellenwert anwenden.

Für Buttons wie A/B/X/Y und ähnliche, bei denen es keine analoge Option gibt, funktioniert der Typ Bool gut.

Bemerkung

Sie können dieselbe Aktion an mehrere Eingänge für denselben Controller im selben Profil binden. In diesem Fall wird die XR Runtime versuchen, die Eingänge zu kombinieren.

• Bei Bool-Eingängen wird eine ODER-Operation zwischen den Buttons durchgeführt.

• Bei Float-Eingaben wird der höchste Wert der gebundenen Eingaben genommen.

• Das Verhalten für Pose-Eingaben ist undefiniert, aber die erste gebundene Eingabe wird wahrscheinlich verwendet.

Sie sollten nicht mehrere Aktionen desselben Action Sets an denselben Controller-Eingang binden. Wenn Sie dies tun, oder wenn Aktionen aus mehreren Action Sets gebunden sind, diese aber überlappende Prioritäten haben, ist das Verhalten undefiniert. Es kann sein, dass die XR-Runtime Ihre Action-Map einfach nicht akzeptiert, oder dass sie diese nach dem Prinzip "Wer zuerst kommt, mahlt zuerst" annimmt.

Wir sind noch dabei, die Einschränkungen für das Binding mehrerer Aktionen an denselben Ausgang zu untersuchen, da dieses Szenario sinnvoll ist. Die OpenXR-Spezifikation scheint dies nicht zu erlauben.

Nun, da wir unsere grundlegenden Aktionen definiert haben, ist es an der Zeit, sie zu verknüpfen.

Profile

In OpenXR controller bindings are captured in so-called "Interaction Profiles". We've shortened it to "Profiles" because it takes up less space.

Dieser generische Name wurde gewählt, weil die Controller nicht das gesamte System abdecken. Derzeit gibt es auch Profile für Tracker, Fernbedienungen und Tracking-Stifte. Es gibt auch Bestimmungen für Geräte wie Laufbänder, haptische Westen und dergleichen, auch wenn diese noch nicht Teil der Spezifikation sind.

Warnung

Es ist wichtig zu wissen, dass OpenXR eine strenge Prüfung der unterstützten Geräte vornimmt. Die Kernspezifikation identifiziert eine Reihe von Controllern und ähnlichen Geräten mit ihren unterstützten Ein- und Ausgängen. Jede XR-Runtime muss diese Interaktionsprofile akzeptieren, auch wenn sie nicht anwendbar sind.

Neue Geräte werden durch Erweiterungen hinzugefügt und XR-Runtimes müssen angeben, welche Geräte sie unterstützen. XR-Runtimes, die ein durch Extensions hinzugefügtes Gerät nicht unterstützen, akzeptieren diese Profile nicht. XR-Runtimes, die hinzugefügte Eingabe- oder Ausgabetypen nicht unterstützen, stürzen oft ab, wenn sie bereitgestellt werden.

Godot speichert Metadaten über alle verfügbaren Geräte, ihre Ein- und Ausgänge und welche Extension sie unterstützt. Sie können Interaktionsprofile für alle Geräte erstellen, die Sie unterstützen möchten. Godot filtert diejenigen heraus, die von der XR-Runtime, die der Benutzer verwendet, nicht unterstützt werden.

Dies bedeutet, dass Sie möglicherweise auf eine neuere Version von Godot aktualisieren müssen, um neue Geräte zu unterstützen.

Es ist jedoch auch wichtig zu wissen, dass die Action-Map unter diesem Gesichtspunkt entwickelt wurde. Wenn neue Geräte auf den Markt kommen oder wenn Ihre Benutzer Geräte verwenden, auf die Sie keinen Zugriff haben, ist das Action-Map-System auf die XR-Runtime angewiesen. Es ist die Aufgabe der XR-Runtime, das am besten geeignete Interaktionsprofil auszuwählen, das angegeben wurde, und es an den vom Benutzer verwendeten Controller anzupassen.

Wie die XR Runtime dies tut, bleibt der Implementierung der Runtime überlassen, und so gibt es große Unterschiede zwischen den Runtimes. Einige Runtimes erlauben es dem Benutzer sogar, die Bindings selbst zu bearbeiten.

Ein üblicher Ansatz für eine Runtime ist es, zunächst nach einem passenden Interaktionsprofil zu suchen. Wird dieses nicht gefunden, werden die gebräuchlichsten Profile wie das des "Touch-Controllers" geprüft und eine Konvertierung vorgenommen. Wenn alles andere fehlschlägt, prüft sie das generische "Einfacher controller".

Bemerkung

Es gibt eine wichtige Schlussfolgerung, die hier gezogen werden muss: Wenn ein Controller gefunden und die Action-Map auf ihn angewendet wird, ist die XR Runtime nicht auf die exakten Konfigurationen beschränkt, die Sie im Action-Map-Editor von Godot eingerichtet haben. Die Runtime wählt in der Regel ein geeignetes Mapping auf der Grundlage einer der von Ihnen in der Action-Map eingerichteten Bindings, kann aber auch davon abweichen.

Bei Verwendung des Touch-Controller-Profils kann beispielsweise eines der folgenden Szenarien zutreffen:

• wir könnten einen Quest 1 Controller verwenden,

• wir könnten einen Quest 2-Controller verwenden,

• wir könnten einen Quest Pro-Controller verwenden, aber es wurde kein Quest Pro-Profil angegeben oder die verwendete XR Runtime unterstützt den Quest Pro Controller nicht,

• es könnte sich um einen völlig anderen Controller handeln, für den kein Profil angegeben wurde, aber die XR-Runtime verwendet die Touch-Bindings als Grundlage.

Daher gibt es derzeit keine Möglichkeit, mit Sicherheit festzustellen, welchen Controller der Benutzer tatsächlich verwendet.

Warnung

Schließlich, und das verwirrt viele Leute, sind die Bindings nicht in Stein gemeißelt. Es ist völlig zulässig und wird sogar erwartet, dass eine XR Runtime dem Benutzer erlaubt, die Bindings anzupassen.

Im Moment bietet keine der XR-Runtimes diese Funktionalität, obwohl SteamVR eine bestehende UI von OpenVRs Action-Map-System hat, die noch zugänglich ist. Daran wird jedoch aktiv gearbeitet.

Unser erstes Controller-Binding

Richten wir unser erstes Controller-Binding ein, indem wir den Touch-Controller als Beispiel verwenden.

Drücken Sie auf "Profil hinzufügen", suchen Sie den Touch Controller und fügen Sie ihn hinzu. Wenn er nicht in der Liste steht, wurde er möglicherweise bereits hinzugefügt.

Unsere Benutzeroberfläche zeigt nun Panels für den linken und rechten Controller. Die Panels enthalten alle möglichen Ein- und Ausgänge für jeden Controller. Wir können das + neben jedem Eintrag verwenden, um ihn an eine Aktion zu binden:

Beenden wir unsere Konfiguration:

Jede Aktion ist an den angegebenen Eingang oder Ausgang für beide Controller gebunden, um anzuzeigen, dass wir die Aktion auf beiden Controllern unterstützen. Die Ausnahme ist die Bewegungsaktion, die nur an den Controller der rechten Hand gebunden ist. Es ist wahrscheinlich, dass wir den Thumbstick der linken Hand für einen anderen Zweck verwenden wollen, z.B. für eine Teleportfunktion.

Bei der Entwicklung Ihres Spiels/Ihrer Anwendung müssen Sie die Möglichkeit berücksichtigen, dass der Benutzer das Binding ändert und die Bewegung an den linken Thumbstick bindet.

Beachten Sie auch, dass unsere booleschen Aktionen Schießen und Greifen mit Eingaben vom Typ Float verknüpft sind. Wie bereits erwähnt, führt OpenXR Konvertierungen zwischen den beiden Typen durch, aber lesen Sie bitte die Warnung zu diesem Thema weiter oben in diesem Dokument.

Bemerkung

Einige der Eingaben scheinen mehrfach in unserer Liste aufzutauchen.

Zum Beispiel können wir den X-Button zweimal finden, einmal als X-Klick und dann als X-Touch. Das liegt daran, dass der Touch-Controller einen kapazitiven Sensor hat.

• X-Touch ist "true", wenn der Benutzer lediglich die X-Taste berührt.

• X-Klick wird "true" sein, wenn der Benutzer tatsächlich auf den Button drückt.

Ähnlich verhält es sich mit dem Thumbstick:

• Thumbstick-Touch, das "true" wird, wenn der Benutzer den Thumbstick berührt.

• Thumbstick, der einen Wert für die Richtung angibt, in die der Thumbstick gedrückt wird.

• Thumbstick-Klick, der "true" ist, wenn der Benutzer den Thumbstick hinein drückt.

Es ist wichtig zu beachten, dass nur eine ausgewählte Anzahl von XR-Controllern Touch-Sensoren unterstützen oder über Klickfunktionen auf den Thumbsticks verfügen. Berücksichtigen Sie dies bei der Entwicklung Ihres Spiels/Ihrer Anwendung. Stellen Sie sicher, dass diese für optionale Funktionen Ihres Spiels/Ihrer Anwendung verwendet werden.

Der einfache Controller

Der "Einfache Controller" ist ein generischer Controller, den OpenXR als Fallback anbietet. Wir werden unser Mapping anwenden:

Wie schmerzlich deutlich wird, ist der einfache Controller oft viel zu einfach und eignet sich nur für die einfachsten VR-Spiele und -Anwendungen.

Aus diesem Grund verwenden viele XR-Runtimes sie nur als letzten Ausweg und versuchen zunächst, Bindings von einem der bekannteren Systeme als Ausweichlösung zu verwenden.

Bemerkung

Da der einfache Controller wahrscheinlich nicht die Bedürfnisse Ihres Spiels abdeckt, ist es verlockend, Bindings für jeden von OpenXR unterstützten Controller bereitzustellen. Die Default Action-Map scheint diese Vorgehensweise zu empfehlen. Wie bereits erwähnt, wurde die Default Action-Map entwickelt, um die Migration von Godot 3 zu erleichtern.

Die OpenXR Working Group empfiehlt, nur Bindings für Controller einzurichten, die vom Entwickler tatsächlich getestet wurden. Die XR-Runtimes sind mit diesem Gedanken im Hinterkopf entworfen worden. Sie können ein bereitgestelltes Binding besser neu verbinden als ein Entwickler, der nur Vermutungen anstellen kann. Zumal der Entwickler nicht testen kann, ob dies zu einem angenehmen Erlebnis für den Endbenutzer führt.

Dies ist auch unser Rat: Beschränken Sie Ihre Action-Map auf die Interaktionsprofile für Geräte, mit denen Sie Ihr Spiel tatsächlich getestet haben. Der Oculus Touch-Controller wird von vielen Runtimes als Fallback-Controller verwendet. Wenn Sie in der Lage sind, Ihr Spiel mit einer Meta Rift oder Quest zu testen und dieses Profil hinzuzufügen, ist die Wahrscheinlichkeit groß, dass Ihr Spiel auch mit anderen Headsets funktionieren wird.

Binding Modifiers

One of the main goals of the action map is to remove the need for the application to know the hardware used. However, sometimes the hardware has physical differences that require inputs to be altered in ways other than how they are bound to actions. This need ranges from setting thresholds, to altering the inputs available on a controller.

Binding modifiers are not enabled by default and require enabling in the OpenXR project settings. Also there is no guarantee that these modifiers are supported by every runtime. You will need to consult the support for the runtimes you are targeting and decide whether to rely on the modifiers or implement some form of fallback mechanism.

If you are targeting multiple runtimes that have support for the same controllers, you may need to create separate action maps for each runtime. You can control which action map Godot uses by using different export templates for each runtime and using a custom feature tag to set the action map.

In Godot, binding modifiers are divided into two groups: modifiers that work on the interaction profile level, and modifiers that work on individual bindings.

Binding modifiers on an interaction profile

Binding modifiers that are applied to the whole interaction profile can be accessed through the modifier button on the right side of the interaction profile editor.

You can add a new modifier by pressing the Add binding modifier button.

Warnung

As Godot doesn't know which controllers and runtimes support a modifier, there is no restriction to adding modifiers. Unsupported modifiers will be ignored.

Dpad Binding modifier

The dpad binding modifier adds new inputs to an interaction profile for each joystick and thumbpad input on this controller. It turns the input into a dpad with separate up, down, left and right inputs that are exposed as buttons:

Bemerkung

Inputs related to extensions are denoted with an asterix.

In order to use the dpad binding modifier you need to enable the dpad binding modifier extension in project settings:

Enabling the extension is enough to make this functionality work using default settings.

Adding the modifier is optional and allows you to fine tune the way the dpad functionality behaves. You can add the modifier multiple times to set different settings for different inputs.

These settings are used as follows:

• Action Set defines the action set to which these settings are applied.

• Input Path defines the original input that is mapped to the new dpad inputs.

• Threshold specifies the threshold value that will enable a dpad action, e.g. a value of 0.6 means that if the distance from center goes above 0.6 the dpad action is pressed.

• Threshold Released specifies the threshold value that will disable a dpad action, e.g. a value of 0.4 means that if the distance from center goes below 0.4 the dpad action is released.

• Center Region specifies the distance from center that enabled the center action, this is only supported for trackpads.

• Wedge Angle specifies the angle of each wedge. A value of 90 degrees or lower means that up, down, left and right each have a separate slice in which they are in the pressed state. A value above 90 degrees means that the slices overlap and that multiple actions can be in the pressed state.

• Is Sticky, when enabled means that an action stays in the pressed state until the thumbstick or trackpad moves into another wedge even if it has left the wedge for that action.

• On Haptic lets us define a haptic output that is automatically activated when an action becomes pressed.

• Off Haptic lets us define a haptic output that is automatically activated when a action is released.

Binding modifiers on individual bindings

Binding modifiers that are applied to individual bindings can be accessed through the binding modifier button next to action attached to an input:

You can add a new modifier by pressing the Add binding modifier button.

Warnung

As Godot doesn't know which inputs on each runtime support a modifier, there is no restriction to adding modifiers. If the modifier extension is unsupported, modifiers will be filtered out at runtime. Modifiers added to the wrong input may result in a runtime error.

You should test your action map on the actual hardware and runtime to verify the proper setup.

Analog threshold modifier

The analog threshold modifier allows you to specify the thresholds used for any analog input, like the trigger, that has a boolean input. This controls when the input is in the pressed state.

In order to use this modifier you must enable the analog threshold extension in the project settings:

The analog threshold modifier has the following settings:

These are defined as follows:

• On Threshold specifies the threshold value that will enable the action, e.g. a value of 0.6 means that when the analog value gets above 0.6 the action is set to the pressed state.

• Off Threshold specifies the threshold value that will disable the action, e.g. a value of 0.4 means that when the analog value goes below 0.4 the action is set in to the released state.

• On Haptic lets us define a haptic output that is automatically activated when the input is pressed.

• Off Haptic lets us define a haptic output that is automatically activated when the input is released.

Haptics on modifiers

Modifiers can support automatic haptic output that is triggered when thresholds are reached.

Bemerkung

Currently both available modifiers support this feature however there is no rule future modifiers also have this capability. Only one type of haptic feedback is supported but in the future other options may become available.

Haptic vibration

The haptic vibration allows us to specify a simple haptic pulse:

It has the following options:

• Duration is the duration of the pulse in nanoseconds. -1 lets the runtime choose an optimal value for a short pulse suitable for the current hardware.

• Frequency is the frequency of the pulse in Hz. 0 lets the runtime choose an optimal frequency for a short pulse suitable for the current hardware.

• Amplitude is the amplitude of the pulse.