commit 86759bb726af6d40a7f16ff2f896d62ecc0f11c6
Author: shen <>
Date: Sun Oct 11 17:52:55 2026 -0700
Initialize shared Metin2 SDK with rendering optimizations and tests
diff --git a/.gitignore b/.gitignore
new file mode 100644
index 0000000..eae0f46
--- /dev/null
+++ b/.gitignore
@@ -0,0 +1,6 @@
+build/
+cmake-build-*/
+.DS_Store
+__pycache__/
+*.pyc
+/check_skel
diff --git a/CMakeLists.txt b/CMakeLists.txt
new file mode 100644
index 0000000..d9e5f65
--- /dev/null
+++ b/CMakeLists.txt
@@ -0,0 +1,21 @@
+cmake_minimum_required(VERSION 3.20)
+project(metin2_crossplatform_sdk LANGUAGES C CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+enable_testing()
+
+add_subdirectory(eterpack)
+add_subdirectory(proto)
+add_subdirectory(effect)
+add_subdirectory(speedtree)
+add_subdirectory(gr2)
+add_subdirectory(terrain)
+add_subdirectory(character)
+add_subdirectory(property)
+add_subdirectory(texture)
+add_subdirectory(network)
+add_subdirectory(spatial)
+add_subdirectory(ui_core)
+add_subdirectory(examples)
diff --git a/README.md b/README.md
new file mode 100644
index 0000000..8676cc3
--- /dev/null
+++ b/README.md
@@ -0,0 +1,208 @@
+# Metin2 Cross-Platform SDK Suite
+
+独立、零图形 API 绑定、高复用度的现代 C++20 渲染前置算法、物理模拟、网络协议、空间剔除与 UI 核心 SDK 套件,服务于跨平台游戏客户端与自研引擎开发。
+
+---
+
+## 📦 SDK 模块矩阵 (12 大独立核心库)
+
+| 模块 | 目录 | 核心职责 | 特性与技术突破 |
+| :--- | :--- | :--- | :--- |
+| **SpeedTree SDK** | `sdk/speedtree` | 植被生成、分层风场动力学、森林管理 | • **3 级分层风场动力学**(主干弯曲/树枝摇曳/叶片局部轴自转翻滚与颤动)
• **树冠球形法线混合**(消除纸片感,打造浑厚饱满的立体树冠)
• **次表面透射与半兰伯特环绕光**(逆光透亮,自然飘逸)
• **跨平台 GPU Foliage Shader + CPU 备用双管线** |
+| **GR2 Core SDK** | `sdk/gr2` (`libgr2`) | 官方 Granny2 资产解密与解算 | • **全压缩算法支持**:Oodle0/1 + BitKnit2(Granny 2.11)
• **19 种曲线解算**(覆盖所有 curve2 / B-spline)
• 纯 C++ 实现,32/64 位无缝兼容,彻底移除闭源 Windows DLL 依赖 |
+| **GR2 Render SDK** | `sdk/gr2` (`libgr2_render`) | 骨骼蒙皮、换装、武器/发型挂接 | • **`Gr2ModelInstance`**:零图形 API 绑定的高阶模型实例
• 骨骼姿态插值与调色板生成(Palette Matrices)
• 武器/发型骨骼挂接(`AttachModel` / `GetBoneWorldTransform`)
• 动态换装与部位替换(`AttachPart` / `SetSkin`) |
+| **Terrain & Water SDK** | `sdk/terrain` | 地形采样、高度图法线、四叉树视锥剔除、水体网格 | • **131x131 raw 高度图**双线性世界高度插值与表面法线计算
• **258x258 tile.raw** 纹理 Splatting 映射与 Dominant 贴图判定
• **256x256 attr.atr** 阻挡/水体/安全区属性碰撞查询
• **8x8 Patch 四叉树视锥剔除**与连续 LOD 分层网格生成
• **water.wtr** 水体动态波动网格算法 |
+| **Character & MSM SDK** | `sdk/character` | 角色体态、RaceData/MSM 脚本解析、多部位装配 | • 官方 `.msm` 脚本语法深度解析(BaseActorData, ShapeData, HairData, AttachingData)
• 身体部件装配(Main, Hair, Weapon, Sash)与换装换色(`SetArmorShape`, `SetHair`, `SetWeapon`)
• 骨骼插槽世界变换矩阵计算(`ComputeSocketWorldTransform`) |
+| **Property & Object SDK** | `sdk/property` | 场景物件属性 (YPRT)、CRC 索引、OBB 碰撞物理 | • FourCC `YPRT` 文本属性解析(.prb 建筑, .prt 树木, .pre 特效, .prd 地牢)
• 大小写不敏感 CRC32 快速索引字典与统一对象管理器
• **OBB 定向包围盒 2D/3D 穿透判定**与分离轴碰撞法线推开计算 |
+| **Texture & SubImage SDK** | `sdk/texture` | 软解纹理、DDS/DXT、TGA 解码、图集子图与九宫格 | • **纯 C++ DXT1/DXT3/DXT5 软解码**为 RGBA8888 像素缓冲(移动端与预览无依赖跨平台)
• **TGA 格式**(未压缩与 RLE 压缩 24/32 位)解码
• 官方 `.sub` 坐标裁剪与图集 UV 计算
• **9-Slice (九宫格) UI 渲染网格生成**(16 顶点、18 三角形标准流) |
+| **Network SDK** | `sdk/network` | 连接状态机、TEA/Rolling XOR 加解密、分包解包重组 | • **客户端严格阶段状态机**(Handshake → Auth → CharacterSelect → GameLoading → InGame)
• **零 Socket 依赖架构**:宿主负责原始 I/O,SDK 负责安全加解密与变长封包重组
• **TEA 32 轮块加密 + 线性反馈 Rolling XOR 混淆**双重防重放与防篡改
• **强类型协议事件回调**(Handshake, AuthResult, CharacterList, GameStart, Chat, Move 等) |
+| **Spatial Octree SDK** | `sdk/spatial` | 动态松散八叉树、相机视锥剔除、距离排序、射线拾取 | • **Loose Octree (扩展系数 $k=2.0$)**:杜绝跨分割面物件堆积在顶层
• **Gribb-Hartmann 视锥平面提取**与 P/N-Vertex 极速 AABB 相交测试
• 视距升序排序(支持从近到远不透明绘制与从远到近半透明排序)
• **球形 AOE 范围索敌查询**与 **Ray-AABB Slab 射线拾取/碰撞检测** |
+| **UI Core SDK** | `sdk/ui_core` | 响应式 UI 节点树、9 点弹性锚点、布局排版、容器网格 | • **纯 C++20 彻底剥离 Python 2.7 运行时依赖**
• **9 点弹性锚点与弹性伸缩排版**(TopLeft, Center, Stretch 等多分辨率自适应)
• **递归命中判定与父级事件冒泡机制**(MouseDown, MouseUp, Click, Move, Hover, Drag)
• **全功能控件族**:Window (可拖拽), Button (四态), Text, Slot (CD 冷却遮罩/多格判定), Grid (背包 5x9 槽位与拖拽转移)
• 2D 顶点批次输出(DrawBatch 顶点流生成) |
+| **EterPack SDK** | `sdk/eterpack` | 虚拟文件系统 (VFS) 与包解密 | • **EPK / EIX 双文件资产归档解析**
• TEA 32 轮加密 / 解密算法
• MiniLZO 内存压缩与 MCOZ 格式解包
• IEEE 802.3 与大小写不敏感 CRC32 哈希表快速索引 |
+| **Proto SDK** | `sdk/proto` | 游戏元数据解密与结构体加载 | • **`item_proto` / `mob_proto` 二进制与文本双向解析**
• FourCC 头部校验 (`MIPX`, `MCPX`)
• 32 位 / 64 位平台结构体对齐与跨架构安全读取 |
+| **Effect SDK** | `sdk/effect` | 粒子特效系统与寻的飞行道具 | • **MSE 特效脚本解析**(发射器、粒子生命周期、时间曲线关键帧插值)
• **MSF 寻的飞行物 (Homing Missile)** 物理轨迹仿真(重力、推力、最大角速度追踪、命中检测)
• 面向相机的公告板朝向计算 (Billboard Facing) 与顶点批次构建 |
+
+---
+
+## 🌲 SpeedTree 真实飘逸渲染核心原理
+
+为了在跨平台渲染器中达到与商业级 SpeedTree 完全一致的真实飘逸质感,SDK 落地了四大渲染与物理核心:
+
+1. **三级分层风场动力学 (3-Tier Wind Dynamics)**:
+ - **Level 1 主干弯曲**:基于高度的二次曲线响应,具备保长修正(Length-Preserving),模拟主干低频受力。
+ - **Level 2 树枝摇曳**:带相位差与空间阻尼的中频振动,消除整体一致的机械感。
+ - **Level 3 叶片自转微颤与翻滚 (Leaf Flutter & Tumble)**:每个叶片卡片顶点携带其局部的中心锚点(`leaf_pivot_offset`)。在风中,叶片以自身局部中心为轴高频摆动和翻转,光影鳞鳞闪烁,彻底消除僵硬片状感。
+ - **空间阵风波 (Spatial Gust Waves)**:风浪以正弦波结合空间坐标传递,形成阵阵风浪席卷森林的宏观视觉效果。
+
+2. **树冠球形法线混合 (Spherical Normal Blending)**:
+ - 将叶片几何法线与以树冠重心为起点的虚拟外向球形法线以动态权重加权混合,消除面片法线琐碎杂乱带来的硬边与黑斑,呈现浑厚饱满的树冠整体体积感。
+
+3. **次表面透射与半兰伯特环绕光 (Subsurface Transmission & Wrap Lighting)**:
+ - 逆光观察树木时,背光透射算法实时解算穿透叶片的翠绿光晕(`pow(max(0.0, dot(-L, V)), 3.5)`)。
+ - 漫反射采用半兰伯特环绕光,避免背光面死黑。
+ - 结合基于树冠中心的内部环境遮挡(Canopy AO),打造外层透亮、内部深邃的层次感。
+
+4. **双模渲染管线**:
+ - 提供 `foliage_shaders.h`(GLSL 450 / Vulkan SPIR-V / Metal / D3D11-12 兼容),GPU 端硬件级解算风力与球形法线。
+ - 提供 `EvaluateCpuTransformedVertices()`,在 CPU 端实时解算几何形变,适配轻量级或老旧设备。
+
+---
+
+## 🎯 新增三大模块集成与调用示例
+
+### 1. `sdk/network` 网络封包与协议状态机
+
+```cpp
+#include
+
+metin2::network::NetworkClient client;
+
+// 1. 设置业务事件回调
+client.SetOnHandshake([](uint32_t server_time) {
+ std::cout << "Handshake synced: " << server_time << std::endl;
+});
+client.SetOnAuthResult([](bool success, uint32_t err, const std::string& msg) {
+ if (success) std::cout << "Auth succeeded!\n";
+});
+
+// 2. 状态机推进与封包发送
+client.SetPhase(metin2::network::ConnectionPhase::Handshake);
+// 宿主 Socket 收到数据后送入 SDK
+client.PushReceivedData(socket_data, data_len);
+
+// 3. 进入验证并发送加密登录包
+client.SetPhase(metin2::network::ConnectionPhase::Auth);
+client.SendLogin("HeroPlayer", "Password123");
+
+// 4. 获取待发送的安全加密字节流
+std::vector outgoing = client.PopSendData();
+::send(socket_fd, outgoing.data(), outgoing.size(), 0);
+```
+
+### 2. `sdk/spatial` 八叉树空间划分与视锥剔除
+
+```cpp
+#include
+
+// 1. 创建场景松散八叉树 (边界: [-50000, 50000], 松散系数: 2.0)
+metin2::spatial::AABB world_box({-50000, -5000, -50000}, {50000, 10000, 50000});
+metin2::spatial::LooseOctree octree(world_box, 2.0f);
+
+// 2. 动态注册世界实体 (建筑、树木、角色、怪物)
+octree.Insert(101, metin2::spatial::SpatialObjectType::Building, building_aabb);
+octree.Insert(202, metin2::spatial::SpatialObjectType::Tree, tree_aabb);
+
+// 3. 每帧视锥剔除与按视距升序排序
+metin2::spatial::Frustum frustum = metin2::spatial::Frustum::CreatePerspective(
+ camera_pos, look_dir, up_dir, 60.0f, aspect_ratio, 1.0f, 3000.0f
+);
+std::vector visible_list = octree.QueryFrustum(frustum, camera_pos, true);
+
+for (const auto& obj : visible_list) {
+ // 按距离从近到远依次提交渲染队列
+ SubmitRenderCommand(obj.id, obj.type, obj.distance);
+}
+```
+
+### 3. `sdk/ui_core` 响应式 UI 节点树与排版
+
+```cpp
+#include
+
+metin2::ui_core::UIManager ui_mgr(1920.0f, 1080.0f);
+
+// 1. 创建窗口容器
+auto window = std::make_shared();
+window->SetName("Inventory");
+window->SetSize(220.0f, 340.0f);
+window->SetAnchor(metin2::ui_core::UIAnchor::Center);
+
+// 2. 创建背包网格 (5列 x 9行,格子 32px,间距 2px)
+auto grid = std::make_shared(5, 9, 32.0f, 2.0f);
+grid->SetPosition(10.0f, 30.0f);
+grid->SetItemAt(0, 0, 10, 1); // 0号槽位放置屠龙刀 (vnum=10)
+
+window->AddChild(grid);
+ui_mgr.AddElement(window);
+
+// 3. 事件派发 (鼠标点击自动冒泡与穿透检测)
+ui_mgr.DispatchEvent(metin2::ui_core::UIEvent::MakeMouseDown(960.0f, 540.0f, 0));
+
+// 4. 构建当前帧纯 2D 渲染批次 (包含九宫格网格与顶点颜色)
+auto batches = ui_mgr.GenerateRenderBatches();
+for (const auto& b : batches) {
+ Render2DBatch(b.vertices, b.indices, b.texture_id);
+}
+```
+
+---
+
+## 🎯 跨平台项目接入指南
+
+### 1. `CMakeLists.txt` 引入与构建
+
+在项目的 `CMakeLists.txt` 中引入 SDK 模块:
+
+```cmake
+# 引入统一 SDK 模块
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../sdk/speedtree ${CMAKE_CURRENT_BINARY_DIR}/sdk_speedtree)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../sdk/gr2 ${CMAKE_CURRENT_BINARY_DIR}/sdk_gr2)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../sdk/terrain ${CMAKE_CURRENT_BINARY_DIR}/sdk_terrain)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../sdk/character ${CMAKE_CURRENT_BINARY_DIR}/sdk_character)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../sdk/property ${CMAKE_CURRENT_BINARY_DIR}/sdk_property)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../sdk/texture ${CMAKE_CURRENT_BINARY_DIR}/sdk_texture)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../sdk/network ${CMAKE_CURRENT_BINARY_DIR}/sdk_network)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../sdk/spatial ${CMAKE_CURRENT_BINARY_DIR}/sdk_spatial)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../sdk/ui_core ${CMAKE_CURRENT_BINARY_DIR}/sdk_ui_core)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../sdk/eterpack ${CMAKE_CURRENT_BINARY_DIR}/sdk_eterpack)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../sdk/proto ${CMAKE_CURRENT_BINARY_DIR}/sdk_proto)
+add_subdirectory(${CMAKE_CURRENT_SOURCE_DIR}/../sdk/effect ${CMAKE_CURRENT_BINARY_DIR}/sdk_effect)
+
+# 目标客户端直接链接
+target_link_libraries(my_game_client PRIVATE
+ speedtree
+ libgr2
+ libgr2_render
+ terrain
+ character
+ property
+ texture
+ network
+ spatial
+ ui_core
+ eterpack
+ proto
+ effect
+)
+```
+
+---
+
+## 🛠️ SDK 编译与全量测试
+
+在 `sdk` 根目录下执行:
+
+```bash
+cd sdk
+mkdir -p build && cd build
+cmake ..
+cmake --build .
+ctest --output-on-failure
+./examples/sdk_demo
+```
+
+当前全套 14 项自动化单元测试全部 100% 通过:
+- `eterpack_test`
+- `proto_test`
+- `effect_test`
+- `speedtree_test`
+- `libgr2.loader_errors`
+- `libgr2.animation`
+- `libgr2.render_test`
+- `terrain_test`
+- `character_test`
+- `property_test`
+- `texture_test`
+- `network_test`
+- `spatial_test`
+- `ui_core_test`
diff --git a/character/CMakeLists.txt b/character/CMakeLists.txt
new file mode 100644
index 0000000..1eedfcd
--- /dev/null
+++ b/character/CMakeLists.txt
@@ -0,0 +1,24 @@
+cmake_minimum_required(VERSION 3.20)
+project(character LANGUAGES CXX)
+
+set(CMAKE_CXX_STANDARD 20)
+set(CMAKE_CXX_STANDARD_REQUIRED ON)
+
+add_library(character STATIC
+ src/msm_data.cpp
+ src/character_assembly.cpp
+)
+
+target_include_directories(character PUBLIC
+ $
+ $
+)
+
+add_library(character::character ALIAS character)
+
+option(CHARACTER_BUILD_TESTS "Build character SDK tests" ON)
+if(CHARACTER_BUILD_TESTS)
+ add_executable(character_test tests/character_test.cpp)
+ target_link_libraries(character_test PRIVATE character)
+ add_test(NAME character_test COMMAND character_test)
+endif()
diff --git a/character/include/character/character.h b/character/include/character/character.h
new file mode 100644
index 0000000..74a6ae0
--- /dev/null
+++ b/character/include/character/character.h
@@ -0,0 +1,5 @@
+#pragma once
+
+#include "types.h"
+#include "msm_data.h"
+#include "character_assembly.h"
diff --git a/character/include/character/character_assembly.h b/character/include/character/character_assembly.h
new file mode 100644
index 0000000..e9d0ccc
--- /dev/null
+++ b/character/include/character/character_assembly.h
@@ -0,0 +1,54 @@
+#pragma once
+
+#include "types.h"
+#include "msm_data.h"
+#include
+#include
+#include
+#include
+
+namespace metin2::character {
+
+struct AssembledPart {
+ uint32_t part_id = PART_MAIN;
+ std::string model_path;
+ std::vector skin_overrides;
+ std::string socket_bone;
+ float local_matrix[16] = {
+ 1,0,0,0,
+ 0,1,0,0,
+ 0,0,1,0,
+ 0,0,0,1
+ };
+};
+
+class CharacterAssembly {
+public:
+ CharacterAssembly(std::shared_ptr msm);
+ ~CharacterAssembly() = default;
+
+ // Equip / Appearance changes
+ bool SetArmorShape(uint32_t shape_index);
+ bool SetHair(uint32_t hair_index);
+ void SetWeapon(uint32_t part_id, const std::string& weapon_model, const std::string& custom_socket = "");
+
+ // Query active visual composition
+ const std::vector& GetAssembledParts() const { return m_parts; }
+ const AssembledPart* GetPart(uint32_t part_id) const;
+
+ // Calculate socket world matrix: out_world = bone_world * local_transform
+ static void ComputeSocketWorldTransform(const float bone_world[16], const float local_offset[3], float out_world[16]);
+
+ std::shared_ptr GetMsm() const { return m_msm; }
+
+private:
+ void RebuildAssembly();
+
+ std::shared_ptr m_msm;
+ uint32_t m_current_shape_index = 0;
+ uint32_t m_current_hair_index = 0;
+ std::unordered_map m_custom_weapons;
+ std::vector m_parts;
+};
+
+} // namespace metin2::character
diff --git a/character/include/character/msm_data.h b/character/include/character/msm_data.h
new file mode 100644
index 0000000..8e74a33
--- /dev/null
+++ b/character/include/character/msm_data.h
@@ -0,0 +1,60 @@
+#pragma once
+
+#include "types.h"
+#include
+#include
+#include
+#include