StoryService

概览

字段	值
Kind	Service · 服务 Service
Realm	common

继承关系

• Service
  • [StoryService]（3 函数 / 3 事件）

剧情对话播放服务，负责对指定玩家驱动地图中配置的剧情对话流程，提供开始播放、结束播放与跳过剧情的控制能力，并通过 OnStoryStart、OnStoryEnd、OnStorySkip 三个事件向服务端暴露剧情生命周期的变化。地图作者可以借助它在玩家触发条件时推进剧情演出，并在剧情开始、结束或跳过时衔接后续玩法逻辑。

适用场景

当玩家进入指定区域、完成某项条件或需要强制播放一段剧情演出时，使用该服务为玩家拉起剧情；当玩家中途不愿继续观看或需要流程提前收尾时，也可以对其调用跳过或结束。监听剧情开始、结束与跳过事件还能用于在剧情结束后发放奖励、切换场景或恢复输入。

使用要点

先通过 game:GetService("StoryService") 获取服务实例，再调用 StartStory(player, storyID) 为指定玩家开始播放对应剧情；需要提前终止时调用 EndStory(player, storyID)，需要跳过时调用 SkipStory(player, storyID)。若要在剧情流程节点上做响应，可连接 OnStoryStart、OnStoryEnd、OnStorySkip 事件，在回调中接收玩家与剧情标识并执行后续处理。

注意事项

StartStory、EndStory、SkipStory 可在服务端为任意玩家调用；客户端调用时只能传入 Players.LocalPlayer。OnStoryStart、OnStoryEnd、OnStorySkip 三个事件仅在服务端触发。storyID 必须对应地图剧情配表中已存在的剧情 ID。

代码示例

服务端监听剧情开始事件

-- @runtime server
local storyService = game:GetService('StoryService')
storyService.OnStoryStart:Once(function(player, storyID)
    print('剧情开始:', player, storyID)
end)

事件 (3)

OnStoryStart

签名：OnStoryStart(player: Player, storyID: String) 触发：local

StoryService 的 OnStoryStart 事件在指定玩家的剧情开始播放时触发，仅服务端可用。回调接收 player（Player 实例）与 storyID（剧情字符串标识）两个参数。

回调参数	类型	说明
player	Player	开始播放剧情的玩家。
storyID	String	本次开始的剧情 ID，对应地图剧情配表中的剧情条目。

示例代码

服务端监听剧情开始

-- @runtime server
local storyService = game:GetService('StoryService')
storyService.OnStoryStart:Once(function(player, storyID)
    print('剧情开始:', player, storyID)
end)

OnStoryEnd

签名：OnStoryEnd(player: Player, storyID: String) 触发：local

StoryService 的 OnStoryEnd 事件在指定玩家的剧情结束时触发，仅服务端可用。回调接收两个参数：player 为对应的 Player 实例，storyID 为结束的剧情的字符串标识，可用于区分同一玩家触发的不同剧情。

回调参数	类型	说明
player	Player	结束剧情的玩家。
storyID	String	本次结束的剧情 ID。

示例代码

服务端监听剧情结束

-- @runtime server
local storyService = game:GetService('StoryService')
storyService.OnStoryEnd:Once(function(player, storyID)
    print('剧情结束:', player, storyID)
end)

OnStorySkip

签名：OnStorySkip(player: Player, storyID: String) 触发：local

StoryService 的 OnStorySkip 事件在指定玩家的剧情被跳过时触发，仅服务端可用。回调接收 player（Player 实例）与 storyID（剧情字符串标识）两个参数。

回调参数	类型	说明
player	Player	跳过剧情的玩家。
storyID	String	本次跳过的剧情 ID。

示例代码

服务端监听剧情跳过

-- @runtime server
local storyService = game:GetService('StoryService')
storyService.OnStorySkip:Once(function(player, storyID)
    print('剧情跳过:', player, storyID)
end)

函数 (3)

StartStory

签名：StartStory(player: Player, storyID: String) -> void

StoryService 的 StartStory 函数用于开始为指定玩家播放指定剧情。调用时传入 player（Player 实例）与 storyID（剧情字符串标识），函数无返回值。

参数	类型	说明
player	Player	要开始播放剧情的玩家。服务端可指定任意玩家；客户端只能传入本地玩家。
storyID	String	要开始播放的剧情 ID，对应地图剧情配表中的剧情条目。

返回值 void

示例代码

客户端为本地玩家开始剧情

-- @runtime client
local storyService = game:GetService('StoryService')
local Players = game:GetService('Players')
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local function startConfiguredStory(storyID)
    if storyID == nil or storyID == '' then return end
    storyService:StartStory(localPlayer, storyID)
end
-- 调用方把地图剧情配表中真实存在的 ID 传给 startConfiguredStory

EndStory

签名：EndStory(player: Player, storyID: String) -> void

StoryService 的 EndStory 函数用于停止指定玩家的指定剧情。调用时传入 player（Player 实例）与 storyID（剧情字符串标识），函数无返回值。

参数	类型	说明
player	Player	要停止剧情的玩家。服务端可指定任意玩家；客户端只能传入本地玩家。
storyID	String	要停止的剧情 ID。

返回值 void

示例代码

客户端结束本地玩家剧情

-- @runtime client
local storyService = game:GetService('StoryService')
local Players = game:GetService('Players')
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local function endConfiguredStory(storyID)
    if storyID == nil or storyID == '' then return end
    storyService:EndStory(localPlayer, storyID)
end
-- 调用方把正在播放的真实剧情 ID 传给 endConfiguredStory

SkipStory

签名：SkipStory(player: Player, storyID: String) -> void

StoryService 的 SkipStory 函数用于为指定玩家跳过指定剧情。调用时传入 player（Player 实例）与 storyID（剧情字符串标识），函数无返回值。

参数	类型	说明
player	Player	要跳过剧情的玩家。服务端可指定任意玩家；客户端只能传入本地玩家。
storyID	String	要跳过的剧情 ID。

返回值 void

示例代码

客户端跳过本地玩家剧情

-- @runtime client
local storyService = game:GetService('StoryService')
local Players = game:GetService('Players')
local localPlayer = Players.LocalPlayer
if localPlayer == nil then return end
local function skipConfiguredStory(storyID)
    if storyID == nil or storyID == '' then return end
    storyService:SkipStory(localPlayer, storyID)
end
-- 调用方把正在播放的真实剧情 ID 传给 skipConfiguredStory