5.2K stars: Unity/Godot architecture in <1000 lines

You know that feeling when your Unity project hits 6 months and suddenly every script references every other script? Your Player script talks to UIManager which talks to GameController which talks back to Player, and fixing one bug breaks three features? That's the architecture void most Unity developers fall into. Unity gives you MonoBehaviour but no guidance on how to organize thousands of them into a maintainable system.

Think of it like a strict building code for your game. Everything goes into one of 4 layers: Presentation (MonoBehaviours, UI), System (stateful logic like AchievementSystem tracking progress), Model (data + data methods), Utility (stateless tools like StorageUtility or StringEncryption). The critical distinction: Systems are stateful and persist across scenes, while Utilities are stateless helper functions. The key rule: upper layers can query lower layers directly, but state changes flow down through Commands, and notifications flow up through Events. Your Player MonoBehaviour can read from PlayerModel, but to change health it sends a TakeDamageCommand, which updates the model, which fires a HealthChangedEvent that the UI listens to.

• 4-layer architecture with enforced rules — Presentation, System (stateful), Model, Utility (stateless) layers with strict communication patterns prevent circular dependencies
• QFramework.cs core <1000 lines — the minimal architecture kernel you can read in one sitting, copy as a single file, or modify; completely decoupled from toolkits
• Modular Toolkits (UIKit, ActionKit, ResKit, AudioKit) — optional extensions for UI management, action sequences, resource loading, and audio; use only what you need
• Command pattern for state changes — all mutations flow through Commands, making debugging and undo systems straightforward
• Event-driven updates — Models fire events on changes, so UI updates automatically without tight coupling
• Unity 2018-6.x and Godot 4 support — same architecture works across both engines (Godot requires C#/.NET, not GDScript)
• Production-proven — multiple shipped Steam games (乌合之众, 银河摸鱼人, ScaleBox, etc.) demonstrate real-world viability

Who It Is For

If you're a Unity developer whose projects turn into spaghetti after 3 months, or you've heard about DDD/CQRS but don't know how to apply them to games, this is for you. Also valuable if you're building medium-to-large indie games and want architecture that scales beyond prototypes. Not useful if you're making game jam projects under 48 hours, or if you prefer visual scripting over code architect...

Worth Exploring?

Yes, especially if you've hit the 'Unity architecture wall' where your projects become unmaintainable. The 5.2K stars and 10-year development history show sustained value. The trade-off: expect a learning curve (understanding the 4 layers and their rules), and documentation is primarily in Chinese (English exists but less complete). Start with the included example projects (CounterApp, FlappyBird clone) to see the patterns in action before adopting.