Files
metin2-SDK/speedtree

SpeedTree Cross-Platform Foliage SDK

A pure C++20, graphics-API-agnostic implementation of SpeedTree foliage rendering and wind dynamics for cross-platform game engines.

🌟 核心特性与渲染真实度突破(Realism & Shading)

为了达到与商业版 SpeedTree 同样真实、飘逸自然的渲染质感,本 SDK 实现了以下四大核心技术管线:

1. 三级分层风场动力学 (3-Tier Hierarchical Wind Dynamics)

  • Level 1 树干弯曲 (Trunk Bending): 基于树高的二次曲线响应,具备长度保持(Length-Preserving)算法,模拟主干在阵风下的柔韧弯曲。
  • Level 2 树枝摇曳 (Branch Sway): 引入大分支相对主干的摆动阻尼与相位差(Phase Offset),营造起伏有致的林间韵律。
  • Level 3 叶片自转翻滚与颤动 (Leaf Flutter & Tumble): 这是“飘逸感”的最关键核心。每个树叶卡片顶点都绑定了叶片局部中心锚点(leaf_pivot_offset)。在微风与阵风下,叶片围绕自身锚点高频翻滚微颤,光影鳞鳞闪烁,彻底消除僵硬片状感。
  • 空间阵风波 (Spatial Gust Waves): 风场跨越坐标系传递低频起伏波,使森林呈现一波波风浪拂过的生动波纹。

2. 树冠球形法线混合 (Canopy Spherical Normal Blending)

  • 传统 Billboard/插片树叶最大的痛点是“纸片感”与法线杂乱破碎。
  • 本 SDK 在几何生成和 Shader 中自动计算以树冠重心为起点的虚拟球形法线(Spherical Normal),并与叶片原始朝向做柔和加权混合。即使是由十字交叉面片组成的树冠,在阳光下也能呈现出浑厚、饱满的体积感。

3. 次表面透射与半兰伯特环绕光 (Subsurface Scattering & Wrap Lighting)

  • 背光透射 (Subsurface Transmission): 逆光观察树木时,阳光穿透薄叶片,Shader 自动产生透光的翠绿光晕(viewThrough = pow(dot(-L, V), 3.5))。
  • 半兰伯特环绕光 (Wrap Lighting): 漫反射平滑过渡,背光区域不会死黑。
  • 树冠内部自遮挡 (Canopy Interior AO): 依据叶片距树冠中心的距离衰减环境光,外层明亮透光、内部深邃幽暗。

4. 跨平台双管线支持 (Modern GPU Shader + CPU Fallback)

  • 现代 GPU 管线: 提供标准的 foliage_shaders.h(GLSL 450 / Vulkan SPIR-V / Metal / D3D11-12 兼容),顶点着色器硬件级高帧率解算风力与球形法线。
  • CPU Fallback 管线: 提供 EvaluateCpuTransformedVertices(),在老旧驱动或无自定义 Shader 环境下依然能实时计算风力变形。

📁 模块架构

sdk/speedtree/
├── include/speedtree/
│   ├── speedtree.h         # 核心模型、顶点布局、SPT 信息、森林实例管理
│   └── foliage_shaders.h   # 现代 GPU 植被顶点/片元着色器源码(含 3 级风力与次表面透光)
├── src/
│   ├── spt_parser.cpp      # 官方 .spt 二进制解析(Token 2000/2001/10000/10002/12000 等)
│   ├── tree_generator.cpp  # 树木骨架圆柱网格、树冠卡片、风力权重生成与 CPU 变形求值
│   └── forest.cpp          # 森林多实例生命周期、视锥剔除基础、风向风力统一控制
└── tests/
    └── speedtree_test.cpp  # 单元测试(生成、Token 嗅探、风力位移)

🚀 集成与使用示例

#include <speedtree/speedtree.h>

// 1. 创建树木模板(可从 .spt 文件或通过参数化生成)
auto model = speedtree::SpeedTreeModel::CreateFromSpt("ymir work/tree/b1_baobab_rt.spt");

// 2. 森林多实例管理
speedtree::SpeedTreeForest forest;
forest.RegisterProperty(crc, "d:/ymir work/tree/b1_baobab.prt");
auto* instance = forest.CreateInstance(150.0f, 0.0f, 320.0f, crc, 45.0f, 1.0f);

// 3. 帧循环更新风力
forest.SetWindStrength(1.5f);
forest.Update(deltaTime);