进阶:3D、动画与预览
代码说明:运行完整示例前,先准备本页说明的项目配置、场景或协议。局部用法中的 Token、节点、回调和业务函数须来自实际项目,不能单独原样粘贴运行。
做2D场景和界面讲的是 2D 场景和界面——按钮、血条、精灵、输入。如果你的游戏需要 3D 角色、骨骼动画、相机控制、离屏预览,就要用到这一页的模块。
这些模块和 2D 那套是同一套 SDK,只是多了 3D 专属的能力。约定不变:所有函数从 ./sdk/flexcore 引入,几乎都返回 Result,先检查 .ok 再读 .value。
3D 坐标和旋转用什么表示
开始之前,先约定两个基础类型——后面所有 3D 模块都用它们:
// 3D 坐标:普通的 {x, y, z} 字面量
interface Vec3 { x: number; y: number; z: number; }
// 颜色:{r, g, b, a?}
interface ColorLike { r: number; g: number; b: number; a?: number; }
旋转分两种表示方式,取决于你在哪个模块:
| 场景 | 类型 | 说明 |
|---|---|---|
节点旋转(transform) | Vec3 | 欧拉角,单位是弧度 |
骨骼变换(skeleton3d、根运动) | Transform3DLike | 3×3 基矩阵,不是欧拉角也不是四元数 |
Transform3DLike 长这样:
interface Transform3DLike {
origin: Vec3; // 位置
basis: { x: Vec3; y: Vec3; z: Vec3 }; // 3 个列向量组成的 3x3 矩阵
}
💡 你不需要手动构造 Transform3DLike——它由骨骼查询、根运动采样等函数返回,你读取里面的值就行。
能力地图
| 想做什么 | 用哪个模块 |
|---|---|
| 移动、旋转、缩放 3D 物体 | transform |
| 播放 3D 动画、提取根运动 | animation |
| 查询骨骼、做 IK | skeleton3d |
| 把东西挂到骨骼上(武器、特效) | attachment |
| 做离屏预览(角色展示窗) | viewport |
| 控制 3D 相机 | camera3d |
| 控制 3D 灯光 | light3d |
| 换材质、改 shader 参数 | material |
3D 变换
transform 模块在 做2D场景和界面讲过 2D 部分,这里看 3D:
import { transform } from "./sdk/flexcore";
// 设置 3D 世界坐标
const move = transform.setPosition3D(model, { x: 10, y: 0, z: -5 });
if (!move.ok) console.error(move.error.code);
// 读取 3D 坐标
const pos = transform.getPosition3D(model);
if (pos.ok) {
console.log(pos.value.x, pos.value.y, pos.value.z);
}
// 旋转(欧拉角,弧度)
transform.setRotation3D(model, { x: 0, y: Math.PI / 2, z: 0 }); // 绕 Y 轴转 90°
// 缩放(传数字 = 均匀缩放,传 Vec3 = 三轴独立)
transform.setScale3D(model, 2.0); // 整体放大 2 倍
transform.setScale3D(model, { x: 1, y: 2, z: 1 }); // 只拉高
💡 旋转用弧度不是角度。Math.PI / 2 = 90°,Math.PI = 180°。
3D 动画与根运动
做2D场景和界面讲过基础的 animation.play / stop / pause。这里讲 3D 动画特有的能力:根运动(Root Motion)和接触轨。
根运动
本节 player 指 AnimationPlayer/AnimationMixer,actor 指要移动的 Node3D 角色根节点;onUpdate 需接入项目实际逐帧更新入口。根运动让角色"边走边移动"——动画里角色往前走,角色在场景里也真的往前移动,而不是原地踏步。
import { animation } from "./sdk/flexcore";
// 开启根运动提取
const enable = animation.setRootMotionEnabled(player, true);
if (!enable.ok) console.error(enable.error.code);
// 每帧取本帧的根运动增量,应用到角色位置
function onUpdate() {
const delta = animation.getRootMotionDelta(player);
if (delta.ok) {
const pos = transform.getPosition3D(actor);
if (pos.ok) {
transform.setPosition3D(actor, {
x: pos.value.x + delta.value.origin.x,
y: pos.value.y + delta.value.origin.y,
z: pos.value.z + delta.value.origin.z,
});
}
}
}
// 清空累积器(切换动画时通常调用)
animation.clearRootMotionAccumulator(player);
getRootMotionDelta 返回的是 Transform3DLike(位置 + 旋转矩阵),origin 就是本帧的位移增量。
离线提取整段动画的根运动轨迹
有时你想预先知道一整段动画的移动轨迹(比如计算攻击位移):
const track = animation.extractRootMotion(player, {
animation: "dash_attack",
rootBone: "Root",
axis: "forward", // 前进方向
});
if (track.ok) {
console.log(`总时长: ${track.value.duration}s`);
console.log(`总距离: ${track.value.distance}`);
// track.value.samples 是每一帧的位置采样
}
骨骼查询
skeleton3d 模块让你读取骨骼信息、查询单根骨骼的位置:
import { skeleton3d } from "./sdk/flexcore";
// 获取角色身上的骨骼节点
const skeleton = skeleton3d.getSkeleton(player);
if (!skeleton.ok) {
throw new Error("找不到骨骼:" + skeleton.error.code);
}
// 拿到所有骨骼名
const names = skeleton3d.getBoneNames(skeleton.value);
if (names.ok) {
console.log(`骨骼数量: ${names.value.length}`);
console.log(names.value); // ["Root", "Spine", "Head", "Hand_L", ...]
}
// 查某根骨骼的世界坐标(用于挂特效、做碰撞判定)
const handWorld = skeleton3d.getBoneWorldTransform(skeleton.value, "Hand_R");
if (handWorld.ok) {
console.log("右手位置:", handWorld.value.origin);
}
// 查骨骼的屏幕坐标(用于 UI 跟随骨骼,比如头顶血条)
const head = skeleton3d.getBoneScreenPosition(skeleton.value, "Head", cameraNode);
if (head.ok) {
// head.value.x / .y 是屏幕坐标
// head.value.behind = true 表示在相机背后
if (!head.value.behind) {
positionHeadLabel(head.value.x, head.value.y);
}
}
💡 bone 参数支持传骨骼名(字符串)或索引(数字),两种都行。
IK:反向动力学
IK 让你指定"脚要踩在这个位置",引擎自动算出腿该怎么弯。适合做脚步贴合地形、手抓扶手等。
if (!skeleton.ok) return;
const ik = skeleton3d.solveIK(skeleton.value, {
chains: [
{
endBone: "Foot_R", // 末端骨骼名
targetWorldPosition: { x: 0, y: 0, z: 0 }, // 目标世界坐标
},
],
});
if (!ik.ok) console.error(ik.error.code);
可以一次传多条链(比如双脚同时贴合)。
挂点:把东西挂到骨骼上
角色拿的武器、穿的装备、身上的特效——都需要跟着骨骼走。用 attachment 模块:
import { attachment } from "./sdk/flexcore";
if (!skeleton.ok) return;
// 在右手骨骼上创建一个挂点
const handSlot = attachment.createBoneAttachment(skeleton.value, "Hand_R", {
name: "WeaponSlot",
});
if (!handSlot.ok) return;
// 把武器节点挂到挂点下
const attached = attachment.attachNode(handSlot.value, weaponNode);
if (attached.ok) {
console.log("武器已挂载,会跟着右手骨骼移动");
}
// 换武器时:解绑旧的,挂新的
attachment.detachChildren(handSlot.value);
attachment.attachNode(handSlot.value, newWeapon);
3D 相机
import { camera3d } from "./sdk/flexcore";
// 视场角(角度,不是弧度)
camera3d.setFov(camera, 75);
// 投影模式
camera3d.setProjection(camera, "perspective"); // 透视
camera3d.setProjection(camera, "orthogonal"); // 正交
// 正交尺寸(只在正交模式下有效)
camera3d.setSize(camera, 5);
// 近远裁剪面
camera3d.setClip(camera, 0.1, 1000);
| 投影模式 | 说明 | 用途 |
|---|---|---|
"perspective" | 近大远小 | 3D 游戏 |
"orthogonal" | 无透视 | 2.5D、等距视角 |
"frustum" | 锥台 | 特殊效果 |
3D 灯光
import { light3d } from "./sdk/flexcore";
// 光照强度
light3d.setEnergy(sunLight, 1.5);
// 灯光颜色
light3d.setColor(sunLight, { r: 1, g: 0.95, b: 0.8 }); // 暖色光
// Omni(点光源)作用范围
light3d.setOmniRange(torchLight, 10);
材质
import { material } from "./sdk/flexcore";
// 读取网格当前材质
const mat = material.get(meshNode);
if (mat.ok) {
console.log("材质句柄:", mat.value);
}
// 设置材质
material.set(meshNode, 0, newMaterialAssetId);
// 节点级材质覆盖(不影响原始材质资源)
material.override(meshNode, overrideMaterial);
// 复制材质(得到独立副本,改了不影响原材质)
const dup = material.duplicate(originalMaterial, { deep: true });
if (dup.ok) {
// 修改副本的 shader 参数
material.setParam(dup.value, "albedo_color", { r: 1, g: 0, b: 0, a: 1 });
}
// 读取 shader 参数
if (mat.ok) {
const color = material.getParam(mat.value, "albedo_color");
if (color.ok) console.log(color.value); // 使用具体颜色字段前验证 unknown 的结构
}
💡 setParam 的 value 是 unknown 类型——具体接受什么取决于 shader。常见的是颜色(ColorLike)、数字(number)、贴图(ResourceHandle)。
离屏预览
很多游戏有"角色预览窗"——主界面是 2D,角落里有个小窗口显示 3D 角色(可以转视角、换装)。这用 viewport 模块实现。
原理
viewport 创建一个独立的渲染视口——它有自己的场景、自己的相机,渲染结果输出成一张纹理,再贴到 2D 界面的 TextureRect 上。
主场景(2D)
└── TextureRect(显示预览)
↑ 绑定纹理
离屏视口(3D)
├── 场景实例(3D 角色)
└── 相机
预览流程
下面函数可放入客户端脚本。sceneAssetId 必须取自实际资源注册表;预览场景须包含 Camera3D 与 AnimationPlayer 节点及 idle 动画。成功时由调用方在页面退出时执行返回的清理函数;失败时释放本次创建的视口及场景。
import { viewport, scene, node, animation } from "./sdk/flexcore";
import type { NodeLike, AssetId } from "./sdk/flexcore";
export function setupPreview(textureRectNode: NodeLike, sceneAssetId: AssetId) {
const vp = viewport.create({
name: "PreviewViewport", size: { x: 512, y: 512 },
transparent: true, updateMode: "always",
});
if (!vp.ok) throw new Error(vp.error.code);
const root = scene.instantiate(sceneAssetId, { name: "PreviewRoot" });
if (!root.ok) {
viewport.dispose(vp.value);
throw new Error(root.error.code);
}
let parented = false;
try {
const added = viewport.addChild(vp.value, root.value);
if (!added.ok) throw new Error(added.error.code);
parented = true;
const camera = node.find(root.value, "Camera3D");
if (!camera.ok) throw new Error(camera.error.code);
const selected = viewport.setCamera(vp.value, camera.value);
if (!selected.ok) throw new Error(selected.error.code);
const player = node.find(root.value, "AnimationPlayer");
if (!player.ok) throw new Error(player.error.code);
const played = animation.play(player.value, "idle", { loop: true });
if (!played.ok) throw new Error(played.error.code);
const bound = viewport.bindToTextureRect(vp.value, textureRectNode);
if (!bound.ok) throw new Error(bound.error.code);
return () => viewport.dispose(vp.value);
} catch (error) {
if (!parented) node.queueFree(root.value);
viewport.dispose(vp.value);
throw error;
}
}
视口配置选项
创建视口时可以调这些参数(创建后也能单独设置):
// 更新模式
viewport.setUpdateMode(vp, "always"); // 每帧渲染
viewport.setUpdateMode(vp, "once"); // 只渲染一次(静态截图)
viewport.setUpdateMode(vp, "whenVisible"); // 可见时才渲染
// 抗锯齿
viewport.setMsaa(vp, "4x"); // 4 倍多重采样
// 渲染缩放(低于 1 省性能,高于 1 更清晰)
viewport.setRenderScale(vp, 0.75);
// 纹理过滤
viewport.setTextureFilter(vp, "linear_mipmap"); // 平滑
viewport.setTextureFilter(vp, "nearest"); // 像素风
💡 如果预览窗口不需要每帧更新(比如静态装备展示),用 updateMode: "once" 能大幅省性能。
串联:换装 + 预览
把骨骼、挂点、材质、视口串起来——一个"角色预览窗口里换武器"的项目接线示例:
import { node, skeleton3d, attachment, material, viewport, animation } from "./sdk/flexcore";
// 假设 previewVp 是已创建的视口,previewRoot 是视口里的角色根节点
// 拿到骨骼
const skeleton = skeleton3d.getSkeleton(previewRoot);
if (!skeleton.ok) return;
// 创建右手挂点
const slot = attachment.createBoneAttachment(skeleton.value, "Hand_R", {});
if (!slot.ok) return;
// 换武器:解绑旧武器,挂新武器
attachment.detachChildren(slot.value);
attachment.attachNode(slot.value, newWeaponNode);
// 同时换材质(比如武器发光效果)
const mat = material.get(newWeaponNode);
if (mat.ok) {
const glowMat = material.duplicate(mat.value, { deep: true });
if (glowMat.ok) {
material.setParam(glowMat.value, "emission_energy", 2.0);
material.override(newWeaponNode, glowMat.value);
}
}
// 播放拔武器动画
const player = node.find(previewRoot, "AnimationPlayer");
if (player.ok) animation.play(player.value, "draw_weapon", {});
常见问题
getSkeleton 返回失败?
检查节点层级:
- 角色根节点下是否有
Skeleton3D类型的子节点
- 3D 模型是否包含骨骼(纯网格模型没有骨骼)
用 node.find(root, "Skeleton3D") 手动找一下,确认路径。
根运动没效果?
- 确认
setRootMotionEnabled(player, true)调用了
- 确认动画本身包含根运动数据(不是所有动画都有,原地循环动画通常没有)
- 确认
rootBone名称正确(默认是"Root",可能因模型不同而异)
IK 解算后角色姿势不对?
targetWorldPosition是世界坐标,不是局部坐标
- 目标位置不要太离谱(脚踩到 2 米高的位置,腿会拉伸变形)
- 多条链的末端骨骼不要冲突
预览窗口是黑的?
按顺序排查:
- 视口里是否有相机,且相机是否绑定(
viewport.setCamera)
- 相机朝向是否对着角色
- 视口里是否有灯光(3D 场景需要灯光才能看到东西)
updateMode不是"disabled"
transparent: true时,背景透明但角色应该还是可见的——如果全透明,检查相机裁剪面
material.setParam 报错?
shader 参数名必须和材质使用的 shader 里定义的 uniform 名一致。用 getParam 先读一下,确认参数存在。参数值的类型也要匹配——颜色传 ColorLike,浮点数传 number,不能混。
回头看
这一页是 2D 那一页的 3D 版本。核心模块关系:
transform(移动旋转)
↓
animation(动画 + 根运动)
↓
skeleton3d(骨骼查询 + IK)── attachment(挂武器/特效)
↓
viewport(离屏预览)── camera3d / light3d / material(画面控制)
大部分 3D 操作的套路是一样的:拿到节点 → 调用函数 → 检查 Result。和 2D 的区别只是坐标从 {x, y} 变成 {x, y, z},旋转从角度变成弧度。