填补空缺！一个开箱即用的 CesiumJS 角色控制器开源了

做三维 GIS 的同学对 CesiumJS 应该都不陌生，数字孪生、智慧城市、实景三维这类项目里它几乎是浏览器端的标配。不过Cesium 本质是个三维地球引擎，不是游戏引擎，一旦项目想做那种"第一/第三人称走进场景里逛一圈"的效果会非常麻烦。Unreal、Unity 这些游戏引擎自带一整套角色控制器，而到了浏览器端的 Cesium，这块基本是空白，需要自己从零去拼物理、碰撞、相机、动画。

最近有人给小编投稿了一个开源库 cesium-player-controller，开箱即用，有这方面需求的可以看看。

PS：下面的内容来自 @航 的投稿。

项目简介

cesium-player-controller 是一个基于 CesiumJS 的玩家控制器，MIT 协议开源，已经发布到 npm。它的底层物理基于 Rapier3d，简单说，就是把游戏引擎里那套成熟的"角色控制器"搬进了 Cesium 的 3D Tiles 场景，让你在地球级别的三维场景里也能像玩游戏一样操控一个角色。

官网（GitHub）：https://github.com/hh-hang/cesium-player-controller

在线示例：https://hh-hang.github.io/cesium-player-controller/index.html

主要能力

要在 Cesium 里做出第一人称的感觉，难点是碰撞、相机、动画这几块得一件件自己拼。这个项目有意思的地方在于，作者把游戏引擎里那套相对成熟的玩法往 Web 端进行了迁移。地形、glTF 乃至动态物体都能接，第一、第三人称随意切，相机还会自己绕开墙体，不用再手写一堆避障逻辑。支持走跑跳飞这些动作，大场景可按 F 起飞俯瞰。手机端支持虚拟摇杆，键位能改，位置和落地这类回调也留了API。小编觉得它未必每一项都做到极致，但把这条路上常见的能力尽量收进了一个能直接用的包里，对做园区漫游、倾斜摄影巡检这类开发来说，做到省时省力。

安装与上手

安装很简单，把库和 Rapier 一起装上：

npm install cesium-player-controller @dimforge/rapier3d-compat

下面是一份完整的示例：

import {
    Cartesian3,
    Cesium3DTileset,
    Viewer,
    Math as CMath,
    Cartographic,
} from "cesium";
import "cesium/Build/Cesium/Widgets/widgets.css";
import { playerController } from "cesium-player-controller";

// 搭建 CesiumJS 环境
const viewer = new Viewer("cesiumContainer", {
    timeline: false,
    animation: false,
});

// 加载 3D Tiles 场景
const tileset = await Cesium3DTileset.fromUrl("./tileset.json");
viewer.scene.primitives.add(tileset);
await viewer.flyTo(tileset);

// 设置人物出生点
const center = tileset.boundingSphere.center;
const carto = Cartographic.fromCartesian(center);
const initPos = Cartesian3.fromDegrees(
    CMath.toDegrees(carto.longitude),
    CMath.toDegrees(carto.latitude),
    carto.height + 20,
);

// playerController 核心用法
const player = new playerController();

// 人物控制初始化
await player.init({
    viewer,   // Cesium Viewer 实例
    initPos,  // 人物初始坐标，ECEF
    playerModelConfig: {
        url: "./glb/person.glb",   // 模型路径（GLB/GLTF）
        scale: 0.01,               // 模型缩放
        idleAnim: "idle",          // 静止动画名
        walkAnim: "walk",          // 行走动画名
        runAnim: "run",            // 跑步动画名
        jumpAnim: "jump",          // 跳跃动画名；或传 ["起跳", "循环", "落地"] 分三段播放
    },
    // 静态碰撞源
    staticCollider: {
        type: "gltf",
        url: "./glb/agi-hq.glb",
        position: center,
    },
});

// 每帧调用
let last = performance.now();
viewer.scene.preUpdate.addEventListener(() => {
    const now = performance.now();
    const delta = (now - last) / 1000;
    last = now;
    player.update(delta);
});

更细的参数（物理、相机、键位、移动端按钮等）都有默认值，需要时再按字段表逐项调即可，可以参考项目文档进行调整。

配套工具

有一个细节值得一提：由于 CesiumJS 无法通过 CPU 直接拿到 3D Tiles 的顶点坐标，给倾斜摄影、实景三维这类 3D Tiles 场景做碰撞体并不方便。作者为此还配了个工具 collider-forge，专门用来制作碰撞体，跟控制器搭配使用，把这条工作流补全了。

总结

在 CesiumJS 里实现一个完整的角色控制，过去一直是个费力的活儿——物理、碰撞、相机避障、动画状态机，每一块自己写都不轻松，拼在一起更是不小的工程。cesium-player-controller 把这些能力打包成了一个开箱即用的库，常见需求基本一站式覆盖。对于正在做数字孪生、智慧城市漫游、三维场景交互或者实景三维展示的团队来说，它能省下相当一部分从零造轮子的时间。目前项目还处在 0.1.x 的早期阶段，迭代比较活跃，有这个需求的小伙伴可以看下。