Scrapbot Engine

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?

Warning

Do not expect this engine to be useful. In particular, do not try to make a game with it! It's a research project with no aims to be production-ready, stable, or even particularly usable. It is a playground for exploring agentic workflows and game engine design and not much else. You have been warned. (We still love you though!)

Contributing

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.

The documentation website includes a conceptual ECS overview plus exact references for engine components, Luau, native extensions, project files, and ECS UI.

What's Inside

Scrapbot is a small Odin CLI and runtime with an embedded Luau scripting layer, a native ECS, a GPU-driven WebGPU renderer, and a first-party editor — all operable through structured CLI output, so agents (and scripts) can build, run, inspect, and screenshot projects without a human at the keyboard.

CLI

• scrapbot init [path] [name] safely creates a runnable text-first project without overwriting existing files. Authored data lives in assets/, native/, resources/, scenes/, and scripts/; generated types and caches live under ignored .scrapbot/ state; distributable packages live under build/.
• scrapbot check [path] [--json] builds declared native extensions, validates the manifest, default scene, and 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> with the game executable, project data, and native extension artifacts.
• scrapbot run [path] [options] loads the scene into a native ECS world, executes scripts/main.luau, runs native and script systems, and renders through the selected backend. Ordinary development is simply scrapbot run <path> (windowed WGPU with hot reload). Options include --backend null|wgpu, --window|--headless, --hot-reload|--no-hot-reload, --editor, --frames n, --framegrab out.png, --scheduler-trace, --runtime-stats, --ui-script, --ui-dump, and --cpu-culling (deterministic CPU reference path for GPU culling).
• scrapbot help <command> prints command-specific options parsed by Odin's core:flags.
• Every command emits structured --json output with stable diagnostic codes — the automation contract for agents. Headless WGPU runs create a device and offscreen target without SDL or an OS presentation surface, can execute without a pixel readback, and optionally support final-frame PNG framegrabs and semantic UI scripting. --ui-script targets reconciled controls by UUID, name, or text, replays interactions, and asserts state; --ui-dump exposes the full logical and screen-space UI tree as JSON.

During development, use mise build to compile the optimized CLI and mise scrapbot -- [args...] to compile and run it. Mise reuses bin/scrapbot while its sources and linked Luau archives are unchanged; use mise run --force build to rebuild explicitly. mise build-dev applies the same incremental behavior to its fast -o:minimal binary, and mise benchmark-profiles compares both build profiles on a bounded run. Run mise setup once after cloning to install pinned tools and the host wgpu-native library, initialize source dependencies, download checksum-verified external fixtures, and configure the tracked Git hooks (mise setup-assets / mise check-assets manage only the fixtures). Builds also prepare the pinned WGPU library on demand, so a fresh Odin toolchain does not require a separate manual download.

ECS and Scripting

• Reflected components with stable project-wide entity UUIDs (distinct from editable names), generation-aware handles, and component lifecycle hooks.
• Scheduled, access-declared native systems running in parallel, with deferred mutations and SIMD-accelerated chunked queries.
• Luau scripting with typed queries, scheduled systems, deferred lifecycle commands, generated type declarations, analyzer checks, and hot reload. mise luau-workspace-types rebuilds the tracked type aggregate for editor completion.
• Native Odin extensions through a small C ABI, also hot-reloadable.
• Derived state is change-driven: UI, render-instance, camera, and light membership update from structural dirty queues and compact active sets instead of per-frame world scans.

Rendering

• Pluggable backends: a deterministic null backend for simulation smoke tests, and a full wgpu backend with independent surface and offscreen execution.
• GPU-driven submission: persistent slot-addressed instances, dirty-only transform uploads, a growing retained draw database, compute camera/shadow culling, adaptive Hi-Z occlusion, screen-radius object LODs, indirect draws, and asynchronous GPU timing readback.
• Crack-aware virtual Geometry: projected error selects resident detail. Adjacent levels overlap through a narrow error band, and streamed refinements join through a bounded 16-frame world/depth handoff. Complete opaque surfaces remain depth-testable; TAA marks the handoff as reactive.
• Bounded virtual-Geometry streaming: coarse pages stay pinned while demand and future-camera prefetch stream finer groups atomically. Native multi-draw retains per-cluster commands; portable adapters compact selected clusters into shared record streams. A pinned coarse indexed proxy keeps world, depth, and shadows drawable when detailed visibility is unavailable.
• Compact imported Geometry: runtime catalogs retain a position-only CPU query proxy instead of complete render vertices and source indices. Exact leaf topology is reconstructed from pages only while establishing a compatibility GPU cache.
• Shared WGPU vertex/index arenas suballocate every Geometry and generated LOD version. Arena-global indirect offsets let compatible same-material commands share fixed multi-draw submissions while structured diagnostics distinguish logical batches from encoded spans and report residency/mutation counters.
• Imported glTF primitives generate deterministic, compact meshoptimizer LOD chains in versioned asset products by default. Projects can tune triangle ratios and screen thresholds or disable generation; runtime selection uses the same generic Geometry contract as procedural and future project-authored levels.
• HDR lighting and post: shared metallic-roughness GGX materials with mipmapped PBR maps, ambient/directional/point lights, GPU-clustered point lighting, four stabilized shadow cascades, imported image-based lighting with independent diffuse/specular strength or roughness-aware analytic environment lighting from a procedural haze sky via one scrapbot.world_environment component, authored global height/distance fog with shadowed directional scattering, half-resolution thickness-aware visibility-bitmask ambient occlusion over indirect diffuse light, temporal antialiasing with reprojection, screen-space reflections, a compute bloom pyramid, composable vignette, ghost-lens-flare, and procedural lens-dirt components, and one ACES-style composite.
• Per-camera render policy: a bounded manual world-resolution scale, optional GPU-budgeted adaptive world/shadow/post quality, TAA, fast AA, AO, SSR, and bloom are authored on scrapbot.camera; UI stays native-resolution, AO and SSR have bounded quality tiers, and disabled effects skip their GPU work.
• UUID-backed resources in resources/**/*.resource.toml (materials, textures, glTF models, HDR environments, SVG icon sets, generated LOD chains, and composition-time UI themes) with hot reload, targeted reimport where applicable, and import diagnostics; scenes serialize stable UUID references that the runtime resolves to generational registry handles.
• Every registered geometry owns deterministic meshoptimizer-built meshlets with bounded local vertex/triangle streams, conservative sphere bounds, and normal cones. Capable WGPU adapters cull clusters for reused batches and mix their indirect counts with whole-primitive draws across world, depth, and shadow submission. Meshlet debug views force cluster submission; unsupported adapters and --cpu-culling retain whole-primitive indexed draws.
• Camera debug views expose material inputs, meshlet identity, selected LOD, GPU visibility decisions, false-color inspection of every retained Hi-Z pyramid mip, and freezeable screen-space Hi-Z query footprints through the same project/editor contract.

Retained UI

• ECS-first retained UI: authored fit/fill/expand/stretch/pixel-perfect canvases, safe areas, per-axis alignment, intrinsic multiline text, grow/shrink/wrapping stacks, overlays, draggable separators, cross-stack and dock-tab panel transfers, transferable tabbed sheet groups with configurable pane surfaces and opt-in edge-created resizable splits, hidden subtrees, smooth clipped scroll areas, selectable lists, progress indicators, collapsible panels, equal/proportional tables, buttons, checkboxes, numeric controls, and keyboard-focused text inputs with Tab traversal.
• MTSDF text with auto-atlased project fonts (embedded Inter fallback), UUID-backed project SVG icon catalogs plus an embedded control catalog, and SDF-rounded styling for backgrounds, borders, and controls.
• One public component contract: scene TOML, Luau systems, native Odin extensions, and the editor all construct and mutate the same typed UI values; reusable semantic actions publish ordered immutable events to independent project/editor readers.
• Revision-driven paint with independent project, editor, and world-overlay GPU streams — unchanged domains skip reconciliation, layout, paint, and uploads entirely.

Editor

• Toggleable ECS-built shell (Cmd/Ctrl+E, or --editor to start open) whose Browse, Game, and Inspect tabs each host a public panel stack around an aspect-correct live viewport, resizable tools, status bar, and scroll panes.
• Entity browser, expandable UUID-backed hierarchy with drag-to-reparent, and runtime type-inspected component panels — no per-component UI code, everything derives from the component registry.
• Play/Pause/Step (Cmd/Ctrl+R, Cmd/Ctrl+T) with a non-destructive in-memory authoring baseline, stopped-mode Undo/Redo, explicit project-wide Save, and scene Revert.
• RMB-captured WASD fly camera, precise entity picking, and translation/rotation/scale gizmos with plane and center handles.
• System profiler publishing engine, project-Odin, Luau, and CPU render-phase timings from a rolling window.
• Bounded headless render profiler with exact frame-correlated GPU pass timestamps, active-CPU timing, per-frame upload/rebuild counters, resolution metadata, and optional lossless replay captures.

Examples

Example projects live in examples/:

• minimal — Luau- and Odin-defined components and systems (mise scrapbot run examples/minimal).
• ecs-showcase — object fountain with spawned renderables, animated point lights, emissive bloom, and a procedural 30-second day/night cycle.
• ecs-stress — roughly 3,000 glowing renderables sustained through retained query plans, chunked storage, and SIMD integration.
• clustered-lights — 320 animated HDR point lights through GPU-computed view-frustum clusters in a bloom-soaked tunnel.
• gltf-showcase — the pinned Khronos Damaged Helmet through the real glTF importer, lit by a pinned CC0 HDR environment.
• pbr-materials — deterministic authored metallic/roughness reference grid for isolating material and lighting changes.
• sponza — the Khronos Sponza atrium as 103 ECS renderables with 25 PBR materials, directional shadows, and clustered point lights.
• impossible-archive — a deterministically generated carved megastructure for virtual-geometry residency, predictive streaming, and cluster-frontier debug views.
• virtual-wilds — five full-detail CC0 scans and 460 public-API scatter renderables arranged as a moving coastal route, with 3.14 million source triangles competing for a 192 MiB virtual-geometry residency budget.

Testing

Run the full local suite with mise test (includes a 2,000-frame lifecycle CPU/RAM growth gate). mise test-soak runs the extended 10,000-frame check; mise test-sanitize runs the Linux AddressSanitizer lane. CI covers macOS, Linux, and Windows, plus the ASan lane on Linux.

mise test-gpu-offscreen runs the bounded surface-free WGPU acceptance gate. It preserves structured diagnostics, GPU timings/counters, and 1:1 PNGs under $TMPDIR/scrapbot-gpu-offscreen by default. Metal CI uploads the complete bundle even when the gate fails.

mise gpu-benchmarks profiles minimal, ecs-showcase, and sponza at 540p, 720p, and 1080p. The scheduled/manual Metal workflow retains each bundle and compares it with the previous successful run only when the adapter and complete render dimensions match. These histories expose trends; they are not portable performance thresholds.

Features / Roadmap

Engine Core

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

ECS Runtime

• World Model
  • Shared ECS runtime
  • Reflected components
  • Stable project-wide entity UUIDs
  • Generation-aware entities
  • Component registry
  • Component lifecycles
  • ID-keyed custom component storage
  • Engine-owned frame time resource
  • Incremental render and retained-UI membership reconciliation
  • Revision-driven retained UI paint and independent GPU streams
  • 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

Scripting And Native Extensions

• 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
  • Chunked native queries with portable SIMD helpers
  • Native extension examples
  • Static native packaging
• Developer Experience
  • Script/native diagnostics
  • Performance documentation

Rendering

• 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 metallic-roughness materials with mipmapped PBR texture channels
  • ECS-owned editor scene camera and captured fly navigation
• Pipeline
  • Geometry/material render batching
  • Four stabilized directional-shadow cascades with explicit caster/receiver components
  • HDR rendering
  • Imported image-based lighting with opt-in independently configured HDR backgrounds and per-camera exposure
  • Authored ECS world environments with a renderer-native procedural haze sky
  • Depth-aware temporal antialiasing, thickness-aware visibility-bitmask ambient occlusion, material-aware screen-space reflections, multi-scale bloom, and tone-mapping postprocessing
  • Compute camera and shadow frustum culling
  • GPU-computed clustered point lighting
  • Persistent GPU instances, visibility compaction, and indexed indirect drawing
  • Compact dirty-transform uploads with GPU matrix and bounds expansion
  • Dynamically growing retained draw database
  • Dirty-only retained render extraction and incremental existing-batch membership
  • Depth prepass and adaptive Hi-Z occlusion culling
  • GPU screen-radius LOD selection
  • Feature-gated GPU meshlet culling with native multi-draw and portable GPU-compacted submission
  • Camera and transient editor Game-view diagnostics for base color, normals, roughness, metallic, depth, and meshlets
  • Asynchronous per-pass GPU timestamps and visibility/LOD counters
  • Ambient, directional, and point-light rendering
• Assets
  • Common versioned runtime-product envelopes with validated typed chunk directories
  • Incremental static glTF 2.0/GLB model imports with embedded, data-URI, and external metallic-roughness PBR images
  • glTF opaque/cutout alpha materials and double-sided rendering across color, depth, and shadows
  • Selected-scene glTF closure imports with semantic reimport identity and authored texture samplers
  • PNG texture assets
  • UUID-backed texture and model resources
  • UUID-backed Radiance HDR environments with source-resolution skies and high-quality importer-built diffuse/specular cubes
  • Targeted live Reimport, import diagnostics, texture thumbnails, and stale model-product retirement
  • UUID-backed material resources
  • UUID-backed generated geometry LOD resources
  • Resource-owned meshlet clustering and bounds for every geometry
  • Compiled UUID-backed SVG icon-set resources and embedded control catalog
• Tooling
  • Resource hot reload
  • GPU-selected LOD heatmap and object/meshlet visibility-classification overlays
  • Hi-Z pyramid and mip inspection
  • Freezeable GPU-native Hi-Z occlusion-query inspection

Input And UI

• Input
  • ECS keyboard and pointer input singletons
  • Luau/native runtime input snapshots with held and edge state
  • UI pointer position and primary-button input
  • Controller input
• Retained UI
  • Retained UI primitives
  • Box-model layout with horizontal, vertical, and overlay composition
  • Intrinsic multiline text measurement and deterministic word wrapping
  • Per-child basis/grow/shrink sizing and wrapping stack flow
  • Element hover and active hit-testing state
  • Ordered immutable UI command events with inheritable semantic actions
  • Smooth clipped vertical scroll areas
  • Collapsible titled panels
  • Equal or proportional tables with draggable column separators
  • Selectable lists and progress indicators
  • Responsive canvas scaling, safe areas, and per-axis alignment
  • Built-in scalable UI text
  • MTSDF-based font rendering
  • Auto-atlased project TTF/OTF fonts with embedded Inter fallback
  • Standalone and icon-bearing controls backed by compiled MTSDF icon sets
  • UI gallery
  • Semantic headless UI replay, assertions, tree dumps, and target framegrabs
• Controls
  • Text and pointer-styled button controls
  • Reusable SDF checkbox controls
  • Reusable numeric editor controls with validation, stepping, and opt-in scrubbing
  • Additional form controls
  • Single-line text input with cursor movement and selection
  • Keyboard focus with Tab and Shift+Tab traversal
  • Clipboard support
• Styling
  • Scene-defined UI API
  • Margins, padding, hidden subtrees, backgrounds, rounded corners, and borders
  • Explicit composition-time theme recipes resolving to ordinary component values
  • Project-facing theme-recipe helpers for Luau, native Odin, and text-first authoring
  • UUID-backed project themes with HDR semantic palettes, metrics, and typography

Editor

• Shell
  • Toggleable editor shell
  • Aspect-correct live game viewport
  • Resizable panels
  • Public dock groups consumed by the editor workspace
  • Public rearrangeable panel stacks with stack-to-dock transfer, consumed by editor sidebars
  • Public horizontal/vertical dock splitting from configurable edge-drop targets
• Inspection
  • System profiler
  • Entity browser
  • Entity selection
  • Runtime type-inspected component panels with generic Bool, String, Number, Vec2, Vec3, Vec4, and Color controls
  • Material resource-reference picker and inline resource fields
  • ECS-built material resource browser with selection and inline inspection
  • Runtime-reflected enum editor using reusable public choice-popup composition
  • Recursive nested-record and fixed-array inspectors using public disclosure composition
  • Resizable dynamic-array schemas with add, remove, and reorder controls
  • Searchable Scene, resource, and system browsers using reusable filtered/virtualized ECS lists
  • Searchable registry-driven component picker using the public filtered-list contract
  • Expandable UUID-backed spatial hierarchy with drag-to-reparent
• Editing
  • Live transform, camera, light, and custom Number/Vec2/Vec3/Vec4/Color inspector editing
  • UUID-addressed authoring transactions with inspector and gizmo undo/redo
  • Registry-driven, namespaced Add Component picker and panel-title removal actions with undo/redo
  • Entity create, duplicate, rename, delete, and runtime promotion
  • Resource create, duplicate, rename, move, delete, usage lookup, and structural undo/redo
  • Explicit stopped-mode scene persistence by stable entity UUID
  • Recoverable project-wide Save transactions across scene and resource files
  • Multi-selection editing
  • Bounded field and structural editor transactions
• Scene Tools
  • Play/Pause/Step with an in-memory authoring baseline, non-destructive Stop, stopped-mode Undo/Redo, explicit Save, and scene-only Revert
  • RMB-captured WASD/Space/Ctrl scene-camera navigation
  • Pickable editor-only wireframe bodies and projection frusta for project camera entities
  • World/local translation, rotation, and scale gizmo orientation
  • Translation, rotation, and scale gizmo modes
  • Two-axis plane handles and center free/uniform transform handles
  • Precise viewport entity picking
• Extensibility
  • Asset browser
  • Editor plugins

Testing And Tooling

• Commands
  • Project validation
  • Deterministic stepping
  • Benchmark runner
  • Deterministic render profiling bundles
  • JSON command output
• Verification
  • Gameplay test fixtures
  • Artifact-preserving offscreen WGPU acceptance gate
  • Editor screenshot tests
  • Compile-time-gated world-integrity validation
  • Seeded editor lifecycle state-machine tests
  • Large-scene persistence torture tests with exact-text, savepoint, schema-roundtrip, and failure-injection coverage
  • Project-save rollback and crash-recovery fault matrix across every filesystem phase
  • Native extension tests
  • Lifecycle CPU/RAM growth gate
  • Linux AddressSanitizer lane
• Project Support
  • Example projects
  • Documentation site
  • Agent workflow docs
  • macOS, Linux, and Windows CI workflow
  • Docs checks
  • Benchmark trend reporting

Assets, Simulation, And Larger Systems

• 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

License

Scrapbot is licensed under the Apache License 2.0. Vendored dependencies under third_party/ retain their own licenses.