shenandshen 62a5f5ad11 Fix terminal foliage dispatch on frond branches
Generate authored terminal leaves independently of frond activation, matching the recovered last-level dispatch. This prevents three umbrella-thorn copies from expanding leaf cards into full frond nodes and hitting the node budget.

Add an active-frond regression with 17500 terminal cards and record verification: all 606 resources generate without truncation, SDK and client targeted tests pass, and corpus ASan/UBSan checks pass.
2026-10-12 18:52:02 -07:00

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 网络封包与协议状态机

#include <network/network.h>

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<uint8_t> outgoing = client.PopSendData();
::send(socket_fd, outgoing.data(), outgoing.size(), 0);

2. sdk/spatial 八叉树空间划分与视锥剔除

#include <spatial/spatial.h>

// 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<metin2::spatial::VisibleObject> 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 节点树与排版

#include <ui_core/ui_core.h>

metin2::ui_core::UIManager ui_mgr(1920.0f, 1080.0f);

// 1. 创建窗口容器
auto window = std::make_shared<metin2::ui_core::UIWindow>();
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<metin2::ui_core::UIGrid>(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 模块:

# 引入统一 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 根目录下执行:

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
S
Description
No description provided
Readme
490 KiB
Languages
C++ 63.9%
C 34.8%
CMake 1.1%
Python 0.2%