QFramework: a sub-1000-line C# architecture for Unity and Godot game projects

The problem QFramework solves: game code with no layer contract

Unity projects tend to rot in a predictable way. A MonoBehaviour starts as a view, then accumulates save logic, then a static singleton for the score, and six months later nothing can be tested or deleted. QFramework's answer is a written set of layer rules rather than a library of helpers. The README states the project provides an architecture that follows SOLID, supports domain-driven design, event-driven and data-driven styles, layering, MVC, CQRS and modularity, and that the source is under 1000 lines and small enough to keep in a note-taking app.

The audience is therefore specific. It is for Unity developers who already feel the pain of view code reaching into data, and who want a small, readable contract they can hand to a new team member. It is not for someone who wants a component library to speed up a weekend prototype. The repository also carries a QFramework.Godot4.5+ directory and Godot-related topics, so the same layering idea is being carried toward Godot 4.5 and later, but the README's install section and its documented runtime range (Unity 2018.4.x to Unity 6.x) are written around Unity.

The four layers, Command, and the direction rules

The architecture has four layers plus one concept. The presentation layer is the ViewController layer, implemented through an IController interface; MonoBehaviour classes are described as belonging there. It may fetch systems, fetch models, send commands and listen to events. The system layer holds ISystem implementations for logic shared across several views, such as a timer system, a shop system or an achievement system; it may fetch systems and models, listen to events and send events. The data layer holds IModel implementations that define data and the methods that add, remove, query and modify it; it may fetch utilities and send events. The utility layer holds IUtility implementations for infrastructure such as storage, serialization, networking, Bluetooth, SDKs and framework integration.

Command is the fifth piece and the one that carries the design. A command may fetch systems and models, and may send events and further commands. The README states that a command must have no state. The direction rules are the part worth reading twice: a controller must change system or model state through a command; a system or model notifies controllers of a change through an event or a BindableProperty; a controller may fetch systems and models for queries; upper layers may reach lower layers but lower layers may not hold references to upper layers; lower layers communicate upward with events; upper layers call downward with methods, but state changes go through commands. The README adds that controller interaction logic is a special case that must also use commands.

That is a CQRS split in miniature: reads are direct calls, writes are command objects. The cost is real. Every state change becomes a class, and a small feature can produce three or four files before it does anything visible. The benefit is that the write path is enumerable, which matters when you need to log, replay or undo.

Installing QFramework.cs and running the first example

The README lists four distribution channels rather than a package manager command. QFramework.cs on its own is installed by copying the file into any script in your own project. QFramework.cs together with the official examples is a unitypackage download. QFramework.ToolKits, which bundles CoreKit, UIKit, ActionKit, ResKit, PackageKit and AudioKit, is a separate unitypackage. QFramework.ToolKitsPro is installed from the Unity Asset Store. There is no documented npm, NuGet or UPM install step, so the first code block below is the whole install for the core architecture.

# QFramework.cs install, per the README:
# copy QFramework.cs from the repository into any script in your project.
# QFramework.cs + official examples: import QFramework.cs.Examples.unitypackage
# QFramework.ToolKits: import QFramework.ToolKits.unitypackage
# QFramework.ToolKitsPro: install from the Asset Store

The examples unitypackage is the fastest way to see the intended shape, because it contains CounterApp, FlappyBird, CubeMaster, ShootingEditor2D and a snake game. Import it into an empty Unity project inside the documented 2018.4.x to Unity 6.x range, then open the CounterApp scene. What you should see is the split in practice: a view that only renders and forwards input, a model that owns the count, and a command that performs the increment.

Once you have read one example, the first real use is to copy the file into your own project and add a model and a command for something you already have. The README does not provide a minimal code snippet for that, so the reliable path is to mirror CounterApp's structure: define an IModel for your data, define a command that mutates it, and have your MonoBehaviour controller send the command. The repository also ships QFramework API.md and Doc.md at the top level, which are the places to check method names rather than guessing.

Where QFramework is the wrong tool

The layer rules are conventions, not constraints. Nothing in the repository description suggests the compiler or an analyzer stops a MonoBehaviour from mutating a model field directly. If your team will not read the rules, the architecture degrades into ordinary Unity code with extra indirection, which is the worst of both worlds.

There is a second boundary. The README documents Unity 2018.4.x through Unity 6.x, and the most recent release listed is v1.0.246-Unity2018Compatible from 2026-05-27, with a v1.0.187-Unity2018Compatible release in 2025 and v1.0.180 in February 2025. The version naming is tied to Unity 2018 compatibility, which tells you the project values a long support tail over chasing new engine APIs. If you depend on a recent Unity feature that conflicts with that compatibility posture, you are outside the documented target.

The Godot side is the third boundary. The repository contains QFramework.Godot4.5+ and Godot topics, but the README's install instructions, examples and runtime range are Unity-specific. Treat the Godot directory as a separate, less documented track rather than an equivalent port, and verify it against your Godot version before planning around it.

Finally, the documentation is split across a Chinese README, an English README_EN.md, Doc.md and QFramework API.md, and much of the tutorial material is video content on Chinese platforms. If your team cannot read Chinese, budget time for the English file plus the source itself.

QFramework compared with GameFramework and FairyGUI

GameFramework appears in the same search space and takes the opposite approach. It is a runtime framework that owns the game loop, entities, resources and procedure flow; you build inside its structure. QFramework does not own your loop. It is a discipline for organizing code you already write, and its core is a single file you can read in one sitting. The practical difference: adopting GameFramework is closer to adopting an engine layer, while adopting QFramework.cs is closer to adopting a coding standard with a small amount of supporting code.

FairyGUI sits in a different category entirely. It is a UI editor and runtime for building interfaces, and it is commonly used alongside an architecture rather than instead of one. QFramework's own ToolKits bundle includes UIKit, so if your reason for looking at QFramework is UI, check whether UIKit covers your case before adding a second UI system to the project.

The honest summary is that QFramework's differentiator is size and rule clarity, not features. A sub-1000-line core is a genuine constraint on what it can do for you, and the README treats that as the selling point.

Licence, maintenance and what an upgrade costs

The repository is MIT licensed, and the README repeats the MIT badge. That permits commercial use and modification with the licence and copyright notice retained; it is a permissive licence, not a copyleft one, so it does not obligate you to publish your game's source. This is a description of the licence text, not legal advice, and the ToolKitsPro channel is an Asset Store purchase, so the terms attached to that paid package are a separate question from the MIT licence on the repository.

Maintenance signals are mixed and worth stating plainly. The last push to the default branch was on 2026-09-20, which is recent. The release cadence is slower: v1.0.180 in February 2025, v1.0.187-Unity2018Compatible in April 2025, and v1.0.246-Unity2018Compatible in May 2026. So the code moves more often than the tagged releases.

Upgrade cost depends on which channel you chose. If you copied QFramework.cs into your project, upgrading is a file diff, and the small core makes that diff readable. If you imported the ToolKits unitypackage, an upgrade means re-importing and reconciling whatever you changed in the imported assets, which is the usual unitypackage problem. If you bought ToolKitsPro from the Asset Store, upgrades run through the Asset Store rather than the repository. The README does not document a rollback procedure for any of these, so keep your own copy of the version you shipped with.

Editorial conclusion

Adopt QFramework if you are building a Unity game with more than one programmer and you want a written layer contract that keeps view code out of data code. Do not adopt it if you are prototyping alone, or if you need the framework to stop you from breaking its own rules: nothing in the repository enforces the layer boundaries at compile time. Before committing, read QFramework.cs end to end, check that the Unity version you target is inside the documented 2018.4.x to 6.x range, and confirm which of the four distribution channels you actually need, because QFramework.cs, QFramework.Toolkits and QFramework.ToolKitsPro ship different amounts of code under the same name.

Frequently asked questions

Official sources

1. liangxiegame/QFramework on GitHub
2. License: MIT
3. Project website
4. README
5. Releases