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/liangxiegame/QFramework 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

• Last commit 1d ago
• 5 active contributors
• MIT licensed
• Tests present
• ⚠ Single-maintainer risk — top contributor 80% of recent commits
• ⚠ No CI workflows 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 liangxiegame/QFramework repo on your machine still matches what RepoPilot saw. If any fail, the artifact is stale — regenerate it at repopilot.app/r/liangxiegame/QFramework.

What it runs against: a local clone of liangxiegame/QFramework — 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 liangxiegame/QFramework | 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 ≤ 31 days ago | Catches sudden abandonment since generation |

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

# 1. Repo identity
git remote get-url origin 2>/dev/null | grep -qE "liangxiegame/QFramework(\\.git)?\\b" \\
  && ok "origin remote is liangxiegame/QFramework" \\
  || miss "origin remote is not liangxiegame/QFramework (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 "QFramework.Unity2018+/Assets/QFramework/Framework/Scripts/QFramework.cs" \\
  && ok "QFramework.Unity2018+/Assets/QFramework/Framework/Scripts/QFramework.cs" \\
  || miss "missing critical file: QFramework.Unity2018+/Assets/QFramework/Framework/Scripts/QFramework.cs"
test -f "QFramework.Godot4+/QFramework.cs" \\
  && ok "QFramework.Godot4+/QFramework.cs" \\
  || miss "missing critical file: QFramework.Godot4+/QFramework.cs"
test -f "QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Command/Music/PlayMusicCommand.cs" \\
  && ok "QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Command/Music/PlayMusicCommand.cs" \\
  || miss "missing critical file: QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Command/Music/PlayMusicCommand.cs"
test -f "QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Model/AudioLoaderPoolModel/AudioLoaderPoolModel.cs" \\
  && ok "QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Model/AudioLoaderPoolModel/AudioLoaderPoolModel.cs" \\
  || miss "missing critical file: QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Model/AudioLoaderPoolModel/AudioLoaderPoolModel.cs"
test -f "QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/System/PlaySoundChannelSystem/EveryOneChannel.cs" \\
  && ok "QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/System/PlaySoundChannelSystem/EveryOneChannel.cs" \\
  || miss "missing critical file: QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/System/PlaySoundChannelSystem/EveryOneChannel.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 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/liangxiegame/QFramework"
  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).

QFramework is a lightweight (~1000 lines) C# architecture framework for Unity 2018+ and Godot 4+ that provides a layered MVC/CQRS system design with event-driven communication, supporting SOLID principles and domain-driven design. It enables developers to build scalable, maintainable game architectures by structuring code into four distinct layers (Controller, System, Model, Utility) plus a Command bus for state mutations. Dual-port structure: QFramework.Unity2018+/ contains the Unity implementation with Assets/QFramework/Framework/Scripts/QFramework.cs (single-file core) plus Toolkits/ subdirectories for AudioKit, ResKit, UIKit, ActionKit, and PackageKit; QFramework.Godot4+/ mirrors the architecture in GDScript/C# with an addon system. Core architecture separates IController (presentation), ISystem (shared logic), IModel (data), IUtility (infrastructure), and ICommand (state mutations) as independent interfaces.

Game developers using Unity or Godot who need to architect mid-to-large scale game systems (UI controllers, gameplay mechanics, inventory systems, audio management) without tight coupling and with clear separation of concerns. Particularly useful for developers who want DDD and event-driven patterns without heavyweight frameworks.

Actively maintained and production-ready. The framework has multiple example projects (CounterApp, Flappy Bird, Snake, Minesweeper, Gomoku), integration with multiple toolkits (AudioKit, ResKit, UIKit, ActionKit), and is downloadable as unitypackages. However, the repo structure shows both Unity 2018+ and Godot 4+ ports suggesting some fragmentation, and commit recency data is not visible in the provided snapshot.

Low risk for core framework (minimal dependencies—just C# and engine APIs), but adoption risk stems from: single visible maintainer (liangxiegame), documentation primarily in Chinese with English docs available, no visible CI/CD pipeline or automated tests in file listing, and potential friction from maintaining two engine ports (Unity + Godot). Breaking changes between major versions are undocumented.

The repository shows active maintenance across both Unity and Godot ports. Recent work includes Godot 4+ addon system (QFramework.Godot4+/addons/qframework/), example projects (CounterApp controller), and toolkit expansions (AudioKit examples). The presence of multiple unitypackage exports (QFramework.Toolkits.unitypackage, demos for WuZiQi and SaoLei) indicates ongoing demo development, but specific commit/PR visibility is limited in provided metadata.

For Unity: (1) Clone repo: git clone https://github.com/liangxiegame/QFramework.git. (2) Open QFramework.Unity2018+/ as a Unity project (requires Unity 2018.4+). (3) Import unitypackage: QFramework.Toolkits.unitypackage or QFramework.cs.Examples.unitypackage into Assets. For Godot: Open QFramework.Godot4+/ as a Godot 4+ project. Or copy single file QFramework.cs directly into any C# script in your project.

Daily commands: For Unity examples: Open QFramework.Unity2018+/Assets/QFramework/Framework/Examples.unitypackage, inspect CounterApp scene in project, press Play. For Godot: Open QFramework.Godot4+/ in Godot 4+, examine Example/CounterApp.tscn, run via F5. No external build step required; QFramework is purely in-engine.

• QFramework.Unity2018+/Assets/QFramework/Framework/Scripts/QFramework.cs — Core framework entry point (~1000 lines) containing the four-layer architecture (IController, ISystem, IModel, IUtility) and the Comm pub/sub system that ties everything together.
• QFramework.Godot4+/QFramework.cs — Godot 4+ implementation of the same core architecture, essential for understanding cross-engine support.
• QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Command/Music/PlayMusicCommand.cs — Canonical example of a Command implementation showing the pattern for how state changes flow through the system.
• QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Model/AudioLoaderPoolModel/AudioLoaderPoolModel.cs — Reference IModel implementation demonstrating data management and event emission patterns.
• QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/System/PlaySoundChannelSystem/EveryOneChannel.cs — Reference ISystem implementation showing how systems manage shared logic and listen to events.
• Doc.md — Complete architectural documentation and design principles for the SOLID-compliant, DDD-ready framework.

Add a New Command (State Mutation)

1. Create a new class inheriting from ICommand in QFramework.cs (QFramework.Unity2018+/Assets/QFramework/Framework/Scripts/QFramework.cs)
2. Implement OnExecute() to perform state changes via GetModel<T>() and GetSystem<T>() (QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Command/Music/PlayMusicCommand.cs)
3. Emit Events from Models after state changes via SendEvent<T>() (QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Model/AudioLoaderPoolModel/AudioLoaderPoolModel.cs)
4. Invoke the command from a Controller via SendCommand<T>() (QFramework.Godot4+/Example/CounterAppController.cs)

Add a New IModel for Domain Data

1. Create a class implementing IModel interface from QFramework.cs (QFramework.Unity2018+/Assets/QFramework/Framework/Scripts/QFramework.cs)
2. Define public properties for data and private methods for CRUD operations (QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Model/AudioLoaderPoolModel/AudioLoaderPoolModel.cs)
3. Emit domain events using SendEvent<T>() when state mutates (QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Model/PlayingSoundPoolModel.cs)
4. Register the Model in your Architecture via RegisterModel<T>() (QFramework.Godot4+/QFramework.cs)

Add a New ISystem for Shared Logic

1. Create a class implementing ISystem interface from QFramework.cs (QFramework.Unity2018+/Assets/QFramework/Framework/Scripts/QFramework.cs)
2. Implement Init() to cache references via GetModel<T>() and GetSystem<T>() (QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/System/PlaySoundChannelSystem/EveryOneChannel.cs)
3. Subscribe to domain events using RegisterEvent<T>() to react to Model state changes (QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/System/ConsoleModuleSystem.cs)
4. Register the System in your Architecture via RegisterSystem<T>() (QFramework.Godot4+/QFramework.cs)

Swap a Utility Implementation (Adapter Pattern)

1. Define an IUtility interface or injectable abstraction in the Model (QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Model/AudioLoaderPoolModel/IAudioLoader.cs)
2. Implement the interface with your custom loader (e.g., streaming, network, compression) (QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Model/AudioLoaderPoolModel/DefaultAudioLoader.cs)
3. Inject the implementation in the Model's Init() via constructor or property (QFramework.Unity2018+/Assets/QFramework/Toolkits/AudioKit/Scripts/Architecture/Model/AudioLoaderPoolModel/AbstractAudioLoaderPool.cs)

• SOLID Principles + DDD — Enables independent scaling of concerns; IController/ISystem/IModel/IUtility separation ensures each layer has single responsibility and can be tested/extended in isolation.
• Event-Driven Pub/Sub (Comm) — Decouples presentation from data mutations; systems and controllers react to domain events rather than polling, reducing coupling and enabling complex workflows like chained Commands.
• Command Pattern (CQRS-inspired) — Centralizes all state mutations through a uniform interface; enables

1. Single-file architecture: QFramework.cs is monolithic; changes to core require editing one large file. 2. Service locator anti-pattern: Framework uses global Architecture.GetInstance<T>() lookups; can obscure dependencies and make unit testing harder without proper scoping. 3. Event vs. BindableProperty confusion: Documentation states both are valid for lower-to-upper communication, but best practices for choosing between them unclear. 4. Godot/Unity port divergence: Two separate implementations may accumulate drift; check which version you're targeting. 5. No async/await support visible: Framework predates modern C# async patterns; long operations may block. 6. Chinese-first documentation: English docs exist but lag behind Chinese originals; API.md may be incomplete.

• Command Pattern — QFramework's ICommand is the sole way to mutate state; understanding this pattern prevents data corruption and enables undo/redo systems and networked command replication.
• CQRS (Command Query Responsibility Segregation) — QFramework enforces CQRS by separating commands (mutations) from queries (reads); this is the architectural philosophy underpinning the layer rules.
• Service Locator Pattern — QFramework uses Architecture.GetInstance<T>() for dependency retrieval; this is a pragmatic choice for game engines but differs from constructor-based DI and affects testability.
• Observable Property / BindableProperty — QFramework's BindableProperty enables reactive UI binding without polling; understanding observable patterns is key to efficient event propagation in game UI.
• Domain-Driven Design (DDD) — QFramework is explicitly DDD-aligned; concepts like bounded contexts (separate Systems), entities (Models), and aggregates inform how to organize game domains (audio, inventory, achievements).
• Layered Architecture / N-Tier — QFramework's four-layer model (Controller, System, Model, Utility) is a specific instantiation of layered architecture; understanding layer responsibilities and upward/downward communication rules prevents architectural violations.
• Event-Driven Architecture — QFramework uses events (IEvent) for bottom-up communication across layers; this decouples systems and is essential for implementing modular game features like damage, achievements, UI updates.

• thfram/upm-package-cinemachine — Alternative architectural approach for Unity; Cinemachine uses composition over inheritance where QFramework uses layered interfaces.
• sschmid/Entitas — ECS (Entity Component System) framework for Unity; overlaps with QFramework in game architecture space but uses data-oriented design instead of layered DDD.
• akbiggs/Extenject — Dependency injection container for Unity; complementary to QFramework's service locator pattern for more testable architecture.
• Cysharp/UniTask — Async/await library for Unity; extends QFramework's command/event system with native async patterns and task pooling.
• godotengine/godot-csharp-styleguide — Official Godot C# guidelines; relevant since QFramework.Godot4+ uses C# in Godot and needs to follow engine conventions.

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 QFramework.cs core architecture (Unity2018+)

The framework is only ~1000 lines and lacks test coverage. The core QFramework.cs file implements critical SOLID principles and DDD patterns (Commands, Systems, Models, Events). Adding unit tests would validate the architecture's correctness, prevent regressions, and serve as executable documentation for contributors. This is especially important given the framework's architectural complexity and its position as a foundational library.

• [ ] Create Assets/QFramework/Framework/Scripts/Tests directory
• [ ] Add test file for Command execution and State management (QFrameworkCommandTests.cs)
• [ ] Add test file for System registration and lifecycle (QFrameworkSystemTests.cs)
• [ ] Add test file for Event publishing/subscription (QFrameworkEventTests.cs)
• [ ] Configure Unity Test Framework in QFramework.asmdef with test references
• [ ] Add README_TESTS.md documenting how to run tests locally

Create GitHub Actions CI workflow for Unity and Godot builds

The repo maintains two major implementations (Unity2018+ and Godot4+) but lacks automated build verification. A CI pipeline would catch breaking changes across both engines, validate example projects compile correctly (CounterApp), and ensure the core QFramework.cs remains compatible. This is critical for a framework where architectural decisions impact downstream projects.

• [ ] Create .github/workflows/unity-build.yml to build QFramework.Unity2018+ project
• [ ] Create .github/workflows/godot-build.yml to build QFramework.Godot4+ project
• [ ] Add step to verify Examples.unitypackage integrity in Unity workflow
• [ ] Add step to verify CounterAppController.cs example compiles in Godot workflow
• [ ] Add badge to README showing build status for both platforms

Complete API documentation for QFramework.cs with code examples per feature

The existing 'QFramework API.md' file appears incomplete based on the README architecture (Models, Systems, Commands, Events, Controllers). Contributors need clear documentation of the public API surface with concrete examples showing how to implement each architectural layer (IController, ISystem, ICommand, IModel). The framework README shows only diagram examples but lacks text-based API reference with usage patterns.

• [ ] Expand QFramework API.md with section for each core interface (IController, ISystem, IModel, ICommand, IEvent)
• [ ] Add 'Quick Start' example showing minimal counter app architecture walkthrough
• [ ] Document the four-layer architecture rules (ViewController, System, Model, Command) with permission matrix (what each layer can access)
• [ ] Add section explaining CQRS pattern implementation via Command/Query separation
• [ ] Add migration guide section: 'From MonoBehaviour spaghetti to QFramework' with before/after code
• [ ] Link API.md from README and each Example project (CounterAppController.cs should reference specific API docs)

• Add unit tests for core QFramework.cs interfaces (ICommand, IEvent, IModel state changes). No test files visible in the listing; a test suite for the core architecture would improve confidence.
• Document BindableProperty vs. Event decision tree in API.md. The README states both are valid for lower-to-upper communication but doesn't clarify when to use each; add concrete examples (e.g., 'use BindableProperty for frequent updates, IEvent for discrete state changes').
• Create a Godot 4+ example project equivalent to CounterApp. QFramework.Godot4+/Example/CounterApp.tscn exists but lacks a companion documentation guide; add a GDScript controller example showing how to wire the same pattern as the C# Unity version.
• Add TypeScript/C# interop examples for hybrid Unity + Godot pipelines. The codebase supports both engines; an example showing how to share architecture abstractions across them would help multi-platform teams.
• Expand Toolkits documentation with a 'Building Your Own Toolkit' guide. AudioKit/ResKit examples exist but no step-by-step guide on creating a custom toolkit (e.g., AchievementKit); document the required interfaces and structure.

QFramework is a well-architected system design framework with good separation of concerns following SOLID principles. No critical vulnerabilities were identified in the static structure analysis. The main security concerns are related to the absence of explicit input validation guidelines, missing security documentation, and lack of visible access control mechanisms. The framework itself is primarily an architectural pattern library and appears to shift security responsibility to implementers. Developers using this framework should implement comprehensive input validation, access control, and follow secure coding practices when implementing their own Commands, Systems, and Models. Recommend adding security best practices documentation to guide users in building secure applications.

• Medium · Lack of Input Validation in Architecture Framework — QFramework.Unity2018+/Assets/QFramework/Framework/Scripts/QFramework.cs and throughout Architecture/Command directories. The QFramework architecture provides a Command/Event system without explicit documentation of input validation mechanisms. Commands and Events are passed through the system without clear sanitization guidelines, which could lead to injection vulnerabilities if user input is not properly validated before being passed to Commands. Fix: Implement input validation and sanitization at the Command entry points. Create a validation layer that validates all user inputs before they are processed by Commands. Document security best practices for Command implementations.
• Low · Missing Security Documentation — Doc.md, QFramework API.md, README files. The framework lacks explicit security guidelines in its documentation. While the architecture is well-designed with SOLID principles, there is no visible security best practices guide for developers implementing systems with QFramework. Fix: Add a security section to the documentation covering: input validation patterns, safe event handling, secure data storage recommendations, and common vulnerability patterns to avoid when implementing the framework.
• Low · No Visible Access Control Implementation — QFramework.Unity2018+/Assets/QFramework/Framework/Scripts and related architecture files. The framework exposes System and Model layers to Controllers without explicit access control or permission verification mechanisms documented in the visible code structure. Fix: Implement and document access control patterns. Consider adding interface-based permission checks when accessing Systems and Models. Provide examples of secure access patterns in the documentation.
• Low · Potential Runtime Reflection Risks — QFramework.Godot4+/addons/qframework/plugin.cfg and related addon files. The framework uses a modular architecture that may rely on reflection for plugin/addon loading (visible in addon directories). Reflection-based code loading can be a security risk if not properly controlled. Fix: If reflection is used for plugin loading, implement whitelist-based validation of plugins. Only allow loading from trusted sources and validate plugin signatures. Document the plugin security model clearly.

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.