lity3d/引擎文件说明.md

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模型