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 game 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 games.

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 a game:

1. From Studio's Window menu or Home tab toolbar, 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 Packages 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 game the module will 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.

   

Create 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.

   

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.

Seek 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.

   LuauCopy

   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 Window menu or Home tab toolbar, 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.

Load and unload 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.

Save and load 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.

Save and load 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.

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

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.

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

	local MainAudio = Schema:audio({
		StartTime = 1,
		SoundId = "rbxassetid://1838673350",
	 class="tok-k">function(self)
			print("Audio playing")
		end,
	 class="tok-k">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.

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.

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

	local MainAudio = Schema:audio({
		StartTime = 1,
		SoundId = "rbxassetid://1838673350",
	 class="tok-k">function(self)
			print("Audio playing")
		end,
	 class="tok-k">function(self)
			print("Audio ended")
		end
	})
end

animate#

Creates an Animation which plays at a certain time.

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,
		},
	 class="tok-k">function(self)
			print("Animation playing")
		end,
	 class="tok-k">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.

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},
		},
	 class="tok-k">function(self)
			print("Tween playing")
		end,
	 class="tok-k">function(self, alpha)
			print("Tween alpha", alpha)
		end,
	 class="tok-k">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.

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
		},
	 class="tok-k">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.

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

	Schema:schedule({
		StartTimes = {5, 27.25},
	 class="tok-k">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.

  LuauCopy

  Schema.OnRun = function()
      print("OnRun (Server)")
  
      Schema:schedule({
          StartTimes = {5},
          class="tok-k">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.

  LuauCopy

  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},
          class="tok-k">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

  LuauCopy

  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.

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.

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.

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.

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 seek and switch 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.

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

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.

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.

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.

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.

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.

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.

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)