adaengine/ada/ada-game-builder

Ada Game Builder

Turn the user's request into a playable game using the current Ada project, supported engine APIs, and Studio's authoring tools. Keep the scope requested by the user. For an existing game, extend its design and conventions; do not replace it with a new template. For a whole game from a brief, an autonomous run, or a request for a design document and plans, load ada-autonomous-studio first; it wraps this workflow with a design document, acceptance criteria and an iterate-until-accepted loop.

Before writing code, look for a working reference instead of searching engine sources: editor.examples.list with genre words ("3D game", "side scroller", "flappy", "runner") and editor.docs.search for "AdaScript gameplay recipes" (input, movement, spawning and despawning, collisions, score, restart, AudioSource). The example side-scroller-3d is a complete multi-file 3D game. Lay code out as ada-coding requires (one responsibility per file, layers, constants in Config); never put a whole game in one file.

Recover the project and choose the next slice

• Start with editor.project.context. Inspect the declared source/assets roots, build system, runtime entry, plugins, input actions, destination and available tools. Read existing project instructions and design/progress notes when present.
• Load ada-project-orientation and only the relevant companion workflows using editor.skills.read. Use editor.docs.search/read, editor.api.describe, editor.components.describe and editor.examples.list/read for current APIs, serialization and working examples. Never translate Unity, Godot or browser-engine API names into guessed AdaEngine calls.
• For a new game, establish the player's goal, repeated action/challenge/reward loop, controls, camera, failure or completion condition, and restart behavior. Infer reasonable defaults from a clear brief and state them briefly. Ask only about missing choices that materially change the result. A request for brainstorming or a plan stays in that mode.
• Choose a small complete playable slice. For a prototype, connect input, movement, challenge, feedback, outcome and restart before adding content or polish. For a feature or bug, define the observable behavior and exercise the affected path without restarting the whole design process.
• Keep useful continuation notes in the project's existing format for work spanning sessions: implemented behavior, paths, validation, unresolved issues and next step. Scale documentation to the task; do not make new planning documents or repeated confirmations prerequisites for an already authorized implementation.

Build through Studio

• Preserve the project's language and build system. AdaScript uses the embedded compiler and runtime; Swift projects require a host/distribution with SwiftPM support. Use ada-coding and ada-gravity-lsp when applicable. User-facing language terminology is AdaScript.
• Check that the current host can create or open the required project before scaffolding. If a project is missing, use the available Studio project workflow or explain the exact setup needed. Do not silently switch to Phaser, Three.js or another engine.
• Keep authored entities, hierarchy, components, scripts, input actions and resources persistent. Desktop open-scene edits use editor.scene.get/apply with the latest revision and preserve undo; load ada-scene-authoring. A component replacement is a complete payload: retain fields not being changed. On a host without structured scene editing, use supported project file tools, preserve schema and unknown fields, and validate the result.
• Verify script attachment and runtime entry, required plugins, input-action mapping, resource references and gameplay collision shapes. A source file or imported model alone does not connect the gameplay path. Use validated project configuration tools when advertised.
• Keep the scene readable: create named parent groups for related gameplay objects, architecture/collision, lighting and effects; use parent/child transform inheritance deliberately. Load ada-scene-authoring for grouping and reparenting, retain world placement, and avoid leaving generated content as a long flat list.
• For 2D work, reuse native sprites, atlases, tile sources and tile maps. Inspect their schemas and existing project resources before writing. Check camera framing, draw order, anchors, collision geometry and scene scale in Play.
• For 3D work, load ada-3d-assets, ada-3d-materials or ada-3d-animation as needed. Start from the basic-3d-scene example for a bare scene, or from side-scroller-3d for a playable 3D loop with its scene, HUD, sounds and tests. Inspect model bounds, dependencies and clip names; place portable resource references, frame the camera, light the scene and author colliders separately. Studio's model tools do not provide rig or skeletal-keyframe authoring.
• Author HUD, menus and restart controls through the project's existing AdaUI or .ui Designer workflow. Inspect current bindings and script exports. AdaScript @view is unavailable; use the supported UI resource path rather than inventing a scripting UI API.

Make the loop readable and responsive

• Show the objective and controls where the player needs them. Keep score, health, timer or progress legible and outside important play areas. Give clear success/failure feedback and make restart reset gameplay state, timers, spawned objects and input.
• Tune movement, collision response, camera and difficulty with the actual game running. Add feedback such as animation, particles, sound or hit reactions where it improves the requested experience; verify that the host and APIs support it.
• For touch destinations, share gameplay actions with desktop bindings and provide visible movement/action controls. Handle simultaneous movement and actions, release/cancel, safe areas and readable targets. Keyboard simulation cannot verify touch input.
• Reuse existing assets first. When creating or importing resources, load ada-assets or the relevant 3D workflow, validate them, connect their resource references, and check them in Play. Preserve source/license attribution for external assets. Use only generation providers actually configured on the host; unavailable generation should not prevent a prototype using suitable placeholders. Do not defer art and sound to the end: generate a minimal set (a few shapes, 3-6 sounds) as soon as the core loop runs, and wire sounds with AudioSource. Studio creates assets from scripts without a provider: ada-pixel-art (sprites, tile sheets), ada-sound-design (sound effects, played by AudioSource), ada-procedural-models and ada-voxel-models (3D).

Close the verification loop

Choose tools advertised by the current host; desktop and mobile tool names and capabilities differ.

1. Save through the supported document workflow. Run the narrowest diagnostics, asset/scene validation and build for the changed path. Desktop uses editor.build.start, editor.task.status and editor.output.read; mobile uses editor.build and editor.output.read. Load ada-build-run for the host's build/run flow. Read errors before repairing and revalidate after a fix.
2. Exercise gameplay logic where simulation is available. Desktop: editor.play.run_scenario replays timed key/mouse input against the project and returns frames, entity/component snapshots and script logs; plan the checks as scenario steps (fall under gravity, input response, scoring, failure, restart). Mobile editor.runtime.start/step/inspect/stop verifies movement and state transitions with held-key sets; send an empty set to release input. Restart the simulation after edits. Make values you must verify observable (an @export field of a scriptable object on a named entity; statics and System.print are not readable by tools). Check the changed behavior, boundaries, outcome and restart. For gameplay rules, write @test functions (load ada-build-run) and run them with editor.test.start; a green run with a failing-then-fixed test is the evidence for logic, not for rendering or feel. Run existing focused tests where supported; AdaScript-only projects do not have a SwiftPM test path.
3. Look at the game and load ada-visual-verification. Desktop: editor.play.start then editor.play.capture (or render.capture_screenshot while Play runs); both return the running game camera's completed frame, not the editor window. Mobile uses editor.play.start, editor.play.inspect, editor.play.capture and editor.image.read. Inspect the image; compare frames at different times for animation, and exercise the actual controls with a scenario when tools permit.
4. Keep compilation, simulation, rendered appearance, touch interaction and audio/network evidence separate. A frame you did not look at, an editor-window screenshot or a build success is not gameplay evidence. If a verification path is unavailable (no tool, no GPU/display, Play shows no frames, foreground access or a required provider is unavailable, input automation refused), do not stall or claim success: mark that exact check manual, state what to look at and how to trigger it, and continue with the remaining slices. Headless simulation and CPU model import do not prove GPU rendering or gameplay feel.

Finish with the playable behavior delivered, the controls, exact validation performed and any remaining limitation. Keep repair work within the host's configured budgets. Publishing, purchases or external account actions require authorization for that action and are not implied by a request to build a game.