事件順序器

事件順序器 是一個強大的框架，讓您能夠在結構化的行動和觸發器序列上構建實已發布、跨服務器事件和片段。更具體地，此模組可幫助您：

• 通過預定的音音訊、動畫和青少年配置建立結構化框架上的事件或場景。
• 在多個伺服器之間切換多個場景，同步複雜的動畫和視覺效果到時間線。
• 通過事件搜尋並預覽體驗以進行測試和開發。

這個框架在 Roblox 活動中，如 Twenty One Pilots 和 24kGoldn 演唱會以及許多受到高度訪問的體驗中進行了戰鬥測試。

若要在可編輯的空間方中看到 事件順序器 的作用，請在 Roblox Studio 中查看 音樂會 樣板。此樣板是開發人員創建事件/演唱會和熟悉各種功能和組件的完整起點。

模組使用

安裝

要在體驗中使用 事件順序器 框架：

1. 從 視圖 開啟 工具箱 並選擇 創作者商店 標籤。

   

2. 確保 模型 排序已選擇，然後單擊 查看全部 按鈕以獲得 類別 。

   

3. 找到並點擊 開發模組 磚塊。

   

4. 找到 事件順序器 模組，然後單擊它或拖放到 3D 視檢視中。

   

5. 在 導航器 窗口中，將整個 事件順序器 模型移至 服務器腳本服務 。執行體驗時，模組會分配到各種服務並開始運行。

   

框架模式

替換模式

預設框架模式是替換模式，在該模式中，您通過放置3D物件、地形、照明特性、環境效果和使用者介面對象來設計獨特的場景。當場景載入時,這些對象和屬性會被分配到Workspace、Terrain和Lighting、 取代 現有對象/屬性來形成複製空間。

線上模式

另一種替代框架模式是 線上模式 ，在其中您類似地設計獨特的 場景 與對應的流程/事件的腳本邏輯，但框架將 不會 摧毀現有的 3D 對象 、地形 、照明特性 、環境效果 和用戶界面對象，以便在載入時從場景的 環境 文件夾複製資產/特性。

要啟用線上模式：

1. 在 伺服器腳本服務 中放置的 事件順序器 模型內，挖掘並選擇 線上 值在 複製存儲服務 文件夾內。

   

2. 在 屬性 窗口中，切換其 值 檢查框。

   

創建場景

一個 場景 本質上是整個事件或切換場景包裝在一系列文件夾中的一部分。每個場景包含定義其流程/事件的腳本邏輯，並且一個場景可以儲存自己的 3D 物件 , 地形 , 照明特性 , 環境效果 , 和使用者介面對象。

若要快速開始，您可以在模組主目錄內找到空白場景：

1. 擴展 事件順序器 文件夾，找到 空白場景 文件夾。

   

2. 將整個 空白場景 文件夾移動或複製到 重複儲存 中。

   

   開發事件時，您可以選擇將場景放置在 導航器 層級中的其他位置，並使用其 順序器場景 欄位將它們標籤化，或 Studio 的 標籤編輯器 ( 空白場景 已被標籤為此)。然而，您需要將所有事件準備好的場景移動到 ReplicatedStorage ，以便它們在整個事件流程中運作。

時間長度

每個場景應該有一個 時間長度 ，以秒為單位，定義其時間長度，就像電影或演唱會有一個固定時間一樣。時間長度被定義為場景夾子的數字 屬性 上的名為 時間長度 的文件夹，您可以直接在 Studio 中設置或通過 Instance:SetAttribute() 程式設定。

環境

場景的 環境 文件夾包含使用者看到和聽到的所有內容，包括 3D 物件、地形、照明特性 和 環境效果，以及使用者介面對象。當場景載入時，這些對象和屬性會被分配到 Workspace、Terrain 和 Lighting，替換現有對象/屬性來形成複製空間。

環境 文件夾 包含以下容器：

事件

場景的 事件 文件夾純粹是用於 RemoteEvents 通訊的暫時位置，用於連接 客戶端 和 服務器 模塊。這個文件夾中沒有放置任何東西的要求。

客戶

此腳本在客戶端執行 資料庫 邏輯。

服務器

此腳本在服務伺服器上執行 資料庫 邏輯。

場景圖

場景的 模型 定義在場景時間線的哪一點發生了什麼事。您應該在其 客戶端模組 和 伺服器模組 中定義場景的 schema，並包含 生命週期鉤子 來管理當 配置 發生時。

生命週期鉤子

Schema 生命週期鉤 讓您管理場景操作發生的時間。生產中的場景通常會在最簡單的流程中運行：

• 在設定中 → 在執行中 → 在結束場景中

在運行時，可能會在尋找時中斷：

• 在設定中 → 在執行中… 尋找 → 在執行中… 尋找 → 在執行結束場景中 → 在結束場景中搜尋

所有三個鉤子也可以重複，如果場景被重玩：

• 在設置中 → 在運行中 → 在結束場景中… 重玩 → 在設置中 → 在運行中 → 在結束場景中

配置

Schema 配置 定義場景的核心操作，例如在00:32播放音頻，將動畫排隊與該音訊同步，在煙花顯示中安排場景事件等等。每個配置都支持某些回呼功能，其中第一個參數（self）是配置實個體、實例。

尋找場景

事件順序器 的獨特功能是能夠「尋找」鏡頭周圍的場景，像你通過視頻尋找一樣。在 取代模式 中，您也可以在部署到生產之前切換場景來預覽整個多場景事件。

尋場不對所有人開放 因為只有簡單享受活動的用戶不應該擁有控制其時間流的能力。相反，您必須根據事件的 PlaceId 以及特定的 UserIds 和/或 群組 和角色內的角色授予許可。

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. 從 Studio 的 視圖 選單開啟 工具箱 。

   

2. 選擇 創作者商店 標籤後，從下拉選單中選擇 插件 。

   

3. 在搜尋欄中，輸入 場景管理器 並按下 Enter 來找到外掛程式。

   

4. 點擊外掛程式的圖示查看其詳情，然後點擊 安裝 按鈕。

5. 一旦插件安裝，它就會出現在 Studio 的 插件 標籤。

載入和卸下場景

如同在 創建場景 所述，場景的 環境 文件夾包含所有用戶看到和聽到的內容，包括 3D 物件。插件可幫助您快速將場景資產載入或從工作區內的組織化文件夾中載出。

儲存和載入燈光

頂層 Lighting 服務存儲所有空間方的照明特性和視覺效果。因為它是一個高級服務，你不能手動將它移動到特定場景的 環境 / 服務器 或 環境 / 客戶端 文件夾。取而代之，您可以使用插件將其屬性和子孫複製到場景的 環境 / 燈光 文件夾。

1. 通過最高級別的 服務 配置場景的 照明特性、後期處理效果、大氣效果 和 天空盒 通過最高級別的服務配置場景的照明特性、後期處理效果、大氣效果和天空盒。

   

2. 在 場景管理器 插件窗口中，點擊 儲存燈光 以獲得所需的場景。

3. 選擇並擴展該場景的 環境 / 燈光 配置和你會看到相同的燈光特性，如 屬性 的文件夾，以及複製的頂層服務的子女。

   

   

   一旦燈光屬性和子燈光被保存到場景中，您可以單擊插件窗口中的載入燈光來快速載入到頂層服務中。

儲存和載入地形

由於 Terrain 是 Workspace 內的高級類別，您無法手動將生成或雕刻的地形移動到特定場景的 環境 / 伺服器 或 環境 / 客戶端 文件夾。取而代之，您可以使用插件將其複製到場景的 環境 / 地形 文件夾。

1. 通過頂層 地形 服務配置場景的地形。

   

2. 在 場景管理器 插件窗口中，點擊 保存地形 以獲得所需的場景。

3. 選擇並擴展該場景的 環境 / 地形 文件夾，您將看到一個 地形區域 對象，它代表已儲存的地形。

   

   一旦地形被保存到場景中，您可以單擊插件窗口中的載入地形來快速將其加載到最高級別的服務中。

API 參考

數據模型生命週期勾子

在設置上

在設置生命週期勾是用於初始化在運行或結束場景中會被引用的資產和變量，設置等會持續到場景期間的等此鉤接收 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

返回場景 模型 的實例，用於創建場景的邏輯。

客戶端模型
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)

設定場景警告時間

設置警告發送到所有場景的 結束 時間量。您可以通過 在場景結束警告客戶端 或 在場景結束警告服務器 來偵測警告。

腳本
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")

事件

在場景結束警告For客戶

在場景即將結束之前，在客戶端發生火災。預設時間為 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)

在OrchestrationFinished

當場景達到其 時間長度 並已有效結束時，在伺服器上發生火災。這個事件會收到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)