Build a better game with the right AI prompts.

# Task: Build a secure remote automation and testing interface for my game

You are a senior game-engine architect, automation engineer, test-infrastructure engineer, and application security engineer.

Build a remote automation system that lets an external AI agent, test runner, CI job, or developer tool inspect and test the running game through a structured protocol. The goal is similar to browser remote automation, but the game must expose semantic game state and actions instead of forcing the tester to infer everything from pixels.

## Project context

- Game and engine: [GAME NAME AND THREE.JS / UNITY / GODOT / UNREAL / OTHER]
- Current repositories: [PATHS]
- Target test environments: [LOCAL / CI / QA DEVICE LAB / OTHER]
- Target platforms and input devices: [WEB / DESKTOP / IOS / ANDROID / KEYBOARD / GAMEPAD / TOUCH]
- Existing test framework and CI: [DESCRIBE OR UNKNOWN]
- Existing debug, console, accessibility, telemetry, or automation systems: [DESCRIBE OR NONE]

## Audit and design first

1. Inspect the architecture, scene/entity model, input layer, save system, networking, tests, CI, developer tools, and documentation before changing anything.
2. Reuse existing debug and testing abstractions where they are sound. Do not build a second competing game-state or input system.
3. Define an engine-independent versioned protocol with explicit capabilities and engine-specific adapters.
4. Prefer localhost HTTP and WebSocket transports by default. Explain when another transport is justified.
5. Produce a short threat model before implementation.

## Required automation contract

Create the equivalent of a game DOM and accessibility tree:

- Give every important scene, entity, component, interactable, UI control, quest, item, and test fixture a stable automation ID.
- Expose type, name, role, tags, visibility, enabled state, position, relevant components, supported actions, and safe inspectable properties.
- Add discovery for scenes, entities, UI, components, and protocol capabilities.
- Add observation APIs for screenshots, game state, entity state, logs, recent events, performance signals, and current available actions.
- Support semantic actions such as move, interact, select, equip, use, confirm, cancel, and choose dialogue where the game supports them.
- Support lower-level keyboard, mouse, gamepad, and trusted touch/pointer input for testing the real input path.
- Add deterministic waits, event subscriptions, assertions, checkpoints, reset, save/load fixtures, and recordings.
- Add a capabilities endpoint so one external client can adapt to different engines and builds.

Do not expose private player data, secrets, unrestricted memory, arbitrary file access, or implementation details that are unnecessary for testing.

## External client and CI

1. Create a typed external client or SDK for the protocol using the project's established language and package conventions.
2. Add a small CLI or test-runner integration that can launch or attach to a build, discover capabilities, perform actions, wait for state, assert results, collect logs, and save screenshots.
3. If useful to the existing workflow, add an MCP or agent adapter on top of the typed client instead of bypassing it.
4. Add one complete automated scenario that launches the game, reaches representative gameplay, performs semantic and raw-input actions, verifies authoritative state, captures a screenshot, and exits cleanly.
5. Integrate the scenario into CI without making ordinary production builds depend on the automation server.

## Security and lifecycle requirements

Create separate capability profiles:

- Development may allow controlled teleport, spawn, reset, fixture creation, console commands, and deep inspection.
- QA should allow inspection, input, screenshots, assertions, events, reset, and approved fixtures.
- Production should disable the server or expose only explicitly approved diagnostics and telemetry.

Require authentication and authorization whenever the interface is not strictly local. Bind to localhost by default, use short-lived credentials where remote device testing requires a connection, rate-limit commands, validate every payload, log automation sessions, and reject unsupported capabilities.

Never expose arbitrary remote console execution or unrestricted game-state mutation in a publicly accessible production build. Ensure disconnects, scene changes, test failures, and application shutdown clean up listeners, sockets, temporary state, input holds, and test fixtures.

## Verification

Add protocol, schema, authorization, lifecycle, engine-adapter, input, screenshot, event, assertion, and end-to-end tests. Verify stable IDs, deterministic waits, held-input release, malformed commands, unauthorized access, reconnects, scene transitions, and production gating.

Finish with the protocol schema, capability matrix, implemented scenario, CI commands, security decisions, known limitations, and instructions for adding automation support to a new entity, action, scene, or engine adapter.

## Internationalization and localization architecture

Build internationalization into the existing architecture before gameplay and UI content multiply. Do not create a separate localization application or bolt translation onto finished screens.

- Centralize player-facing text behind stable translation keys and locale resources. Do not hard-code display strings in gameplay, menus, tutorials, errors, notifications, subtitles, or content data.
- Define a fallback locale, missing-key behavior, resource ownership, extraction and validation commands, translator notes, and a safe process for adding or updating a language.
- Support Unicode, plural/select rules through an ICU-style message system or the engine's equivalent, locale-aware number/date/time/currency/unit formatting, and invariant internal IDs for saves, networking, analytics, achievements, and game rules.
- Plan for right-to-left layout and bidirectional text, CJK and other line-breaking rules, diacritics, input methods and IME where players type, font fallback and glyph coverage, translated text expansion, subtitles/captions, localized audio or asset variants where required, and runtime language selection with a persisted preference.
- Keep localization data separate from trusted game rules. Servers, SDKs, automation, and analytics should exchange stable language-independent identifiers while clients turn them into localized player-readable text.
- Add pseudolocalization, missing/unused-key validation, fallback-locale tests, long-string and text-expansion tests, right-to-left tests, font/glyph checks, and representative locale screenshots to the normal test and CI strategy.

Document the supported launch locales, later-locale workflow, ownership, file locations, naming rules, formatting rules, font and audio strategy, platform limitations, and exact commands another developer or translator uses.

## Player-readable output requirement

Everything shown to a player must be written and presented for a human player, not for a developer or debugger. This includes menus, HUD labels, buttons, prompts, tutorials, objectives, dialogue, tooltips, loading and save states, empty states, confirmations, warnings, errors, rewards, notifications, accessibility messages, and connection or recovery states.

Use concise plain language, the game's established terminology and tone, recognizable icons with text where meaning could be ambiguous, and a clear next action. A player-facing error should explain what happened in useful terms, whether progress is safe, and what the player can do next.

Never expose raw exceptions, stack traces, JSON, database IDs, internal event names, enum or variable names, file paths, debug coordinates, HTTP status codes without explanation, server implementation details, developer TODOs, placeholder text, or raw telemetry on a player-facing surface. Send technical details to development-only logs, diagnostics, telemetry, or an authenticated support view. A short support reference code may be shown to the player only when it helps support locate the private diagnostic record.

Verify representative success, failure, offline, loading, empty, permission, validation, timeout, save, reconnect, and recovery states from the player's perspective. Developer documentation and final engineering reports may remain technical; this requirement applies to anything the game presents to players.

## Required game documentation

Documentation is part of the definition of done for this task.

Before finishing:

1. Read the existing README, docs directory, architecture notes, decision records, and AI instructions that apply to this system.
2. Update the existing relevant documentation instead of creating a competing document or a second source of truth.
3. If no relevant document exists, create a clearly named Markdown document in the game's established documentation directory. Use docs/ when the project has no existing convention.
4. Document the current system, the decisions made, ownership and lifecycle rules, configuration, files or assets changed, commands and tests run, known limitations, and how another developer should extend or troubleshoot the work.
5. Update AI_INSTRUCTIONS.md or the project's equivalent when this task changes architectural boundaries, required workflows, naming rules, or validation commands.
6. Keep documentation accurate to the implementation. Do not claim support, measurements, or test coverage that was not verified.
7. In the final report, list every documentation file created or updated.