Steuerung (Spieler-sichtbare Zeichen – nicht invertiert ausliefern)
Lesen Sie dies vollständig, bevor Sie Bewegungs-/Lenkungs-/Flug-Code schreiben für jedes Spiel, das WASD, Pfeiltasten, eine Verfolgungskamera oder ein Fluggerät verwendet. Überspringen Sie dies nicht und öffnen Sie nur racing-kart oder fps – diese Genre-Dateien setzen voraus, dass Sie diese Zeichen bereits kennen. Invertiertes A/D ist der häufigste Auslieferungs-Blocker bei Fahrzeug- und Flug-Demos.
Kombinieren mit building-games (Schleife, Kamera, 3D-Orientierung) und building-games/references/input.md (Tastendruck-Status, Gamepad, Touch). Diese Skill definiert was links/rechts/oben für den Spieler bedeuten und wie Sie dies beweisen.
0. Harte Regeln (Build brechen, wenn verletzt)
- Spieler-sichtbares links/rechts ist Gesetz. Bei einer Verfolgungs-/hinterher-Kamera während sich das Fahrzeug vorwärts bewegt:
- A / ← → Nase (oder Neigung) dreht links auf dem Bildschirm
- D / → → Nase (oder Neigung) dreht rechts auf dem Bildschirm
- Nie FPS-Strafe als Fahrzeuglenkung verwenden. FPS "D → +rechts-Vektor" ist Position auf der Bodenebene. Fahrzeug A/D ist Gier- (oder Roll-)Rate, kein Strafe-Offset. Diese Vermischung ist die häufigste Ursache für invertiertes A/D.
- Sie müssen einen Steuerungs-Selbsttest (§5) durchführen, bevor Sie "fertig" sagen. Nur Screenshot-QA ist nicht ausreichend. Wenn A nach rechts dreht, kehren Sie das Lenk-/Roll-Vorzeichen um, testen Sie erneut und liefern Sie aus – erfinden Sie keine neue Koordinatengeschichte.
1. Gemeinsame 3D-Basis (überall verwenden)
drei.js: rechtshändig, +Y oben, Meshes zeigen in +Z, Kameras schauen −Z.
Nur-Gier-Ausrichtung auf XZ (Bodenfahrzeuge, Läufer, die meisten Arcade-Fahrzeuge):
// gier = 0 zeigt in Welt −Z; +gier ist CCW um +Y (Nase bewegt sich in Richtung −X)
vorwärts = (-sin(gier), 0, -cos(gier))
rechts = ( cos(gier), 0, -sin(gier)) // = normalize(cross(vorwärts, weltOben))
Mit einer Verfolgungskamera hinter dem Fahrzeug (Kamera nahe position - vorwärts * dist):
| Spieler sieht | Welt (diese Basis) | Eingabe |
|---|---|---|
| Nase links | +gier | A / ← muss +gier erzeugen (oder äquivalente Linksneigung bei Flugzeugen) |
| Nase rechts | −gier | D / → muss −gier erzeugen |
Wenn Ihre Basis abweicht, behalten Sie ein konsistentes Paar – aber die spieler-sichtbare Zeile oben ist zwingend.
2. Genre-Zuordnungen
2a. FPS / zu Fuß (Strafe, nicht Lenkung)
W = +vorwärts, S = −vorwärts, D = +rechts, A = −rechts // Position, nicht Gier
Maus: gier -= movementX * empf; nicken -= movementY * empf; nicken begrenzen
Körper-Gier zum Umdrehen; Bewegung verwendet nur Gier (Nicken nicht auf Gehen anwenden).
2b. Boden-/Wasserfahrzeug (Kart, Bike, Jetski, Boot, Panzer, Rover, Schneemobil)
Arcade-Körper mit heading/gier und Vorwärts-geschwindigkeit:
// Eingabe (gehaltene Tasten → Aktionen pro Frame)
let lenkung = 0; // -1..+1, spieler-sichtbar
if (tasten.has('KeyA') || tasten.has('ArrowLeft')) lenkung += 1; // LINKS
if (tasten.has('KeyD') || tasten.has('ArrowRight')) lenkung -= 1; // RECHTS
// Optional: lenkung = clamp(lenkung + gamepadX, -1, 1) mit gleicher Vorzeichenkonvention
// Integration (geschwindigkeitsFaktor ~ 0..1 von |geschwindigkeit|)
const rückwärts = geschwindigkeit >= 0 ? 1 : -1; // Rad-links fühlt sich auch im Rückwärtsgang links an
gier += lenkung * drehRate * geschwindigkeitsFaktor * rückwärts * dt;
// Bewegung entlang der Ausrichtung
const fx = -Math.sin(gier), fz = -Math.cos(gier);
position.x += fx * geschwindigkeit * dt;
position.z += fz * geschwindigkeit * dt;
Kanonischer Fehler (nicht kopieren):
// FALSCH – so wird invertiertes A/D in freier Wildbahn ausgeliefert
if (TasteA) lenkung -= 1;
if (TasteD) lenkung += 1;
gier += lenkung * drehRate * dt; // A → −gier → NASE RECHTS bei Verfolgungskamera
Wenn Sie bereits TasteA → lenkung-- geschrieben haben, tauschen Sie entweder die Tastenzuordnung oder negieren Sie einmal bei der Integration (gier += -lenkung * …) – führen Sie dann §5 aus. Nicht zweimal umdrehen (Tasten + Integration + Mesh-Neigung).
2c. Starrflügelflug (Flugzeug, Segelflugzeug, RC-Flugzeug)
| Eingabe | Aktion | Spielererwartung |
|---|---|---|
| A / ← | Links rollen (Querruder) | Linke Flügel nach unten / nach links neigen |
| D / → | Rechts rollen | Rechte Flügel nach unten / nach rechts neigen |
| W / ↑ | Nicken (ein Schema wählen und HUD beschriften) | Normalerweise Nase nach unten oder hochziehen – konsistent sein |
| S / ↓ | Entgegengesetztes Nicken | |
| Q / E | Gier / Seitenruder (optional) | Q links, E rechts |
- A/D sind nicht Strafe und nicht „Bodenlenkung mit FPS-Vorzeichen".
- Wenden Sie Rollen in der lokalen Vorwärtsachse des Fahrzeugs mit einem Vorzeichen an, das Neigung nach links bei A entspricht. Wenn das Mesh falsch neigt, drehen Sie ein Vorzeichen bei der Rollenanwendung (oder bei der A/D → Rollen-Zuordnung) um, nicht die gesamte Basis.
- Koordinierte Kurve: Positive Neigung sollte eine Kurve erzeugen, die unter der Verfolgungs-/Außenkamera der Neigungsrichtung entspricht.
2d. Heli / Drohne / 6DOF
Dokumentieren Sie das Schema auf einem Start-Overlay. Minimum:
- Gas/Höhe auf diskreten Tasten darf nicht nach einem Druck „immer oben" bleiben (gehaltenen Zustand oder explizites Auf/Ab verwenden).
- Strafe/Gier: A links, D rechts im horizontalen Rahmen des Fahrzeugs (spieler-sichtbar).
2e. 2D-Seitenscroller / Plattformer
D / → bewegt sich rechts auf dem Bildschirm; A / ← bewegt sich links. Schwerkraft nur umgekehrt, wenn das Genre explizit auf dem Kopf steht.
3. Kamera muss zustimmen
- Verfolgungskamera:
gewünscht = fahrzeugPos + oben*höhe + vorwärts*(-folgeAbstand); interpolieren;lookAt(fahrzeug). - Berechnen Sie
vorwärtseinmal sowohl für Bewegung als auch für Kamera – nicht mit entgegengesetztem Gier-Vorzeichen im Kamerapfad neu aufbauen. - Debug-Reihenfolge: (1) Tasten registrieren → (2) Vorzeichen korrekt (§5) → (3) Kamera stimmt überein.
4. Eingabe-Infrastruktur (kurz)
- Tasten mit einem
Setbeikeydown/keyupverfolgen,event.codeverwenden; beiblur/visibilitychangelöschen. Bewegung in der Spielschleife mit dt, nicht im Ereignishandler. - Tastatur + Touch + Gamepad in Aktionen vereinheitlichen (
gas,lenkung,nicken,rollen, …). Siehebuilding-games/references/input.md. - Touch: linker Stick = Bewegung/Lenkung, rechter = Aktionen; ≥44px Ziele.
5. Obligatorischer Steuerungs-Selbsttest (vor „fertig")
Nur Screenshot ist nicht ausreichend für jedes Fahrzeug mit A/D.
5a. Spieler-sichtbare Checkliste (jeder Fahrzeug-/Flug-Build)
Während Sie vorwärts fahren (Geschwindigkeit > kleine Epsilon), Verfolgungskamera hinterher:
| Halten | Muss innerhalb von ~0,5s beobachtet werden |
|---|---|
| A | Nase oder Neigung bewegt sich links auf dem Bildschirm |
| D | Nase oder Neigung bewegt sich rechts auf dem Bildschirm |
| W (Boden) | Geschwindigkeit steigt / bewegt sich in Blickrichtung |
| S (Boden) | Bremst oder rückwärts (wie vorgesehen) |
Wenn A fehlschlägt: Lenk-/Roll-Vorzeichen einmal umdrehen, beide A und D erneut testen.
5b. Minimale Testoberfläche (implementieren)
Machen Sie einen winzigen Hook verfügbar, damit Sie (und automatisierte QA) Vorzeichen beweisen können, ohne private Closures zu erraten:
// z.B. src/game/controlsTest.ts – Dev/QA-only ist in Ordnung
export type ControlsProbe = {
getGier: () => number; // Radiant; oder getHeading()
getGeschwindigkeit: () => number;
/** Injizieren Sie gehaltene Aktionen anstelle echter Tasten; beide bleiben
* angewandt, bis Sie sie ändern, damit §5c eine Taste über mehrere Frames
* halten und am Ende löschen kann. */
setLenkung?: (v: number) => void; // -1..1, gleiches Vorzeichen wie Produktion
setTasten?: (codes: string[]) => void; // gehalten bis zum nächsten Aufruf; `[]` löscht
};
declare global {
interface Window {
__controlsTest?: ControlsProbe;
}
}
window.__controlsTest aus der Spielschleife verdrahten, wenn import.meta.env.DEV oder ein ?qa=1-Flag gesetzt ist.
5c. Automatisierter Smoke-Test (ausführen)
Treibe die §5b-Sonde mit der vorinstallierten agent-browser-CLI an – das ist der erste Schritt, kein handgeschriebenes Skript. Ein geworfenes eval beendet mit Exit-Code ungleich Null; ein bloß falsches tut dies nicht, also durch Werfen bestätigen. Als einen batch ausführen – ein CLI-Aufruf, nicht einer pro Verb – mit JSON von stdin; --bail stoppt beim ersten fehlgeschlagenen Schritt und beendet mit Exit-Code ungleich Null.
agent-browser batch --bail <<'JSON' # find's label ist groß-/kleinschreibungssensitiv: aus `snapshot -i` kopieren
[["open","http://127.0.0.1:8080/"],
["find","text","Start","click"],
["eval","if (!window.__controlsTest?.setTasten) throw Error('keine §5b-Sonde: setTasten hinzufügen')"],
["eval","__controlsTest.setTasten(['KeyW'])"],
["wait","600"],
["eval","if (__controlsTest.getGeschwindigkeit() <= 0.1) throw Error('W: keine Bewegung')"],
["eval","(async () => { const t = __controlsTest, y0 = t.getGier(); t.setTasten(['KeyW','KeyA']); await new Promise(r => setTimeout(r, 300)); t.setTasten(['KeyW']); const d = t.getGier() - y0, w = Math.atan2(Math.sin(d), Math.cos(d)); if (w < -0.05) throw Error('A dreht nach RECHTS — invertiert, bekam ' + w.toFixed(2)); if (w <= 0.05) throw Error('A dreht kaum (' + w.toFixed(2) + ') — länger halten oder prüfen, ob die Simulation läuft'); return 'A ok' })()"],
["eval","__controlsTest.setTasten([])"],
["screenshot","/workspace/screenshots/controls.png"],
["close"]]
JSON
Tasten durch die Sonde halten, nicht mit keydown – agent-browser keydown erreicht nicht §4's Set, also wird ein korrektes Spiel als defekt gelesen. Kein setTasten auf Ihrer Sonde? Fügen Sie es hinzu (§5b), oder senden Sie das Tastaturereignis selbst – die Browser-QA-Referenz Keys-Notiz hat den Mechanismus und das Formular.
Das Halten findet innerhalb eines eval statt: Über mehrere Befehle verteilt dauert es so lange, wie sie brauchen, und die ±π-Umschließung in Math.atan2(Math.sin(d), Math.cos(d)) liest ein Fahrzeug, das mehr als π gedreht hat, als eines, das in die andere Richtung dreht. Das IIFE ist das, was den Schritt wiederholbar macht – ein nacktes const d = … schlägt beim zweiten Mal mit „bereits deklariert" fehl – und async ist das, was das Halten in Seitenzeit laufen lässt. Wiederholen für D mit 'KeyD' und beiden Vergleichen gespiegelt (w > 0.05 ist invertiert, w >= -0.05 ist kaum), in einfachen Anführungszeichen, damit das JSON keine Escape-Zeichen benötigt; für Flugzeuge Rollen bestätigen: A ⇒ Linksneigung.
A dreht nach RECHTS ist der Vorzeichenfehler: ein Vorzeichen umdrehen und erneut ausführen.
A dreht kaum ist es nicht – das Fahrzeug bewegte sich in die richtige Richtung, nur weniger als 0,05 rad in 300 ms, was ein Boot oder ein schwerer Rover tun wird; das Halten verlängern oder prüfen, ob die Simulation läuft, und nichts umdrehen. Jeder andere Exit-Code ungleich Null – keine Sonde, ein festgefahrener Daemon – bedeutet, dass die Prüfung nie lief: zuerst die Nachricht lesen. Lesen Sie die Browser-QA-Referenzlinks in AGENTS.md vor Ihrem ersten Durchlauf – dort finden Sie Verben, Argumentformen und den Fallback.
5d. Was nicht zu tun ist
- Nicht nur testen, ob „D eine interne Variable erhöht".
- Nicht FPS „D → +X bei Blickrichtung −Z" als Fahrzeug-Durchgangskriterium verwenden.
- Nicht Mesh-Neigung, Kamera und Lenkung alle gleichzeitig umdrehen, wenn Sie etwas korrigieren – ein Vorzeichen ändern, erneut testen.
6. Fertigstellungskriterien (Steuerung)
- Diese Skill vor dem Schreiben von Bewegungs-/Lenkungs-/Flug-Code geöffnet.
- Genre-Zuordnung gewählt (§2) und Startbildschirm-/HUD-Beschriftungen stimmen damit überein.
- Verfolgungskamera A/D-Spieler-sichtbarer Test bestanden (§5a).
-
window.__controlsTest(oder Äquivalent) in Dev/QA verfügbar und einmal verwendet. - Kein invertiertes Neigungs-Mesh relativ zum Roll-/Lenkungs-Eingabe.
- Tasten werden im gehaltenen Zustand + dt-skaliert verarbeitet; kein klebriger Schub von einem einzelnen Leertasten-Druck, es sei denn, dies ist beabsichtigt und beschriftet.
Wenn irgendein Kästchen nicht angekreuzt ist, ist das Spiel nicht fertig.