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/Facepunch/sbox-public 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 the board

• Last commit 1d ago
• 15 active contributors
• Distributed ownership (top contributor 17% of recent commits)
• Other licensed
• CI configured
• Tests present
• ⚠ Non-standard license (Other) — review terms

_{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 Facepunch/sbox-public repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/Facepunch/sbox-public.

What it runs against: a local clone of Facepunch/sbox-public — 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 Facepunch/sbox-public | Confirms the artifact applies here, not a fork | | 2 | License is still Other | Catches relicense before you depend on it | | 3 | Default branch master exists | Catches branch renames | | 4 | 5 critical file paths still exist | Catches refactors that moved load-bearing code | | 5 | Last commit ≤ 31 days ago | Catches sudden abandonment since generation |

#!/usr/bin/env bash
# RepoPilot artifact verification.
#
# WHAT IT RUNS AGAINST: a local clone of Facepunch/sbox-public. If you don't
# have one yet, run these first:
#
#   git clone https://github.com/Facepunch/sbox-public.git
#   cd sbox-public
#
# 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 Facepunch/sbox-public and re-run."
  exit 2
fi

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

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

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

# 4. Critical files exist
test -f ".github/PULL_REQUEST_TEMPLATE.md" \\
  && ok ".github/PULL_REQUEST_TEMPLATE.md" \\
  || miss "missing critical file: .github/PULL_REQUEST_TEMPLATE.md"
test -f "CONTRIBUTING.md" \\
  && ok "CONTRIBUTING.md" \\
  || miss "missing critical file: CONTRIBUTING.md"
test -f "engine/Definitions/engine.def" \\
  && ok "engine/Definitions/engine.def" \\
  || miss "missing critical file: engine/Definitions/engine.def"
test -f "engine/Definitions/common/SceneSystem/ISceneWorld.def" \\
  && ok "engine/Definitions/common/SceneSystem/ISceneWorld.def" \\
  || miss "missing critical file: engine/Definitions/common/SceneSystem/ISceneWorld.def"
test -f "Bootstrap.bat" \\
  && ok "Bootstrap.bat" \\
  || miss "missing critical file: Bootstrap.bat"

# 5. Repo recency
days_since_last=$(( ( $(date +%s) - $(git log -1 --format=%at 2>/dev/null || echo 0) ) / 86400 ))
if [ "$days_since_last" -le 31 ]; then
  ok "last commit was $days_since_last days ago (artifact saw ~1d)"
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/Facepunch/sbox-public"
  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).

s&box is a modern game engine built on Valve's Source 2 runtime, combining C# (.NET 10) with a visual editor for creating games. It exposes Source 2's graphics, physics, animation, and asset systems through managed code, enabling developers to build games without C++ while leveraging a AAA-grade engine foundation. Monolithic source structure: engine/ contains the C# engine code, Definitions/, and Benchmark/ projects; game/ holds compiled binaries and assets; .github/workflows orchestrate CI/CD. Definition files (*.def in engine/Definitions/) declare native interfaces (Physics, Render, AnimGraph, AssetSystem) that get code-generated and bound to C# via interop, centralizing engine API contracts.

Game developers and engine contributors who want to create games using C# and a modern editor UI, without writing C++. Contributors work on engine core systems (physics, rendering, asset pipeline) defined in engine/Definitions/*.def files and implemented via C# interop.

Actively developed and production-ready: the project is publicly available on Steam, has a full documentation site (sbox.game/dev/), enforces code formatting/PR checks via GitHub Actions (.github/workflows/), and includes native binaries under an EULA. The large C# codebase (18MB) and structured definition system indicate mature architecture, though the Source 2 interop layer is proprietary Facepunch code.

Standard open source risks apply.

Active development ongoing: README specifies Visual Studio 2026 and .NET 10 SDK support (cutting-edge tooling), GitHub Actions workflows validate pull requests (formatting, checks), and issue templates (bug_report.yml, feature_request.yml, crash.yml) suggest ongoing community engagement. Facepunch maintains the engine continuously for Steam distribution.

Check README for instructions.

Daily commands: Run Bootstrap.bat to build, then execute game binaries from game/bin/ folder directly. No dev server—this is a compiled game engine and editor distributed as desktop application (also available via Steam).

• .github/PULL_REQUEST_TEMPLATE.md — All contributors must follow this PR template for consistent code review and submission standards.
• CONTRIBUTING.md — Essential guide outlining contribution workflow, coding standards, and expectations for this engine project.
• engine/Definitions/engine.def — Core engine definitions file that bridges native Source 2 code with .NET bindings—critical for understanding the C#/C++ interop layer.
• engine/Definitions/common/SceneSystem/ISceneWorld.def — Foundational scene system interface; essential for understanding how worlds, objects, and rendering are coordinated.
• Bootstrap.bat — Build bootstrap script; required reading for local setup and compilation workflows.
• engine/Definitions/assetsystem/IAssetSystem.def — Core asset loading and management system; critical for understanding resource pipelines in the engine.
• LICENSE.md — Licensing terms that govern all contributions and usage of this engine codebase.

Add a New Native Engine Interface

1. Create a new .def file in engine/Definitions/ or appropriate subdirectory to declare the native interface with method signatures and properties. (engine/Definitions/common/SceneSystem/ISceneWorld.def)
2. Reference the interface in the main engine.def or a parent .def file to ensure it's included in the code generation pass. (engine/Definitions/engine.def)
3. Run the code generation build target (CodeGen.Targets) to auto-generate the .NET P/Invoke wrapper bindings. (engine/CodeGen.Targets)
4. Access the generated interface from C# code using the native interop layer and implement required functionality. (engine/Definitions/engine/CManagedSceneObject.def)

Add a New Asset Type

1. Define the asset type metadata in a .def file under engine/Definitions/assetsystem/ or create a new type definition. (engine/Definitions/assetsystem/IAssetType.def)
2. Register the asset type with the asset system using IAssetSystem during engine initialization. (engine/Definitions/assetsystem/IAssetSystem.def)
3. Implement the compilation pipeline via IResourceCompilerContext if the asset requires preprocessing. (engine/Definitions/assetsystem/IResourceCompilerContext.def)
4. Add preview/editor UI support via IAssetPreviewSystem for the s&box editor integration. (engine/Definitions/assetsystem/IAssetPreviewSystem.def)

Add a Custom Rendering Feature

1. Extend IRenderContext.def or create a new render interface definition for your custom rendering pass. (engine/Definitions/common/Render/IRenderContext.def)
2. Register render callbacks using RenderCallbacks.def to hook into the rendering pipeline at the appropriate stages. (engine/Definitions/engine/Render/RenderCallbacks.def)
3. Define material properties and shader parameters in the material system using CMaterialSystem2AppSystemDict.def. (engine/Definitions/engine/CMaterialSystem2AppSystemDict.def)
4. Implement camera setup and viewport configuration via CCameraRenderer.def if your feature requires custom camera behavior. (engine/Definitions/engine/Render/CCameraRenderer.def)

Report or Fix an Issue

1. Review CONTRIBUTING.md to understand the development workflow and code standards before submitting changes. (CONTRIBUTING.md)
2. File a bug report using the GitHub issue template located at .github/ISSUE_TEMPLATE/bug_report.yml with reproduction steps. (.github/ISSUE_TEMPLATE/bug_report.yml)
3. Create a feature request using .github/ISSUE_TEMPLATE/feature_request.yml if proposing new functionality. (.github/ISSUE_TEMPLATE/feature_request.yml)
4. Submit your fix via a pull request following the PR_PULL_REQUEST_TEMPLATE.md format for review. (.github/PULL_REQUEST_TEMPLATE.md)

• Valve Source 2 Engine (C++) — Proven AAA graphics and physics foundation; enables high-fidelity visuals and complex simulations without reinventing core systems.
• .NET (C#) — Modern, garbage-collected runtime; offers rapid game development iteration, extensive standard library, and strong IDE support for gameplay scripting.
• P/Invoke (Native Interop via .def files) — Zero-copy bridge between managed C# and native Source 2 code; allows leveraging engine optimizations while maintaining .NET language benefits.
• Component-based Architecture (Scene Objects, Layers) — Modular entity composition enables flexible game object design and efficient spatial queries (layers, culling, batching).
• Steam Integration — First-class support for matchmaking, lobbies,

1. Native binaries in game/bin/ are precompiled Valve Source 2 code—you cannot rebuild them from source and must accept the EULA to redistribute. 2) .def files (engine/Definitions/.def) drive code generation; modifying them requires re-running Bootstrap.bat to regenerate C# interop stubs. 3) .NET 10 SDK and Visual Studio 2026 are hard requirements (not VS 2022 or older); version mismatch will break builds. 4) game/thirdpartylegalnotices must be reviewed before shipping games—mixed licenses (MIT + EULA + third-party) apply. 5) Windows-first tooling: Bootstrap.bat is batch file; *nix developers may encounter path/tooling friction.

• P/Invoke (Platform Invoke) and native interop — s&box bridges C# managed code to Valve's closed-source Source 2 native binaries via P/Invoke; understanding this interop layer is critical for debugging crashes and performance issues.
• Code generation from interface definitions — The engine/Definitions/*.def files are used to auto-generate C# interop stubs; contributors must understand the definition → code-gen → C# binding pipeline to modify engine APIs.
• HLSL shader compilation and material pipeline — 829KB of HLSL shaders in the codebase drive the render system; understanding shader compilation and the material mode abstraction (IMaterialMode.def) is essential for graphics work.
• Physics engine abstraction (rigid bodies, joints, shapes) — Physics API is fully abstracted in engine/Definitions/common/Physics/ (IPhysicsBody, IPhysicsJoint, IPhysicsShape); understanding the interface contracts is necessary for gameplay programming.
• Asset system and resource compilation — The IAssetSystem.def and IResourceCompilerContext.def define how game assets flow through the pipeline; understanding this is critical for tooling and import workflows.
• Animation graph system (AnimGraph) — engine/Definitions/animgraph/Animgraph.def exposes skeletal animation and blending; essential for character animation and state machine integration.
• Managed memory and GC in game engines — s&box runs game code in .NET's garbage-collected runtime; understanding GC pauses, heap fragmentation, and allocation patterns is critical for frame-rate stability.

• godotengine/godot — Alternative modern game engine with integrated editor; uses GDScript instead of C# but shares goal of visual game development without C++.
• MonoGame/MonoGame — C# game framework building on XNA; lower-level than s&box but also leverages C#/.NET for cross-platform game dev.
• ValvePython/source2 — Community reverse-engineering of Valve's Source 2 engine formats; complements s&box by documenting the underlying native engine architecture.
• Facepunch/garrysmod — Facepunch's previous game engine (Source 1-based, Lua scripting); historical predecessor showing evolution to s&box's C#/.NET approach.
• dotnet/runtime — .NET 10 runtime that powers s&box; understanding runtime internals (GC, interop, AOT compilation) is essential for engine performance tuning.

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 comprehensive unit tests for ByteStream benchmark module

The engine/Benchmark/Benchmarks/ByteStream.cs exists but there's no corresponding unit test suite in the repository structure. ByteStream is a critical low-level component used throughout the engine for serialization. Adding unit tests would catch regressions and provide documentation for expected behavior.

• [ ] Create engine/Tests/ByteStream.Tests.cs with xUnit test fixtures
• [ ] Test edge cases: empty streams, overflow conditions, endianness handling
• [ ] Reference existing benchmarks in engine/Benchmark/Benchmarks/ByteStream.cs to ensure test coverage aligns with performance-critical paths
• [ ] Ensure tests run in pull_request_checks.yml workflow

Create Physics API definition tests for IPhysicsBody and IPhysicsWorld

The engine/Definitions/common/Physics/ directory contains multiple .def files (IPhysicsBody.def, IPhysicsWorld.def, IPhysicsJoint.def, IPhysicsShape.def) but there's no evidence of corresponding C# wrapper tests. These are core engine APIs that need test coverage to prevent breaking changes.

• [ ] Create engine/Tests/Physics/PhysicsBodyTests.cs to verify physics body creation, transformation, and collision state
• [ ] Create engine/Tests/Physics/PhysicsWorldTests.cs to test world queries, raycasts, and shape interactions
• [ ] Use the .def files in engine/Definitions/common/Physics/ as reference for expected API surface
• [ ] Add physics-related test categories to pull_request_checks.yml

Add missing CI workflow for code generation validation (CodeGen.Targets)

The engine/CodeGen.Targets file exists and appears to be responsible for generating code from .def files, but there's no visible CI workflow validating that generated code matches committed artifacts. This could lead to out-of-sync generated code being merged.

• [ ] Create .github/workflows/codegen_validation.yml that runs CodeGen.Targets and checks for uncommitted changes
• [ ] Validate that all .def files in engine/Definitions/ produce expected generated code
• [ ] Reference engine/Definitions/ directory recursively in the workflow to detect new .def files
• [ ] Integrate codegen_validation.yml into pull_request_checks.yml as a required check

• Add unit tests for engine/Benchmark/Benchmarks/ micro-benchmarks: currently benchmark code exists (FastHash.cs, MemoryAlloc.cs) but no test assertions or xUnit/NUnit harness visible. Beginner could add test project under engine/Benchmark/Tests/ with passing assertions.: low
• Expand CONTRIBUTING.md with workflow diagrams: file exists but lacks visual diagrams of the definition-to-C# code-generation pipeline and PR checklist. Contributor could add flowcharts or checklists showing how to modify *.def files and rebuild.: low
• Add shell script equivalents for Bootstrap.bat: currently only Bootstrap.bat exists (Windows-only). Contributor could create Bootstrap.sh for macOS/Linux, wrapping the same dependency download and build steps, enabling broader platform support.: medium

The s&box codebase demonstrates a moderate security posture. The primary concerns involve the extensive native code interoperability with Source 2 engine (which requires careful memory safety handling), asset system input validation, and dependency management visibility. The project has basic security infrastructure (SECURITY.md, issue templates) but would benefit from expanded security documentation, automated dependency scanning, and more rigorous review processes for security-sensitive components. The .NET platform itself provides some inherent protections, but the native interop layer requires particular attention to prevent memory-based vulnerabilities.

• Medium · Dependency Management Visibility — Root directory / Dependencies. No Package.lock or dependency manifest files are visible in the provided file structure. This makes it difficult to verify that dependencies are pinned to specific versions, which could lead to supply chain attacks or unexpected behavior from transitive dependency updates. Fix: Ensure all package managers (NuGet for .NET projects) use lock files (packages.lock.json). Commit these lock files to version control and regularly audit dependencies using tools like OWASP Dependency-Check or GitHub Dependabot.
• Low · Limited Security Policy Documentation — SECURITY.md. The SECURITY.md file only contains a single link to an external vulnerability reporting page without providing additional security guidance, disclosure timeline expectations, or supported versions information. Fix: Expand SECURITY.md to include: vulnerability disclosure timeline, supported versions, security best practices for contributors, and responsible disclosure guidelines.
• Low · Missing CODEOWNERS File — .github/. No CODEOWNERS file is present in the .github directory, which means pull request reviews may not automatically route to security-critical components. Fix: Create a CODEOWNERS file that specifies security-sensitive components (Physics, Render, native interop) to ensure they receive appropriate review attention.
• Medium · Native Code Interoperability Risk — engine/Definitions/common/, engine/Definitions/engine/. The codebase contains extensive native interop definitions (.def files for Physics, Rendering, Asset Systems) interfacing with Source 2 engine. Without visible security controls, this creates potential for memory corruption, buffer overflows, or privilege escalation vulnerabilities. Fix: Implement comprehensive memory safety validation, use bounds checking on all native interop calls, enable address sanitizers in build pipelines, and conduct regular security audits of native boundary code.
• Medium · Third-Party Asset System Attack Surface — engine/Definitions/assetsystem/. The asset system (IAsset, IAssetType, IAssetSystem definitions) accepts external data without visible validation logic. This could enable malicious asset loading, arbitrary code execution, or resource exhaustion attacks. Fix: Implement strict validation of all asset inputs, implement resource quotas, use sandboxing for asset processing, and validate file signatures before loading.
• Low · Debug/Benchmark Code in Production — engine/Benchmark/, engine/Definitions/engine/PerformanceTrace.def. Benchmark and performance tracing code (engine/Benchmark/, PerformanceTrace.def) may expose performance characteristics that could aid attackers in timing attacks or identifying bottlenecks. Fix: Ensure benchmark and tracing functionality is disabled in production builds and protected behind debug-only compilation directives.

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.