找回密码
 立即注册
搜索
热搜: 活动 交友 discuz
跳到内容
FlexCore开发者社区

学习与实践

文档中心

从入门操作到版本更新,找到适合当前阶段的说明。

进阶: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、根运动)Transform3DLike3×3 基矩阵,不是欧拉角也不是四元数

Transform3DLike 长这样:

interface Transform3DLike {
  origin: Vec3;                              // 位置
  basis: { x: Vec3; y: Vec3; z: Vec3 };      // 3 个列向量组成的 3x3 矩阵
}

💡 你不需要手动构造 Transform3DLike——它由骨骼查询、根运动采样等函数返回,你读取里面的值就行。


能力地图

想做什么用哪个模块
移动、旋转、缩放 3D 物体transform
播放 3D 动画、提取根运动animation
查询骨骼、做 IKskeleton3d
把东西挂到骨骼上(武器、特效)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},旋转从角度变成弧度。

Archiver|小黑屋|FlexCore开发者社区

GMT+8, 2026-11-20 00:20 , Processed in 0.081873 second(s), 5 queries .

Powered by Discuz! X5.0

© 2001-2026 Discuz! Team.

返回顶部