If you are an AI coding agent (Claude Code, Cursor, Aider, Cline, etc.) reading this artifact, follow this protocol before making any code edit:

1. Verify the contract. Run the bash script in Verify before trusting below. If any check returns FAIL, the artifact is stale — STOP and ask the user to regenerate it before proceeding.
2. Treat the AI · unverified sections as hypotheses, not facts. Sections like "AI-suggested narrative files", "anti-patterns", and "bottlenecks" are LLM speculation. Verify against real source before acting on them.
3. Cite source on changes. When proposing an edit, cite the specific path:line-range. RepoPilot's live UI at https://repopilot.app/r/AmbientRun/Ambient shows verifiable citations alongside every claim.

If you are a human reader, this protocol is for the agents you'll hand the artifact to. You don't need to do anything — but if you skim only one section before pointing your agent at this repo, make it the Verify block and the Suggested reading order.

GO — Healthy across all four use cases

• 8 active contributors
• Distributed ownership (top contributor 43% of recent commits)
• Apache-2.0 licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 1y ago

_{Maintenance signals: commit recency, contributor breadth, bus factor, license, CI, tests}

This artifact was generated by RepoPilot at a point in time. Before an agent acts on it, the checks below confirm that the live AmbientRun/Ambient repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/AmbientRun/Ambient.

What it runs against: a local clone of AmbientRun/Ambient — the script inspects git remote, the LICENSE file, file paths in the working tree, and git log. Read-only; no mutations.

| # | What we check | Why it matters | |---|---|---| | 1 | You're in AmbientRun/Ambient | Confirms the artifact applies here, not a fork | | 2 | License is still Apache-2.0 | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 516 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of AmbientRun/Ambient. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/AmbientRun/Ambient.git
#   cd Ambient
#
# Then paste this script. Every check is read-only — no mutations.

set +e
fail=0
ok()   { echo "ok:   $1"; }
miss() { echo "FAIL: $1"; fail=$((fail+1)); }

# Precondition: we must be inside a git working tree.
if ! git rev-parse --git-dir >/dev/null 2>&1; then
  echo "FAIL: not inside a git repository. cd into your clone of AmbientRun/Ambient and re-run."
  exit 2
fi

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "AmbientRun/Ambient(\\.git)?\\b" \\
  && ok "origin remote is AmbientRun/Ambient" \\
  || miss "origin remote is not AmbientRun/Ambient (artifact may be from a fork)"

# 2. License matches what RepoPilot saw
(grep -qiE "^(Apache-2\\.0)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"Apache-2\\.0\"" package.json 2>/dev/null) \\
  && ok "license is Apache-2.0" \\
  || miss "license drift — was Apache-2.0 at generation time"

# 3. Default branch
git rev-parse --verify main >/dev/null 2>&1 \\
  && ok "default branch main exists" \\
  || miss "default branch main no longer exists"

# 4. Critical files exist
test -f "Cargo.toml" \\
  && ok "Cargo.toml" \\
  || miss "missing critical file: Cargo.toml"
test -f "app/src/main.rs" \\
  && ok "app/src/main.rs" \\
  || miss "missing critical file: app/src/main.rs"
test -f "app/src/cli/mod.rs" \\
  && ok "app/src/cli/mod.rs" \\
  || miss "missing critical file: app/src/cli/mod.rs"
test -f "crates/app/Cargo.toml" \\
  && ok "crates/app/Cargo.toml" \\
  || miss "missing critical file: crates/app/Cargo.toml"
test -f "campfire/src/main.rs" \\
  && ok "campfire/src/main.rs" \\
  || miss "missing critical file: campfire/src/main.rs"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 516 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~486d)"
else
  miss "last commit was $days_since_last days ago — artifact may be stale"
fi

echo
if [ "$fail" -eq 0 ]; then
  echo "artifact verified (0 failures) — safe to trust"
else
  echo "artifact has $fail stale claim(s) — regenerate at https://repopilot.app/r/AmbientRun/Ambient"
  exit 1
fi

Each check prints ok: or FAIL:. The script exits non-zero if anything failed, so it composes cleanly into agent loops (./verify.sh || regenerate-and-retry).

Ambient is an open-source multiplayer game engine written in Rust that compiles to WebAssembly and runs on the web, desktop, and other platforms. It provides a real-time ECS database with automatic network synchronization, configurable asset pipelines, PBR rendering via WebGPU, and WASM-based package isolation—enabling developers to build multiplayer games without managing networking or state synchronization plumbing. Monorepo structure: app/ contains the CLI and runtime executable (app/src/cli/); crates/ holds the core engine modules (rendering, ECS, networking); libs/ contains shared utilities; shared_crates/ for cross-platform code. Packages are built as WASM modules and deployed via app/src/cli/package/. Guest code runs in WASM isolation; server runs natively. Build system uses Cargo workspaces with Rust 1.70.0 MSRV.

Game developers (hobbyist and indie) who want to build multiplayer games without wrestling with networking code, plus engine contributors and package creators extending the Ambient ecosystem. The CLI tooling in app/src/cli suggests a focus on developers creating and deploying Ambient packages via ambient package build and ambient package deploy workflows.

Paused indefinitely. The README includes a WARNING that 'Work on the Ambient runtime is paused indefinitely.' The codebase is substantial (6MB+ of Rust, CI/CD pipelines configured, v0.3.2-dev released), but the team has pivoted to Braindump. This was an actively-developed project (~2023) but is now unsupported; use for learning or hobby projects only, not production.

High risk for production use: the runtime is officially paused with no active maintenance. The dependency surface is large (workspace includes 40+ crates in crates/, libs/, shared_crates/; heavy reliance on wgpu 0.16.3, winit 0.28.6, tokio 1.32) and pinned versions may accumulate security issues. WASM+WebGPU stack is still emerging; browser support varies. Community support has moved to Braindump's Discord.

Active development is stopped. The repo is in maintenance mode; the README points users to Braindump (https://braindump.me/blog-posts/building-an-ai-game-studio) for future work. Existing CI workflows (.github/workflows/) remain configured (ci.yml, deploy-*.yml, publish-api.yml), but no commits are expected. The latest version is 0.3.2-dev.

git clone https://github.com/AmbientRun/Ambient.git
cd Ambient
cargo build --release -p ambient_app
# Or run the CLI directly:
cargo run --release -p ambient_app -- --help

Note: Requires Rust 1.70.0+. For cross-platform builds, install native dependencies per platform (SDL2 on Linux, Xcode on macOS, MSVC on Windows).

Daily commands:

cargo run --release -p ambient_app -- join [world_url]
# Or build a game package:
cargo run --release -p ambient_app -- package build
# Then run it locally:
cargo run --release -p ambient_app -- run

The app binary is in app/src; it accepts CLI subcommands for join, login, package (build/deploy/new), and assets management.

• Cargo.toml — Workspace root configuration defining all crates, dependencies, and version management for the entire multiplayer game engine
• app/src/main.rs — Main entry point for the Ambient runtime application, orchestrates CLI and client/server initialization
• app/src/cli/mod.rs — CLI module root that routes all command-line operations (build, deploy, serve, login, join)
• crates/app/Cargo.toml — Core application crate defining the runtime engine and its critical dependencies (wgpu, winit)
• campfire/src/main.rs — Build and deployment orchestration tool; handles package compilation, documentation generation, and release workflows
• app/src/shared/mod.rs — Shared components between client and server runtime, including certificate handling and common data structures
• crates/animation/src/lib.rs — Animation system core providing skeletal animation, retargeting, and playback for game entities

Create a New Game Package

1. Run ambient CLI to scaffold a new package structure (app/src/cli/package/new.rs)
2. Define package metadata (name, version, assets) in the generated file (app/src/cli/package/new_package_template/ambient.toml)
3. Implement client-side game logic in the client.rs module (app/src/cli/package/new_package_template/src/client.rs)
4. Implement server-side multiplayer logic in server modules (app/src/cli/package/new_package_template/src/server_quad.rs)
5. Compile to WASM and test locally using serve command (app/src/cli/package/serve.rs)
6. Deploy to the Ambient platform using deploy command (app/src/cli/package/deploy.rs)

Add Animation Support to Game Entities

1. Import animation player and resources from the animation crate (crates/animation/src/lib.rs)
2. Create animation player instance and load skeleton data (crates/animation/src/player.rs)
3. Apply retargeting to bind animations to different character models (crates/animation/src/retargeting.rs)
4. Register animation resources and manage playback state in game logic (crates/animation/src/resources.rs)

Build and Publish a Package Release

1. Ensure package is complete and all assets are included (app/src/cli/assets.rs)
2. Run the build command to compile package to WASM (app/src/cli/package/build.rs)
3. Use campfire CLI to manage version bumping and changelog (campfire/src/release.rs)
4. Execute release workflow to publish to package registry (campfire/src/package.rs)
5. Verify documentation generation and deployment (campfire/src/doc/mod.rs)

• WebAssembly (WASM) — Enables cross-platform code sharing between web and desktop; provides sandboxed execution for user game logic while maintaining security and performance
• Rust + wgpu — Type-safe systems language with memory safety guarantees; wgpu provides portable graphics API abstraction across GPU backends (Metal, Vulkan, DX12, WebGPU)
• Cargo workspace — Monorepo structure enables code reuse across client, server, and tools while maintaining clear crate boundaries and dependency hygiene
• winit + WebGPU — Cross-platform window management and modern graphics API support unifies desktop and web rendering pipelines
• Campfire (custom build tool) — Specialized orchestration for package compilation, documentation generation, and deployment workflows specific to Ambient's WASM-based architecture

• WASM sandbox execution for game logic

  • Why: Enables safe execution of untrusted game packages; simplifies deployment and updates across platforms
  • Consequence: Game logic performance overhead (~5-15% vs native) due to WASM interpretation and FFI boundaries

• Monolithic CLI tool covering build, deploy, serve, login

  • Why: Single entry point simplifies developer experience and reduces context switching
  • Consequence: CLI must maintain multiple feature sets; coupling between build and deployment concerns

• Single Rust codebase for client and server

  • Why: Code reuse and consistent type system across multiplayer boundaries; shared animation/graphics libraries
  • Consequence: Larger runtime footprint; client bundle includes server-compatible code even when unused

• Platform-specific WASM modules (client vs server)

  • Why: Enables optimization and selective API exposure (server has no graphics, client has no persistence)
  • Consequence: Requires separate compilation and test targets; increased build complexity

• Real-time multiplayer netcode/replication engine (deferred to game logic in WASM)
• Built-in authentication system (delegated to platform via login CLI)
• Game editor or visual development tools (code-first approach)
• Platform availability - development is paused indefinitely

Development paused: The biggest trap—do not expect support or merges. WASM compilation: Guest packages must target wasm32-unknown-unknown; build.rs in templates handles this, but manual builds will fail without proper Cargo features. Network sync is automatic: Entities must use defined Components; custom types outside the ECS sync layer may not replicate. Hot-reload expects live editor: The runtime is designed for real-time iteration; offline workflows are not the primary path. WebGPU support varies: Requires modern browser or native WebGPU implementation; older systems may not run web builds.

• Entity-Component-System (ECS) — Ambient's core architecture for state and simulation; understanding ECS is essential to modeling game logic and syncing multiplayer state.
• Automatic Network Synchronization (CRDT-inspired) — Ambient abstracts away manual networking; components automatically replicate to clients, and the engine handles merge conflicts—critical to the selling point.
• WebAssembly (WASM) Sandboxing — Guest game packages run isolated in WASM; understanding WASM security model and host/guest boundaries is key to safe extension design.
• WebGPU & GPU Rendering Pipeline — Ambient uses wgpu (WebGPU abstraction) for PBR rendering; understanding GPU state, shader binding, and pipeline architecture is needed to optimize rendering.
• Real-Time Asset Pipeline — Ambient supports hot-reload and configurable asset transformation (gltf, images, etc.); the asset system bridges game code and external tools.
• Rust MSRV (Minimum Supported Rust Version) — The project pins rust-version = '1.70.0' in Cargo.toml; builds may fail on older or newer toolchains if features diverge.
• Monorepo Workspace Management — The project uses Cargo workspaces (crates/, libs/, shared_crates/) to share code; understanding how workspace members depend on each other prevents circular deps and build failures.

• bevyengine/bevy — Alternative Rust game engine with ECS architecture; targets native and web (via Wasm) but is not multiplayer-first and remains actively maintained.
• gfx-rs/gfx — Low-level graphics abstraction layer underlying Ambient's rendering; wgpu is built on gfx concepts.
• not-fl3/macroquad — Lightweight Rust game library for web/desktop; simpler alternative to Ambient without multiplayer or ECS, still active.
• AmbientRun/Ambient-examples — Official example games and demos for Ambient (if repo exists); demonstrates package structure and game patterns.
• WebAssembly/wasi — WASI standard for WASM system interface; Ambient's guest packages run in WASM sandboxes with restricted host access.

To work on one of these in Claude Code or Cursor, paste: Implement the "<title>" PR idea from CLAUDE.md, working through the checklist as the task list.

Add integration tests for CLI package commands (build, serve, deploy)

The CLI package management system in app/src/cli/package/ (build.rs, serve.rs, deploy.rs, run.rs) lacks visible test coverage. Given this is a core developer workflow for a game engine platform, integration tests would catch regressions in package lifecycle management and improve contributor confidence when modifying CLI behavior.

• [ ] Create app/src/cli/package/tests/ directory with integration test module
• [ ] Add tests for ambient package build command with the new_package_template as test fixture
• [ ] Add tests for ambient package serve startup and hot-reload behavior
• [ ] Add tests for ambient package deploy with mock server endpoints
• [ ] Document test setup in CONTRIBUTING.md for running CLI tests locally

Extract and document shared component schema definitions

The codebase has app/src/shared/components.rs and a top-level schema/ directory in workspace members, but the relationship between shared component definitions and the schema system is unclear. New contributors struggle to understand how to define entities/components. Creating comprehensive documentation with examples would lower the barrier to contribution.

• [ ] Review schema/src/ and app/src/shared/components.rs to map component definition patterns
• [ ] Create docs/COMPONENT_SCHEMA.md explaining how to define and register new components
• [ ] Add code examples showing: basic component definition, serialization requirements, and schema registration
• [ ] Add a worked example converting a simple component from app/src/shared/components.rs into documented schema form
• [ ] Link the new guide from CONTRIBUTING.md under 'Adding Game Components'

Add CI workflow for validating new_package_template generates buildable packages

The new_package_template in app/src/cli/package/new_package_template/ is critical for new users but has no automated validation that it compiles and runs correctly. Adding a GitHub Actions workflow to generate a package from the template and build it would prevent template rot and catch breaking API changes early.

• [ ] Create .github/workflows/validate-package-template.yml workflow
• [ ] Implement steps to: (1) copy new_package_template to temp location, (2) run ambient package build, (3) run ambient package serve with timeout
• [ ] Add validation that generated WASM artifacts exist and are non-zero size
• [ ] Configure workflow to run on: pull requests touching app/src/cli/package/, workspace.dependencies changes, and rust-version bumps
• [ ] Document in CONTRIBUTING.md that template changes require green CI before merge

• Add comprehensive tests for the CLI package builder (app/src/cli/package/build.rs). Currently no test file visible; covering the WASM compilation and asset bundling pipeline would catch regressions.: Write unit tests in app/src/cli/package/build.rs::tests verifying mock WASM builds and asset tree construction.
• Document the ECS component schema system with examples in the book. The README references 'an in-game real-time database' but the actual API (which Components exist, how to define custom ones) is absent from the file list.: Create docs/reference/components.md with examples of defining and querying Components in both Rust and WASM guest code.
• Add shell completion generation to the CLI (bash, zsh). app/src/cli/mod.rs parses all commands; use a crate like clap_complete to auto-generate completions during build.: Modify app/build.rs to generate completions and install them in app/target/completions; document in CONTRIBUTING.md.

• High · Outdated Rust Toolchain Version — Dockerfile (line 1), Cargo.toml (workspace.package.rust-version). The Dockerfile uses Rust 1.73 (released September 2023), which is significantly outdated. The workspace specifies rust-version = '1.70.0' which is even older. Using outdated Rust versions exposes the codebase to known security vulnerabilities in the compiler and standard library that have been patched in newer versions. Fix: Update to the latest stable Rust version (1.75+). Change 'FROM rust:1.73-bullseye' to a recent version and update workspace.package.rust-version accordingly. Implement a process to regularly update Rust toolchain versions.
• High · Outdated Base OS Image — Dockerfile (FROM rust:1.73-bullseye, second stage). The Dockerfile uses Debian Bullseye (released August 2021), which is no longer receiving security updates. This base image contains numerous unpatched vulnerabilities in system libraries and packages. Fix: Upgrade to a more recent Debian version (Bookworm or newer) or use a minimal image like 'rust:latest-slim'. Execute 'apt-get upgrade' in addition to 'apt-get install' to ensure all packages are patched.
• High · Incomplete Dependency Version Pinning — Cargo.toml (workspace.dependencies). Several critical dependencies use loose version constraints that allow minor/patch version upgrades, potentially introducing breaking changes or security issues. Examples include 'reqwest = 0.11.20', 'tokio = 1.32', which could pull in untested versions automatically. Fix: Use exact version pinning (=0.11.20) for security-critical dependencies or implement Cargo.lock enforcement. Regularly audit and update dependencies with controlled testing rather than automatic version selection.
• Medium · Use of rustls-tls Without Verification Details — Cargo.toml (reqwest dependency configuration). While rustls is a good choice over OpenSSL, the reqwest dependency configuration includes 'rustls-tls' feature but there's no evidence of certificate pinning or additional TLS validation configuration. This could expose the application to MITM attacks in certain scenarios. Fix: Implement certificate pinning for critical external APIs. Add explicit TLS configuration validation. Document TLS security requirements in the deployment guide.
• Medium · Docker Image Exposes Multiple Network Ports Without Rate Limiting — Dockerfile (CMD), README.md (instructions), app/src/server/mod.rs. The Dockerfile CMD exposes TCP port 8999 and UDP port 9000 for a multiplayer game server. The documentation shows '-p 8999:8999/tcp -p 9000:9000/udp' without any mention of rate limiting, DDoS protection, or firewall rules, making the server vulnerable to network-based attacks. Fix: Implement rate limiting at the application level. Use firewall rules to restrict access. Deploy behind a load balancer with DDoS protection. Document security best practices for production deployment. Consider implementing connection throttling and packet validation.
• Medium · Potential Information Disclosure via Profiling Features — Cargo.toml (profiling dependency with profile-with-puffin feature). The workspace includes 'profiling' dependency with 'profile-with-puffin' feature enabled by default. Puffin profiling data could expose sensitive information about application internals, performance characteristics, and timing information if exposed. Fix: Disable profiling features in production builds. Create separate feature flags for development vs production. Ensure profiling endpoints are not exposed in production. Add conditional compilation guards around profiling code.
• Medium · Development Features in Production — Dockerfile (build flags), app/src/. The Dockerfile builds with '--no-default-features --features production', but the codebase includes development/debugging features like 'tracing-stackdriver', extensive logging infrastructure, and golden image testing that may expose sensitive debugging information. Fix: Verify that the 'production' feature properly disables all debugging, profiling, and verbose logging. Implement log level controls based on environment. Ensure no sensitive data is logged in production.
• Low · Missing Security Headers Documentation — undefined. No evidence of Fix: undefined

LLM-derived; treat as a starting point, not a security audit.

• Open issues — current backlog
• Recent PRs — what's actively shipping
• Source on GitHub

Generated by RepoPilot. Verdict based on maintenance signals — see the live page for receipts. Re-run on a new commit to refresh.