---
title: "Bounce"
description: "按节拍压缩和拉伸载具与行人的渲染期视觉效果。"
---


`include/XBase/Bounce.h` · `XBase::Bounce`

> `Bounce` 只修改渲染矩阵，不改写物理、碰撞、速度和操控。宿主只传值类型设置，渲染事件、矩阵快照和恢复由 XBase 后端统一管理。

## 设置

```cpp
struct Settings {
    bool enabled = false;
    bool otherVehicles = false;
    bool people = false;
    float bpm = 135.0f;
    float amplitude = 0.20f;
    int easing = 1;
};

bool SetSettings(const Settings& settings);
Settings GetSettings();
```

- `enabled` 控制地面载具，包括汽车、卡车和四轮摩托。
- `otherVehicles` 控制摩托、船、直升机、飞机等其余载具。
- `people` 控制行人和玩家角色；已经在弹跳载具内的人物由载具整体矩阵带动，避免重复缩放。
- `bpm` 收敛到 20~300，`amplitude` 收敛到 0~0.75，`easing` 支持 0 线性、1 正弦、2 二次和 3 回弹。
- 三个开关可以独立组合，只有至少一个开关开启且幅度大于零时才执行渲染变形。

```cpp
XBase::Bounce::Settings settings;
settings.enabled = true;
settings.otherVehicles = true;
settings.people = false;
settings.bpm = 128.0f;
settings.amplitude = 0.18f;
settings.easing = 1;
XBase::Bounce::SetSettings(settings);
```

## 生命周期

```cpp
void Init();
void NotifyGameInit();
void Process();
void Shutdown();
```

`Init()` 订阅载具、行人和销毁事件，挂载是幂等的。`Process()` 每帧推进节拍相位并恢复上一帧的矩阵快照；`NotifyGameInit()` 丢弃旧世界快照，避免读档后访问失效对象；`Shutdown()` 恢复矩阵并解除所有事件订阅。

## 渲染边界

- 使用载具和行人的渲染事件，在渲染前写入呈现矩阵，下一帧开始前恢复原始矩阵。
- 车辆会按碰撞包围盒保持最低点接地，避免压缩时轮胎穿入地面。
- 行人会同时处理根矩阵和动画骨骼矩阵，保留脚底锚点。
- 游戏暂停、代码暂停、世界未就绪或对象没有 RenderWare 对象时直接跳过。
- 载具和行人销毁事件会先恢复矩阵，防止悬空矩阵指针。

## 版本能力

| FeatureCapability | SA | VC | III |
|---|:-:|:-:|:-:|
| BounceVehicles | ✅ | ✅ | ✅ |
| BouncePeople | ✅ | ✅ | ✅ |

当前实现不接管 ViceBounce 的音乐导入、节拍图同步和过场演员渲染；这些属于独立的音频与过场管线。