可视化编辑器

引擎进程内嵌的 Qt 编辑器：「搭场景、写脚本、调试、导出」全流程可视化完成，工作流对齐 Unity。

ShitEngine 附带一个基于 Qt Widgets 的进程内嵌编辑器（不是独立 IPC）：Editor.exe 里直接创建了一个独立的 EngineContext 做引擎预览，场景树、属性检查器、视口等面板读写的就是同一批引擎对象——所见即所得，并共用引擎的 .scene 序列化格式，编辑与运行结果完全一致。

进程内嵌意味着编辑器的每个视口就是你游戏的渲染管线：场景视图只用编辑器相机（约定名 scene_camera，不入库 / 树中隐藏 / 拒删），运行视图则从场景启用相机中自动挑选（游戏相机不定名，Unity 语义），多相机分屏在运行视图完整支持。

环境与启动

• SDK 包中自带 Editor.exe（bin/ 目录），双击启动
• 若从源码构建：cmake --preset x64-debug → cmake --build out/build/x64-debug --target Editor（需本机已装 Qt6/Qt5 Widgets；未检测到 Qt 会静默跳过编辑器）
• 编辑器启动时从 exe 同目录 config.json 加载插件，再进入最近项目（无则空会话）

项目

新建 / 打开项目

「文件 → 新建项目…」向导：填项目名、位置、SDK 目录，可选生成 C++ 脚本工程。项目目录结构：

MyGame/
├── config.json          # engine.sdkDir / plugins / scene / inputMappings
├── Scenes/              # .scene 场景文件
├── Assets/              # 游戏资源（png / wav / ttf / .anim / .prefab / .scene）
├── Scripts/             # C++ 行为脚本工程（可选）
│   ├── CMakeLists.txt   # find_package(ShitEngine) + 反射扫描
│   ├── Behaviors.h      # 你的 SHIT_REFLECT 行为类
│   └── plugin_export.cpp
├── bin/                 # 脚本编译产物 DLL
└── .shitengine/
    └── state.ini        # 窗口布局 / 最近场景等项目私有状态

「文件 → 打开项目…」有最近项目列表，启动自动恢复上次项目。「文件 → 项目设置…」配置项目名、SDK 目录、启动场景（写入 config.json 的 scene 字段）与输入映射（见下文）。

脚本构建（Ctrl+B）

「构建脚本」（Ctrl+B）：自动探测本机编译器（MSVC → 尝试 VS 生成器；MinGW → Ninja），配置编译 Scripts/ 工程，DLL 输出到项目 bin/。构建成功后热重载：场景 JSON 快照 → 卸载旧 DLL → 重载注册 → 快照恢复——编辑器现场不清空，循环开发无需重启。构建失败不影响已加载的旧插件（文件锁在卸载后释放）。

主窗口布局

┌──────────┬──────────────────────────┬──────────┐
│  场景树   │   场景视口 │ 运行视口       │ 属性检查器 │
│ （左侧）  │   （中央标签页叠放）       │ （右侧）  │
│          │                          │          │
├──────────┴──────────────────────────┴──────────┤
│   资源 │ 日志   （底部标签页合并）                 │
└──────────────────────────────────────────────────┘

全部面板都是可停靠 QDockWidget：可拖动、可浮动；右上角关闭后可从菜单栏「窗口」重新勾选显示。布局持久化随项目走（带版本号，旧布局自动落回默认）。中央为双视口标签页：场景视口（编辑相机）+ 运行视口（游戏相机），叠放切换。

场景树

• 顶部名称过滤框（Ctrl+F 聚焦）：输入即过滤，匹配节点保留整条祖先链
• 右键菜单：新建（空对象 / 精灵 / 相机 / UI Canvas / 文本五个模板，文本自动挂到已有 Canvas 下、无则顺带创建）、添加组件（与检查器共用菜单）、删除对象、存为预置…
• 双击 / F2 重命名；拖拽改层级（防止环）；Ctrl+C / Ctrl+V 复制粘贴对象、Ctrl+D 原地复制（Prefab 序列化内部剪贴板 + 重名自动去重 + 父级继承，输入框聚焦时不劫持快捷键）
• 多选 + 批量删除：Ctrl/Shift 点选，Del / 右键批量；scene_camera 混选时被过滤，其余照删

属性检查器

顶部为双页标签：「组件」与「**系统」——选中对象时自动切到组件页，系统页常驻、随时可切换查看（播放态两页只读但仍可切页看运行时值）。

组件页

每帧从引擎回读反射字段（只读回读、非双向绑定）：

• 顶部对象属性区（Unity 同款）：[启用 ✓][名称] 行 + Tag 行——取消勾选「启用」对象即失活（不渲染 / 不更新行为与物理，子对象随父级联，场景树灰显）；Tag 用于分类标记，随 .scene 保存；均入撤销栈
• 每个组件一个标题栏段落：拖动标题栏可引用（拖到别的引用字段上赋值）；「✕」按钮移除组件（TransformComponent 与 scene_camera 的相机组件拒删）
• 路径类字段统一控件：字段名含纹理 / 音频 / 字体等语义时渲染为 [路径框][✕][…] —— 从资源窗口拖文件到字段自动填充、「…」弹出按语义过滤的文件选择框、也支持手输相对或绝对路径；保存统一为相对项目根的路径
• 底部 Add Component 按钮：Unity 风格菜单，已持有类型置灰标注「（已有）」
• 组件引用字段（ComponentRef<T>）渲染为拖拽引用控件：显示「对象名 (组件类型)」+ 清除按钮，接受组件标题拖拽，也接受场景树对象拖入（自动挑第一个可赋引用组件，沿反射基类链做类型校验）
• 顶部搜索框：按组件类型名 / 字段名过滤显示（清空恢复全显）
• Animator / AnimationComponent 只保留入口按钮 → 打开对应独立窗口

系统页

常驻的**「场景系统」面板**——列出当前场景注册的系统（默认三系统 Behavior/Render/UI + 手动添加的系统），每行可调优先级（越小越先执行）、「✕」移除（默认三系统拒删）；点击系统名展开反射字段编辑（如 PhysicsSystem2D 的重力、像素/米比例），修改立即生效并入撤销栈；底部「添加系统」菜单列全部 System 派生类型（含插件自定义系统），已注册的置灰标注「（已有）」。

场景系统

系统列表和字段（如重力值）随 .scene 文件保存，运行时（含导出的游戏包）按文件恢复——自定义系统无需写一行注册代码就能进游戏。详见场景管理 · 场景系统。默认三系统（BehaviorSystem/RenderSystem/UIRenderSystem）由 Scene::init 自动注册，不落盘；PhysicsSystem2D 可手动添加/移除（已有刚体时物理系统会自愈重新注册）。

播放态只读锁：▶ 进入播放后两页内容统一禁用（Unity 语义），回读刷新照常——运行时值实时可见，且仍可切页对照查看。

视口

• Gizmo 三模式：工具栏或 Q/W/E 切换移动 / 旋转 / 缩放；移动支持 X/Y 轴与中心整体拖，Ctrl 吸附（移动 10px / 旋转 5° / 缩放 0.1）
• F 键聚焦：选中对象后按 F，编辑器相机立即对准它并按包围盒自动调整缩放（Unity 帧化；任意面板选中后均可用）
• 滚轮缩放锚定鼠标：缩放前后保持光标下的世界点不动（Unity/Godot 手感），中键拖拽平移
• 状态栏常驻信息：右下角实时显示当前选中对象名 + 鼠标世界坐标
• 拖放建对象：从资源窗口拖图片进视口 → 在光标世界坐标创建精灵；拖 .prefab → 实例化（重名去重、落点定位、自动选中）；拖 .anim → 应用到选中对象
• 物理调试绘制：工具条「碰撞体」开关（默认开）——碰撞体轮廓按刚体类型着色（动态绿 / 运动学黄 / 静态蓝灰），关节画青色连接线 + 锚点圆点
• 碰撞体编辑手柄：选中含碰撞体的对象时轮廓黄色高亮 + 白色手柄，Box 四角拖尺寸 / Circle 右端拖半径（Ctrl 吸附，入撤销栈；播放态禁拖）
• Tilemap 刷瓦片：选中含 Tilemap 的对象 → 「瓦片」Dock 显示瓦片集缩略图网格，点选瓦片作为画笔；视口 左键+Shift 刷瓦片、右键擦除，可拖拽连续刷、入撤销栈

播放态

工具栏 ▶ 运行 / ⏸ 暂停 / ■ 停止（Unity 三态）：

• ▶ 运行：若项目含脚本工程且已配 SDK，先编译脚本并热加载，再进入播放；自动切换到运行视口标签，停止后切回场景视口
• 运行中：运行视口接收 Qt 键鼠事件并合成 SDL_Event 转发给引擎（WASD/鼠标/滚轮可驱动游戏）；检查器只读但实时回读；引擎日志实时滚动到日志面板
• ⏸ 暂停 / 继续（Ctrl+P）：只冻结逻辑与物理（Game::SetPaused），画面与 UI 保持
• 单步（Ctrl+Shift+P）：暂停态下推进一帧，逐帧核对逻辑
• ■ 停止：恢复进入运行前的场景快照——运行期的对象/属性改动全部回退（保留编辑器相机）；每次进入运行从头开始（Time 归零、Behavior onStart 重跑、输入状态清空防卡键）
• 播放中游戏逻辑销毁/新建对象：场景树按 Scene::getGeneration 代数变化重建并保持选中，检查器/Gizmo 同步重绑——不悬垂、不崩溃

撤销 / 重做

场景级快照栈：Gizmo 拖拽、检查器字段变更、场景树操作（含瓦片刷、碰撞体拖拽、批量删除）全部入栈。Ctrl+Z / Ctrl+Shift+Z（或「编辑」菜单 / 工具栏）。撤销/重做后整体重建场景并联动面板；dirty 标记跟快照对比——撤回到保存态时标题栏 * 自动消失。

项目设置（输入映射 / IDE）

「文件 → 项目设置…」：

• 通用页：项目名、SDK 目录、启动场景下拉（不在 Scenes/ 目录时追加「（当前）」兜底项，保存不丢 scene 字段）
• 输入页：动作 / 轴按键映射可视化编辑——点击键名进入「按下任意键」捕获（支持多键与鼠标键、重复键警告），保存即写入 config.json 的 inputMappings 段并热编译到引擎（运行时与编辑器播放共用）
• 代码编辑器下拉：自动探测 VS Code / Visual Studio（vswhere）/ CLion / Qt Creator，也可手动指定；「编辑 → 打开代码…」（Ctrl+Shift+O）用所选 IDE 打开项目根目录

资源窗口（Unity 风格）

「窗口 → 资源」，Unity Project 窗口式双栏：

• 左侧文件夹树（仅目录，隐藏 bin/ build/ .shitengine/ 等生成目录），右侧文件网格（图片显示缩略图，其余类型显示专属彩色图标：.scene 蓝 / .anim 橙 / .prefab 青 / .sprite 紫 / .wav 绿 / 字体灰）
• 根目录为整个项目（可见 Assets/ Scenes/ Scripts/）
• 双击 .scene 打开场景、.prefab 实例化、.anim 在 Animation 窗口中打开；网格双击子目录进入（树同步高亮）
• 支持 png/jpg/bmp/wav/ttf/otf/scene/prefab/anim；拖图片 / 拖预置进视口创建对象

动画窗口

• Animator 窗口（「窗口 → Animator」，检查器 Animator 入口按钮触发）：Unity 风格状态机图——拖动节点重排（坐标随 .scene 保存）、右键勾连创建转换（空白引出 = 任意状态）、入口状态黄色标记、任意状态节点、滚轮缩放；左侧参数面板（float / bool / trigger）、底部选中状态/转换属性（名称 + 入口 + .anim 剪辑资产（必选） +「浏览…」/「打开」/ from-to + 条件）；状态只引用 .anim 资产（Unity 语义），内嵌剪辑编辑已移除——想改动画在 Animation 窗口编辑对应的 .anim 文件
• Animation 窗口（「窗口 → Animation」，检查器 AnimationComponent 入口按钮触发）：独立 .anim 资产编辑器——精灵表面板网格点选帧、中央 Dope Sheet 时间轴（拖块排序、拉右缘调逐帧时长、双击移除）、播放预览；保存写 .anim，供 Animator 状态引用

导出游戏

「文件 → 导出游戏…」一键把项目装配为绿色免安装游戏目录：

MyGame/
├── MyGame.exe          # ShitRuntime.exe 改名
├── ShitEngine.dll + SDL 等运行库
├── MyGameScripts.dll   # 脚本插件
├── Scenes/ + Assets/   # 场景与资源（资源路径改写为包内相对路径）
└── config.json         # scene / plugins / inputMappings 自动生成

Runtime 启动时 chdir 到 exe 所在目录，导出包可复制到任意位置双击即玩。

快捷键速查

快捷键	功能
Ctrl+N / O / S	新建 / 打开 / 保存场景
Ctrl+Shift+S	场景另存为
Ctrl+Z / Ctrl+Shift+Z	撤销 / 重做
Ctrl+C / Ctrl+V	复制 / 粘贴对象
Ctrl+D	原地复制选中对象
Ctrl+B	构建脚本（热重载）
Ctrl+Shift+O	打开代码（所选 IDE）
Q / W / E	Gizmo 移动 / 旋转 / 缩放
F	聚焦选中对象（相机帧化）
Ctrl+F	聚焦场景树过滤框
Ctrl+P	暂停 / 继续（运行态）
Ctrl+Shift+P	单步推进一帧（暂停态）
Del	删除选中对象（重命名编辑中豁免）
F2 / 双击	重命名