Spottedcat

Lightweight cross-platform 2D/3D game engine for Rust.

Spottedcat is small, fast, and a little wild—named after the rusty-spotted cat and built for desktop, Web/WASM, iOS, Android, and AI-assisted game creation.

The Example Checks workflow compiles the desktop examples in scripts/check_examples.sh, including the default, utils, model-3d, effects, and gltf feature combinations.

Why Spottedcat?

• Small core API: build around Spot, Context, Image, Text, Model, and run.
• 2D and 3D: draw images, text, custom shaders, primitives, GLTF models, billboards, instanced models, and foggy 3D scenes.
• Cross-platform: target desktop, Web/WASM, iOS, and Android from one Rust codebase.
• AI-friendly: stable lifecycle, focused examples, and a dedicated guide make it easier for AI tools to generate runnable game prototypes.
• Practical by default: start with zero default features for lean 2D apps; enable 3D, effects, GLTF, image helpers, or sensors only when needed.

Links

• Documentation: rustyspottedcat.dev
• API reference: docs.rs/spottedcat
• Crate: crates.io/crates/spottedcat
• AI generation guide: AI_GAME_GENERATION_GUIDE.md

Install

Minimal 2D core:

[dependencies]
spottedcat = "1.0.2"

Common feature set for richer projects:

[dependencies]
spottedcat = { version = "1.0.2", features = ["model-3d", "utils", "gltf", "effects", "sensors"] }

Feature guide:

Minimal app

Spottedcat apps are ordinary Rust types that implement Spot:

use spottedcat::{Context, DrawOption, Image, Pt, Spot, WindowConfig, run};
use std::time::Duration;

struct Game {
    player: Image,
}

impl Spot for Game {
    fn initialize(ctx: &mut Context) -> Self {
        let rgba = vec![255; 32 * 32 * 4];
        let player = Image::new(ctx, Pt::from(32.0), Pt::from(32.0), &rgba)
            .expect("create player image");

        Self { player }
    }

    fn update(&mut self, _ctx: &mut Context, _dt: Duration) {
        // Move your world forward here.
    }

    fn draw(&mut self, ctx: &mut Context, screen: Image) {
        let (w, h) = spottedcat::window_size(ctx);
        screen.draw(
            ctx,
            &self.player,
            DrawOption::default().with_position([w / 2.0, h / 2.0]),
        );
    }

    fn remove(&mut self, _ctx: &mut Context) {}
}

fn main() {
    run::<Game>(WindowConfig {
        title: "Spottedcat".to_string(),
        ..Default::default()
    });
}

Run an example:

cargo run --example input_example
cargo run --example fog_world --features model-3d,effects
cargo run --example gltf_loader --features gltf

AI-assisted creation

Spottedcat is intentionally easy for AI coding tools to read and extend:

• the game loop is explicit: initialize, update, draw, remove
• examples are small enough to use as generation anchors
• the 1.0 API gives AI tools a stable surface to target

If you use Codex or another AI coding tool, a good prompt shape is:

Use Spottedcat 1.0 to make a tiny playable 2D dodge game.
Start from one Spot scene, read keyboard input, draw simple images,
show score text, and keep the code close to the existing examples.

See AI_GAME_GENERATION_GUIDE.md for LLM-oriented API guidance.

Install the Codex skill in a game project

Install the Spot CLI once:

cargo install spottedcat

Then run this command from the root of any game project that uses Spottedcat:

spot install-skill

It installs spot-game-builder into the current project's .agents/skills/spot-game-builder directory. To target another project, run:

spot install-skill --project /path/to/your-game

Examples

Useful starting points:

For a guided mini-game, see the Flappy Cat guide on rustyspottedcat.dev.

Core concepts

Spot

Spot is the application or scene lifecycle:

• initialize loads assets and creates state.
• update runs fixed-step gameplay logic.
• draw renders the current frame.
• resumed and suspended handle platform lifecycle when needed.
• remove cleans up scene-specific state.

Keep gameplay mutation in update and rendering in draw. Use interpolation when fixed updates and display refresh do not line up.

Rendering

• Image handles 2D textures, render targets, sub-images, layers, transforms, clipping, and custom 2D shaders.
• Text handles font-backed text rendering, wrapping, color, and stroke.
• Model handles 3D primitives, GLTF content, billboards, instancing, lighting, fog, and custom model shaders when model-3d is enabled.

Platform support

Declared support:

• Desktop: Windows, macOS, Linux
• Web: WASM builds
• iOS: UIKit integration and native sensor access
• Android: Android GameActivity integration and native sensor access

Generated platform outputs such as target/, .gradle/, pkg/, .xcframework/, and IDE caches are intentionally excluded from version control.

Stability

Spottedcat 1.0 treats the main user-facing surfaces as stable:

• Context
• Spot
• Image
• Text
• Model
• WindowConfig
• run

Minor and patch releases should preserve public API compatibility wherever possible. Pin an exact crate version if you need fully reproducible builds.

Name

The name comes from the rusty-spotted cat (Prionailurus rubiginosus): tiny, quick, and a little wild. It also nods to Rust, the language behind the engine.

License

Licensed under either of:

• Apache License, Version 2.0
• MIT License

at your option.