Component

SubtitleSystem

A cinematic subtitle manager featuring a character registry, typewriter text effects, color-coded names, and synced voice blips.

Overview

Subtitles can be displayed manually or triggered automatically via the Cutscene module. By utilizing the Character Registry, you can define an NPC's display name, text color, and talking sound once, and the system will automatically format all of their lines.

GUI Hierarchy Requirements

This module expects a specific GUI structure to exist in the player's PlayerGui. Ensure you have the following hierarchy created:

PlayerGui └─ SubtitleGui (ScreenGui) └─ SubtitleContainer (Frame) └─ SubtitleLabel (TextLabel, with RichText enabled)

Global Configuration

luau

local Subtitles = require(game.ReplicatedStorage.Subtitles.SubtitleSystem)

-- You can mutate the global config table at runtime to fit your game's pacing

Subtitles.Config.TypeSpeed = 0.05 -- Seconds between each character in typewriter mode

Subtitles.Config.FadeTime = 0.3 -- UI fade in/out duration

Subtitles.Config.BackgroundOpacity = 0.6 -- How dark the container frame gets

Subtitles.Config.UseTypewriter = true -- Default typewriter state for all subtitles

Registering Characters

luau

Subtitles:RegisterCharacter("commander", {

Name = "Cmdr. Shepard",

Color = Color3.fromRGB(56, 189, 248),

SoundId = "rbxassetid://123456789" -- Short blip sound played on reveal

})

Subtitles:RegisterCharacter("ai", {

Name = "SYSTEM",

Color = Color3.fromRGB(239, 68, 68),

SoundId = "rbxassetid://987654321"

})

Showing Subtitles & Using Callbacks

luau

-- Simple usage

Subtitles:Show({

character = "commander",

text = "We need to move, now!",

duration = 3

})

-- Advanced usage with a callback when the subtitle finishes reading

Subtitles:Show({

character = "ai",

text = "WARNING: Core temperature critical.",

duration = 4,

typewriter = true,

onComplete = function()

print("Subtitle finished! Trigger explosion here.")

end

})

Show() Options Dictionary

Prop	Type	Default	Description
text	string	""	The line of dialogue to display. HTML tags are stripped during character counting.
character	string	nil	The ID of a pre-registered character to fetch Name, Color, and SoundId from.
duration	number	2	Time in seconds to keep the subtitle on screen after typing finishes.
typewriter	boolean	Config default	Overrides the global UseTypewriter config for this specific line.
speaker / speakerColor	string / Color3	nil	Allows you to bypass the registry and provide a one-off speaker name and color.
onComplete	function	nil	Task spawned when the subtitle duration ends and the fade-out begins.

Show() Options Dictionary

Prop	Type	Default	Description
text	string	""	The line of dialogue to display. HTML tags are stripped during character counting.
character	string	nil	The ID of a pre-registered character to fetch Name, Color, and SoundId from.
duration	number	2	Time in seconds to keep the subtitle on screen after typing finishes.
typewriter	boolean	Config default	Overrides the global UseTypewriter config for this specific line.
speaker / speakerColor	string / Color3	nil	Allows you to bypass the registry and provide a one-off speaker name and color.
onComplete	function	nil	Task spawned when the subtitle duration ends and the fade-out begins.