Event Sequencer

EventSequencer is a powerful framework that enables you to build live, cross-server events and cutscenes on a structured sequence of actions and triggers. More specifically, this module helps you:

• Build an event or cutscene on a structured framework through scheduled configurations of audio, animations, and tweens.
• Transition between multiple scenes across multiple servers, synchronizing complex animations and visuals to a timeline.
• Seek through an event and preview the experience for testing and development purposes.

This framework has been battle tested in Roblox events like the Twenty One Pilots and 24kGoldn concerts, as well as many highly visited experiences.

To see EventSequencer in action within an editable place, check out the Concert template in Roblox Studio. This template is a comprehensive starting point for developers to create events/concerts and familiarize themselves with the various features and components involved.

Module Usage

Installation

To use the EventSequencer framework in an experience:

1. From the View, open the Toolbox and select the Creator Store tab.

   

2. Make sure the Models sorting is selected, then click the See All button for Categories.

   

3. Locate and click the Dev Modules tile.

   

4. Locate the Event Sequencer module and click it, or drag-and-drop it into the 3D view.

   

5. In the Explorer window, move the entire EventSequencer model into ServerScriptService. Upon running the experience, the module will distribute itself to various services and begin running.

   

Framework Modes

Replace Mode

The default framework mode is replace mode in which you design unique scenes by placing 3D objects, terrain, lighting properties, environmental effects, and user interface objects into that scene's Environment folder. When a scene loads, those objects and properties get distributed into Workspace, Terrain, and Lighting, replacing existing objects/properties to form a cloned space.

Inline Mode

An alternate framework mode is inline mode in which you similarly design unique scenes with scripting logic for their flow/events, but the framework will not destroy existing 3D objects, terrain, lighting properties, environmental effects, and user interface objects in order to clone assets/properties from a scene's Environment folder upon loading.

To enable inline mode:

1. Inside the EventSequencer model that you placed in ServerScriptService, drill down and select the Inline value inside the ReplicatedStorage folder.

   

2. In the Properties window, toggle on its Value checkbox.

   

Creating Scenes

A scene is essentially part of an overall event or a cutscene wrapped up in a series of folders. Each scene contains scripting logic that defines its flow/events, and a scene can store its own 3D objects, terrain, lighting properties, environmental effects, and user interface objects.

To get started quickly, you can find an empty scene inside the module's main folder:

1. Expand the EventSequencer folder and locate the BlankScene folder.

   

2. Move or copy the entire BlankScene folder into ReplicatedStorage.

   

   While developing an event, you can alternatively place scenes elsewhere in the Explorer hierarchy and tag them with SequencerScene using the Tags section of their properties, or Studio's Tag Editor (BlankScene is already tagged as such). However, you'll need to move all event-ready scenes to ReplicatedStorage in order for them to work within the overall event flow.

Time Length

Each scene should have a time length, in seconds, defining its duration — just like a movie or concert has a set duration. Time length is defined as a numeric attribute on the scene's folder named TimeLength which you can set directly in Studio or programmatically through Instance:SetAttribute().

Environment

A scene's Environment folder contains everything that users see and hear, including 3D objects, terrain, lighting properties and environmental effects, and user interface objects. When a scene loads, those objects and properties get distributed into Workspace, Terrain, and Lighting, replacing existing objects/properties to form a cloned space.

The Environment folder contains the following containers:

Events

A scene's Events folder is purely a placeholder for RemoteEvents that communicate between the Client and Server modules. It's not a requirement to place anything in this folder.

Client

This script executes schema logic on the client.

Server

This script executes schema logic on the server.

Scene Schemas

A scene's schema defines what happens at what point in the scene's timeline. You should define a scene's schema in both its Client and Server modules and include lifecycle hooks to manage when configurations occur.

Lifecycle Hooks

Schema lifecycle hooks let you manage when scene operations occur. A scene in production will typically run in the most simple flow:

• OnSetup → OnRun → OnEndScene

OnRun may be interrupted when seeking:

• OnSetup → OnRun… seek → OnRun… seek → OnRun → OnEndScene

All three hooks can also repeat if the scene is replayed:

• OnSetup → OnRun → OnEndScene… replay → OnSetup → OnRun → OnEndScene

Configurations

Schema configurations define the core operations of a scene, for example playing audio at 00:32, queuing an animation to sync with that audio, scheduling a scene event like a fireworks show, and more. Every configuration supports certain callback functions where the first parameter (self) is the configuration instance.

Seeking Scenes

A unique feature of EventSequencer is the ability to "seek" around scenes as you might seek through a video. In Replace Mode, you can also switch between scenes to preview an entire multi-scene event before deploying it to production.

Scene seeking is not accessible to everybody since users simply enjoying the event should not have the ability to control its time flow. Instead, you must grant seeking permission based on the event's PlaceId as well as specific UserIds and/or groups and roles within them.

1. Create a new Script within ServerScriptService.

2. Paste the following code into the new script.

   Script - Set Seeking Permissions
   local ReplicatedStorage = game:GetService("ReplicatedStorage")
   
   local EventSequencer = require(ReplicatedStorage:WaitForChild("EventSequencer"))
   
   EventSequencer.setSeekingPermissions({
   	placeIDs = {},
   	userIDs = {},
   	groups = {
   		{GroupID = , MinimumRankID = },
   	}
   })

3. Fill in the following tables within the setSeekingPermissions call as follows:

   placeIDs	Comma-delimited list of PlaceId values to support seeking within.
   userIDs	Comma-delimited list of UserIds for those who can seek within the supported places.
   groups	Comma-delimited list of tables, each containing a group ID and the minimum rank of that group's members who can seek within the supported places.

Scene Manager Plugin

The Scene Manager plugin is a useful tool for loading and unloading scenes, lighting, and terrain. Unless you're using Inline Mode, it's highly recommended that you use this plugin instead of manually placing/editing scene objects and properties.

To install the plugin:

1. From Studio's View menu, open the Toolbox.

   

2. With the Creator Store tab selected, select Plugins from the dropdown menu.

   

3. In the search field, type Scene Manager and press Enter to locate the plugin.

   

4. Click the plugin's icon to view its details and then click the Install button.

5. Once the plugin is installed, it appears in Studio's Plugins tab.

Loading and Unloading Scenes

As outlined in Creating Scenes, a scene's Environment folder contains everything that users see and hear, including 3D objects. The plugin helps you quickly load a scene's assets into or out of organized folders within the workspace.

Saving and Loading Lighting

The top-level Lighting service stores all of a place's lighting properties and visual effects. Since it's a top-level service, you cannot manually move it to a particular scene's Environment/Server or Environment/Client folder. Instead, you can utilize the plugin to copy its properties and children to the scene's Environment/Lighting folder.

1. Configure the scene's lighting properties, post-processing effects, atmospheric effects, and skyboxes through the top-level Lighting service.

   

2. In the Scene Manager plugin window, click Save Lighting for the desired scene.

3. Select and expand that scene's Environment/Lighting configuration and you'll see the same lighting properties as attributes of the folder, as well as cloned children of the top-level Lighting service.

   

   

   Once lighting properties and children are saved for a scene, you can quickly load them back into the top-level Lighting service by clicking Load Lighting from the plugin window.

Saving and Loading Terrain

Since Terrain is a top-level class within Workspace, you cannot manually move generated or sculpted terrain to a particular scene's Environment/Server or Environment/Client folder. Instead, you can utilize the plugin to copy it to the scene's Environment/Terrain folder.

1. Configure the scene's terrain through the top-level Terrain service.

   

2. In the Scene Manager plugin window, click Save Terrain for the desired scene.

3. Select and expand that scene's Environment/Terrain folder and you'll see a TerrainRegion object which represents the saved terrain.

   

   Once terrain is saved for a scene, you can quickly load it back into the top-level Terrain service by clicking Load Terrain from the plugin window.

API Reference

Schema Lifecycle Hooks

OnSetup

The OnSetup lifecycle hook is intended for initializing assets and variables that will be referenced in OnRun or OnEndScene, setting up connections that are intended to last for the duration of the scene, etc. This hook receives the timePositionObject parameter which lets you read the current time at setup.

Client Schema
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)")

	-- Access scene environments; does not apply to Inline Mode
	clientEnvironment = EventSequencer.getCurrentSceneEnvironment()
	serverEnvironment = EventSequencer.getCurrentServerEnvironmentFromClient()
	-- Wait for assets
	dummy = clientEnvironment:WaitForChild("Dummy")

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

Server Schema
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)")

	-- Access scene environment; does not apply to Inline Mode
	serverEnvironment = EventSequencer.getCurrentSceneEnvironment()
	partColorConnection = changePartColorEvent.OnServerEvent:Connect(function(player, changedPart, newColor)
		serverEnvironment.changedPart.Color = newColor
	end)

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

OnRun

OnRun is the main operational lifecycle hook within a schema. It should contain all timed configurations for the scene, from playing audio or an animation to scheduling an event like a fireworks display.

Client Schema
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

The OnEndScene lifecycle hook is useful for cleaning up anything outstanding in the scene, such as disconnecting connections created in OnSetup or OnRun that remain for the duration of the scene.

Server Schema
Schema.OnEndScene = function()
	print("OnEndScene (Server)")

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

Schema Configurations

audio

Creates a Sound object in the workspace which plays at a certain time. The sound is then deleted after the scene is over or after the Sound object finishes playing.

Client Schema
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

animate

Creates an Animation which plays at a certain time.

Client Schema
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

Creates a configurable Tween which is preserved in seeking and in dynamic join, meaning you can chain tweens at separate points in time and everything should play and sync as expected.

Client Schema
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

interval

Executes a custom callback function over a specified duration on a specified frequency, in seconds. Useful for repeating events like flashing lights, pulsing an audio's intensity, etc. The lowest possible frequency is 0 seconds, but technically the minimum frequency is always clamped to Heartbeat.

Client Schema
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

schedule

Similar to interval except that you can define multiple specific starting times for the same event, such as scheduling a fireworks display twice in a scene.

Client Schema
Schema.OnRun = function()
	print("OnRun (Client)")

	Schema:schedule({
		StartTimes = {5, 27.25},
		OnStart = function(self)
			-- Initialize temporary heartbeat connection
			local tempConnection = RunService.Heartbeat:Connect(function()

			end)
			-- Inform framework of connection
			Schema:inform(tempConnection)
		end
	})
end

inform

Informs the framework of any modules, UI objects, connections, etc. which are created in the OnRun lifecycle hook, ensuring they are properly cleaned up when seeking. Use cases include:

• Informing the framework of a temporary ad-hoc connection such as RunService.Heartbeat so that the connection is cleaned up when seeking to an earlier point in the scene's duration.

  Server Schema
  Schema.OnRun = function()
  	print("OnRun (Server)")
  
  	Schema:schedule({
  		StartTimes = {5},
  		OnStart = function(self)
  			-- Initialize temporary heartbeat connection
  			local tempConnection = RunService.Heartbeat:Connect(function()
  
  			end)
  			-- Inform framework of connection
  			Schema:inform(tempConnection)
  		end
  	})
  end

• Calling a custom "cleanup" function in a ModuleScript that initializes a connection or other reference during the OnRun lifecycle hook.

  Server Schema
  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)
  			-- Call "init" function in custom module
  			customModule.init()
  			-- Call "clean" function in custom module on scene cleanup
  			Schema:inform(customModule, customModule.clean)
  		end,
  	})
  end

  ModuleScript - CustomModule
  local RunService = game:GetService("RunService")
  
  local CustomModule = {}
  
  CustomModule.init = function()
  	-- Initialize heartbeat connection
  	CustomModule.connection = RunService.Heartbeat:Connect(function()
  
  	end)
  end
  
  CustomModule.clean = function()
  	-- Disconnect and clear heartbeat connection
  	if CustomModule.connection then
  		CustomModule.connection:Disconnect()
  		CustomModule.connection = nil
  	end
  end
  
  return CustomModule

Functions

loadScene

Programmatically loads a scene by sceneName and starts it at startTime from its beginning. There will be a 5 second "grace period" for the scene to load from the server before the seek occurs and the scene starts playing. This means that if you call loadScene("[SceneName]", 20) at exactly 4:15:00 PM, the framework will wait 5 seconds in addition to the requested 20, kicking off the scene at 4:15:25 PM.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

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

-- Figure out next scene to load when current scene finishes
EventSequencer.onOrchestrationFinished:Connect(function(endedSceneName)
	if endedSceneName == "PreShow" then
		-- "PreShow" ended; load the first scene in the concert
		EventSequencer.loadScene("Track1")
	elseif endedSceneName == "Track1" then
		-- "Track1" ended; load the second scene in the concert
		EventSequencer.loadScene("Track2")
	else
		-- Loop back to the pre-show scene
		EventSequencer.loadScene("PreShow")
	end
end)

createSchema

Returns an instance of the scene schema to create logic for the scene.

Client Schema
local ReplicatedStorage = game:GetService("ReplicatedStorage")

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

local Schema = EventSequencer.createSchema()

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

seek

Seeks to the time value, in seconds, from the currently loaded scene's beginning.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

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

EventSequencer.seek(95.58)

setSceneWarningTime

Sets the amount of time from the end of all scenes at which a warning is dispatched. You can detect the warning either client-side through onSceneEndingWarningForClient or server-side through onSceneEndingWarningForServer.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

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

-- Load scene
EventSequencer.loadScene("BeautifulScene")

-- Set warning time to 5 seconds before the scene ends
EventSequencer.setSceneWarningTime(5)

-- Detect when scene is about to end
EventSequencer.onSceneEndingWarningForServer:Connect(function()
	warn("Scene is about to end!")
end)

setSeekingPermissions

Grants seeking permission based on the event's PlaceId as well as specific UserIds and/or groups and roles within them. See Seeking and Switching Scenes for more information.

getCurrentSceneEnvironment

Returns the current scene's client-side or server-side Environment folder, depending on whether it's called from the Client schema script or Server schema script respectively.

Client Schema
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)")

	-- Access scene environments; does not apply to Inline Mode
	clientEnvironment = EventSequencer.getCurrentSceneEnvironment()
	serverEnvironment = EventSequencer.getCurrentServerEnvironmentFromClient()

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

Server Schema
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

getCurrentServerEnvironmentFromClient

Returns the current scene's server-side Environment folder. Unlike getCurrentSceneEnvironment, you can call this from the Client schema script.

Client Schema
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)")

	-- Access scene environments; does not apply to Inline Mode
	clientEnvironment = EventSequencer.getCurrentSceneEnvironment()
	serverEnvironment = EventSequencer.getCurrentServerEnvironmentFromClient()

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

isLoadingScene

Called from the server to know if a scene is currently loading.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

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

print(EventSequencer.isLoadingScene())

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

Events

onSceneEndingWarningForClient

Fires on the client before the scene is about to end. The default time is 3 seconds, but you can configure it through setSceneWarningTime. This event can only be connected in a LocalScript.

LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

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

-- Detect when scene is about to end (client-side)
EventSequencer.onSceneEndingWarningForClient:Connect(function()
	warn("Scene is about to end!")
end)

onSceneEndingWarningForServer

Fires on the server before the scene is about to end. The default time is 3 seconds, but you can configure it through setSceneWarningTime. This event can only be connected in a Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

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

-- Detect when scene is about to end (server-side)
EventSequencer.onSceneEndingWarningForServer:Connect(function()
	warn("Scene is about to end!")
end)

onSceneLoadedForClient

Fires on the client when the scene is starting. This event can only be connected in a LocalScript.

LocalScript
local ReplicatedStorage = game:GetService("ReplicatedStorage")

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

-- Detect when scene is starting (client-side)
EventSequencer.onSceneLoadedForClient:Connect(function()
	warn("Scene is starting!")
end)

onOrchestrationFinished

Fires on the server when a scene has reached its time length and has effectively ended. This event receives an endedSceneName string name argument for the scene that just finished and you can chain off this event to conditionally load another scene. Can only be connected in a Script.

Script
local ReplicatedStorage = game:GetService("ReplicatedStorage")

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

-- Figure out next scene to load when current scene finishes
EventSequencer.onOrchestrationFinished:Connect(function(endedSceneName)
	if endedSceneName == "PreShow" then
		-- "PreShow" ended; load the first scene in the concert
		EventSequencer.loadScene("Track1")
	elseif endedSceneName == "Track1" then
		-- "Track1" ended; load the second scene in the concert
		EventSequencer.loadScene("Track2")
	else
		-- Loop back to the pre-show scene
		EventSequencer.loadScene("PreShow")
	end
end)