A compact, experimental, and probably mostly useless game engine that tries to answer the question: what if a game engine was 100% agentically engineered, and structured specifically so agents can help you build your game?

Scrapbot is maintained as an agent-first codebase. Before opening a PR, read CONTRIBUTING.md for contributor expectations and AGENTS.md for the rules coding agents must follow when changing this repository.

The high-level roadmap is below. Active follow-up work lives in docs/TODO.md, with architecture and feature decisions tracked in docs/adr/ and docs/fdr/. Project vocabulary lives in docs/GLOSSARY.md.

Scrapbot currently has a small Odin CLI and runtime skeleton:

• scrapbot init [path] [name] creates a text-first project with project.toml, scenes/main.scene.toml, scripts/main.luau, an assets/ directory, and Luau LSP metadata.
• scrapbot check [path] [--json] builds declared native extensions, validates the project manifest, default scene, and project Luau component schemas, refreshes generated Luau LSP types, and runs Luau static analysis when luau-analyze is available.
• scrapbot build [path] [--target host] [--json] creates a host-native runnable package under build/<target>, including the game executable, project data, and active native extension artifacts.
• scrapbot run [path] [--backend null|wgpu] [--window] [--editor] [--hot-reload] [--scheduler-trace] [--runtime-stats] [--frames n] [--framegrab out.png] [--framegrab-region x,y,width,height] [--json] builds declared native extensions, loads the scene into a tiny native ECS world, executes scripts/main.luau if present, runs registered native and script systems, and submits the world through the selected renderer backend. Ctrl+Esc toggles the editor shell in a visible window, and --editor starts it open. Scheduler tracing reports native worker utilization. Runtime statistics report early/late engine-frame cost through render preparation, engine-allocator bytes including post-teardown retention, and ECS storage high-water marks. Windowed runtime statistics require a bounded --frames value. Framegrab regions preserve 1:1 output pixels and use top-left coordinates.
• scrapbot help <command> prints command-specific options parsed by Odin's core:flags.

During development, use mise build to compile the CLI and mise scrapbot -- [args...] to compile and run it with arguments forwarded to Scrapbot.

This first slice intentionally uses a narrow schema-driven TOML reader instead of a complete TOML implementation. Rendering is pluggable at the runtime boundary. The null backend supports headless smoke tests, while the wgpu backend renders full indexed geometry with shared base-color and PNG-textured materials, ECS ambient/directional/point lights, backend-owned GPU caches, automatic instanced batching, live window resizing, and a retained ECS UI overlay with a box model, horizontal and vertical stacks, smooth clipped scroll areas, MTSDF text, pointer-aware buttons, and SDF-rounded backgrounds. An engine-owned editor shell can frame the live project viewport with top, status, scene, and inspector chrome, independently smoothed scroll panes, and an ECS-owned fly camera that navigates independently from the project's camera. Headless WGPU can write a final-frame PNG with --framegrab. Luau scripting is embedded from a pinned source dependency and exposes the ECS, full geometry/material resource creation, scheduled systems, deferred lifecycle commands, generated types, native extension integration, and hot reload.

Example projects live in examples/. The minimal example demonstrates Luau-defined and Odin-defined components and systems, and can be verified with mise scrapbot run examples/minimal. The ECS showcase runs a native object fountain with visible spawned cube renderables, velocity, lifetime, spin, despawn, animated point lights, editor-movable static point lights, and Luau typed queries.

Run the full local test suite with mise test; it includes a 2,000-frame lifecycle CPU/RAM growth gate. Use mise test-soak for the extended 10,000-frame check and mise test-sanitize for the Linux AddressSanitizer lane. Linux CI runs both the normal suite and AddressSanitizer.

• Runtime
  • Single-binary CLI
  • Cross-platform runtime
  • Interactive commands
  • Headless commands
• Projects
  • Text-first projects
  • TOML scene files
  • Project initialization
  • Project templates
  • Scene migrations
• Reloading
  • Live reload
  • Structured diagnostics
• Distribution
  • Host game builds
  • Package dependencies
  • Cross-platform exports
  • Console/mobile publishing

• World Model
  • Shared ECS runtime
  • Reflected components
  • Generation-aware entities
  • Component registry
  • Component lifecycles
  • ID-keyed custom component storage
  • Engine-owned frame time resource
  • World snapshots
• Scheduling
  • Scheduled systems
  • Access-controlled systems
  • Deferred mutations
  • Parallel native system scheduling
• Queries
  • Bulk Luau query views
  • Multi-component Luau queries
  • Typed three-component Luau queries
  • Advanced queries

• Luau
  • Luau scripting
  • Luau type definitions
  • Luau analyzer checks
  • Basic script components
  • Basic script systems
  • Script hot reload
  • Reflected script components
  • Scheduled script systems
  • Editor scripting
• Native
  • Native Odin modules
  • Native hot reload
  • Native ECS systems
  • Native extension examples
  • Static native packaging
• Developer Experience
  • Script/native diagnostics
  • Performance documentation

• Backend
  • WebGPU surface smoke
  • Headful rendering smoke
  • WebGPU triangle render loop
  • Headless WebGPU framegrab
  • WebGPU ECS cube renderer
  • Multi-entity WebGPU cube renderer
  • General indexed-geometry WebGPU renderer
  • Offscreen render comparison
• Scene Data
  • Basic cameras
  • Lighting
  • Generated cube, plane, icosphere, UV sphere, pyramid, and cylinder geometry
  • Shared base-color materials
  • ECS-owned editor scene camera and captured fly navigation
• Pipeline
  • Geometry/material render batching
  • Directional shadow maps with explicit caster/receiver components
  • HDR rendering
  • Postprocessing
  • Frustum culling
  • GPU-driven rendering
  • Ambient, directional, and point-light rendering
• Assets
  • Mesh assets
  • PNG texture assets
  • Material system
• Tooling
  • Resource hot reload
  • Render debug views

• Input
  • ECS platform input
  • Runtime input resources
  • UI pointer position and primary-button input
  • Controller input
• Retained UI
  • Retained UI primitives
  • Box-model layout with horizontal, vertical, and overlay composition
  • Element hover and active hit-testing state
  • UI command events
  • Smooth clipped vertical scroll areas
  • Canvas scaling
  • Built-in scalable UI text
  • MTSDF-based font rendering
  • UI gallery
• Controls
  • Text and pointer-styled button controls
  • Reusable editor controls
  • Form controls
  • Text input
  • Keyboard focus
  • Clipboard support
• Styling
  • Scene-defined UI API
  • Margins, padding, backgrounds, and rounded corners
  • UI themes

• Shell
  • Toggleable editor shell
  • Aspect-correct live game viewport
  • Resizable panels
  • Dockable editor workspace
• Inspection
  • System profiler
  • Entity browser
  • Entity selection
  • Read-only component field/value inspector
  • Component value editing
  • Searchable browser
  • Hierarchical browser
• Editing
  • Inspector editing
  • Inspector undo/redo
  • Component management
  • Entity management
  • Scene edit persistence
  • Multi-selection editing
  • Editor transactions
• Scene Tools
  • Playback controls
  • RMB-captured WASD/Space/Ctrl scene-camera navigation
  • World-space translation gizmo
  • Transform gizmo modes
  • Precise viewport entity picking
• Extensibility
  • Asset browser
  • Editor plugins

• Commands
  • Project validation
  • Deterministic stepping
  • Benchmark runner
  • JSON command output
• Verification
  • Gameplay test fixtures
  • Offscreen render verification
  • Editor screenshot tests
  • Native extension tests
• Project Support
  • Example projects
  • Documentation site
  • Agent workflow docs
  • CI workflow
  • Docs checks
  • Benchmark trend reporting

• Assets
  • Primitive geometry helpers
  • Embedded UI font
  • Asset references
  • Asset import pipeline
  • Asset browser
• Scene Composition
  • Prefabs
  • Scene instancing
• Simulation
  • Physics
  • Animation clips
  • Skeletal meshes
  • Animation state machines
• Runtime Systems
  • Audio resources
  • Runtime audio
  • Networking
  • Terrain streaming
  • Large-world streaming

Scrapbot is licensed under the Apache License 2.0. Third-party notices and vendored dependency license details are tracked in NOTICE.