---
title: "Scene"
description: "动画、粒子、过场动画。"
---

---
title: Scene
description: 动画、粒子、过场动画。
---

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

> Scene 的游戏对象访问和生命周期由 XBase 持有。XMenu 只负责菜单参数转换、通知和能力判断；当前静态库不支持的版本必须通过 `FeatureCapability` 禁用。

## 动画

```cpp
struct AnimationOptions {
    bool loop = false;
    bool secondary = false;
    bool onTargetPed = false;
};

bool PlayAnimation(const char* group, const char* name, bool loop);
bool PlayAnimation(const char* group, const char* name, const AnimationOptions& options);
bool StopAnimation();
```

- 三参数版本等价于 `AnimationOptions{ .loop = loop }`。
- `secondary` 使用 `TASK_PLAY_ANIM_SECONDARY` 播放上半身叠加动画。
- `onTargetPed` 对玩家当前瞄准的 Ped 播放；没有有效目标时返回 `false`。
- 非 `PED` 动画组由 XBase 负责请求与延迟卸载，宿主不要自行调用 `REQUEST_ANIMATION`。
- 只有 SA 实现返回真实结果；VC/III 通过 `FeatureCapability::SceneAnimation` 报告不支持。

## 粒子

```cpp
bool PlayParticle(const char* name);
bool RemoveAllParticles();      // 清除所有通过 XBase 创建的粒子
bool RemoveLatestParticle();    // 清除最近创建的粒子
```

## 过场动画

```cpp
bool StartCutscene(const char* name);
bool StartCutscene(const char* name, int interior);
bool StopCutscene();
bool IsCutsceneRunning();
```

带 `interior` 的重载会切换 `SET_AREA_VISIBLE`，并在过场结束时把玩家恢复到原来的室内编号与载具座位。

## 任务

```cpp
const char* GetMissionStatus(); // 返回 "No Mission" / "On Mission" / "Passed" / "Failed"
bool FailMission();             // 失败当前任务
bool StartMission(int missionId); // 启动指定任务
```

`StartMission()` 在玩家不存在、玩家当前无法开始任务或处于室内区域时返回 `false`；成功启动前会清空通缉等级。任务编号是游戏内部编号，任务目录由宿主数据维护，XBase 不内置任务名称表。

VC/III 的 portable 后端同样支持任务状态、失败与启动：状态只区分 `On Mission` 与 `No Mission`，且不检查室内区域，`SceneMission` 在 VC/III 报告为 `Partial`。动画、粒子与过场在 VC/III 仍无实现。

## 角色风格

```cpp
bool SetFightingStyle(int style);  // 设置战斗风格（0=普通, 1=拳击, ...）
bool SetWalkingStyle(int style);   // 设置走路风格
```

战斗风格对应 GTA SA opcode 0x0730，行走风格对应 0x0747。

## 版本能力

| FeatureCapability | SA | VC | III |
|---|:-:|:-:|:-:|
| SceneMission | ✅ | ◐ | ◐ |
| SceneAnimation | ✅ | ✖ | ✖ |
| SceneParticle / SceneCutscene | ◐ | ✖ | ✖ |

VC/III 上 `SceneMission` 为 `Partial`，其余 Scene 能力返回 `Unsupported`；页面必须逐项查询 `FeatureCapability`，不能因为 `Capability::Scene` 可链接就启用全部入口。

## 生命周期

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

`Scene::Process()` 由 `Core::Process()` 唯一调用，用于清理已结束粒子和延迟释放动画组。宿主不得直接调用它。`NotifyGameInit()` 丢弃上一局的粒子与动画组状态。

`Shutdown()` 清理 XBase 创建的粒子、动画组状态和待释放任务。