Gamepad-Emulation für die Steam-Eingabe – Bewährte Praktiken (Steamworks-Dokumentation)

Steamworks-Dokumentation

Gamepad-Emulation für die Steam-Eingabe – Bewährte Praktiken

Steamworks-Dokumentation > Funktionen > Steam-Eingabe > Gamepad-Emulation für die Steam-Eingabe – Bewährte Praktiken

Die Steam-Eingabe ist ein Dienst, der es Steam-Nutzern ermöglicht, jedes beliebige Spiel mit Controller-Unterstützung mit dem Gerät ihrer Wahl zu spielen. Dabei übersetzt die Steam-Eingabe die Nutzereingabe in etwas, was das Spiel entweder über die Gamepad-Emulation, Maus- und Tastatur-Emulation oder die Steam-Eingabe-API versteht. Im Folgenden konzentrieren wir uns darauf, wie man die Steam-Eingabe-Gamepad-Emulation am besten nutzt, um die bestehende Controller-Unterstützung Ihres Spiels zu erweitern.

Was ist eine Gamepad-Emulation?

Auf Windows bindet das Steam-Overlay traditionelle Eingabe-APIs wie XInput, DirectInput, RawInput und Windows.Gaming.Input ein und fügt ein emuliertes Xbox-Controllergerät hinzu. Auf macOS und Linux emulierte Controller-Eingaben werden von einem Treiber bereitgestellt.
Der Controller wird in Ihrem Spiel als XBox-Controller angezeigt, was bedeutet, dass Controller mit zusätzlichen Eingabemöglichkeiten über einige doppelte Belegungen verfügen. Beispiel: Der PlayStation-Trackpad-Klick und die OPTIONEN-Taste sind beide der XInput-Start-Taste zugeordnet.
Zuzüglich zur normalen Gamepad-Eingabe ist es möglich, Gyroskop-Eingaben für Switch, PlayStation und Steam Controller in die Maus-Emulation einzubinden und Bewegungssteuerungen bereitzustellen. Dies funktioniert nur in Spielen mit lokaler Einzelspielerunterstützung, da für diese nur eine Maus-Eingabe existiert und es auch die Akzeptanz gleichzeitiger Maus- und Gamepad-Eingaben erfordert. Wenn Sie an diesen Funktionen ohne diese Ausnahmen interessiert sind, fügen Sie bitte die Steam-Eingabe-API hinzu.
Sie können den Controllertyp zurzeit über Steam abfragen, um Geräte-spezifische Glyphen anzeigen zu können, sind aber auf die von Ihrer aktuellen Steamworks-SDK unterstützten Typen beschränkt. Wenn Sie an der Unterstützung zukunftssicherer Glyphen interessiert sind, integrieren Sie bitte die Steam-Eingabe-API.
Es kann sein, dass Sie Nutzer haben, die über die Steam-Eingabe spielen, selbst mit Controllern, die Sie bereits unterstützen, da Steam Remote Play sie verwendet, um während des Streamens Eingaben zu ermöglichen. Des Weiteren hat eine beträchtliche Anzahl an Nutzern die Steam-Eingabe für ihre Controller für ihre gesamte Steam-Bibliothek aktiviert. Insgesamt verwendeten 2020 ca. 25 % aller Controller-Sitzungen auf Steam die Steam-Eingabe, inklusive fast der Hälfte aller PlayStation Controller-Sitzungen.

Die Gamepad-Emulation wird von über 2000 Spielen auf Steam inklusive namhafter Spiele wie Monster Hunter: World, Ace Combat 7, Dragon Quest XI, Into the Breach, und Middle Earth: Shadow of War für mindestens einen Controller-Typ verwendet, wobei nicht alle davon sämtliche bewährte Praktiken befolgen. Ein Spiel, das sämtliche bewährte Praktiken befolgt und das wir aus diesem Grund besonders ins Rampenlicht rücken möchten ist Into the Breach.

Anzeige gerätespezifischer Grafiken

Wir unterstützen einige Methoden, um mit der Gamepad-Emulation für die Steam-Eingabe spezifische Glyphen anzuzeigen. Zum einen für Spiele, die Bilder zukunftssicher während der Laufzeit laden können, also solche, deren Bilder auch nach einer Aktualisierung der Steam-Eingabe ohne eine eigene Spielaktualisierung fehlerfrei funktionieren. Zum anderen für Spiele, die die Bilder in ihre Elemente integrieren müssen oder dieselben stilisierten Grafiken der Konsolenportierung ihres Spiels verwenden möchten. Into the Breach verwendet eigene Grafiken für Xbox / Steam Controller:

PlayStation:

und Nintendo Switch Controller:

Hinweis: Wir empfehlen, auch bei Verwendung eigener Grafiken als Backup auf Steam-Grafiken zurückzugreifen, wenn ein Controller nicht erkannt wird. Sie können außerdem unsere Hilfefunktion aufrufen, um die die zum Veröffentlichungszeitpunkt Ihres Spiels erhältliche Option mit der höchsten Übereinstimmung zu finden. So werden auch zukünftig erhältlichen Geräten angemessene Glyphen zugewiesen.

Anzeige von zukunftssicheren Steam-Glyphen

Verwenden Sie bitte die folgenden Funktionen:

Beispielcode:

// Initialisieren Sie die Schnittstelle, bevor Sie individuelle Funktionen verwenden. Dies muss nur einmal aufgerufen werden!
SteamInput()->Init()

// ...

// SteamAPI_RunCallbacks() ruft die RunFrame-Funktionen für alle initialisierten Schnittstellen auf.
// Die meisten Spiele rufen dies bereits periodisch auf. Wenn Sie das nicht tun, müssen Sie
//  die Steam-Eingabe-Schnittstelle manuell aktualisieren
SteamInput()->RunFrame();

// ...

// Ersetzen Sie dies mit dem XInput-Platz nach dem Sie abfragen. Diese Zahl liegt zwischen 0 und 3.
// Wenn Sie RawInput zur Geräteerkennung verwenden, bevor Sie entscheiden, welche API Sie verwenden,
// lesen Sie bitte den Abschnitt „Verwendung von RawInput zur Geräteerkennung“.
int nXinputSlot = 0;

// Ersetzen Sie die Taste mit der, nach der Sie abfragen.
EXboxOrigin eXboxButtonToGetGlyphFor = k_EXboxOrigin_A;
EInputActionOrigin buttonOrigin = k_EInputActionOrigin_XBoxOne_A;

// Wenn der Controller über die Steam-Eingabe konfiguriert wird, übersetzen Sie diese Taste.
InputHandle_t controller1Handle = SteamInput()->GetControllerForGamepadIndex( nXinputSlot );
if ( controller1Handle > 0 )
{
	// Gültige Handles sind nicht-null; dies ist ein Controller, der über die Steam-Eingabe konfiguriert wird.
	// Hinweis: Controller, die die Steam-Eingabe-API verwenden, geben keinen Handle über GetControllerForGamepadIndex() zurück.
	buttonOrigin = SteamInput()->GetActionOriginFromXboxOrigin( controller1Handle, k_EXboxOrigin_A );
}
else
{
	// Gültige Handles sind nicht-null; dies ist ein normaler Xbox-Controller.
	// Verwenden Sie weiterhin die Originaltaste.
}

// Die Werte von EInputActionOrigin wachsen ständig weiter, da Steam weitere Unterstützung hinzufügt, aber das ist in Ordnung,
// da wir in diesem Beispiel die Gerätebilder von Steam erhalten, das auch ein neues Glyphenbild mitliefern kann.

// Rufen Sie das Bild vom Steam-Client ab.
const char *localGlyphPath = SteamInput()->GetGlyphForActionOrigin( buttonOrigin );
printf( "path = %s\n", localGlyphPath ); // "path = C:\Program Files (x86)\Steam\tenfoot\resource\images\library\controller\api\ps4_button_x.png"

// Ersetzen Sie dies mit einer Funktion des Spiels, die einen Dateipfad in eine verwendbare Spieltextur umwandelt.
glyphTextureID = loadButtonGlyphTextureFromLocalPath( localGlyphPath );

Anzeige eigener Grafiken – Glyphenpalette

Wenn Sie mehrere Glyphenpaletten verwenden und eine auf Basis des Controllertyps auswählen, können Sie Steam nach dieser Information über den verwendeten XInput-Platz fragen:

Beispielcode:

// Initialisieren Sie die Schnittstelle, bevor Sie individuelle Funktionen verwenden. Dies muss nur einmal aufgerufen werden!
SteamInput()->Init()

// ...

// SteamAPI_RunCallbacks() ruft die RunFrame-Funktionen für alle initialisierten Schnittstellen auf.
// Die meisten Spiele rufen dies bereits periodisch auf. Wenn Sie das nicht tun, müssen Sie
//  die Steam-Eingabe-Schnittstelle manuell aktualisieren
SteamInput()->RunFrame();

// ...

// Ersetzen Sie dies mit dem XInput-Platz nach dem Sie abfragen. Diese Zahl liegt zwischen 0 und 3.
// Wenn Sie RawInput zur Geräteerkennung verwenden, bevor Sie entscheiden, welche API Sie verwenden,
// lesen Sie bitte den Abschnitt „Verwendung von RawInput zur Geräteerkennung“.
int nXinputSlotIndex  = 0;

InputHandle_t inputHandle = SteamInput()->GetControllerForGamepadIndex( nXinputSlotIndex  );
if ( inputHandle == 0 )
{
	// Gültige Eingabe-Handles sind nicht-null; dies ist ein normaler Xbox-Controller. 
}
else
{
	// Steam gibt immer einen Aufzählungswert zurück, der für Ihre SDK-Version gültig ist.
	ESteamInputType inputType = SteamInput()->GetInputTypeForHandle( inputHandle );
	switch( inputType )
	{
	case k_ESteamInputType_Unknown: 
		printf( "unknown!\n" ); break;
	case k_ESteamInputType_SteamController:
		printf( "Steam controller!\n" ); break;
	case k_ESteamInputType_XBox360Controller:
		printf( "XBox 360 controller!\n" ); break;
	case k_ESteamInputType_XBoxOneController:
		printf( "XBox One controller!\n" ); break;
	case k_ESteamInputType_GenericXInput:
		printf( "Generic XInput!\n" ); break;
	case k_ESteamInputType_PS4Controller:
		printf( "PS4 controller!\n" ); break;
	}
}

Anzeige eigener Artworks – Artwork auf Knopfdruck

Falls Sie eine einzelne Lookup-Tabelle verwenden, die nach Aktionsursprüngen indiziert ist, können Sie mit diesen Funktionen gerätespezifische Glyphen implementieren und nicht erkannte Controller in ihre nächsten Entsprechungen übersetzen.

Beispielcode:

// Initialisieren Sie die Schnittstelle, bevor Sie individuelle Funktionen verwenden. Dies muss nur einmal aufgerufen werden!
SteamInput()->Init()

// ...

// SteamAPI_RunCallbacks() ruft die RunFrame-Funktionen für alle initialisierten Schnittstellen auf.
// Die meisten Spiele rufen dies bereits periodisch auf. Wenn Sie das nicht tun, müssen Sie
//  die Steam-Eingabe-Schnittstelle manuell aktualisieren
SteamInput()->RunFrame();

// ...

// Ersetzen Sie dies mit dem XInput-Platz nach dem Sie abfragen. Diese Zahl liegt zwischen 0 und 3.
// Wenn Sie RawInput zur Geräteerkennung verwenden, bevor Sie entscheiden, welche API Sie verwenden,
// lesen Sie bitte den Abschnitt „Verwendung von RawInput zur Geräteerkennung“.
int nXinputSlot = 0;

// Ersetzen Sie die Taste mit der, nach der Sie abfragen.
EXboxOrigin eXboxButtonToGetGlyphFor = k_EXboxOrigin_A;
EInputActionOrigin buttonOrigin = k_EInputActionOrigin_XBoxOne_A;

// Wenn der Controller über die Steam-Eingabe konfiguriert wird, übersetzen Sie diese Taste.
InputHandle_t controller1Handle = SteamInput()->GetControllerForGamepadIndex( nXinputSlot );
if ( controller1Handle > 0 )
{
	// Gültige Handles sind nicht-null; dies ist ein Controller, der über die Steam-Eingabe konfiguriert wird.
	// Hinweis: Controller, die die Steam-Eingabe-API verwenden, geben keinen Handle über GetControllerForGamepadIndex() zurück.
	buttonOrigin = SteamInput()->GetActionOriginFromXboxOrigin( controller1Handle, k_EXboxOrigin_A );  //i.e, k_EInputActionOrigin_PS4_X
}
else
{
	// Gültige Handles sind nicht-null; dies ist ein normaler Xbox-Controller.
	// Verwenden Sie weiterhin die Originaltaste.
}

// Steam fügt fortlaufend Aktionssursprünge hinzu und zukünftige Controller werden die aktuelle Bandbreite überschreiten.
// Wenn Sie einen Test durchführen möchten, können Sie vorgeben, dass Switch/PS5 Controller nicht existieren, und dies ändern zu:
// if ( buttonOrigin >= k_EInputActionOrigin_XBox360_Reserved10 )
if ( buttonOrigin >= k_EInputActionOrigin_Count )
{
	// Unser Spiel wurde ohne Artwork für diesen Ursprung veröffentlicht! Wir nehmen an, dass Steam Unterstützung für
// einen neuen Controller hinzugefügt hat. Wir nehmen also den nächstgelegenen Wert, der von der eingebauten SDK unterstützt wird
	buttonOrigin = SteamInput()->TranslateActionOrigin( k_ESteamInputType_Unknown, buttonOrigin );
}

// Ersetzen Sie dies mit einer Funktion des Spiels, die Ihr Artwork für eine Taste zurückgibt
int glyphTextureID = getHardCodedButtonGlyphTexture( buttonOrigin );

Verwendung von RawInput zur Geräteerkennung

Einige Spiele verwenden RawInput, um den Einsatz von mehr als vier Controllern zu unterstützen oder festzustellen, ob Playstation Controller verbunden wurden. Diese API gibt auch Nicht-Gamepad-Geräte zurück und verfügt über keinen zuverlässigen Index, um Zuweisungen direkt aus Steam-Eingabefunktionen durchzuführen. Stattdessen können Sie diese Information über Aufruf des Strings RIDI_DEVICENAME über GetRawInputDeviceInfo() erhalten, der mit dem USB VID/PID des realen Geräts, des Gamepad-Indexes und des Steam-Eingabe-Handles mit dem folgenden Format kodiert ist:
\\.\pipe\HID#VID_045E&PID_028E&IG_00#{Real device VID}&{Real Device PID}&{Steam Input API handle}#{Steam Input Gamepad Index}}#{ProcessID}
Beispiel: \\.\pipe\HID#VID_045E&PID_028E&IG_00#045E&0B00&00045EB00704DAF3#0#20160 für einen Xbox One Controller mit einem VID/PID von 0x45e/0x0b00.

Beispielcode:

#define VALVE_DIRECTINPUT_GAMEPAD_VID		0x28DE
#define VALVE_DIRECTINPUT_GAMEPAD_PID		0x11FF
#define STEAM_INPUT_VID_INDEX				37
#define STEAM_INPUT_PID_INDEX				42
#define STEAM_INPUT_SIAPI_HANDLE_INDEX		47
#define STEAM_INPUT_GAMEPAD_INDEX			64
#define MAX_PATH          260
//…
void YourFunction()
{
    PRAWINPUTDEVICELIST devices = NULL;
    UINT i, j, device_count = 0;

    if ((GetRawInputDeviceList(NULL, &device_count, sizeof(RAWINPUTDEVICELIST)) == -1) || (!device_count)) {
        return;  /* oh well. */
    }

    devices = (PRAWINPUTDEVICELIST)malloc(sizeof(RAWINPUTDEVICELIST) * device_count);
    if (devices == NULL) {
        return;
    }

    if (GetRawInputDeviceList(devices, &device_count, sizeof(RAWINPUTDEVICELIST)) == -1) {
        free(devices);
        return;  /* Was soll's. */
    }

    for (i = 0; i < device_count; i++) {
        RID_DEVICE_INFO rdi;
        char devName[MAX_PATH];
        UINT rdiSize = sizeof(rdi);
        UINT nameSize = MAX_PATH;
        rdi.cbSize = sizeof(rdi);
		if ( devices[i].dwType == RIM_TYPEHID &&
			GetRawInputDeviceInfoA( devices[i].hDevice, RIDI_DEVICEINFO, &rdi, &rdiSize ) != (UINT)-1 &&
			GetRawInputDeviceInfoA( devices[i].hDevice, RIDI_DEVICENAME, devName, &nameSize ) != (UINT)-1 )
		{
			if ( rdi.hid.dwVendorId == VALVE_DIRECTINPUT_GAMEPAD_VID && rdi.hid.dwProductId == VALVE_DIRECTINPUT_GAMEPAD_PID )
			{
				uint32 ulVID = strtoul( &devName[STEAM_INPUT_VID_INDEX], NULL, 16 );
				uint32 ulPID = strtoul( &devName[STEAM_INPUT_PID_INDEX], NULL, 16 );
				uint64 ulDeviceHandle = strtoull( &devName[STEAM_INPUT_SIAPI_HANDLE_INDEX], NULL, 16 );
				uint32 unGamepadIndex = strtoul( &devName[STEAM_INPUT_GAMEPAD_INDEX], NULL, 16 );
[/i][/i][/i]
				Log( "Raw input device: VID = 0x%x, PID = 0x%x, handle = 0x%llx, index = 0x%x,  %s\n", ulVID, ulPID, ulDeviceHandle, unGamepadIndex, devName );
				// Sie können VID/PID verwenden, um das Gerät direkt zu identifizieren, oder ulDeviceHandle mit GetInputTypeForHandle.
				ESteamInputType inputType = SteamInput()->GetInputTypeForHandle( ulDeviceHandle );
				switch( inputType )
				{
				case k_ESteamInputType_Unknown: 
					printf( "unknown!\n" ); break;
				case k_ESteamInputType_SteamController:
					printf( "Steam controller!\n" ); break;
				case k_ESteamInputType_XBox360Controller:
					printf( "XBox 360 controller!\n" ); break;
				case k_ESteamInputType_XBoxOneController:
					printf( "XBox One controller!\n" ); break;
				case k_ESteamInputType_GenericGamepad:
					printf( "Generic Gamepad(DirectInput)!\n" ); break;
				case k_ESteamInputType_PS3Controller:
				case k_ESteamInputType_PS4Controller:
				case k_ESteamInputType_PS5Controller:
					printf( "PlayStation controller!\n" ); break;
				}
			}
			else
			{
				// Das Gerät ist kein Controller über die Steam-Eingabe. Verwenden Sie Ihre normale ID-Logik für Ihren Controller.
				continue;
			}
		}
	}
    free(devices);
}

Konfiguration der Steamworks-Einstellungen

Legen Sie zunächst im entsprechenden Bereich unter „Anwendungen > Steam-Eingabe“ in den Steamworks-Einstellungen fest, welche Controller die Steam-Eingabe verwenden sollen. Für ein Standardspiel mit Xbox-Controllerunterstützung empfehlen wir, alle Optionen außer denen für Xbox zu markieren:

Wenn Ihr Spiel Unterstützung für Lenkräder oder Flugsteuerknüppel anbietet, sollten Sie das Kontrollkästchen für generische/DirectInput-Controller deaktivieren, da Steam die Neuzuordnung dieser Geräte nicht unterstützt.

Auswahl einer Konfiguration

Sie können Ihre eigene Konfiguration erstellen oder eine aus unseren Vorlagen wählen. Sie brauchen nur dann eine eigene Konfiguration zu erstellen, wenn Sie die Konfigurationen über unsere Standardeinstellungen hinaus verändern oder einzelnen Zuordnungen andere Aktionen im Spiel zuweisen möchten. Die integrierten Vorlagen für die Steam-Eingabe sind für alle Steam-Sprachen lokalisiert. Stellen Sie also bitte sicher, dass Sie Ihre Konfiguration ebenfalls lokalisieren, um zu verhindern, dass anderssprachigen Nutzern Englisch angezeigt wird.

Auswahl einer Vorlage

Konsolencontroller unterscheiden nicht zwischen verschiedenen Gamepad-Vorlagenvarianten. Diese Einstellungen sind jedoch für den Steam Controller wichtig. Hier ist eine Erklärung zu den Vorlagen und für welche Arten von Spielen sie gedacht sind:

Gamepad: Dies emuliert einen Xbox-Controller, wobei das rechte Trackpad zu einem reinen emulierten Joystick umgewandelt wird. Perfekt für Spiele mit zwei Sticks, Plattform- oder Sportspiele.
Gamepad mit hochpräziser Kamera/Zielfunktion: Diese Konfiguration ist ideal für ein FPS oder ein beliebiges Spiel mit Kamerasteuerung. Testen Sie vor der Auswahl, ob Ihr Spiel die gleichzeitige Verwendung von Gamepad und Maus unterstützt, einschließlich zusätzlicher Anzeigen wie des Inventars oder Karten.
Gamepad mit Kamerasteuerung: Diese Konfiguration übernimmt den Maus-Eingabestil vom Trackpad und übersetzt sie in schnelle Bewegungen eines emulierten Joysticks. Wenn die Konfiguration für Ihr Spiel eine sehr hohe Joystick-Empfindlichkeit, keine Totzone und eine lineare Beschleunigungskurve vorsieht, kann diese Konfiguration gut funktionieren. Andernfalls sollten Sie stattdessen eine Konfiguration für Tastatur und Maus in Betracht ziehen.

Eine Anleitung dazu, wie Sie die Vorlage für Ihr Spiel in Steamworks live schalten, finden Sie hier.

Erstellung einer benutzerdefinierten Konfiguration

Konfigurationen können automatisch zwischen den meisten Controllertypen konvertiert werden. Sie benötigen allerdings mindestens eine Steam-Controller- und eine Xbox-Controllerkonfiguration.

Hinweis: Wenn Sie den Vorteil gerätespezifischer Funktionen wie die Bewegungssteuerung nutzen möchten, empfiehlt es sich, auch Konfigurationen für PlayStation 4 bzw. Nintendo Switch Controller einzurichten.

Text-Eingabe

Direkte Texteingabe auf dem Bildschirm gehört nicht direkt zu ISteamInput (Steam-Eingabe) und befindet sich stattdessen unter ISteamUtils. Dies ist aktuell nur implementiert, wenn Spieler ein Spiel im Big-Picture-Modus starten.

Dokumentation hierzu:

Lokalisierung Ihrer Konfiguration
Eine lokalisierte Konfiguration ist ohne die Steam-Eingabe-API etwas schwieriger, aber machbar.

Stellen Sie zunächst sicher, dass Ihre Konfiguration seit dem letzten Export nicht geändert wurde. Öffnen Sie den Konfigurator und nehmen Sie eine Änderung vor (Sie können diese anschließend rückgängig machen).
Rufen Sie Steam\Logs\controller_ui.txt auf und suchen Sie nach einem String wie diesem:
Steam Controller Saving Controller Configuration Autosave for [SERIENNUMMER DES CONTROLLERS]- AppID: [IHRE APP-ID]. Loaded Config for Local Selection Path for App ID [IHRE APP-ID], Controller 0: F:\ProgramFiles\Steam\client\userdata\[STEAMID]\config\controller_configs\apps\[IHRE APP-ID]\[SERIENNUMMER DES CONTROLLERS]\guest\controller_configuration.vdf
Fügen Sie die Lokalisierungs-Token für die gewünschten Belegungen hinzu.
- Titel/Beschreibung:
  "controller_mappings" { "version" "3" "revision" "5" "title" "#title" "description" "#description" ...
- Tastenbelegung:
  "button_a" { "activators" { "Full_Press" { "bindings" { "binding" "xinput_button A, #abutton" } } } } ...
Erstellen Sie nun die entsprechenden Werte für jede Sprache im Lokalisationsblock:
"localization" { "german" { "title" "Dies ist ein lokalisierter Titel" "description" "Dies ist eine lokalisierte Beschreibung. Die Zuordnungen der rautenförmig angeordneten Tasten verfügen ebenfalls überlokalisierte Namen." "abutton" "Hier Ihren Namen eingeben 1" "bbutton" "Hier Ihren Namen eingeben 2" "xbutton" "Hier Ihren Namen eingeben 3" "ybutton" "Hier Ihren Namen eingeben 4" } …
Sie können die Konfiguration nun exportieren und mithilfe dieser Anleitung auf Ihrer Partnerseite einstellen. Sie sollten das Kontrollkästchen „Aktionsblock nutzen“ mit einer Ihrer Konfigurationen besetzen.

Unter der folgenden URL in Ihrem Browser finden Sie die Vorschau einer Beispielkonfiguration im Steam-Client: steam://controllerconfig/681280/1744110334. Die entsprechende VDF-Datei finden Sie hier.