Before calling any skill in this module: if you are about to call a skill with parameters guessed from its name or description, STOP — read this file (or fetch its schema via
GET /skills/recommend?includeSchema=true) first. If you already have the parameter definitions from recommend/schema, you may proceed straight to dryRun.
Triggers
- Writing or reviewing QFramework architecture code (Controller/System/Model/Utility)
- Registering Systems/Models/Utilities, sending Commands/Queries/Events
- Binding BindableProperty / BindableList / BindableDictionary in views
- Choosing between the core IOCContainer and the Toolkits IOCKit, or between architecture events and EasyEvent
- Write or review QFramework architecture code, four-layer responsibility division, Command/Query/Event/BindableProperty usage, core container and Toolkits container selection
Advisory module. All rules are distilled from the official QFramework source code and tutorials:
- QFramework.cs(single-file core architecture source code, repository root
QFramework.cs, internal comments annotatedLatest Update: 2026.8.12 return module instance after register） - Doc.md(full text of the official tutorial, 8820 lines, repository root
Doc.md） - QFramework API.md(signature index of the core layer; Toolkits is not covered, and as of this capture has still not synced the 2026-08-12 return value change)
Each rule is annotated with the specific file/line number (line numbers correspond to the upstream liangxiegame/QFramework main repository v1.0.257 snapshot; Toolkits source code is located at QFramework.Unity2018+/Assets/QFramework/). When there is a discrepancy, QFramework.cs source code prevails; Doc.md/API.md are only for cross-verification—the tutorial itself may lag behind the source code. The body text is in Chinese; API names/code remain in English.
Mode: Documentation only — no REST skills to gate; load freely under any operating mode (Approval / Auto / Bypass).
When to Load This Module
Load before generating or reviewing any of the following:
Architecture<T>subclass'sInit()startup logic,RegisterSystem/RegisterModel/RegisterUtilitycallsIController / ISystem / IModel / IUtilityinterface implementations, or adding/removingICan*capability interfaces for these interfacesSendCommand / SendQuery / SendEvent / RegisterEventcalls,ICommand / ICommand<TResult> / IQuery<TResult>implementationBindableProperty<T> / BindableList<T> / BindableDictionary<TKey,TValue>declaration, Register/RegisterWithInitValue/Comparer usageTypeEventSystem/EasyEventseries registration and manual unregistration- Override
Architecture<T>.ExecuteCommandto do Command interception (logging/middleware/undo/automated testing) - Determine whether a piece of data should go in the Model or remain local to the MonoBehaviour
- In the
IOCContainerthat comes with QFramework.cs and ToolkitsCoreKit.IOCKit（IQFrameworkContainer+[Inject]) selection - Toolkits installation form confirmation (unitypackage import
Assets/, no UPM), version number verification
Critical Rule Summary
| # | Rule | Source anchor |
|---|---|---|
| 1 | RegisterSystem<T>/RegisterModel<T>/RegisterUtility<T> Returns the registered instance itself(no longer void), effective since 2026-08-12;IArchitecture The interface has declared the TSystem/TModel/TUtility return type. All tutorial examples in the official Doc.md (including the "Designing Modules with Interfaces" section, lines 2408-2422) still use the old style of discarding the return value;is an outdated example and does not represent current recommended usage |
QFramework.cs:43,45,47,132-163 |
| 2 | Four-layer interfaces:IController(226) ISystem(235) IModel(264) IUtility(291)；ICommand(299) / ICommand<TResult>(305)；IQuery<TResult> has only the generic form,has no non-generic IQuery(342) |
QFramework.cs:226,235,264,291,299,305,342 |
| 3 | General layering rules: IController changing System/Model state must go through Command; System/Model notifying upper layers must use Event or BindableProperty; upper layers can directly obtain lower layers,lower layers cannot obtain upper layers; Command/Query cannot have state. The rules are an "ideal state"; the author's own words allow relaxing them as needed (e.g., appending to IController ICanSendEvent） |
Doc.md:2682-2820(relaxation statement at 2791, interface modification example at 2793-2805) |
| 4 | Determine whether data should go in the Model: only three categories go in the Model—shared over time (persisted across launches), shared physically (resident in memory across screens/scenes), and configuration tables; counterexample—Enemy health does not go in the Model, leave it to the enemy script to manage itself | Doc.md:4051-4077(counterexample 4064-4066) |
| 5 | BindableProperty<T>.Value setter relies on Comparer to compare for equality before triggering the event;ComparerAutoRegister（[RuntimeInitializeOnLoadMethod]) has already replaced the default Equals with ==。Register only subscribes to subsequent changes,RegisterWithInitValue will first invoke the callback once with the current value |
QFramework.cs:711,762-789,740-749 |
| 6 | BindableList<T> / BindableDictionary<TKey,TValue> is a Toolkits add-on tool added only on 2024-09-18/19 (_CoreKit/BindableKit/, not in the QFramework.cs single file), an edge tool rather than a core concept; the author's own words admitnot knowing what scenarios BindableDictionary can be used in.— evaluate on demand, do not treat it as a default choice.BindableList Indexer assignment only triggers OnReplace，Move only triggers OnMove(neither will also trigger OnAdd/OnRemove） |
Doc.md:8438-8592,8593-8712(original words 8595);BindableList.cs:38-115,BindableDictionary.cs:17-44 |
| 7 | Choose one of three event tools:TypeEventSystem(cross-object, supports interface-inherited events, suitable for general systems)/EasyEvent(decoupled from architecture, more lightweight, no field names)/architecture built-in SendEvent(based on a TypeEventSystem instance). Manual unregistration must usenamed methods(anonymous delegates cannot -=）；UnRegisterWhenCurrentSceneUnloaded() No need to pass a GameObject, automatically cleared when changing scenes; event types are recommended to use struct to reduce GC |
Doc.md:3305-3461(summary 3440-3461),QFramework.cs:610-611,624-641 |
| 8 | Command interception: override Architecture<T>.ExecuteCommand(ICommand)(insert a segment of logic before and after) can be used for logging/middleware/undo/automated testing; the official source code's default implementation simply directly command.Execute() |
Doc.md:3137-3186，QFramework.cs:183-187 |
| 9 | Do not confuse the two container sets: core IOCContainer（Dictionary<Type,object>, singleton registration/retrieval only,Architecture<T> internally privately holds one copy, no reflection); Toolkits CoreKit.IOCKit（IQFrameworkContainer/QFrameworkContainer) is a completely independent reflection-based dependency injection implementation—supports type mapping, named registration, relationship mapping, by [Inject] attribute for field/property injection, automatically resolving dependencies based on the public constructor with the most parameters—not in the QFramework.cs source file |
Core:QFramework.cs:130,647-684；Toolkits：IOCKit.cs:19-31,33-136,141,239-263,315-358（_CoreKit/IOCKit/IOCKit.cs） |
| 10 | Toolkits installation form:.unitypackage Import Assets/，No UPM package; for the installed version, see the PackageKit editor panel or the installation directory's PackageVersion.json, GitHub/Gitee Release tags lag behind the PackageKit real-time source |
Doc.md:4178-4182；PackageData.cs:286（PackageVersion.json write path, Toolkits source code) |
Sub-doc Routing
| Sub-doc | When to read |
|---|---|
| LAYERS.md | Four-layer interfaces and responsibilities, general rules and relaxation methods, shared data criteria, Command interception,Architecture<T> lifecycle (InitArchitecture/Deinit） |
| BINDABLE_QUERY.md | BindableProperty(including Comparer/RegisterWithInitValue),BindableList/BindableDictionary、Command vs Query CQRS division of labor |
| EVENT_TOOLS.md | TypeEventSystem、EasyEvent family,IOCContainer(core) vs IOCKit(Toolkits), unregistration modes (UnRegisterWhenGameObjectDestroyed/UnRegisterWhenCurrentSceneUnloaded/IUnRegisterList） |
| CODEGEN_UIKIT.md | CodeGenKit two-stage code generation (Designer override rules, namespace migration, ScriptsFolder no fallback, ViewController nesting, OtherBinds) and UIKit interface workflow (panel toggling/lifecycle/hard pitfall of choosing the wrong UIRoot with Apply/UIKitSettingData configuration) |
| RESKIT.md | ResKit resource scheme: AssetBundle marking granularity, scene-exclusive AB, simulation/non-simulation mode, ResLoader reference counting semantics, build output directory, Unity official bug with AB cross-package Prefab dependencies |
| ACTIONKIT.md | ActionKit chained action sequences (Delay/Sequence/Parallel/Repeat/Condition, global lifecycle, TimeScale and scene switching), SingletonKit six singleton choices, AudioKit three channels andthe pitfall that pure editor-mode access to Settings causes an NPE、ScreenTransition |
| DATA_KITS.md | FSMKit (chained vs class mode), TableKit (joint queries and internal infrastructure positioning), PoolKit (semantic differences between the two pools), GridKit/DynaGrid |
Routing to Other Modules
- REST endpoint/operation-level QFramework skill calls → load the parallel-written qframework REST module (this module only covers design rules, not REST parameters)
- Bridging with UniTask/coroutines (ActionKit sequences vs async) → unitask-design / async
- Overall architecture layering review, state management selection → architecture / patterns
- Performance review of high-frequency event/BindableProperty trigger scenarios → performance
- Resource lifecycle when ResKit uses Addressables underneath → addressables-design
- Asmdef layout (QFramework.cs and Toolkits assembled separately) → asmdef
Version Scope
Anchored v1.0.257(the comments inside QFramework.cs were last updated on 2026-08-12; this module was captured in 2026-08).
- QFramework.cs is the single-file core architecture; its version number is not released independently from Toolkits but follows the GitHub/Gitee main repository tags.
- Toolkits (CoreKit/UIKit/ResKit/ActionKit/AudioKit/PackageKit…) versions are subject to the PackageKit panel/
PackageVersion.jsonand may be ahead of the unitypackage snapshot referenced by this module. - Key watershed:
RegisterSystem/RegisterModel/RegisterUtilityThe semantic of the return value changed from void to returning an instance on 2026-08-12—any third-party tutorials or historical code that reference a version earlier than this may have examples that do not match the current source signatures; refer to QFramework.cs.
When in doubt, go read the line numbers referenced in the source code, rather than relying on memory or old tutorial examples.
Known Gaps
- Zero coverage of LocaleKit in official tutorials: The entirety of Doc.md mentions LocaleKit in only one sentence in the tool list ("localization & multilingual toolkit"), with no usage examples or API documentation. From the source code, it is currently mainly an in-editor CN/EN display toggle (
LocaleKitEditor.IsCN，EditorPrefskeyEDITOR_CN) plus a language definition ScriptableObject (LanguageDefineConfig），it is not a complete multilingual solution for game runtime text, which is a gap compared with its self-description. When runtime localization is needed, do not assume LocaleKit can handle it directly; read the source code to confirm first. - FluentAPI method list not itemized：
_CoreKit/FluentAPI/covers a large number of chainable extensions for GameObject/Transform/Camera/Color/Graphic/Vector/RectTransform and C# primitive types; the quantity is too large to expand in this module; when needed, look up the corresponding source file according to the target type.