# Lity3D 引擎文件说明

## 顶层结构

```
lity3d/
├── Engine/          核心引擎代码（C + MASM汇编）
├── Demo/            示例程序
├── Assets/          3D模型资源
├── EditorCS/        编辑器（C#）
├── build/           编译输出
├── CMakeLists.txt   CMake构建配置
├── build.bat        Windows一键编译
├── README.md        项目说明
├── DESIGN.md        架构设计
└── scene.txt        场景保存文件
```

---

## Engine/ASM/ — 汇编加速层

引擎的性能热路径用 MASM x64 汇编实现，通过 SSE/AVX2 指令集加速。当汇编不可用时自动降级到纯C版本。

- **math.asm** (1013行) — 向量加减乘除、矩阵乘法、四元数旋转，全部用 SIMD 指令
- **math_c_fallback.h** (65行) — 数学函数的纯C实现，作为汇编的备选
- **memory.asm** (146行) — 对齐内存分配，保证 SIMD 操作需要的16/32/64字节对齐
- **string_ops.asm** (253行) — 用SIMD加速的内存拷贝、字符串长度计算、字符串比较
- **profiling.asm** (122行) — 用CPU的RDTSC指令做高精度计时，用于性能分析

## Engine/Core/ — 引擎核心

- **engine.c/h** — 引擎主控。负责初始化所有子系统、运行游戏循环（每帧调update→render）、关闭时清理资源。这是整个引擎的入口
- **timer.c/h** — 用Windows的QueryPerformanceCounter做毫秒级计时，计算帧间隔(delta time)
- **logger.c/h** — 日志系统。支持INFO/WARN/FATAL三级日志，同时输出到控制台和文件
- **asset_manager.c/h** — 资源管理器。统一处理shader/mesh/texture的加载和缓存，避免重复加载

## Engine/Window/ — 窗口系统

- **window.c/h** — 创建Win32窗口，处理Windows消息循环。把键盘、鼠标、窗口大小变化等事件转发给引擎回调函数

## Engine/Rendering/ — D3D11渲染管线

- **graphics_device.c/h** — D3D11设备初始化。创建Device、SwapChain、RenderTarget、DepthStencil，管理渲染状态
- **renderer.c/h** — 渲染器。设置视口、清屏、管理渲染目标切换
- **shader.c/h** — 着色器管理。编译HLSL着色器、设置常量缓冲区、绑定到管线
- **mesh.c/h** — 网格系统。支持立方体/球体/平面程序化生成，也支持OBJ文件加载。管理顶点缓冲区和索引缓冲区
- **texture.c/h** — 纹理系统。通过WIC加载BMP/PNG/JPEG，也支持生成纯色和棋盘格纹理
- **camera.c/h** — 摄像机。透视投影、lookAt矩阵、自由移动和旋转
- **camera_controller.c/h** — 摄像机控制器。封装常用的WASD+鼠标操作
- **frustum.c/h** — 视锥体裁剪。判断物体是否在摄像机视野内，跳过不可见物体的渲染
- **lighting.c/h** — 光照系统。方向光+点光源，Lambert漫反射计算
- **material.c/h** — 材质。把shader和纹理组合在一起，定义物体的外观属性

## Engine/Scene/ — 场景图

- **scene_graph.c/h** — 场景树。节点有父子关系，子节点继承父节点的位移/旋转/缩放
- **scene_render.c/h** — 场景渲染。遍历场景树，把每个节点的MeshRenderer提交给渲染器
- **scene_serialize.c/h** — 场景序列化。把整个场景树保存成text文件或从文件加载

## Engine/Input/ — 输入系统

- **input.c/h** — 键盘/鼠标/手柄输入。跟踪按键状态，支持轮询（GetAsyncKeyState）和事件回调两种模式

## Engine/Audio/ — 音频系统

- **audio.c/h** — XAudio2音频引擎。动态加载DLL（兼容Win7~11），加载WAV文件，播放/暂停/音量控制

## Engine/Physics/ — 物理系统

- **physics.c/h** — 简易物理。AABB碰撞检测、球体碰撞、重力模拟、速度积分

## Engine/ECS/ — 实体组件系统

- **world.c/h** — ECS世界。实体=组件的容器，系统批量处理同类组件

## Engine/UI/ — 用户界面

- **ui.c/h** — 2D UI渲染。按钮、标签、面板等基础控件，用D3D11的2D投影绘制

## Engine/Editor/ — 内置编辑器

- **editor.c/h** — 编辑器主逻辑
- **editor_2d.c/h** — 2D编辑模式（俯视图）
- **uilayer.c/h** — 编辑器UI层
- **bitmap_font.c/h** — 位图字体渲染
- **glyph_atlas.c/h** — 字体图集生成

## Engine/VisualScript/ — 积木式可视化编程

这是引擎最复杂的模块之一，实现了类似Scratch的积木编程系统：

- **block_core.c/h** — 积木核心数据结构（输入/输出端口、连接线）
- **block_types.c/h** — 30+种积木类型定义（移动、旋转、条件、循环等）
- **block_executor.c/h** — 积木执行器。解析积木图，按连接顺序执行逻辑
- **block_serializer.c/h** — 积木序列化。把积木图保存为.ly文件或从文件加载
- **block_workspace.c/h** — 积木工作区。管理所有积木的位置和连接关系
- **block_renderer.c/h** — 积木渲染。在屏幕上绘制积木方块和贝塞尔连线
- **block_interaction.c/h** — 积木交互。拖拽移动、连线创建、端口连接
- **block_palette.c/h** — 积木面板。侧边栏显示可用积木列表
- **block_editor.c/h** — 积木编辑器主控

## Engine/Scripting/ — 脚本系统

- **lity.py** — LityPy。Python脚本库，用Python语法写游戏逻辑
- **lua_engine.c/h** — Lua脚本引擎桩（预留接口）

## Engine/Asset/ — 资源定义

- **mesh.h** — Mesh结构体定义（顶点数组、索引数组、顶点缓冲区）
- **texture.h** — Texture结构体定义（宽高、像素数据、SRV）

## Engine/include/ — 对外接口

- **engine_api.h** — C/C++便利封装。暴露汇编函数给C代码，提供运算符重载

---

## Demo/ — 示例程序

| 文件 | 说明 |
|------|------|
| main.c | 场景Demo（方块+球体+地面+光照） |
| lity_explorer.c | 3D开放世界探索（村庄+树木+第三人称） |
| cube_dodge.c | 躲避游戏（障碍物+碰撞+计分） |
| game_test.c | 纯D3D11渲染测试（无Engine依赖） |
| raw3d_test.c | 引擎3D渲染验证（彩色面） |
| scene_test.c | 场景图测试 |
| light_test.c | 光照系统测试 |
| input_test.c | 输入系统测试 |
| obj_viewer.c | OBJ模型查看器（鼠标旋转） |
| ly_interpreter.c | .ly积木文件解释器 |
| editor_main.c | 编辑器入口 |
| open_world_demo.c | 开放世界demo |

## EditorCS/ — 编辑器

C# 编写的可视化积木编辑器，用Dear ImGui + D3D11实现。

## Assets/ — 模型资源

- cube.obj — 简单立方体OBJ模型
- pyramid.obj — 金字塔OBJ模型