Stop fighting menus, meta, gameplay, and scenes
Hierarchical game state architecture for managing game states and scenes
Clean and testable from prototype to productionFlexy.AssetRefs 6.1.0 and Flexy.Core 6.1.2 packages bundled insideGitHub | Docs | ForumOverviewFlexy.GameFlow is a runtime architecture framework for Unity that replaces fragmented, ad-hoc game flow logic with explicit hierarchical statesInstead of spreading flow logic across scenes, managers, FSMs, coroutines, and callbacks, your game becomes a structured State graph with clear ownership and lifecycleGlobal stages like Boot → Menu/Meta → Play/Core are first-class runtime statesUI screens are statesGameplay phases are statesCutscenes, popups, boss fights, results, and overlays are statesScenes are used where they make sense and are controlled by states when neededTransitions are deterministic and awaitableAny state can be launched and tested in isolationFlexy.GameFlow has been used and refined in real production projects since 2014When Game Starts Working Against YouAs projects grow, game flow logic becomes fragile and hard to reason aboutAdding a new menu or gameplay step introduces hidden couplingFlow logic becomes scattered across scenes, managers, and MonoBehavioursAsync transitions turn into complex coroutine or callback chainsDependencies spread across unrelated systems, even when using DITesting a single screen or gameplay phase requires running the entire gameFlexy.GameFlow addresses these problems by designOne hierarchical state model for boot, menus, and gameplayAny state can be launched and tested directlyEnter Play Mode from any scene with the correct state hierarchy on frame 0Scene loading and unloading driven by statesAwaitable states with explicit input and outputDeterministic transitions with guaranteed execution orderClean lifecycle ownership and automatic cleanupScales naturally from prototype to productionWhat Flexy.GameFlow IsFlexy.GameFlow is a production-grade runtime framework that structures the entire game as explicit hierarchical statesIt orchestrates:Global game stages (Boot → Menu/Meta → Play/CoreUI navigation as states (Main Menu, Settings, Shop, Rewards, Arsenal)Gameplay states (Play, Pause, Win, Lose, Results, Cutscenes, Dialogs)Nested substates (Boss fights, result tabs, phase controllers)Scenes, transitions, data flow, and runtime context are controlled through the state hierarchyThis keeps every part of the game isolated, testable, and deterministicKey BenefitsOne unified system for game flow, scenes, and UIExplicit hierarchical state architectureScene-independent navigationDeterministic async transitionsLaunch any state directly for testingScoped service lifecycle per GameStageSafe from prototype to long-term productionRemoves the need for custom flow managersHow It WorksCreate a State MonoBehaviour describing behaviorCreate a prefab representing that stateState is automatically added to the FlowGraphOpen states through ServiceGameFlowStates load scenes, manage transitions, and return resultsGame flow becomes navigation between states rather than hardwired scene switchingKey FeaturesHierarchical GameStages (Boot, Menu, Gameplay)FlowGraph & FlowNodes for logical navigationState-driven scene loading (Single & Additive)Back/Forward navigation with historyAwaitable states with explicit resultsGameContext scoped per GameStagePlay Mode entry from any sceneTestScenes and TestCases for isolationCrossSceneRef systemTransitionHost for safe visual transitionsIs This for You?Flexy.GameFlow is a good fit if you:Build games with multiple menus and gameplay phasesStruggle with fragmented or ad-hoc game flow logicWant deterministic async transitionsNeed fast iteration and isolated testingWork solo or in a teamPlan long-term productionFlexy.GameFlow is not a good fit if you:Build very small single-scene gamesPrefer fully hardcoded scene logicExpect a visual no-code flow editorFlexy.GameFlow is an architectural foundation and is intended to be adopted earlyWhy Not FSMs or Scene Managers?Classic FSMs do not scale to full game hierarchies with async transitionsScene managers couple logic to scenes and make testing difficultFlexy.GameFlow treats game states as first-class, with hierarchy, isolation, and deterministic transitionsIt uses standard Unity concepts with minimal additional abstractions, so it feels like vanilla Unity — just much more powerfulIt provides a higher-level orchestration layer that defines how game states relate, transition, and execute safelyShowcase ProjectsLearn through real, buildable template projectsFlexyTT.Barley-BreakFlexy.TTMinimal GameFlow ShowcaseThese demonstrate full game flow, scene control, UI states, and testing workflowsAdditional GameFlow Pro CapabilitiesCustomizable transition logic for unique and rich state transitionsExtended control over Play Mode initializationState lockingAdditional virtual Open/Close and Forward/Back lifecycle methodsSupport for substate layers (e.g. popup layer)Deterministic await points for logical and visual state changesAsynchronous preload of state viewsRestart, Respawn, Reboot abilitiesAnd more...CompatibilityUnity 2022.3 → Unity 6.3Modern C# (C# 10)Domain Reload safeDepends on Flexy.Core & Flexy.AssetRefsSceneManager used under the hood via SceneRefsRender pipeline agnosticPlatform agnosticNetworking friendlyCode BasicsSingle State base class for all state types (gameplay, UI, substates)Virtual Show/Hide and BackShow/ForwardHide methodsDeterministic bootstrap initializes the correct state hierarchy from any sceneExplicit state cleanup via Stage.CloseAndDestroyExplicit input and output data passed between statesAwaitable states and transitions with strongly defined resultsCross-scene references without hard scene dependenciesBootstrap prefab initializes the Service_GameFlow runtimeExplicit GameStage abstraction for major phases (Boot, Menu, Play)FlowLibrary is centralized registry of statesGraph-based state model using FlowGraph and FlowNodeRuntime tracking of active and current state nodes
