事件顺序器

事件顺序器 是一个强大的框架，可以让你构建实已发布、跨服务器事件和场景，以及基于结构化行动和触发的顺序。更具体地，该模块可帮助您：

• 通过预定的音频、动画和青少年配置在结构化框架上构建事件或场景。
• 在多个服务器之间转换多个场景，同步复杂的动画和视觉效果到时间线。
• 通过事件查找并预览体验以进行测试和开发。

这个框架在 Roblox 活动中已被战斗测试，例如 Twenty One Pilots 和 24kGoldn 音乐会以及许多高度访问的体验。

要在编辑可编辑的场景方中看到 事件顺序器 的行动，请检查 Roblox Studio 中的 音乐会模板。该模板是开发人员创建事件/音乐会的全面起点，以及熟悉其涉及的各种功能和组件。

模块使用

安装

要在体验中使用 事件顺序器 框架：

1. 从视图打开工具箱并选择 创建者商店 标签。

   

2. 确保 模型 排序已选择，然后单击 查看全部 按钮以获取 类别 。

   

3. 找到并单击 开发模块 瓦片。

   

4. 找到 事件顺序器 模块，单击它或拖放到 3D 视查看中。

   

5. 在 探索器 窗口中，将整个 事件顺序器 模型移至 服务器脚本服务 。在运行体验时，模块将分配到各种服务并开始运行。

   

框架模式

替换模式

默认框架模式是 替换模式 ，在该模式中，您通过放置3D对象、地形、照明属性、环境效果和用户界面对象到该场景的 环境 文件夹中，设计独特的场景。当场景加载时，这些对象和属性会被分配到 Workspace , Terrain , 和 Lighting , 替换 现有对象/属性以形成克隆空间。

在线模式

替换框架模式是 线程模式 ，在其中您类似地设计独特的 场景 与脚本逻辑为其流程/事件，但框架将不会 摧毁现有的 3D 对象 、 地形 、 灯光属性 、 环境效果 和用户界面对象，以便从场景的 环境文件夹 复制资产/属性。

要启用插入模式：

1. 在 服务器脚本服务 中放置的 事件顺序器 模型内，钻取并选择 在线 值，放置在 复制存储服务 文件夹内。

   

2. 在 属性 窗口中，切换其 价值 检查框。

   

创建场景

一个 场景 基本上是整个事件或一段剪辑的一部分。包装在一系列文件夹中。每个场景包含定义其流程/事件的脚本逻辑，一个场景可以存储自己的 3D 对象 , 地形 , 照明属性 , 环境效果 ,和用户界面对象。

要快速开始，您可以在模块的主文件夹内找到一个空场景：

1. 扩展 事件顺序器 文件夹，找到 空白场景 文件夹。

   

2. 移动或复制整个 空白场景 文件夹到 复制存储 。

   

   开发事件时，你可以在 Explorer 层次中另选择将场景放置在其他地方，并使用 编程器场景 使用其属性的 标签部分标记它们，或 Studio 的 标签编辑器 ( 空白场景 已被标记为此)。然而，您需要将所有准备事件场景移至 复制存储 以便它们在整个事件流程中工作。

时间长度

每个场景应该有一个 时长 ，以秒为单位，定义其时长 — 就像电影或音乐会有一个固定时长一样。时长被定义为场景文件夹名为 时长 的数字属性，您可以直接在 Studio 中设置或通过 程序化设置。

环境

场景的 环境 文件夹包含用户看到和听到的一切，包括3D对象、地形、照明属性和环境效果，以及用户界面对象。当场景加载时，这些对象和属性会被分配到 Workspace , Terrain 和 Lighting , 并替换现有对象/属性形成克隆空间。

环境文件夹 包含以下容器 ：

事件

场景的 事件 文件夹是纯粹的占位符，用于在 RemoteEvents 之间传达的 客户端 和 服务器 模块。这个文件夹中放置任何东西不是必需的。

客户

这个脚本在客户端执行数据库逻辑。

服务器

该脚本在服务器上执行数据库逻辑。

场景图

场景的 框架 定义了在场景时间线的某个时刻发生的事情。你应该在其 客户端模块 和 服务器模块 中定义场景的 schema，并包含 生命周期钩 来管理当 配置 发生时。

生命周期 Hooks

Schema 生命周期钩 让你管理场景操作发生的时间。生产中的场景通常会在最简单的流程中运行：

• 在设置中 → 在运行中 → 在结束场景中

在运行时可能在寻找时中断：

• 在设置中 → 在运行中 … 寻找 → 在运行中 … 寻找 → 在运行结束场景中 → 在运行结束场景中

三个钩子也可以重复，如果场景被重播：

• 在设置中 → 在运行中 → 在结束场景中 … 重播 → 在设置中 → 在运行中 → 在结束场景中

配置

Schema 配置 定义场景的核心操作，例如在 00:32 播放音频，将 动画 排队与该音频同步，在烟花显示中安排场景事件，等等。每个配置都支持某些回调函数，其中第一个参数（self）是配置实例。

寻找场景

事件顺序器 的独特功能是能够“寻找”周围的场景，像你通过视频寻找一样。在 替换模式 中，您还可以在部署到生产之前在场景之间切换，预览整个多场景事件。

场景寻找不对所有人开放 因为用户仅仅享受活动的情况下不应该有控制其时间流的能力。相反，您必须根据事件的 以及特定的 和/或 组和角色来授予权限。

1. 在 Script 内创建一个新的 ServerScriptService 。

2. 将以下代码粘贴到新脚本中。

   脚本 - 设置寻求权限
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))
   
   EventSequencer.setSeekingPermissions({
   	placeIDs = {},
   	userIDs = {},
   	groups = {
   		{GroupID = , MinimumRankID = },
   	}
   })

3. 按照以下步骤填写 setSeekingPermissions 调用中的下列表：

   placeIDs	分号分隔的列表 PlaceId 值以支持在内部寻找。
   userIDs	分号分隔的列表 UserIds 对于那些可以在支持的地点内搜索的人。
   groups	分号分隔的表列表，每个列表包含一个 组 ID 和那个群组成员的最低等级，可以在支持的地点内寻找。

场景管理插件

场景管理器插件是加载和卸载场景、照明和地形的有用工具。除非您正在使用 在线模式，否则建议您使用此插件而不是手动放置/编辑场景对象和属性。

要安装插件：

1. 从工作室的 视图 菜单打开 工具箱 。

   

2. 选择 创建者商店 选项卡后，从下拉菜单中选择 插件 。

   

3. 在搜索字段中，输入 场景管理器 并按 Enter 找到插件。

   

4. 点击插件的图标查看详细信息，然后单击 安装 按钮。

5. 安装完成后，插件会出现在 Studio 的 插件 选项卡中。

加载和卸载场景

如同在 创建场景 中所述，场景的 环境 文件夹包含用户看到和听到的一切，包括 3D 对象。插件可以帮助你快速将场景资产加载到或从工作区内的组织文件夹中。

保存并加载灯光

顶层 Lighting 服务存储了一个地方的所有照明属性和视觉效果。由于它是顶层服务，您不能手动将其移至特定场景的 环境 / 服务器 或 环境 / 客户端 文件夹。相反，您可以使用插件将其属性和子项复制到场景的 环境 / 照明 文件夹。

1. 通过顶层 服务 配置场景的 照明属性、后期效果、大气效果 和 天空盒 通过顶层服务配置。

   

2. 在 场景管理器 插件窗口中，单击 保存灯光 为所需场景。

3. 选择并扩展该场景的 环境 / 灯光 配置，您将看到与文件夹的属性相同的灯光属性，以及顶级服务的Lighting的克隆。

   

   

   一旦灯光属性和子灯被保存到场景中，您可以单击插件窗口中的加载灯光来快速将它们加载回顶层服务。

保存并加载地形

由于 Terrain 是 Workspace 内的顶层类，你不能手动将生成或雕刻的地形移至特定场景的 环境 / 服务器 或 环境 / 客户端 文件夹。相反，您可以使用插件将其复制到场景的 环境 / 地形 文件夹。

1. 通过顶层 地形 服务配置场景的地形。

   

2. 在 场景管理器 插件窗口中，单击 保存地形 为所需场景。

3. 选择并扩展那个场景的 环境 / 地形 文件夹，你会看到一个 地形区域 对象，它代表已保存的地形。

   

   一旦地形为场景保存，您可以单击插件窗口中的“加载地形”来快速将其加载到顶级服务中。

API 参考

数据模型生命周期钩子

在启动时

在设置 生命周期钩是用于初始化在运行或结束场景中引用的资产和变量，设置connections，用于持续时间的场景等。这个钩接收 timePositionObject 参数，可以让你在设置时读取当前时间。

客户端模型
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

local Schema = EventSequencer.createSchema()

local clientEnvironment
local serverEnvironment
local dummy

Schema.OnSetup = function(timePositionObject)
	print("OnSetup (Client)")

	-- 访问场景环境；不适用于并行模式
	clientEnvironment = EventSequencer.getCurrentSceneEnvironment()
	serverEnvironment = EventSequencer.getCurrentServerEnvironmentFromClient()
	-- 等待资产
	dummy = clientEnvironment:WaitForChild("Dummy")

	print("Current time is:", timePositionObject.Value)
end

服务器模型
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

local Schema = EventSequencer.createSchema()

local serverEnvironment
local partColorConnection
local changePartColorEvent = script.Parent.Events.ChangePartColor

Schema.OnSetup = function(timePositionObject)
	print("OnSetup (Server)")

	-- 访问场景环境；不适用于并行模式
	serverEnvironment = EventSequencer.getCurrentSceneEnvironment()
	partColorConnection = changePartColorEvent.OnServerEvent:Connect(function(player, changedPart, newColor)
		serverEnvironment.changedPart.Color = newColor
	end)

	print("Current time is:", timePositionObject.Value)
end

在运行中

在运行 是在模型中的主操作生命周期钩。它应该包含场景所有的时间配置配置，从播放音频或动画到安排事件，如烟花显示。

客户端模型
Schema.OnRun = function()
	print("OnRun (Client)")

	local MainAudio = Schema:audio({
		StartTime = 1,
		SoundId = "rbxassetid://1838673350",
		OnStart = function(self)
			print("Audio playing")
		end,
		OnEnd = function(self)
			print("Audio ended")
		end
	})
end

在结束场景

OnEndScene 生命周期钩对清理场景中的任何突出问题都有用，例如清理在OnSetup或OnRun期间创建的连接，这些连接仍然存在于场景期间。

服务器模型
Schema.OnEndScene = function()
	print("OnEndScene (Server)")

	if partColorConnection then
		partColorConnection:Disconnect()
		partColorConnection = nil
	end
end

模型配置

音频

在工作区创建一个 Sound 对象，在特定时间播放。音效将在场景结束或 Sound 对象播放完毕后删除。

客户端模型
Schema.OnRun = function()
	print("OnRun (Client)")

	local MainAudio = Schema:audio({
		StartTime = 1,
		SoundId = "rbxassetid://1838673350",
		OnStart = function(self)
			print("Audio playing")
		end,
		OnEnd = function(self)
			print("Audio ended")
		end
	})
end

动画

创建一个 Animation ，在特定时间播放。

客户端模型
Schema.OnRun = function()
	print("OnRun (Client)")

	local MainAudio = Schema:audio({
		StartTime = 1,
		SoundId = "rbxassetid://1838673350",
	})

	local DanceAnimation = Schema:animate({
		AnimationId = "rbxassetid://3695333486",
		Rig = Dummy,
		Speed = 1,
		FadeInTime = 0.1,
		FadeOutTime = 0.3,
		SyncToAudio = {
			Audio = MainAudio,
			StartAtAudioTime = 5,
		},
		OnStart = function(self)
			print("Animation playing")
		end,
		OnEnd = function(self)
			print("Animation stopped")
		end
	})
end

青少年

创建一个可配置的 Tween ，它在寻找和动态匹配中保存，这意味着您可以在不同时间点链接青少年，所有东西都应该像预期一样播放和同步。

客户端模型
Schema.OnRun = function()
	print("OnRun (Client)")

	local MainAudio = Schema:audio({
		StartTime = 1,
		SoundId = "rbxassetid://1838673350",
	})

	local LightFadeOut = Schema:tween({
		StartTimes = {29.884},
		Tween = {
			Object = game:GetService("Lighting"),
			Info = TweenInfo.new(2, Enum.EasingStyle.Sine, Enum.EasingDirection.Out),
			Properties = {
				Brightness = 0,
			}
		},
		SyncToAudio = {
			Audio = MainAudio,
			StartAtAudioTimes = {5, 7.2, 9.4, 11.6},
		},
		OnStart = function(self)
			print("Tween playing")
		end,
		OnHeartbeat = function(self, alpha)
			print("Tween alpha", alpha)
		end,
		OnEnd = function(self)
			print("Tween completed")
		end,
	})
end

间隔

在指定的时间和频率上执行自定义回调函数，在秒内。用于重复事件，例如闪烁的灯光、脉冲音频强度等最低可能的频率为 0 秒，但技术上最低频率总是被限制为 Heartbeat 。

客户端模型
Schema.OnRun = function()
	print("OnRun (Client)")

	local MainAudio = Schema:audio({
		StartTime = 1,
		SoundId = "rbxassetid://1838673350",
	})

	local ClientTimerUpdate = Schema:interval({
		Frequency = 1,
		SyncToAudio = {
			StartAtAudioTime = 2.5,
			EndAtAudioTime = 10,
			Audio = MainAudio
		},
		OnInterval = function(self)
			print(MainAudio.Sound.TimePosition, MainAudio.CurrentSoundIntensityRatio)
		end,
	})
end

日程表

与 间隔 相似，除了你可以为同一事件定义多个特定起始时间，例如在场景中两次安排烟花显示。

客户端模型
Schema.OnRun = function()
	print("OnRun (Client)")

	Schema:schedule({
		StartTimes = {5, 27.25},
		OnStart = function(self)
			-- 初始化临时心跳连接
			local tempConnection = RunService.Heartbeat:Connect(function()

			end)
			-- 连接框架的信息
			Schema:inform(tempConnection)
		end
	})
end

通知

向框架通知任何模块、用户界面对象、连接等信息这些在 在运行 生命周期钩中创建，确保在 寻找 时正确清理。使用案例包括：

• 通知框架暂时的临时连接，例如 RunService.Heartbeat ，以便连接在寻找场景持续时间的早期时被清理。

  服务器模型
  Schema.OnRun = function()
  	print("OnRun (Server)")
  
  	Schema:schedule({
  		StartTimes = {5},
  		OnStart = function(self)
  			-- 初始化临时心跳连接
  			local tempConnection = RunService.Heartbeat:Connect(function()
  
  			end)
  			-- 连接框架的信息
  			Schema:inform(tempConnection)
  		end
  	})
  end

• 在 ModuleScript 中调用一个自定义的“清理”函数，在 OnRun 生命周期钩中初始化连接或其他参考。

  服务器模型
  local ReplicatedStorage = game:GetService("ReplicatedStorage")
  local RunService = game:GetService("RunService")
  
  local customModule = require(ReplicatedStorage:WaitForChild("CustomModule"))
  
  local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))
  
  local Schema = EventSequencer.createSchema()
  
  Schema.OnRun = function()
  	print("OnRun (Server)")
  
  	Schema:schedule({
  		StartTimes = {5},
  		OnStart = function(self)
  			-- 在自定义模块中调用“init”函数
  			customModule.init()
  			-- 在场景清理时调用“清洁”函数在自定义模块上
  			Schema:inform(customModule, customModule.clean)
  		end,
  	})
  end

  模块脚本 - 自定义模块
  local RunService = game:GetService("RunService")
  
  local CustomModule = {}
  
  CustomModule.init = function()
  	-- 初始化心跳连接
  	CustomModule.connection = RunService.Heartbeat:Connect(function()
  
  	end)
  end
  
  CustomModule.clean = function()
  	-- 断开并清除心跳连接
  	if CustomModule.connection then
  		CustomModule.connection:Disconnect()
  		CustomModule.connection = nil
  	end
  end
  
  return CustomModule

功能

加载场景

通过 sceneName 程序atically加载场景，并从其开始时起将其开始在 startTime 。在寻找发生之前，场景从服务器加载的时间将有 5 秒的“优惠期”，场景开始播放。这意味着如果你在下午 4:15:00 正确地调用 loadScene("[SceneName]", 20)，框架将在请求的 20 秒之外等待 5 秒，并在下午 4:15:25 开始场景。

脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

-- 当当前场景完成时确定要加载的下一个场景
EventSequencer.onOrchestrationFinished:Connect(function(endedSceneName)
	if endedSceneName == "PreShow" then
		-- “演出前”结束；在演唱会中加载第一场景
		EventSequencer.loadScene("Track1")
	elseif endedSceneName == "Track1" then
		-- “Track1”结束；在演唱会中加载第二场景
		EventSequencer.loadScene("Track2")
	else
		-- 循环返回演出前的场景
		EventSequencer.loadScene("PreShow")
	end
end)

创建 Schema

返回场景schema的实例，用于创建场景的逻辑。

客户端模型
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

local Schema = EventSequencer.createSchema()

Schema.OnSetup = function(timePositionObject)
	print("OnSetup (Client)")
end

寻找

寻找time值，在几秒钟内，从当前加载的场景开始。

脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

EventSequencer.seek(95.58)

设置场景警告时间

设置警告发送的所有场景的 结束 时间量。您可以通过客户端的 onSceneEndingWarningForClient 或服务器的 onSceneEndingWarningForServer 检测警告。

脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

-- 加载场景
EventSequencer.loadScene("BeautifulScene")

-- 将警告时间设置为场景结束前 5 秒
EventSequencer.setSceneWarningTime(5)

-- 检测场景即将结束时
EventSequencer.onSceneEndingWarningForServer:Connect(function()
	warn("Scene is about to end!")
end)

设置寻找权限

根据事件的 PlaceId 以及特定 UserIds 和/或 组 和角色内的特定权限进行权限寻求。请参阅寻找和切换场景获取更多信息。

获取当前场景环境

返回当前场景的客户端或服务器端 环境 文件夹，根据是否从 客户端 脚本或 服务器 脚本分别调用。

客户端模型
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

local Schema = EventSequencer.createSchema()

local clientEnvironment
local serverEnvironment

Schema.OnSetup = function(timePositionObject)
	print("OnSetup (Client)")

	-- 访问场景环境；不适用于并行模式
	clientEnvironment = EventSequencer.getCurrentSceneEnvironment()
	serverEnvironment = EventSequencer.getCurrentServerEnvironmentFromClient()

	print("Current time is:", timePositionObject.Value)
end

服务器模型
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

local Schema = EventSequencer.createSchema()

local serverEnvironment
local partColorConnection
local changePartColorEvent = script.Parent.Events.ChangePartColor

Schema.OnSetup = function(timePositionObject)
	print("OnSetup (Server)")

	serverEnvironment = EventSequencer.getCurrentSceneEnvironment()

	partColorConnection = changePartColorEvent.OnServerEvent:Connect(function(player, changedPart, newColor)
		serverEnvironment.changedPart.Color = newColor
	end)
end

从客户端获取当前服务器环境

返回当前场景的 服务器端 环境 文件夹。与 getCurrentSceneEnvironment 不同，您可以从 客户端 脚本脚本中调用此操作。

客户端模型
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

local Schema = EventSequencer.createSchema()

local clientEnvironment
local serverEnvironment

Schema.OnSetup = function(timePositionObject)
	print("OnSetup (Client)")

	-- 访问场景环境；不适用于并行模式
	clientEnvironment = EventSequencer.getCurrentSceneEnvironment()
	serverEnvironment = EventSequencer.getCurrentServerEnvironmentFromClient()

	print("Current time is:", timePositionObject.Value)
end

正在加载场景

从服务器调用以确定场景是否正在加载。

脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

print(EventSequencer.isLoadingScene())

while EventSequencer.isLoadingScene() do
	task.wait()
end
print("Scene loaded")

事件

在场景结束警告为客户

在场景即将结束之前，在客户端发生火焰。默认时间为 3 秒，但您可以通过 setSceneWarningTime 来配置它。此事件只能在 LocalScript 中连接。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

-- 检测场景即将结束（客户端）
EventSequencer.onSceneEndingWarningForClient:Connect(function()
	warn("Scene is about to end!")
end)

关于服务器的场景结束警告

在场景即将结束之前，服务器上发生火灾。默认时间为 3 秒，但您可以通过 setSceneWarningTime 来配置它。此事件只能在 Script 中连接。

脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

-- 检测场景即将结束（服务器端）
EventSequencer.onSceneEndingWarningForServer:Connect(function()
	warn("Scene is about to end!")
end)

在场景加载为客户端时

当场景开始时，在客户端发生火焰。此事件只能在 LocalScript 中连接。

本地脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

-- 检测场景何时开始（客户端）
EventSequencer.onSceneLoadedForClient:Connect(function()
	warn("Scene is starting!")
end)

关于协调完成

当场景达到其 时间长度 并已有效结束时，在服务器上发生火焰。这个事件收到了endedSceneName字符串名称参数对刚刚完成的场景，你可以链接这个事件来条件地加载另一个场景。只能在 Script 中连接。

脚本
local ReplicatedStorage = game:GetService("ReplicatedStorage")

local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))

-- 当当前场景完成时确定要加载的下一个场景
EventSequencer.onOrchestrationFinished:Connect(function(endedSceneName)
	if endedSceneName == "PreShow" then
		-- “演出前”结束；在演唱会中加载第一场景
		EventSequencer.loadScene("Track1")
	elseif endedSceneName == "Track1" then
		-- “Track1”结束；在演唱会中加载第二场景
		EventSequencer.loadScene("Track2")
	else
		-- 循环返回演出前的场景
		EventSequencer.loadScene("PreShow")
	end
end)