compiler/examples/minecraft-godot

TypePHP Minecraft Demo

这是一个 demo 级 Godot 方块世界示例，用来验证：

• Godot 负责窗口、3D 渲染、输入、水面 shader 和场景表现。
• TypePHP/PHP 负责世界生成、地形高度、河流位置、水块类型等业务逻辑。
• C++ 只做底层对接：GDExtension、DLL 加载、C ABI 调用和数据转换。

当前版本使用 -m lib 编译 TypePHP 动态库，不使用 -m ext。

结构

php-src/world.php                  PHP 世界生成规则
cpp-src/typephp_world_api.cc       TypePHP 动态库 C ABI 导出
gdextension-src/                   Godot GDExtension 桥接
typephp_bridge.gdextension         Godot 扩展声明
scripts/voxel_world.gd             方块、水面、树、材质与渲染
assets/craft/                      Craft 项目的 MIT 授权贴图资源

编译 TypePHP 动态库

php bin\compiler.php examples\minecraft-godot\typephp.yml -f
Copy-Item -LiteralPath typephp_world.dll -Destination examples\minecraft-godot\bin\typephp_world.dll -Force

编译 Godot GDExtension

cmake -S examples\minecraft-godot\gdextension-src -B examples\minecraft-godot\gdextension-src\build-nmake -G "NMake Makefiles" -DCMAKE_TOOLCHAIN_FILE=D:\workspace\vcpkg\scripts\buildsystems\vcpkg.cmake -DVCPKG_TARGET_TRIPLET=x64-windows -DCMAKE_BUILD_TYPE=Release
cmake --build examples\minecraft-godot\gdextension-src\build-nmake --config Release

GDExtension 会输出到：

examples\minecraft-godot\bin\typephp_godot_bridge.dll

运行

D:\workspace\godot\Godot_v4.7-stable_win64.exe --path examples\minecraft-godot

操作

• W/A/S/D 移动
• Space 跳跃
• 鼠标移动视角
• 鼠标左键挖方块
• 鼠标右键放方块
• Esc 释放或重新捕获鼠标

对接链路

Godot scene
  -> TypePhpBridge GDExtension Node
  -> LoadLibrary(typephp_world.dll)
  -> typephp_world_block_type_at(x, y, z)
  -> PHP world.php 生成规则
  -> Godot 根据返回的 block type 渲染地形和水面

当前画面策略

• 方块尺寸缩小为 0.6，生成半径扩大为 28，世界密度比初版更高。
• 地形按 chunk 合并为少量 ArrayMesh，同一 chunk 内按材质分 surface，避免每个方块都创建独立节点。
• 碰撞按 chunk 生成 ConcavePolygonShape3D，编辑方块时只重建受影响 chunk。
• 方块使用 Craft 的 texture.png atlas，按方块六个面分别映射 tile，比如草方块的顶部、侧面、底面使用不同贴图。
• 使用 ProceduralSkyMaterial 渲染蓝天。
• 运行时生成两层半透明云面，shader 控制云形和缓慢漂移。
• 水面使用透明 shader，带轻微顶点波动和高光。

后续如果继续追求画质，可以为草地、石头、水面增加贴图/法线贴图，并加入远处低细节 chunk 或雾效过渡。

借鉴 Craft 的部分

assets/craft 中的 texture.png、sky.png、font.png 来自 Michael Fogleman 的 Craft 项目，原项目使用 MIT License，许可证已保留在 assets/craft/LICENSE.md。

当前示例借鉴了 Craft 的几个核心思路：

• 使用 16x16 tile atlas，而不是每种方块一张独立纹理。
• Craft 的 tile 编号以 atlas 底部为原点，Godot UV 以顶部为原点，渲染时已做 Y 轴翻转。
• 使用方块 registry 描述每个方块六个面的 tile。
• 透明方块和普通方块分材质处理。
• PHP 层负责世界规则：地形高度、水域、沙滩、树木、方块类型判定。
• C++/Godot 层只负责桥接、渲染、输入和碰撞。