DearTs Framework 开发技能

概述

DearTs 是一个基于 SDL3 + ImGui 的现代 C++20 应用程序框架，参考 ImHex 设计理念，提供完整的模块化架构。

核心特性：

C++20 (Concepts, Ranges, std::format)
SDL3 + ImGui 2.13.3 (Docking, Multi-viewport)
类型安全事件总线 (EventBus)
Result<T, E> 错误处理
Content Registry (ImHex 风格命令/工具/设置系统)
多视图停靠窗口系统
插件架构 (API 版本检查，动态加载)
异步日志 (liblogger)
任务管理器 (TaskManager)
配置管理 (ConfigManager)

快速开始

1. 项目结构

DearTs/
├── core/              # 核心系统
│   ├── app/           # 应用生命周期
│   ├── events/        # 事件总线
│   ├── ui/            # ImGui 集成、视图
│   ├── content/       # Content Registry
│   ├── tasks/         # 任务管理
│   ├── plugin/        # 插件系统
│   └── config/        # 配置管理
├── plugins/           # 插件实现
│   └── builtin/       # 内置插件
└── main/gui/          # 入口

2. 创建应用

#include "core/app/application.h"

class MyApp : public DearTs::Core::Application {
    bool on_initialize() override {
        LOG_INFO("Application starting");
        return true;
    }

    void on_render() override {
        ImGui::Begin("Hello");
        ImGui::Text("Hello DearTs!");
        ImGui::End();
    }
};

int main() {
    MyApp app;
    return app.run();
}

3. 创建插件

#include "core/plugin/plugin.h"

class MyPlugin : public IPlugin {
public:
    PluginInfo get_info() const override {
        return PluginInfo{
            .name = "MyPlugin",
            .author = "You",
            .description = "My plugin",
            .version = "1.0.0",
            .api_version = "1.0.0"
        };
    }

    Result<void, std::string> on_load() override {
        // 注册命令、视图
        ContentRegistry::Commands::register_handler(
            "my.action", "My Action", []() { /* ... */ }
        );
        ContentRegistry::Views::add<MyView>();
        return Result::ok();
    }
};

// 注册插件
PluginManager::instance().add_builtin(
    std::make_unique<MyPlugin>()
);

4. 核心系统快速示例

事件系统:

// 订阅
EventBus::Token token = EventBus::instance().subscribe<Event>(
    [](const Event& e) { /* handle */ }
);

// 发布
EventBus::instance().publish(Event{ ... });
// Token RAII 自动取消订阅

配置管理:

ConfigScope cfg("app.window");
cfg.set("width", 1280);
int width = cfg.get_or<int>("width", 1280);

// 加载/保存 JSON
ConfigManager::instance().load_from_file("config.json");
ConfigManager::instance().save_to_file("config.json");

任务管理:

auto task = TaskManager::instance().launch(
    "Loading File",
    [](const auto& cancel) {
        for (int i = 0; i < 100 && !cancel; i++) {
            // do work
        }
    }
);

日志:

LOG_INFO("Loading: {}", filename);
LOG_ERROR("Failed: {}", error);

核心系统架构

1. 应用生命周期

UNINITIALIZED → INITIALIZING → RUNNING ←→ PAUSED
                            ↓         ↓
                         STOPPING ←──┘
                            ↓
                        STOPPED

2. 插件生命周期

未加载 (Unloaded)
    ↓ add_builtin() / load_from_file()
已加载 (Loaded)
    ↓ enable()
已启用 (Enabled)
    ↓ disable()
已加载 (Loaded)
    ↓ unload()
未加载 (Unloaded)

3. 数据流

用户操作
    ↓
ContentRegistry::Commands::invoke()
    ↓
EventBus::publish(Event)
    ↓
插件事件处理器
    ↓
UI 更新 / 后台任务

构建和运行

构建

# Configure
cmake -B build -DCMAKE_BUILD_TYPE=Release

# Build
cmake --build build --config Release

# Run
./build/bin/DearTsApp.exe

依赖

CMake 3.20+
C++20 编译器 (MSVC 2022 / GCC 11+ / Clang 13+)
SDL3
ImGui 2.13.3+
nlohmann/json
fmtlib

参考文档

📘 核心 API 手册（优先阅读）

| 文档 | 说明 | 用途 | |------|------|------| | config_manager_api.md | ConfigManager 完全手册 | 配置管理、层级键、JSON 持久化 | | logger_api.md | Logger 完全手册 | 日志记录、文件输出、级别控制 | | task_manager_api.md | TaskManager 完全手册 | 异步任务、进度跟踪、任务取消 | | plugin_system_api.md | Plugin System 完全手册 | 插件开发、生命周期、API 集成 |

📕 其他参考文档

核心系统:

result_type.md - Result<T, E> 类型详解
event_system.md - EventBus 事件系统
content_registry.md - Content Registry 详解
ui_system.md - UI 系统（视图、停靠窗口）

应用层:

application_api.md - Application 类 API
task_system.md - 任务系统详解
plugin_system.md - 插件系统详解

集成指南:

sdl3_init.md - SDL3 初始化指南
imgui_integration.md - ImGui 集成指南
cmake_config.md - CMake 配置详解
logging_guide.md - 日志系统使用指南

📙 示例和模板

插件示例:

plugins/builtin/ - 内置插件完整实现
plugins/builtin/include/views/ - 视图示例

代码模板:

assets/app_template.cpp - 应用程序模板
assets/view_template.cpp - 视图模板
assets/plugin_template.cpp - 插件模板
assets/cmake_template.txt - CMake 模板

渲染示例:

examples/SDL3_ImGui_Hybrid_Rendering.md - SDL3 + ImGui 混合渲染
examples/interactive_sdl_render.md - 交互式 SDL 渲染

常见任务快速索引

| 任务 | 查阅文档 | |------|---------| | 创建插件 | plugin_system_api.md | | 管理配置 | config_manager_api.md | | 异步任务 | task_manager_api.md | | 添加日志 | logger_api.md | | 事件系统 | event_system.md | | 注册命令 | content_registry.md | | 创建视图 | ui_system.md | | 错误处理 | result_type.md | | CMake 配置 | cmake_config.md |

开发最佳实践

✅ DO

使用 Result<T, E> 处理错误

Result<Data, std::string> load() {
    if (error) return Result::err("Failed");
    return Result::ok(data);
}

使用 RAII 管理资源
- EventBus::Token (自动取消订阅)
- ConfigScope (自动前缀)
- 智能指针
查看 API 文档而非源码
- 4 个核心 API 手册在 references/
- 每个手册都有完整示例

使用 Content Registry

ContentRegistry::Commands::register_handler("id", "Name", callback);
ContentRegistry::Views::add<MyView>();

❌ DON'T

不要用异常做控制流 - 使用 Result<T, E>
不要忘记 API 版本 - 插件必须匹配
不要使用全局状态 - 存储在插件成员或 ConfigManager
不要手动管理资源 - 让 RAII 处理

技能使用场景

此技能在以下场景自动激活：

创建基于 SDL3 + ImGui 的 C++ 应用
实现类型安全的事件系统
开发插件系统
创建多视图停靠窗口
使用 Result 类型错误处理
使用 ConfigManager 管理配置
使用 TaskManager 执行异步任务
使用 Logger 记录日志
开发 UI 插件（视图、命令、工具）
查看 DearTs API 文档

项目资源

文档

项目文档: docs/
插件快速开始: plugins/QUICKSTART.md
插件用户指南: docs/plugin_system_guide.md

架构图

14 个高分辨率架构图: docs/diagrams/
包括：生命周期、类关系、事件流程、渲染管线等

外部链接

SDL3 文档: https://wiki.libsdl.org/SDL3/
ImGui GitHub: https://github.com/ocornut/imgui
ImHex GitHub: https://github.com/WerWolv/ImHex
CMake 文档: https://cmake.org/documentation/
C++ 参考: https://en.cppreference.com/w/cpp

技能版本: 3.0.0 最后更新: 2025-12-30 框架版本: DearTs Framework 1.0.0