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/sschmid/Entitas 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.

AVOID — Looks unmaintained — solo project with stale commits

• MIT licensed
• CI configured
• Tests present
• ⚠ Stale — last commit 2y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)

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

What it runs against: a local clone of sschmid/Entitas — 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 sschmid/Entitas | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | Catches relicense before you depend on it | | 3 | Default branch main exists | Catches branch renames | | 4 | Last commit ≤ 891 days ago | Catches sudden abandonment since generation |

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

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

# 2. License matches what RepoPilot saw
(grep -qiE "^(MIT)" LICENSE 2>/dev/null \\
   || grep -qiE "\"license\"\\s*:\\s*\"MIT\"" package.json 2>/dev/null) \\
  && ok "license is MIT" \\
  || miss "license drift — was MIT 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"

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

Entitas is a high-performance Entity Component System (ECS) framework written in C# that decouples game logic into reusable Entities, Components, and Systems for both Unity and standalone C# projects. It includes an integrated code generator (in gen/Entitas.Generators/) that eliminates boilerplate by auto-generating Context classes, Matchers, and entity extension methods from annotated Component declarations. Modular structure: src/ contains core ECS runtime (Contexts, Entities, Components, Systems), gen/Entitas.Generators/ holds the C# analyzer and code-generation logic with separate subdirectories for Component and Context generation, benchmarks/Entitas.Benchmarks/ measures GC pressure and system performance, and examples/ (implied) demonstrates patterns. Entitas.sln ties it together as a multi-project solution.

Game developers and technical architects using C# and Unity who need a battle-tested ECS architecture for large multiplayer games (battle-tested at Popcore/Zynga, Gram Games, Wooga, Plarium). They want garbage-collection-friendly entity management with visual debugging tools and minimal hand-written glue code.

Production-ready and actively maintained. Entitas is the #1 open-source ECS on GitHub with significant adoption at major studios (Zynga, Wooga, Plarium). The repo shows active CI/CD pipelines (build.yml, ci.yml, release.yml), comprehensive benchmarks (benchmarks/Entitas.Benchmarks/), and organized code generation infrastructure. However, check CHANGELOG.md and recent commits to confirm release cadence.

Low risk for core ECS functionality, but moderate risk for cutting-edge features. Single maintainer (sschmid) means feature velocity depends on one person; verify recent commit dates in git history. The code generator (gen/Entitas.Generators/) is complex—generated code can hide bugs. Check EntitasUpgradeGuide.md for breaking changes between major versions that could affect large codebases.

Active development on code generation and performance. The benchmarks directory (AERCBenchmarks.cs, CreateComponentBenchmarks.cs, DelegateBenchmarks.cs) indicates ongoing optimization work. GitHub workflows (ci.yml, release.yml) suggest regular builds and release automation. Check GitHub Issues and Discussions for current priorities.

Clone the repo and open the solution: git clone https://github.com/sschmid/Entitas.git && cd Entitas && dotnet build Entitas.sln. For Unity integration, add Entitas as a submodule or NuGet package. Review README.md and CONTRIBUTING.md for project guidelines.

Daily commands: dotnet build Entitas.sln builds the core framework. dotnet run --project benchmarks/Entitas.Benchmarks/Entitas.Benchmarks.csproj runs performance benchmarks. For Unity: import the generated Entitas.Unity package or submodule and access via using Entitas; statements.

• gen/Entitas.Generators/Component/ComponentGenerator.cs: Main code generator orchestrating all Component-related source generation (Matchers, Context extensions, event systems)
• gen/Entitas.Generators/Context/ContextGenerator.cs: Generates Context classes that hold entity pools and define the API surface for creating/destroying entities per context
• benchmarks/Entitas.Benchmarks/AERCBenchmarks.cs: Measures automatic entity reference counting performance—critical for understanding GC pressure in this framework
• Entitas.sln: Multi-project solution file; defines project dependencies and build order
• .github/workflows/ci.yml: Continuous integration pipeline showing how the framework is tested and validated on each commit
• [Directory.Build.props and Directory.Build.targets](https://github.com/sschmid/Entitas/blob/main/Directory.Build.props and Directory.Build.targets): Centralized build configuration; defines .NET version, code analysis rules, and common compiler settings across all projects

For core ECS: modify src/ files directly. To add a new Component type: create a class inheriting from IComponent, run the code generator (gen/Entitas.Generators/), which auto-generates Context extensions and Matchers under gen/Entitas.Generators/Component/. For new System types: extend ISystem or use concrete system interfaces (ExecuteSystem, ReactiveSystem) in your game logic layer. Review gen/Entitas.Generators/Component/ComponentGenerator.cs to understand code generation entry points.

Code generation is implicit—running the analyzer (likely triggered on build) modifies your source tree with generated files; unaware developers may commit generated code or suffer merge conflicts. ComponentGenerator output varies by decorated attributes on Components; review ComponentDeclaration.cs to understand required metadata. Unity version compatibility: check Unity3D.props for minimum Unity version constraints. Breaking API changes between major versions—always review EntitasUpgradeGuide.md before upgrading.

• Entity Component System (ECS) — The architectural foundation of Entitas—you must understand entities (game objects), components (data), and systems (logic) separately to use this framework effectively
• Automatic Entity Reference Counting (AERC) — Entitas uses AERC to avoid garbage collection pauses in game loops; benchmarks measure this directly, and incorrect usage can tank performance
• Code Generation via Reflection & Analyzers — Entitas generates boilerplate from declarative Component definitions; understanding how Roslyn analyzers scan attributes and emit code is essential for extending the generator
• Matcher Pattern (Query API) — Matchers auto-generated by ComponentGenerator let systems efficiently find entities with specific component combinations; Entitas generates type-safe matchers to avoid string-based lookups
• Sparse Set Data Structure — Entitas contexts internally use sparse sets for entity storage to enable O(1) component lookups and dense iteration without fragmentation
• Reactive Systems — ReactiveSystem in Entitas only executes when entities matching a Matcher gain/lose components, reducing unnecessary iterations per frame
• Garbage Collection Friendly Design — Entitas trades some API ergonomics for minimal allocations per frame; object pooling and struct components are core to the design philosophy

• gorelRelated/Arch — Modern C# ECS alternative with higher-level API; useful for comparing API design and archetype-vs-sparse-set trade-offs
• theor/BECSy — Burst-compatible ECS for Unity; shows integration with Unity's job system and Burst compiler, which Entitas predates
• jbogard/MediatR — C# message/command dispatch pattern often paired with ECS for event handling between systems
• Unity-Technologies/entities — Official Unity ECS (DOTS), the modern successor framework; Entitas remains valuable for non-DOTS projects and backward compatibility
• sebas77/Svelto.ECS — Alternative C# ECS with emphasis on data-oriented design and cache locality; comparable feature set and philosophy to Entitas

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 Entitas.Generators code generation logic

The gen/Entitas.Generators directory contains critical code generation logic (ComponentGenerator.cs, ContextGenerator.cs, and their partial classes) but there are no visible test files in the repo. Given that code generation directly impacts the entire framework's usability, adding unit tests for template generation, component declaration parsing, and context initialization would catch regressions early and make contributions safer.

• [ ] Create tests/Entitas.Generators.Tests directory with xUnit test project
• [ ] Add tests for ComponentGenerator.cs covering all partial classes (Matcher, ContextExtension, EntityExtension, etc.)
• [ ] Add tests for ContextGenerator.cs covering context, entity, and matcher generation
• [ ] Add tests for ComponentDeclaration.cs, ContextDeclaration.cs, and EventDeclaration.cs parsing logic
• [ ] Integrate test execution into .github/workflows/ci.yml

Add benchmark comparison documentation and CI validation for performance regressions

The repo contains benchmarks/Entitas.Benchmarks (AERC, CreateComponent, Delegate benchmarks) but there's no CI workflow or documentation explaining how to run them or what acceptable performance thresholds are. Adding benchmark validation to CI would prevent performance regressions and provide contributors with performance baselines.

• [ ] Create benchmarks/BENCHMARK_GUIDE.md documenting how to run Entitas.Benchmarks.csproj locally
• [ ] Add a new GitHub workflow .github/workflows/benchmarks.yml to run benchmarks on PR and compare against baseline
• [ ] Document current baseline performance metrics in benchmarks/BENCHMARK_RESULTS.md
• [ ] Update CONTRIBUTING.md with a section on performance considerations for core ECS changes

Create integration tests for the complete code generation workflow with realistic component/context definitions

While unit tests for generators are important, there are no visible integration tests validating the end-to-end code generation pipeline (parsing component definitions → generating matchers, extensions, systems → compiling generated code). This gap risks breaking the full workflow despite individual components working. Integration tests would ensure generated code actually compiles and functions correctly.

• [ ] Create tests/Entitas.Generators.Integration.Tests with test fixtures defining sample components and contexts
• [ ] Add integration tests that invoke the full generation pipeline (ComponentGenerator + ContextGenerator) and verify generated C# code compiles
• [ ] Verify generated extensions (ContextExtension, EntityExtension) work correctly with actual Entity/Context instances
• [ ] Test event system code generation and generated event handlers
• [ ] Integrate into ci.yml with warnings for breaking changes to generated code structure

• Add integration tests for ComponentGenerator.EntityExtension.cs to verify generated entity accessor methods match the component signature—currently only benchmarks exist for performance, not correctness.
• Document the ContextInitializationMethod code generation path in gen/Entitas.Generators/Component/ComponentGenerator.ContextInitializationMethod.cs with inline examples showing input Component → output generated method.
• Create a minimal example in examples/ showing a two-Context game (Game + UI) with cross-context event propagation, since most docs focus on single-context setups.

The Entitas ECS framework codebase demonstrates a reasonable security posture for an open-source game development library. No critical vulnerabilities were identified in the visible file structure. Key strengths include proper use of .gitignore, organized project structure, and established CI/CD workflows. Primary concerns center around: (1) potential code injection risks in the code generation pipeline without explicit input validation documentation, (2) reflection-based security risks inherent to ECS frameworks, and (3) missing security governance documentation (SECURITY.md, security advisories). The framework does not appear to handle sensitive data processing directly, reducing exposure to common web/data vulnerabilities. Recommendations focus on implementing input validation in generators, establishing security policies, and integrating automated security scanning into the development pipeline.

• Medium · Missing Input Validation in Code Generation — gen/Entitas.Generators/Component/ComponentGenerator.cs, gen/Entitas.Generators/Context/ContextGenerator.cs. The codebase contains code generation components (Entitas.Generators) that process component and context declarations. Without visible input sanitization, there's a potential risk of code injection through malformed component definitions or metadata that could be processed by the generators. Fix: Implement strict input validation for all component and context declarations. Validate naming conventions, type constraints, and metadata before code generation. Use allowlists for permitted characters and patterns.
• Medium · Potential Reflection-based Vulnerabilities in ECS Framework — gen/Entitas.Generators/ (entire generator module). Entity Component System frameworks typically use reflection extensively for component discovery, type resolution, and dynamic entity manipulation. While not explicitly visible in the file structure, this is a common attack surface in ECS implementations where untrusted component types could be instantiated. Fix: Implement whitelist-based type filtering for reflection operations. Avoid instantiating components from untrusted sources. Use sealed types where appropriate and implement proper error handling for reflection failures.
• Low · No CHANGELOG Security Advisory Section — CHANGELOG.md. The CHANGELOG.md file exists but there is no visible security advisories or vulnerability disclosure section. This makes it difficult for users to identify security-related updates. Fix: Add a dedicated 'Security' section to the CHANGELOG to document all security fixes and advisories. Follow semantic versioning for security patches.
• Low · Missing Security Policy File — Repository root. No SECURITY.md or security policy file is present in the root directory. This makes it unclear how security vulnerabilities should be reported responsibly. Fix: Create a SECURITY.md file documenting the vulnerability disclosure process, supported versions, and contact information for reporting security issues.
• Low · No SAST/Dependency Scanning Configuration — .github/workflows/ci.yml, build.yml. While CI/CD workflows exist (.github/workflows/), there is no visible configuration for static analysis security testing (SAST) tools or automated dependency vulnerability scanning. Fix: Integrate automated security scanning tools such as Snyk, OWASP Dependency-Check, or GitHub's native dependency scanning into the CI/CD pipeline.
• Low · Missing License Compliance Verification — Directory.Build.props, Directory.Build.targets. No license compliance checking or dependency license verification mechanisms are visible in the configuration, which could pose legal and security risks if transitive dependencies have restrictive licenses. Fix: Implement license compliance checking using tools like FOSSA or similar. Document all dependencies and their licenses. Review transitive dependencies regularly.

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.