Scene

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

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

动画

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 报告不支持。

粒子

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

过场动画

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

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

任务

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 仍无实现。

角色风格

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

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

版本能力

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

生命周期

void NotifyGameInit();
void Process();
void Shutdown();

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

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