内容
# imgui-forge
> 从 JSON 规范设计 Dear ImGui 菜单 — 实时 C++ 预览，支持热重载，一个用于程序化编辑的 MCP 服务器，以及一个双向 Figma 桥接。
一个 JSON 文件 (`spec/ui_spec.json`) 描述了 UI；一个原生 C++ 主机渲染它并**每次更改都热重载**，因此编辑规范会实时更新窗口。一个 MCP 服务器公开了用于程序化编辑的工具，一个 Figma 桥接器在两个方向上同步设计。这使得更改、移植和适配 ImGui 变得极为容易，尤其是使用 MCP 服务的 AI 工具，可以获得更大的 ImGui 功能。
`imgui-tool` 是捆绑的 MCP 服务器的名称 (`mcp/server.mjs`)。
```
spec/ui_spec.json ──(文件监视)──▶ C++ 主机窗口 (实时预览)
▲ ▲
│ └── MCP 服务器 (mcp/server.mjs): 添加/更新/删除小部件
└───── Figma 桥接器 (figma/): 在 Figma 中设计，同步双向
```
## 布局
| 路径 | 描述 |
|------|------|
| `spec/ui_spec.json` | UI 文档（真实来源） |
| `host/UiRenderer.h` / `.cpp` | 可重复使用的规范→ImGui 解释器 — 复制到您自己的项目中 |
| `host/main.cpp` | 预览应用程序：Win32 + DirectX11 + 热重载 + 截图 |
| `build.bat` | 使用 MSVC 编译主机（自动通过 vswhere 检测 VS；无需 cmake） |
| `mcp/server.mjs` | MCP 服务器，公开编辑工具 |
| `figma/` | Figma ↔ ImGui 双向桥接器（参见 `FIGMA.md`） |
| `.mcp.json` | MCP 客户端注册 |
| `vendor/` | Dear ImGui（停靠）+ nlohmann/json + stb_image_write |
## 设置
1. 构建主机（需要带有 C++ 工作负载的 Visual Studio）：
```
build.bat
```
生成 `build/imgui_tool.exe`。
2. 安装 MCP 服务器依赖项：
```
cd mcp && npm install
```
3. 注册 MCP 服务器。`.mcp.json` 位于此文件夹中，因此在此处打开的 MCP 客户端会自动拾取它。否则，在客户端的 MCP 配置中注册 `node mcp/server.mjs` 的 stdio 命令。
## 使用
1. 启动预览：
```
build\imgui_tool.exe spec\ui_spec.json
```
2. 手动编辑 `spec/ui_spec.json`，或通过 MCP 工具驱动它 — 窗口在约 250 毫秒内更新（主机每秒轮询文件 4 次）。
## MCP 工具
| 工具 | 用途 |
|------|---------|
| `get_spec` | 返回整个规范 |
| `set_spec` | 替换整个规范 |
| `list_widgets` | 所有窗口/小部件的树形结构，带有 ID |
| `widget_catalog` | 每种支持的小部件类型 + 其属性 |
| `add_window` | 添加顶级窗口 |
| `add_widget` | 通过 `parent_id` 将小部件插入容器 |
| `update_widget` | 修补小部件的属性（按 ID） |
| `remove_widget` | 删除小部件/窗口（按 ID） |
| `move_widget` | 重新父级/重新排序（按 ID） |
| `clear` | 空白画布 |
| `export_cpp` | 为当前规范发出立即模式 C++ |
| `screenshot` | 捕获实时预览并返回图像 |
## 在您自己的 C++ 项目中使用 UI
- **发布解释器** — 复制 `host/UiRenderer.{h,cpp}` + `vendor/json.hpp`，发布您的 `.json`，并在 ImGui 帧内调用：
```cpp
static ui_render::UiState ui;
ui_render::RenderSpec(mySpecJson, ui);
```
- **发布纯代码** — 调用 `export_cpp` 并粘贴生成的 `RenderUI()`。
## 支持的小部件
text / text_disabled / text_wrapped / bullet_text / label_text / separator_text /
bullet · button / small_button / arrow_button / checkbox / radio_button /
selectable / progress_bar · input_text / input_text_multiline / input_int /
input_float · slider_int / slider_float / slider_float2-4 / slider_angle /
vslider_float · drag_int / drag_float / drag_float2-4 · combo / listbox ·
color_edit3-4 / color_picker3-4 / color_button · plot_lines / plot_histogram ·
separator / same_line / new_line / spacing / dummy / indent / unindent · group /
child / collapsing_header / tree_node / tab_bar+tab_item / table / columns ·
menu_bar / menu / menu_item · popup / modal / tooltip / disabled / style_color /
style_var.
调用 `widget_catalog` 获取每个小部件的确切属性。
## Figma ↔ ImGui
在 Figma 中设计 → 在 ImGui 中实时看到它，反之亦然。参见 **`FIGMA.md`**：
```
cd figma && npm install
node figma/bridge.mjs
# Figma → 插件 → 开发 → 导入清单 → figma/plugin/manifest.json
```
