f8-features-module-workflow

name	f8-features-module-workflow
description	Use when implementing or troubleshooting Module feature workflows — ModuleCenter lifecycle, module creation, StaticModule, ActivityModule, update attributes in F8Framework.

Module Feature Workflow

⚠️ IMPORTANT: Before using this feature, you MUST formally initialize F8Framework in the launch sequence. Ensure ModuleCenter.Initialize(this); has run first before any ModuleCenter.CreateModule<T>() call.

Use this skill when

• The task is about creating custom modules, managing module lifecycle, or using StaticModule / ActivityModule.
• The user asks about ModuleCenter, module initialization order, or update loops.

Path resolution

1. Prefer project source at Assets/F8Framework.
2. For usage docs, read: Assets/F8Framework/Tests/Module/README.md

Sources of truth

• Runtime module: Assets/F8Framework/Runtime/Module
• Editor module: Assets/F8Framework/Editor/Module
• Test docs: Assets/F8Framework/Tests/Module

Key classes and interfaces

Class	Role
ModuleCenter	Core lifecycle management. Initialize, Create, Get, Destroy modules.
ModuleSingleton<T>	Non-MonoBehaviour module base with singleton.
ModuleSingletonMono<T>	MonoBehaviour module base with singleton.
IModule	Module interface: OnInit, OnUpdate, OnLateUpdate, OnFixedUpdate, OnTermination.
StaticModule	Auto-initialized static modules with OnEnterGame/OnQuitGame.
ActivityModule	Auto-discovered activity modules with unlock/visible/open state evaluation and state change callbacks.

API quick reference

ModuleCenter usage

// Initialize with MonoBehaviour driver
ModuleCenter.Initialize(this);

// Create module with optional priority (lower = earlier update)
ModuleCenter.CreateModule<TimerManager>(100);

// Access module
ModuleCenter.GetModule<TimerManager>().GetServerTime();
// Or via singleton
TimerManager.Instance.GetServerTime();

Custom module template

[UpdateRefresh]
[LateUpdateRefresh]
[FixedUpdateRefresh]
public class MyModule : ModuleSingleton<MyModule>, IModule
{
    public void OnInit(object createParam)
    {
        // Module created
    }
    public void OnUpdate() { }
    public void OnLateUpdate() { }
    public void OnFixedUpdate() { }
    public void OnTermination()
    {
        Destroy(gameObject);
    }
}

StaticModule template

public class MyStaticModule : StaticModule
{
    public static MyStaticModule Instance => GetInstance<MyStaticModule>();

    protected override void Init() { }
    public override void OnEnterGame() { }
    public override void OnQuitGame() { }
}

// Usage
StaticModule.GetStaticModule();                      // Get all
StaticModule.GetStaticModuleByType(typeof(MyStaticModule)); // Get one
MyStaticModule.Instance.OnEnterGame();

// Iterate all static modules
foreach (var center in StaticModule.GetStaticModule())
{
    center.Value.OnEnterGame();
}

ActivityModule template

public class MyActivityModule : ActivityModule
{
    public static MyActivityModule Instance => GetInstance<MyActivityModule>();

    protected override void Init() { }
    public override void OnEnterGame() { }
    public override void OnQuitGame() { }
    protected override bool EvaluateUnlockedCore() => true;
    protected override bool EvaluateVisibleCore(bool isUnlocked) => isUnlocked;
    protected override bool EvaluateOpenCore(bool isUnlocked) => isUnlocked;
    protected override void OnStateChanged(ActivityModuleState previousState, ActivityModuleState currentState) { }
}

// Usage
ActivityModule.GetActivityModule<MyActivityModule>();
ActivityModule.GetActivityModules();      // Get all instances
ActivityModule.GetActivityModuleTypes();  // Get all discovered types
ActivityModule.RefreshAllModules();       // Re-evaluate activity state

Update attributes

• [UpdateRefresh] — Enable OnUpdate loop
• [LateUpdateRefresh] — Enable OnLateUpdate loop
• [FixedUpdateRefresh] — Enable OnFixedUpdate loop

Module creation (right-click menu)

Right-click in Project → F8 Module Center → Create Module / ModuleMono / StaticModule / ActivityModule template.

Workflow

1. Decide module type: ModuleSingleton<T> (pure C#) or ModuleSingletonMono<T> (MonoBehaviour).
2. Implement IModule interface.
3. Add update attributes as needed.
4. Create module via ModuleCenter.CreateModule<T>() with priority.
5. For auto-initialized global modules, use StaticModule pattern.
6. For activity gating and state-driven modules, use ActivityModule pattern.
7. Use right-click context menu to generate template files.

Module types comparison

Type	Base Class	MonoBehaviour	Init	Update	Usage
Game Module	ModuleSingleton<T>	No	Lazy via CreateModule	Via attributes	Most modules
Game Module Mono	ModuleSingletonMono<T>	Yes	Lazy via CreateModule	Via attributes	Needs coroutines
Static Module	StaticModule	No	Auto on game start	Manual	Global utilities
Activity Module	ActivityModule	No	Auto-discovered and initialized	State refresh via RefreshAllModules	Unlock/show/open activity logic

Common error handling

Error	Cause	Solution
Module is null	Not created via CreateModule	Create before accessing
Update not running	Missing [UpdateRefresh] attribute	Add appropriate attribute
Module init order issue	Dependency module not yet created	Adjust priority or creation order

Cross-module dependencies

• Foundation: GameLauncher uses ModuleCenter to create all framework modules.

Output checklist

• Module type selected (Singleton / SingletonMono / StaticModule / ActivityModule).
• Lifecycle methods implemented.
• Update attributes applied.
• Validation status and remaining risks.