Developer Guide

API Reference v3.0.0

For Developers

This guide covers all exports and events available in IF Subtitle. Perfect for integrating with your custom scripts.

Client Export

Use this export in any client-side script to show a subtitle.

exports['if-subtitle']:ShowSubtitle(speaker, text, color, icon, persistent, avatar, animation)

Arguments

Argument	Type	Description
speaker	string	Name of the character speaking.
text	string	The dialogue text content.
color	string	(Optional) Hex color for speaker name (e.g., '#ff0000').
icon	string	(Optional) Emoji/icon to display next to name.
persistent	boolean	(Optional) If true, subtitle won't auto-hide.
avatar	string	(Optional) URL to an image for the avatar.
animation	string	(Optional) 'fade', 'slide', 'bounce', 'glow'.

Example

exports['if-subtitle']:ShowSubtitle(
    'John',
    'Hello! This is a test subtitle message.',
    '#ff0000',
    '👤',
    false,
    'https://example.com/avatar.png',
    'fade'
)

Clear Subtitles

Remove all subtitles from the screen.

exports['if-subtitle']:ClearSubtitles()

---

Server Exports

Show to All Players

exports['if-subtitle']:ShowSubtitleToAll(speaker, text, color, icon, persistent, avatar, animation)

Show to Specific Player

exports['if-subtitle']:ShowSubtitleToPlayer(targetId, speaker, text, color, icon, persistent, avatar, animation)

Show to Nearby Players

exports['if-subtitle']:ShowSubtitleNearby(coords, radius, speaker, text, color, icon, persistent, avatar, animation)

Argument	Type	Description
coords	vector3	The center coordinates.
radius	number	Distance in units to broadcast.

Clear Subtitles

exports['if-subtitle']:ClearAllSubtitles()        -- Clear for all players
exports['if-subtitle']:ClearPlayerSubtitles(targetId)  -- Clear for specific player

---

Server Events

You can also use events instead of exports:

-- Show to all players
TriggerEvent('subtitle:showToAll', speaker, text, color, icon, persistent, avatar, animation)

-- Show to specific player
TriggerEvent('subtitle:showToPlayer', targetId, speaker, text, color, icon, persistent, avatar, animation)

-- Show to nearby players
TriggerEvent('subtitle:showNearby', coords, radius, speaker, text, color, icon, persistent, avatar, animation)

-- Clear subtitles
TriggerEvent('subtitle:clearAll')
TriggerEvent('subtitle:clearPlayer', targetId)

Best Practices

• ✅ Keep subtitle text concise (under 60 characters per line)
• ✅ Use appropriate display durations (3000-7000ms recommended)
• ✅ Use persistent = true only when necessary (e.g., mission objectives)
• ✅ Call ClearSubtitles() when done with persistent subtitles
• ❌ Avoid showing too many subtitles at once

📝 Complete Example

Here's a real-world example integrating IF Subtitle with a cutscene:

-- Client-side cutscene dialogue
RegisterNetEvent('cutscene:dialogue', function(dialogues)
    for _, dialogue in ipairs(dialogues) do
        exports['if-subtitle']:ShowSubtitle(
            dialogue.speaker,
            dialogue.text,
            dialogue.color,
            '',
            false,
            dialogue.avatar,
            'fade'
        )
        Wait(dialogue.duration or 3000)
    end
end)