Three.js Gyroscope 全解析：用附加对象实现"姿态与世界解耦"的视角控制

Gyroscope 是 three.js 提供的一种特殊 Object3D：它从场景图层级中继承位置，却将其局部旋转直接当作世界旋转使用，让对象姿态相对世界保持固定。本文将从其工作原理解析、矩阵分解数学细节到真实用例（第三人称视角跟随、头顶第一人称相机稳定、轨道器姿态锁定等）逐步展开，带你完全掌握这一面向"物体移动、观察不随动"场景的轻量级工具。

一、Gyroscope 是什么

Gyroscope（陀螺仪）是一个附加组件（addon），本质上是 Object3D 的子类，行为类似真实世界的陀螺仪：

• 可以被移动 —— 通过场景图父节点挂载和层级位移，位置完全跟随父级。
• 姿态保持固定 —— 无论父节点如何旋转，Gyroscope 自身在世界空间中的朝向（orientation）都不会改变。

换句话说，父物体旋转时，作为子物体的 Gyroscope 不随父级的旋转而倾斜，只随父级的平移而移动。它的应用语义与旋转稳定平台 / 万向平台（gimbal）高度一致，常被用来实现"把人或相机从旋转容器中解放出来"的需求。

从源码注释（examples/jsm/misc/Gyroscope.js）可知官方对它的精确定义：

A special type of 3D object that takes a position from the scene graph hierarchy but uses its local rotation as world rotation.

这一特性使其在以下场景中非常有用：

• 将相机固定在某个旋转的刚体（角色、车辆、飞行器）上，但让视角保持世界水平；
• 让 HUD、标识牌、粒子系统跟随移动主体却不随之翻滚；
• 搭建"平台转动、物体始终面向世界"的机械结构演示。

二、导入与基础用法

Gyroscope 不属于 three.js 核心包，而是以 addon 形式提供，需要显式导入（对应官方文档 Installation#Addons 所描述的附加组件安装方式）。在源码注释（examples/jsm/misc/Gyroscope.js）与 Addons 入口（examples/jsm/Addons.js）中都明确了导入路径：

import { Gyroscope } from 'three/addons/misc/Gyroscope.js';

由于它是 Object3D 的轻量子类，构造非常简单，不需要任何参数：

// 无参数构造
const gyro = new Gyroscope();

// 挂载一个相机：相机获得 gyro 的"世界旋转解耦"能力
gyro.add( camera );

// 再将 gyro 挂到一个会在世界中运动的物体上
movingBody.add( gyro );

// 之后移动 movingBody，相机跟随其平移，但不会继承其旋转

场景图结构示意如下：

scene
└── movingBody            // 会平移 + 旋转的父节点
    └── gyro (Gyroscope)  // 继承父级位置，但不继承父级旋转
        └── camera        // 跟随平移，姿态相对世界固定

三、工作原理解析：为什么"旋转被解耦"

要理解 Gyroscope 为什么能"只见平移、不见旋转"，需要先回顾常规 Object3D 的世界矩阵更新流程。

3.1 常规对象的世界矩阵

在 src/core/Object3D.js 中，普通 Object3D.updateMatrixWorld() 的逻辑是：

updateMatrixWorld( force ) {

    if ( this.matrixAutoUpdate ) this.updateMatrix();

    if ( this.matrixWorldNeedsUpdate || force ) {

        if ( this.matrixWorldAutoUpdate === true ) {

            if ( this.parent === null ) {

                this.matrixWorld.copy( this.matrix );

            } else {

                // 关键：世界矩阵 = 父世界矩阵 × 自身局部矩阵
                this.matrixWorld.multiplyMatrices( this.parent.matrixWorld, this.matrix );

            }

        }

        this.matrixWorldNeedsUpdate = false;

        force = true;

    }

    // 递归让子节点继续更新
    // ...
}

对一般对象，若父级发生旋转，其旋转会经由矩阵乘法被完整地"传染"给子级，于是子级在世界中也随之旋转。

3.2 Gyroscope 的差异化重写

Gyroscope 重写（override）了 updateMatrixWorld，打断上述"旋转传染"。完整实现见 examples/jsm/misc/Gyroscope.js：

updateMatrixWorld( force ) {

    this.matrixAutoUpdate && this.updateMatrix();

    // update matrixWorld

    if ( this.matrixWorldNeedsUpdate || force ) {

        if ( this.parent !== null ) {

            this.matrixWorld.multiplyMatrices( this.parent.matrixWorld, this.matrix );

            // 拆解父级贡献：世界平移 / 世界旋转 / 世界缩放
            this.matrixWorld.decompose( _translationWorld, _quaternionWorld, _scaleWorld );

            // 拆解自身局部矩阵：局部平移 / 局部旋转 / 局部缩放
            this.matrix.decompose( _translationObject, _quaternionObject, _scaleObject );

            // 用“世界平移 + 自身局部旋转 + 世界缩放”重组世界矩阵
            this.matrixWorld.compose( _translationWorld, _quaternionObject, _scaleWorld );

        } else {

            // 无父节点时退化为普通行为
            this.matrixWorld.copy( this.matrix );

        }

        this.matrixWorldNeedsUpdate = false;

        force = true;

    }

    // 递归更新子节点
    for ( let i = 0, l = this.children.length; i < l; i ++ ) {

        this.children[ i ].updateMatrixWorld( force );

    }

}

核心思想是拆解后重组：先按常规方式算出父级影响下的 matrixWorld，随后调用 Matrix4.decompose() 将世界矩阵拆分为平移、旋转、缩放三元组，再调用 Matrix4.compose() 将 _translationWorld（来自父级的平移）+ _quaternionObject（自身的局部旋转）+ _scaleWorld（来自父级的缩放） 组合成一个新的世界矩阵。父级世界矩阵中的旋转分量被直接丢弃，从而实现了"父级旋转不再影响自身朝向"。

从数学上解释，常规对象的仿射变换形如 M_world = T * R * S；Gyroscope 则将世界变换改写为 M_world = T_parent * R_self * S_parent。这样：

• 平移分量完全继承父级，所以 Gyroscope 会跟着父节点走；
• 旋转分量使用自身局部四元数 _quaternionObject（注意这里取的是 this.matrix 的旋转而非 this.rotation，对二者关系可参见 Object3D 的欧拉角—四元数同步机制），不随父级改变；
• 缩放分量仍保留父级缩放，保证自身被父级缩放时不会变形。

这也解释了它在使用时的一个重要约束：父级对 Gyroscope 的旋转效果是通过修改 Gyroscope 自身而非父级来实现——例如想让一个挂在旋转平台上但始终保持水平的物体，应去设置 Gyroscope 自身的 rotation/quaternion 来取得所需的世界姿态。

四、与普通 Object3D 的行为差异对照

行为维度	普通 Object3D	Gyroscope
平移跟随父级	✔	✔（继承 _translationWorld）
旋转跟随父级	✔（矩阵级联传染）	✘（使用自身 _quaternionObject）
缩放跟随父级	✔	✔（保留 _scaleWorld）
实现方式	父矩阵 × 局部矩阵	decompose → 用局部旋转重组 → compose
无父节点	世界矩阵 = 自身局部矩阵	同左（退化行为一致）
矩阵更新入口	继承 Object3D	重写 updateMatrixWorld

可以看到：在没有父节点时，Gyroscope 退化为普通对象（this.matrixWorld.copy( this.matrix )），无任何特殊行为；只有存在父节点时，"平移继承、旋转解耦"的效果才会生效。

五、应用实战

5.1 真实仓库用例：跟随角色动画的稳定相机

官方示例 examples/webgl_loader_md2_control.html 演示了 Gyroscope 最经典的实战场景。该示例用 MD2CharacterComplex 在场景中布局了多排游戏角色（webgl_loader_md2_control 以键盘控制角色行走、挥剑），当角色加载完成后：

// 创建 gyroscope，把相机挂进去
const gyro = new Gyroscope();
gyro.add( camera );

// 将 gyro 挂到中间那排角色的 root 节点上
characters[ Math.floor( nSkins / 2 ) ].root.add( gyro );

用法只有三步，非常简洁：

1. new Gyroscope() 创建实例；
2. gyro.add( camera ) 把相机作为子节点；
3. 把 gyro 挂到移动/旋转的父节点（角色的 root）上。

效果是：当角色模型因走路、攻击而整体前后倾或旋转时，相机位置紧贴角色移动，但画面视角始终保持世界水平稳定，不会跟着角色的晃动而天旋地转。这是第一人称"稳定视角"类实现的直接参考范例。示例的完整运行环境依赖 examples/jsm/loader/MD2Loader 等资源，实际运行时需要在仓库本地通过 examples 目录 提供的服务器方式浏览（例如使用 three.js 仓库常规的 npm run dev/静态服务器从仓库根目录访问 examples/webgl_loader_md2_control.html）。

5.2 典型玩法：锁定朝向的辅助对象

希望让一个标记（如浮动箭头、血条、模型头顶的提示文字精灵）在世界中始终朝向固定方向，而它的载体不断旋转时：

const gyro = new Gyroscope();
parent.add( gyro );        // parent 可能持续翻滚

const marker = new THREE.Mesh( geometry, material );
gyro.add( marker );
marker.position.y = 3;     // 局部偏移仍有效

// marker 的朝向由 gyro 的自身旋转决定，
// 不受 parent 翻滚的影响，适合做“始终水平”的辅助 UI。

5.3 替代方案选择

若需求只是"绕某点转但自身不转"（如卫星绕着星球），也可以通过直接设置子对象的世界旋转或使用 camera.lookAt/轨道控制器来达成；Gyroscope 的优势在于：

• 天然融合进场景图（无需每帧手动同步矩阵）；
• 随 matrixWorldNeedsUpdate 体系自动递归，性能开销仅为两次 decompose/compose 矩阵运算；
• 对整体层级携带旋转的父结构（角色骨骼、复杂装配体）尤其省心。

六、深入：矩阵分解与复用零分配

进一步审视实现可发现性能与健壮性设计：

• 文件顶部声明了 6 个模块级复用变量：_translationObject、_quaternionObject、_scaleObject、_translationWorld、_quaternionWorld、_scaleWorld（examples/jsm/misc/Gyroscope.js）。这些是临时缓冲，每次 updateMatrixWorld 只复用不新建，避免在渲染循环中造成 GC 压力。
• _quaternionWorld 被分解出来但没有参与重组——这正是"丢弃父级旋转"的代码证据；其余世界分量（平移、缩放）被保留。
• 注意 this.matrixWorld 从 parent.matrixWorld 和自身 this.matrix 相乘开始，并最终被 compose 覆盖；中间结果不会污染父节点矩阵。

整个 class 本身极其精简：构造器空实现 + 唯一的 updateMatrixWorld 重写，没有引入任何额外属性或事件派发，因此可以放心地与渲染器、骨骼动画混合使用。

七、参考与源码导航

• 附加组件源码（含官方语义注释）：examples/jsm/misc/Gyroscope.js
• addon 统一导出入口（确认其被注册为 three/addons/misc/Gyroscope.js）：examples/jsm/Addons.js
• 被重写的基类方法（了解普通对象的矩阵更新语义作对比）：src/core/Object3D.js
• 真实使用范例（角色行走时保持相机稳定）：examples/webgl_loader_md2_control.html
• 底层分解/重组 API 来自 Matrix4.decompose() 与 Matrix4.compose()，实现于 src/math/Matrix4.js

小结：Gyroscope 以约 40 行核心逻辑，通过"世界矩阵 decompose → 局部旋转替换 → compose 重组"的手法，优雅地解决了"层级携带旋转"这一场景图常见难题。无论是为第三人称角色添加稳定的观察相机，还是在复杂装配体上叠加面向世界的 HUD，它都是一个值得优先考虑的内置 addon 方案。