WasiCore 3D坐标系统指南

重要提醒 - AI开发助手必读

WasiCore框架使用左手坐标系，与Unreal Engine保持一致，请务必理解以下关键信息：

3D坐标轴定义

WasiCore 3D坐标系统（左手坐标系）：
- X轴：水平方向（左右移动）
- Y轴：水平方向（前后移动，深度）  
- Z轴：高度方向（上下移动，跳跃方向）
- XY平面：地面/水平面
- Z轴正方向：向上

默认镜头设置：
- Yaw: -90°, Pitch: -70°, Roll: 0°
- 默认视角：俯视角2.5D镜头
- 默认镜头下的原点位置：左上角

关键约定

1. 地面定义：XY平面（Z=0）是地面
2. 高度轴：Z轴是高度轴，Z值越大越高
3. 跳跃方向：角色跳跃时Z坐标增加
4. 重力方向：重力沿Z轴负方向作用

世界尺寸与角色建模单位

星火编辑器和 WasiCore 的 3D 世界采用厘米制：1 个世界单位 = 1 厘米，不是 1 米。

• 1 米应写作 100 个世界单位。
• 常规 1.8 米高的人形角色，导入后的模型包围盒高度应约为 180。
• 角色的模型、骨架、动画、挂点和附加模型应使用一致的厘米尺寸；标准资源建议保持节点/数编缩放为 (1, 1, 1)。
• 物理胶囊、碰撞半径、移动距离、镜头距离和 3D 音频距离等世界空间参数也按厘米理解。例如角色胶囊高度 180 表示 180 厘米。

FBX 导入流程当前为了兼容既有资源，默认不会仅根据 FBX 的单位元数据自动换算场景尺寸。因此不要把一个以“米”为数值基准、身高约 1.8 的模型直接导入后再期待编辑器自动放大到 180。推荐在 DCC/导出阶段使用厘米，或在导出前完成米到厘米的 100 倍换算；导入后再通过资源预览/包围盒确认实际高度。第三方资源尺寸不统一时，可以使用模型资产层缩放做适配，但不建议把单位模型的运行时缩放长期当作资源单位修正方案。

“使用 Unity3D 规格”导入 FBX

模型或动画的 FBX 已经按照 Unity 的空间约定制作或导出时，可以在导入窗口勾选“使用 Unity3D 规格”。它是一个坐标系与单位预设，不是 Unity 工程或 Unity 资源包导入器。

导入方式	FBX 场景转换
默认导入	转换为星火模型使用的 Z 轴向上、左手坐标系；为了兼容既有资源，不主动按 FBX 单位元数据换算尺寸。
使用 Unity3D 规格	转换为 Y 轴向上、左手坐标系，并把 FBX 场景单位统一为米。

转换发生在编辑器提取 FBX 内容之前，因此会一起影响网格的方向与尺寸、节点变换、骨骼层级和绑定姿势，以及动画轨道中的位移和旋转。模型与它的独立动画必须使用同一导入规格，否则可能出现朝向、骨骼姿势、根节点位移或动作幅度不一致。编辑器会为新导入的模型和动画记住该选择，后续“更新模型”或重新导入动画时继续使用原规格。

这个选项不会转换 Unity 材质、Shader、贴图通道、Prefab、.meta 文件或其他 Unity 专用数据，也不会自动判断一个 FBX 是否来自 Unity。以下情况适合勾选：

• 模型和动画来自同一套 Unity 工作流，并明确以 Y 轴向上、左手系和米为制作约定。
• 默认导入后确认出现了由坐标或单位约定不一致导致的朝向、镜像或尺寸问题。

已经按星火的 Z 轴向上、厘米制作规范导出的 FBX，或项目中需要与既有星火模型、骨架和动画保持一致的资源，不要仅因为文件曾在 Unity 中打开过就勾选。WasiCore 游戏世界仍然采用厘米制；该选项只决定 FBX 内容如何写入模型和动画资源，不会把场景、物理或运行时代码中的距离单位改成米。导入后仍应检查模型包围盒、骨架和动画预览，并确认它与角色碰撞尺寸及项目内其他资源的比例一致。

模型可见尺寸与角色逻辑碰撞尺寸是两套配置。即使模型高度约为 180，仍应按玩法单独设置 GameDataUnit 的碰撞半径、攻击半径，以及物理角色控制器的 Radius / Height。

实际应用示例

Vector3 坐标构建

// 正确的3D位置创建
var groundPosition = new Vector3(100, 200, 0);    // 地面位置
var jumpingPlayer = new Vector3(100, 200, 50);    // 跳跃中的玩家（高50厘米）
var flyingObject = new Vector3(100, 200, 150);    // 飞行物体（高150厘米）

ScenePoint 使用

// 地面上的位置
var groundPoint = new ScenePoint(new Vector3(x, y, 0), scene);

// 空中的位置（如跳跃、飞行）
var airPoint = new ScenePoint(new Vector3(x, y, height), scene);

物理系统

// 重力向下（Z轴负方向）
velocity.Z -= gravity * deltaTime;

// 跳跃向上（Z轴正方向）
velocity.Z = jumpForce;

平台/地形创建

// 地面平台（Z=0）
var groundPlatform = new ScenePoint(new Vector3(x, y, 0), scene);

// 高台（Z>0）
var elevatedPlatform = new ScenePoint(new Vector3(x, y, platformHeight), scene);

常见错误和避免方法

错误示例

// ❌ 错误：将Y轴用作高度
var wrongJump = new Vector3(x, jumpHeight, z);

// ❌ 错误：重力作用在Y轴
velocity.Y -= gravity * deltaTime;

正确示例

// ✅ 正确：将Z轴用作高度
var correctJump = new Vector3(x, y, jumpHeight);

// ✅ 正确：重力作用在Z轴
velocity.Z -= gravity * deltaTime;

游戏开发场景应用

1. 跳跃游戏

// 玩家跳跃
playerVelocityZ = jumpForce;  // Z轴向上跳跃

// 重力下落
playerVelocityZ -= gravity * deltaTime;  // Z轴向下重力

// 平台碰撞检测
if (playerZ <= platformZ + platformHeight)
{
    // 玩家落在平台上
}

2. 飞行游戏

// 飞机升降
aircraft.Position = new Vector3(x, y, altitude);  // Z为飞行高度

// 高度调整
altitude += climbRate * deltaTime;  // Z轴上升

3. 建筑系统

// 多层建筑
var floor1 = new Vector3(x, y, 0);     // 一楼在地面
var floor2 = new Vector3(x, y, 300);   // 二楼高300单位
var floor3 = new Vector3(x, y, 600);   // 三楼高600单位

Shape系统中的坐标约定

形状原点位置

• 立方体/圆柱体：底面中心（便于放置在地面）
• 球体：几何中心
• 胶囊体：底端中心（角色脚部位置）
• 平面：几何中心

形状缩放

// 立方体缩放：宽度(X), 厚度(Y), 高度(Z)
var cubeScale = new Vector3(width, depth, height);

// 胶囊体缩放：横截面(X), 横截面(Y), 高度(Z)
var capsuleScale = new Vector3(radius, radius, height);

AI助手开发提示

1. 始终记住：Z轴是高度，XY是地面平面
2. 跳跃动作：使用Z轴速度
3. 重力物理：作用于Z轴负方向
4. 碰撞检测：地面接触检查Z坐标
5. 相机设置：从适当的Z高度俯视XY平面

相关文档

• Actor系统文档
• 物理系统文档

---

> 关键提醒：在进行任何3D相关开发时，请始终确认您使用的是Z轴作为高度轴。这将避免方向混淆和物理错误。