Extra2D/docs/module_system.md

# Extra2D 模块系统

## 概述

Extra2D 采用模块化架构设计，所有核心功能通过模块系统和服务系统管理。系统提供：

- **统一的生命周期管理**：初始化、关闭、依赖处理
- **优先级排序**：确保模块/服务按正确顺序初始化
- **配置驱动**：每个模块可独立配置
- **依赖注入**：通过服务定位器解耦模块间依赖
- **可测试性**：支持 Mock 服务进行单元测试

## 架构图

```
┌─────────────────────────────────────────────────────────────┐
│                      Application                             │
│  (协调模块和服务，通过服务定位器获取依赖)                       │
└─────────────────────────────────────────────────────────────┘
                              │
              ┌───────────────┴───────────────┐
              ▼                               ▼
┌─────────────────────────────┐   ┌─────────────────────────────┐
│      ModuleRegistry         │   │      ServiceLocator         │
│  (模块注册表，管理平台级模块) │   │  (服务定位器，管理运行时服务) │
└─────────────────────────────┘   └─────────────────────────────┘
              │                               │
        ┌─────┴─────┐                 ┌───────┴───────┐
        ▼           ▼                 ▼               ▼
┌───────────┐ ┌───────────┐   ┌───────────┐   ┌───────────┐
│  Config   │ │  Window   │   │  Scene    │   │  Timer    │
│  Module   │ │  Module   │   │  Service  │   │  Service  │
└───────────┘ └───────────┘   └───────────┘   └───────────┘
                                    │               │
                              ┌─────┴─────┐   ┌─────┴─────┐
                              ▼           ▼   ▼           ▼
                        ┌──────────┐ ┌──────────┐ ┌──────────┐
                        │  Event   │ │  Camera  │ │   ...    │
                        │  Service │ │  Service │ │          │
                        └──────────┘ └──────────┘ └──────────┘
```

## 模块 vs 服务

| 特性 | 模块 (Module) | 服务 (Service) |
|-----|--------------|---------------|
| 用途 | 平台级初始化 | 运行时功能 |
| 生命周期 | Application 管理 | ServiceLocator 管理 |
| 依赖方式 | 通过 ModuleRegistry | 通过 ServiceLocator |
| 可替换性 | 编译时确定 | 运行时可替换 |
| 测试支持 | 需要重构 | 原生支持 Mock |
| 示例 | Window, Render, Config | Scene, Timer, Event, Camera |

## 模块优先级

模块按优先级从小到大初始化，关闭时逆序执行：

| 优先级值 | 枚举名称 | 用途 | 模块示例 |
|---------|---------|------|---------|
| 0 | `Core` | 核心模块，最先初始化 | Logger, Config, Platform, Window |
| 100 | `Graphics` | 图形渲染 | Render |
| 200 | `Audio` | 音频系统 | Audio |
| 500 | `Resource` | 资源管理 | Resource |

## 服务优先级

服务按优先级从小到大初始化：

| 优先级值 | 枚举名称 | 用途 | 服务示例 |
|---------|---------|------|---------|
| 0 | `Core` | 核心服务 | - |
| 100 | `Event` | 事件系统 | EventService |
| 200 | `Timer` | 计时器 | TimerService |
| 300 | `Scene` | 场景管理 | SceneService |
| 400 | `Camera` | 相机系统 | CameraService |
| 500 | `Resource` | 资源管理 | - |
| 600 | `Audio` | 音频系统 | - |

---

## 模块系统

### IModuleConfig

模块配置接口，定义模块的元数据和配置：

```cpp
class IModuleConfig {
public:
    virtual ~IModuleConfig() = default;
    
    virtual ModuleInfo getModuleInfo() const = 0;
    virtual std::string getConfigSectionName() const = 0;
    virtual bool validate() const = 0;
    virtual void resetToDefaults() = 0;
    virtual bool loadFromJson(const void* jsonData) = 0;
    virtual bool saveToJson(void* jsonData) const = 0;
    virtual void applyPlatformConstraints(PlatformType platform) {}
};
```

### IModuleInitializer

模块初始化器接口，管理模块的生命周期：

```cpp
class IModuleInitializer {
public:
    virtual ~IModuleInitializer() = default;
    
    virtual ModuleId getModuleId() const = 0;
    virtual ModulePriority getPriority() const = 0;
    virtual std::vector<ModuleId> getDependencies() const = 0;
    
    virtual bool initialize(const IModuleConfig* config) = 0;
    virtual void shutdown() = 0;
    virtual bool isInitialized() const = 0;
};
```

### ModuleRegistry

模块注册表，管理所有模块：

```cpp
class ModuleRegistry {
public:
    static ModuleRegistry& instance();
    
    ModuleId registerModule(
        UniquePtr<IModuleConfig> config,
        ModuleInitializerFactory factory
    );
    
    IModuleConfig* getModuleConfig(ModuleId id);
    IModuleInitializer* getInitializer(ModuleId id);
    std::vector<ModuleId> getInitializationOrder() const;
};
```

---

## 服务系统

### IService

服务接口基类，所有服务必须实现：

```cpp
class IService {
public:
    virtual ~IService() = default;
    
    virtual ServiceInfo getServiceInfo() const = 0;
    virtual bool initialize() = 0;
    virtual void shutdown() = 0;
    virtual void pause();
    virtual void resume();
    virtual void update(float deltaTime);
    virtual bool isInitialized() const;
    
    ServiceState getState() const;
    const std::string& getName() const;
};
```

### ServiceLocator

服务定位器，实现依赖注入和服务发现：

```cpp
class ServiceLocator {
public:
    static ServiceLocator& instance();
    
    // 注册服务实例
    template<typename T>
    void registerService(SharedPtr<T> service);
    
    // 注册服务工厂（延迟创建）
    template<typename T>
    void registerFactory(ServiceFactory<T> factory);
    
    // 获取服务
    template<typename T>
    SharedPtr<T> getService() const;
    
    // 检查服务是否存在
    template<typename T>
    bool hasService() const;
    
    // 批量操作
    bool initializeAll();
    void shutdownAll();
    void updateAll(float deltaTime);
    void pauseAll();
    void resumeAll();
    void clear();
};
```

### 内置服务

#### SceneService

场景管理服务，包装 SceneManager：

```cpp
class ISceneService : public IService {
public:
    virtual void runWithScene(Ptr<Scene> scene) = 0;
    virtual void replaceScene(Ptr<Scene> scene) = 0;
    virtual void pushScene(Ptr<Scene> scene) = 0;
    virtual void popScene() = 0;
    
    virtual Ptr<Scene> getCurrentScene() const = 0;
    virtual size_t getSceneCount() const = 0;
    
    virtual void render(RenderBackend& renderer) = 0;
};
```

#### TimerService

计时器服务，包装 TimerManager：

```cpp
class ITimerService : public IService {
public:
    virtual uint32 addTimer(float delay, Timer::Callback callback) = 0;
    virtual uint32 addRepeatingTimer(float interval, Timer::Callback callback) = 0;
    virtual void cancelTimer(uint32 timerId) = 0;
    virtual void pauseTimer(uint32 timerId) = 0;
    virtual void resumeTimer(uint32 timerId) = 0;
};
```

#### EventService

事件服务，整合 EventQueue 和 EventDispatcher：

```cpp
class IEventService : public IService {
public:
    virtual void pushEvent(const Event& event) = 0;
    virtual bool pollEvent(Event& event) = 0;
    
    virtual ListenerId addListener(EventType type, EventCallback callback) = 0;
    virtual void removeListener(ListenerId id) = 0;
    
    virtual void dispatch(Event& event) = 0;
    virtual void processQueue() = 0;
};
```

#### CameraService

相机服务，整合 Camera 和 ViewportAdapter：

```cpp
class ICameraService : public IService {
public:
    virtual void setPosition(const Vec2& position) = 0;
    virtual void setZoom(float zoom) = 0;
    virtual void setRotation(float degrees) = 0;
    
    virtual glm::mat4 getViewProjectionMatrix() const = 0;
    virtual Vec2 screenToWorld(const Vec2& screenPos) const = 0;
    
    virtual void setViewportConfig(const ViewportConfig& config) = 0;
    virtual void updateViewport(int width, int height) = 0;
};
```

---

## 使用示例

### 在 Application 中使用服务

```cpp
// 获取服务
auto sceneService = Application::get().scenes();
auto timerService = Application::get().timers();
auto eventService = Application::get().events();
auto cameraService = Application::get().camera();

// 使用场景服务
sceneService->pushScene(myScene);

// 使用计时器服务
timerService->addTimer(1.0f, []() {
    E2D_LOG_INFO("Timer fired!");
});

// 使用事件服务
eventService->addListener(EventType::KeyDown, [](Event& e) {
    E2D_LOG_INFO("Key pressed: {}", e.key.keycode);
});

// 使用相机服务
cameraService->setPosition(Vec2(100.0f, 200.0f));
cameraService->setZoom(2.0f);
```

### 注册自定义服务

```cpp
// 定义服务接口
class IAudioService : public IService {
public:
    virtual void playSound(const std::string& path) = 0;
    virtual void stopAll() = 0;
};

// 实现服务
class AudioService : public IAudioService {
public:
    ServiceInfo getServiceInfo() const override {
        ServiceInfo info;
        info.name = "AudioService";
        info.priority = ServicePriority::Audio;
        return info;
    }
    
    bool initialize() override {
        // 初始化音频系统...
        setState(ServiceState::Running);
        return true;
    }
    
    void shutdown() override {
        // 清理音频系统...
        setState(ServiceState::Stopped);
    }
    
    void playSound(const std::string& path) override {
        // 播放音效...
    }
    
    void stopAll() override {
        // 停止所有音效...
    }
};

// 注册服务
Application::get().registerService<IAudioService>(makeShared<AudioService>());

// 使用服务
auto audio = Application::get().getService<IAudioService>();
audio->playSound("explosion.wav");
```

### 测试时注入 Mock 服务

```cpp
// 创建 Mock 服务
class MockSceneService : public ISceneService {
public:
    std::vector<std::string> sceneHistory;
    
    void pushScene(Ptr<Scene> scene) override {
        sceneHistory.push_back("push:" + scene->getName());
    }
    
    void popScene() override {
        sceneHistory.push_back("pop");
    }
    
    // 实现其他必要方法...
};

// 测试代码
void testSceneNavigation() {
    // 注入 Mock 服务
    auto mockService = makeShared<MockSceneService>();
    ServiceLocator::instance().registerService<ISceneService>(mockService);
    
    // 执行测试
    auto sceneService = ServiceLocator::instance().getService<ISceneService>();
    sceneService->pushScene(createTestScene("level1"));
    sceneService->pushScene(createTestScene("level2"));
    sceneService->popScene();
    
    // 验证结果
    assert(mockService->sceneHistory.size() == 3);
    assert(mockService->sceneHistory[0] == "push:level1");
    assert(mockService->sceneHistory[1] == "push:level2");
    assert(mockService->sceneHistory[2] == "pop");
}
```

---

## 创建新模块

### 步骤 1：定义配置类

```cpp
class MyModuleConfig : public IModuleConfig {
public:
    int someSetting = 42;
    
    ModuleInfo getModuleInfo() const override {
        ModuleInfo info;
        info.name = "MyModule";
        info.version = "1.0.0";
        info.priority = ModulePriority::Graphics;
        info.enabled = true;
        return info;
    }
    
    std::string getConfigSectionName() const override { return "my_module"; }
    bool validate() const override { return someSetting > 0; }
    void resetToDefaults() override { someSetting = 42; }
    bool loadFromJson(const void* jsonData) override;
    bool saveToJson(void* jsonData) const override;
};
```

### 步骤 2：定义初始化器

```cpp
class MyModuleInitializer : public IModuleInitializer {
public:
    ModuleId getModuleId() const override { return moduleId_; }
    ModulePriority getPriority() const override { return ModulePriority::Graphics; }
    std::vector<ModuleId> getDependencies() const override { return {}; }
    
    bool initialize(const IModuleConfig* config) override {
        if (initialized_) return true;
        
        const MyModuleConfig* cfg = dynamic_cast<const MyModuleConfig*>(config);
        if (!cfg) return false;
        
        // 执行初始化逻辑...
        
        initialized_ = true;
        E2D_LOG_INFO("MyModule initialized");
        return true;
    }
    
    void shutdown() override {
        if (!initialized_) return;
        // 执行清理逻辑...
        initialized_ = false;
        E2D_LOG_INFO("MyModule shutdown");
    }
    
    bool isInitialized() const override { return initialized_; }
    void setModuleId(ModuleId id) { moduleId_ = id; }

private:
    ModuleId moduleId_ = INVALID_MODULE_ID;
    bool initialized_ = false;
};
```

### 步骤 3：注册模块

```cpp
// my_module.cpp
#include <extra2d/config/module_registry.h>

namespace extra2d {

static ModuleId s_myModuleId = INVALID_MODULE_ID;

ModuleId get_my_module_id() { return s_myModuleId; }

void register_my_module() {
    if (s_myModuleId != INVALID_MODULE_ID) return;
    
    s_myModuleId = ModuleRegistry::instance().registerModule(
        makeUnique<MyModuleConfig>(),
        []() -> UniquePtr<IModuleInitializer> {
            auto initializer = makeUnique<MyModuleInitializer>();
            initializer->setModuleId(s_myModuleId);
            return initializer;
        }
    );
}

} // namespace extra2d
```

---

## 内置模块

### Logger 模块

**职责**：管理日志系统初始化和关闭

**配置**：
```cpp
LoggerModuleConfig config;
config.logLevel = LogLevel::Info;
config.consoleOutput = true;
config.fileOutput = true;
config.logFilePath = "app.log";
```

---

### Config 模块

**职责**：管理 ConfigManager 和应用配置

**配置**：
```cpp
ConfigModuleConfig config;
config.configPath = "config.json";
config.appConfig = AppConfig::createDefault();
```

---

### Platform 模块

**职责**：平台检测和平台特定初始化

**平台特定操作**：
- Switch：初始化 romfs 和 socket

---

### Window 模块

**职责**：窗口创建和后端管理

**后端支持**：
- SDL2：跨平台
- GLFW：跨平台
- Switch：原生

**配置**：
```cpp
WindowModuleConfig config;
config.windowConfig.title = "My App";
config.windowConfig.width = 1280;
config.windowConfig.height = 720;
config.windowConfig.vsync = true;
```

---

### Render 模块

**职责**：渲染器初始化和管理

**配置**：
```cpp
RenderModuleConfig config;
config.backend = BackendType::OpenGL;
config.vsync = true;
config.targetFPS = 60;
config.multisamples = 4;
```

---

## 配置文件格式

模块配置使用 JSON 格式：

```json
{
    "logger": {
        "logLevel": 2,
        "consoleOutput": true,
        "fileOutput": false
    },
    "window": {
        "title": "My Application",
        "width": 1280,
        "height": 720,
        "vsync": true
    },
    "render": {
        "targetFPS": 60,
        "multisamples": 4
    }
}
```

---

## 最佳实践

### 1. 模块用于平台初始化，服务用于运行时功能

```cpp
// 模块：平台级初始化
class WindowModule : public IModuleInitializer {
    bool initialize(const IModuleConfig* config) override {
        // 创建窗口、初始化 OpenGL 上下文
    }
};

// 服务：运行时功能
class SceneService : public ISceneService {
    void update(float deltaTime) override {
        // 每帧更新场景
    }
};
```

### 2. 通过服务定位器解耦依赖

```cpp
// 好的做法：通过服务定位器获取依赖
void MyNode::onUpdate(float dt) {
    auto camera = ServiceLocator::instance().getService<ICameraService>();
    auto pos = camera->screenToWorld(mousePos);
}

// 不好的做法：直接依赖 Application
void MyNode::onUpdate(float dt) {
    auto& camera = Application::get().camera();  // 耦合度高
}
```

### 3. 使用接口便于测试

```cpp
// 定义接口
class IAudioService : public IService { ... };

// 生产环境使用真实实现
auto audio = makeShared<AudioService>();

// 测试环境使用 Mock
auto audio = makeShared<MockAudioService>();
```

### 4. 安全关闭

```cpp
void shutdown() override {
    if (!initialized_) return; // 避免重复关闭
    
    // 清理资源
    resource_.reset();
    
    setState(ServiceState::Stopped);
    initialized_ = false;
}
```

---

## 调试

### 查看模块初始化顺序

```cpp
auto order = ModuleRegistry::instance().getInitializationOrder();
for (ModuleId id : order) {
    auto* config = ModuleRegistry::instance().getModuleConfig(id);
    if (config) {
        auto info = config->getModuleInfo();
        E2D_LOG_INFO("Module: {} (priority: {})", 
                     info.name, static_cast<int>(info.priority));
    }
}
```

### 查看服务状态

```cpp
auto services = ServiceLocator::instance().getAllServices();
for (const auto& service : services) {
    auto info = service->getServiceInfo();
    E2D_LOG_INFO("Service: {} (state: {})", 
                 info.name, static_cast<int>(info.state));
}
```

---

## 示例

完整示例请参考：
- [examples/basic/main.cpp](../../examples/basic/main.cpp) - 基础示例
- [Extra2D/src/services/scene_service.cpp](../../Extra2D/src/services/scene_service.cpp) - Scene 服务实现
- [Extra2D/src/services/event_service.cpp](../../Extra2D/src/services/event_service.cpp) - Event 服务实现
- [Extra2D/src/platform/window_module.cpp](../../Extra2D/src/platform/window_module.cpp) - Window 模块实现
- [Extra2D/src/graphics/render_module.cpp](../../Extra2D/src/graphics/render_module.cpp) - Render 模块实现