spot-game-builder

name

spot-game-builder

description

Plan and implement games quickly with the spottedcat (`spot`) Rust engine. Use when Codex needs to turn a game idea into working code in a repo that uses `spottedcat`, especially for scaffolding a new `Spot` scene, choosing 2D vs 3D engine features, mapping gameplay into `Context`/`Spot`/draw calls, reusing the repo's examples, wiring input, text, audio, fog, models, or preparing desktop, WASM, Android, or iOS game builds. Also use when the request is phrased in Chinese, such as “用 spot 快速做游戏”, “帮我用 spottedcat 做一个小游戏”, “把这个玩法实现成 Spot 场景”, “基于这个仓库做游戏原型”, or in English, such as “build a game with spottedcat”, “prototype a game in spot”, “turn this game idea into a Spot scene”, “add gameplay/HUD/audio to this spottedcat project”, or “use the repo examples to make a playable demo”.

Spot Game Builder

Overview

Use this skill to move from a game idea to a playable spottedcat prototype with as little ceremony as possible. Favor a small vertical slice first, reuse existing engine examples aggressively, and keep the implementation aligned with the engine's stable surfaces: Context, Spot, Image, Model, Text, and run.

Workflow

1. Confirm the engine root and existing baseline

Look for:

• Cargo.toml with package name spottedcat
• README.md
• AI_GAME_GENERATION_GUIDE.md
• examples/

If those files exist, treat that repo as the primary engine source of truth. Read AI_GAME_GENERATION_GUIDE.md first for architecture and lifecycle expectations. Read references/repo-map.md when you need example selection, feature flags, or build commands.

2. Turn the request into a tiny playable slice

Before writing code, reduce the request into:

• player fantasy: what the player does repeatedly
• camera/render mode: 2D, 3D, or mixed UI + 3D
• inputs: keyboard, mouse, touch, sensors
• renderables: image, text, model, instancing, fog, shader
• win loop: survive, dodge, collect, score, explore

Start with the smallest playable version that proves the loop. Examples:

• "做一个俯视角射击原型" -> move, aim, spawn bullets, one enemy type, score text
• "做一个 3D 雾气场景漫游" -> camera, environment models, movement, fog tuning, FPS overlay
• "做一个手机计步小游戏" -> sensor input, simple HUD, daily step readout, one interaction loop

Avoid building menus, save systems, and content pipelines before the core loop feels real.

3. Choose the engine path

Use this decision rule:

• Choose pure 2D when the game can be expressed with Image, Text, DrawOption, and screen-space coordinates.
• Choose 3D when the request needs Model, camera placement, lighting, fog, billboards, or instancing.
• Choose mixed 2D + 3D when the world is 3D but HUD or overlays should remain 2D text/images.

Choose features conservatively:

• no extra features for minimal 2D
• model-3d for procedural 3D primitives and model drawing
• effects when using fog or effect helpers
• utils when loading PNGs and similar helper-driven assets
• gltf when loading glTF models
• sensors for motion or step APIs on supported platforms

4. Reuse the nearest example instead of inventing structure

Pick the closest baseline from the repo and adapt it:

• examples/input_example.rs for movement, input polling, and text HUD
• examples/audio_test.rs for quick sound verification
• examples/fog_world.rs for 3D scene setup, camera, fog, and overlay text
• examples/instancing_test.rs for many repeated 3D objects
• examples/gltf_loader.rs for asset-loaded 3D content
• examples/wasm/ or mobile wrappers when the target is browser or device-specific

Do not rewrite engine conventions from scratch when an example already demonstrates the needed pattern.

5. Implement around Spot

Structure game code around one Spot implementation per scene or prototype state.

Typical shape:

1. initialize Load or register assets, set camera/light/fog defaults, and create the initial state.
2. update Read input and advance simulation. This runs at a fixed frequency (usually 60Hz), so dt is constant. All physics/logic should be here.
3. draw Issue draw calls for the frame. This runs at the display refresh rate (variable). Use ctx.draw_interpolation() or Interpolated<T> for smooth movement. Keep gameplay mutation out of rendering unless the pattern is trivial and already established in the repo.
4. resumed / suspended Use when platform lifecycle matters, especially on mobile.
5. remove Clean up scene-specific state and clear temporary global scene configuration like fog when needed.

Honor these rules:

• Always use the lifecycle ctx that the engine provides.
• Multiply motion and time-based effects by delta time.
• Treat 2D origin as top-left.
• Use Pt for logical 2D units and viewport-relative helpers when layout should scale.
• For encoded PNG/JPEG/WebP bytes, prefer spottedcat::utils::image::from_image(...) or from_rgba_image(...) when the utils feature is enabled. Those helpers keep source pixel dimensions and derive the default logical size from the current scale_factor.
• Keep the first implementation simple enough to run immediately.

6. Map common game needs to spottedcat

• sprite or HUD element -> Image::new plus target.draw(ctx, &image, opts)
• smooth movement -> use Interpolated<T> for positions/rotations and read via .value(ctx) in draw
• on-screen text -> register_font, Text::new, target.draw(ctx, &text, opts)
• player movement -> key_down, key_pressed, mouse_down, mouse_pos, touches
• simple sound feedback -> register_sound + play_sound, or play_sine for fast smoke tests
• 3D blockout -> model::create_cube, create_plane, create_sphere
• large repeated props -> model::draw_instanced
• scene transitions -> switch_scene or switch_scene_with
• shared state -> insert_resource and get_resource
• atmosphere -> set_fog, light helpers, camera helpers
• custom 2D effects -> ImageShaderTemplate plus bindings.with_history() / .with_screen() (Semantic Bindings)

7. Verify in the cheapest environment first

Prefer this validation order unless the request is platform-specific:

1. compile or run on desktop first
2. verify the closest example or new prototype locally
3. move to WASM or mobile only after the core loop behaves correctly

When debugging:

• start with cargo check
• then run the narrowest example or target
• separate engine misuse from game logic mistakes
• read existing examples before adding new abstractions

8. Escalate complexity only after the slice works

After the first playable slice works, then add:

• more scenes
• asset loading
• custom shaders
• better camera behavior
• platform packaging
• content polish

When the request is broad, prefer shipping a playable prototype plus a clear next-step list instead of an unfinished full game architecture.

Prompt Patterns

These are good triggers for this skill:

• "用 spot 快速做一个 2D 平台跳跃原型"
• "帮我在 spottedcat 里搭一个 3D 雾景漫游 demo"
• "把这个游戏想法映射成 Spot 场景和实现步骤"
• "基于这个 repo 的 examples 做一个可玩的小游戏"
• "帮我给这个 spottedcat 项目加输入、HUD 和音效"
• "Use spottedcat to build a small 2D platformer prototype"
• "Help me create a 3D foggy exploration demo in spot"
• "Turn this game idea into a Spot scene and implementation plan"
• "Use this repo's examples to build a playable mini-game"
• "Add input, HUD, and audio to this spottedcat game project"

Reference Use

Read references/repo-map.md when you need:

• the recommended example to start from
• Cargo.toml feature selection
• common local run commands
• a quick map of repo files that matter for game work