Skip to main content

HSC Chat — Complete Documentation

Product: HSC Chat
Documented version: 1.0.1 (includes the 919 Admin key-release notification fix)
Get it here: Standalone; can be used alongside QBCore, Qbox, ESX, and other frameworks

1. Overview​

HSC Chat replaces FiveM's default text-chat interface with a configurable NUI chat system. It includes message templates, command suggestions, typed command execution, history navigation, visual styling, and compatibility with standard FiveM chat events.

Included features​

  • Standalone FiveM chat interface using HTML, CSS, JavaScript, and Vue.
  • T keybind by default, rebindable through FiveM settings.
  • Normal global text chat with the player's FiveM display name.
  • /clearchat to clear your own chat window.
  • /chatopen to open the chat manually.
  • Command suggestions, help descriptions, and parameter hints when supplied by other resources.
  • Built-in display templates for OOC, local OOC, reports, advertisements, 911/311, service chat, identification cards, and more.
  • Chat fading after a configurable delay.
  • Theme and UI styling support.
  • 919 Admin / other keybind compatibility fix in v1.0.1 for certain unregistered -command key-release events.

Not included automatically​

HSC Chat does not automatically register /ooc, /911, /311, /advert, /report, /showid, or police/EMS chat commands. Their display templates exist, but the behavior must come from another script or a custom integration.

HSC Chat also does not include a built-in chat cooldown, mute database, Discord logger, proximity-chat mode, job-only channel system, or character-name bridge. Implement these separately if your server needs them.

2. Requirements and Installation​

Requirements​

  • A working FiveM server.
  • Access to your server's resources folder and server.cfg.
  • A current, compatible FiveM server artifact.
  • No mandatory QBCore, ESX, Qbox, ox_lib, or database dependency.

Installation steps​

  1. Download the v1.0.1 release archive.

  2. Extract it so the resource is located at a path such as:

    resources/[standalone]/hsc_chat/

  3. Confirm that fxmanifest.lua is directly inside hsc_chat, not inside a duplicate nested hsc_chat/hsc_chat folder.

  4. In server.cfg, start HSC Chat:

    ensure hsc_chat

  5. Ensure that only one chat UI is actually running. The included manifest declares provide 'chat' so HSC Chat can act as a replacement for the standard chat resource. Check your existing resource groups and custom chat installations to avoid a second chat UI loading.

  6. Restart your server. You can use ensure hsc_chat in the server console for later testing, but a full server restart is recommended for the initial installation.

  7. Join the server and press T.

  8. Send a normal message, run /clearchat, and confirm that command suggestions appear when you start typing / followed by a known command.

Suggested resource order​

# Framework and general dependencies (examples, if used)
ensure qb-core

# Use HSC Chat as the server's chat interface
ensure hsc_chat

# Resources that add their own chat commands or suggestions
ensure my_chat_commands

The framework line is just an example. HSC Chat does not require qb-core.

3. File Structure​

hsc_chat/
├── fxmanifest.lua              # Resource metadata and scripts
├── cl_chat.lua                 # Chat UI, keybind, events and NUI callbacks
├── sv_chat.lua                 # Chat messages, suggestions and /clearchat
└── html/
    ├── index.html             # Chat interface markup
    ├── css/
    │   └── style.css          # Layout, colors and appearance
    ├── js/
    │   ├── config.default.js  # Shipped defaults; DO NOT EDIT
    │   ├── config.js          # Your main editable configuration
    │   ├── App.js             # UI state, input, history, command actions
    │   ├── Message.js         # Message rendering, escaping, color codes
    │   └── Suggestions.js     # Command suggestion matching and hints
    └── vendor/
        ├── vue.2.3.3.min.js
        ├── flexboxgrid.6.3.1.min.css
        └── animate.3.5.2.min.css

Most server owners only need to edit:

  • html/js/config.js — template definitions and behavior settings.
  • html/css/style.css — colors, layout, font sizes and UI styling.

Advanced developers may also edit:

  • cl_chat.lua — input controls, initial welcome message, client events.
  • sv_chat.lua — global message handling, server-side command behavior.
  • html/index.html — layout markup, placeholder text, frontend imports.

Avoid editing minified vendor libraries or config.default.js.

4. Player Controls and Commands​

InputResult
TOpens chat by default.
EnterSends the message or executes the entered command.
EscCloses chat without sending.
↑ / ↓Moves through previously sent entries while typing.
TabCompletes the selected command suggestion.
Ctrl + ↑ / ↓Moves through suggestion selections.
Page Up / Page DownScrolls the message area in steps.
/clearchatClears only the executing player's visible messages and local input history.
/chatopenOpens HSC Chat.

Rebinding the chat key​

  1. Open FiveM Settings.
  2. Go to Key Bindings → FiveM.
  3. Find Open HSC Chat.
  4. Change its default T assignment.

Developers can change the default mapping in cl_chat.lua:

RegisterKeyMapping(
    'chatopen',
    'Open HSC Chat',
    'keyboard',
    't'
)

Note: Changes to a resource's default key mapping may not override a player's existing saved binding. Players can rebind it in their FiveM settings.

Commands with and without /​

A command entered with a leading slash is executed as a FiveM command, for example /clearchat. An entry without the slash can also execute as a command if HSC Chat already knows it from its suggestion/command registry. Otherwise, it is sent as a normal chat message. Use the slash form for consistency.

5. Main Configuration (html/js/config.js)​

The editable configuration is a JavaScript object named window.CONFIG. It is loaded after config.default.js and takes precedence.

The main settings are:

window.CONFIG = {
  defaultTemplateId: "default",
  defaultAltTemplateId: "defaultAlt",

  templates: {
    // Existing message templates go here.
    // Keep the shipped templates unless you intentionally replace them.
  },

  fadeTimeout: 4000,
  suggestionLimit: 5,

  style: {
    background: "transparent",
    width: "28vw",
    height: "22vh",
  },
};

Do not replace your entire live config.js with this abbreviated illustration: it omits the default templates. Edit the existing file instead.

SettingDefaultMeaning
defaultTemplateId"default"Template for messages that use the default two-argument form.
defaultAltTemplateId"defaultAlt"Template used for a one-argument message when the default template is selected.
templatesSeveral presetsMap of named HTML message templates.
fadeTimeout4000Milliseconds after which the chat message window fades when chat input is closed.
suggestionLimit5Maximum matching command suggestions shown at once.
style.background"transparent"Background applied to the top-level chat window element.
style.width"28vw"CSS width assigned to that chat window element.
style.height"22vh"CSS height assigned to that chat window element.

Keep chat visible longer​

fadeTimeout: 10000, // 10 seconds

Setting the timeout higher keeps new messages visible for longer. It does not independently implement a permanent-always-on chat mode.

Show more command suggestions​

suggestionLimit: 8,

Change the chat window's size​

style: {
  background: "transparent",
  width: "32vw",
  height: "26vh",
},

Important: The message cards and input box also have their own CSS dimensions and positions in style.css. If a size or position adjustment is not reflected across the whole UI, edit those CSS rules too.

6. Changing Colors, Branding, and Layout​

Open html/css/style.css.

Global brand color variables​

Near the top of the stylesheet:

:root {
  --hsc-accent: #ff3b30;
  --hsc-accent-secondary: #ff8a3d;
  --hsc-background: rgba(9, 11, 16, 0.94);
  --hsc-background-soft: rgba(20, 21, 27, 0.9);
  --hsc-border: rgba(255, 255, 255, 0.13);
  --hsc-text: #f7f8fb;
  --hsc-muted: #a9aebb;
  --hsc-shadow: rgba(0, 0, 0, 0.65);
}

To use a blue primary accent, for example:

:root {
  --hsc-accent: #3478f6;
  --hsc-accent-secondary: #6ea6ff;
}

Apply the modifications to the existing :root block rather than adding contradictory definitions in several places.

Reposition the chat window​

Find .chat-window:

.chat-window {
  position: absolute;
  top: 2.5%;
  left: 40px;
  width: 26%;
  height: 530px;
  max-width: 550px;
}
  • top moves the message area down from the top.
  • left moves it horizontally.
  • width, height, and max-width control its layout.

Then adjust .chat-input to keep the input aligned:

.chat-input {
  position: absolute;
  top: 33.8%;
  left: 50px;
  width: 26%;
  max-width: 610px;
}

Resize individual message cards​

Look for .chat-message and modify its width and padding:

.chat-message {
  width: 22vw;
  padding: 1vh 1.2vh;
}

Change text size​

The styles use a mix of vh, rem, and other CSS units. Edit the relevant font-size declarations under textarea, .chat-message, .label-msg-type, and .label-msg-txt instead of assuming one universal font-size setting.

Change fonts​

The supplied stylesheet imports Saira and Salsa from Google Fonts at the top of style.css. Replace that import and associated font-family declarations if you want a different typeface. External fonts may require internet access for clients; self-hosting an appropriately licensed font is an alternative.

Customize message category colors​

The shipped stylesheet includes these message classes:

CSS classDefault accentIntended use
.normalBlueStandard chat.
.successGreenSuccess feedback.
.errorRedErrors and failures.
.warningYellowWarnings.
.systemPurpleSystem messages.
.advertCyanAdvertisements.
.emergencyBright redEmergency notifications.
.nonemergencyMuted redNon-emergency calls.
.reportGreenReports.
.oocGrayOOC-themed styling; see customization note below.

For example:

.emergency {
  --message-accent: #ff2020;
}

.success {
  --message-accent: #34c759;
}

Customization note: The shipped ooc and oocl templates currently use normal and system CSS classes respectively, rather than .ooc. If you want the dedicated gray .ooc styling, change the class on the relevant template in config.js to chat-message ooc.

7. Understanding Message Templates​

A template is an HTML layout for one kind of message. Templates are defined under window.CONFIG.templates in html/js/config.js.

A placeholder such as {0} represents the first supplied argument, {1} the second, {2} the third, and so on. Arguments are escaped before they are inserted into the template.

Example template:

success:
  '<div class="chat-message success">' +
    '<div class="header">' +
      '<span class="label-msg-type">{0}</span>' +
    '</div>' +
    '<span class="label-msg-txt">{1}</span>' +
  '</div>',

Example Lua use:

TriggerClientEvent('chat:addMessage', source, {
    templateId = 'success',
    args = { 'VEHICLE', 'Your vehicle has been stored.' }
})

Here VEHICLE becomes {0} and the message text becomes {1}.

Existing templates and expected arguments​

Template IDArgumentsPurpose
default{0} label, {1} messageDefault two-argument messages.
defaultAlt{0} messageDefault one-argument messages.
print{0} textServer-print styled output.
example:important{0} textImportant notice example.
hsc{0} textHSC-branded notice.
cnormal{0} player name, {1} messageDefault global chat messages.
normal{0} messageGeneral message.
ooc{0} name, {1} ID, {2} messageOOC presentation.
oocl{0} name, {1} ID, {2} messageLocal OOC presentation.
report{0} name, {1} ID, {2} reportReport display.
creport{0} label, {1} messageCustom report.
success{0} label, {1} messageSuccessful action.
error{0} label, {1} messageError feedback.
warning{0} label, {1} messageWarning feedback.
system{0} messageHSC system notice.
advert{0} messageAdvertisement.
emergency{0} messageEmergency notice.
911{0} call number, {1} call detail/location, {2} message911 call presentation.
311{0} call number, {1} call detail/location, {2} message311 call presentation.
911r{0} call number, {1} detail, {2} reply911 reply presentation.
311r{0} call number, {1} detail, {2} reply311 reply presentation.
ems-chat{0} sender, {1} messageEMS message presentation.
police-chat{0} sender, {1} messagePolice message presentation.
showid{0} person label, {1} BSN, {2} first name, {3} last name, {4} birthday, {5} sex, {6} heightIdentification card.
showlawyer{0} label, {1} BSN, {2} first name, {3} last name, {4} birthday, {5} sex, {6} nationalityLawyer ID.
showdl{0} label, {1} first name, {2} last name, {3} birthday, {4} driving licensesDriver license.
showlawyerl{0} label, {1} No-ID, {2} first name, {3} last name, {4} BSN, {5} jobLawyer license.

The argument descriptions above reflect the fields displayed in the shipped templates. The template does not fetch those values itself. A resource must supply them.

Create your own template​

Inside templates: { ... } in config.js, add a new entry:

mechanic:
  '<div class="chat-message advert">' +
    '<div class="header">' +
      '<span class="label-msg-type">MECHANIC</span>' +
      '<span>{0}</span>' +
    '</div>' +
    '<span class="label-msg-txt">{1}</span>' +
  '</div>',

Call it from a server resource:

TriggerClientEvent('chat:addMessage', -1, {
    templateId = 'mechanic',
    args = {
        'Benny\'s Motorworks',
        'We are open for repairs.'
    }
})

The -1 target broadcasts the message to all connected players. Substitute a player server ID to send it privately.

Add a completely new colored message category​

Add a custom class:

.mechanic {
  --message-accent: #ff9f0a;
}

Then change the template wrapper to:

<div class="chat-message mechanic"> ... </div>

Use actual complete markup in config.js; the line above only illustrates the class change.

Inline FiveM formatting codes​

The message renderer recognizes color codes such as ^1 (red), ^2 (green), ^3 (yellow), ^4 (blue), ^5 (light blue), ^6 (purple), ^8, and ^9, plus formatting codes like ^* (bold), ^_ (underline), ^~ (strike-through), and ^r (reset). Styling is implemented by Message.js and style.css.

Example:

TriggerClientEvent('chat:addMessage', -1, {
    templateId = 'system',
    args = { '^2The event is now live!^r' }
})

The renderer also escapes supplied argument text. Do not use unsanitized player-provided HTML as a dynamic template string.

8. Sending Messages from Other Resources​

HSC Chat listens for the standard chat:addMessage event, making it straightforward to integrate with other FiveM scripts.

Send a private server-side message​

Server Lua:

TriggerClientEvent('chat:addMessage', playerId, {
    templateId = 'warning',
    args = { 'NOTICE', 'You must be on duty to do that.' }
})

Replace playerId with the desired player's server ID.

Broadcast a message to everybody​

Server Lua:

TriggerClientEvent('chat:addMessage', -1, {
    templateId = 'system',
    args = { 'A scheduled restart will begin in 10 minutes.' }
})

Show a message only to the local player​

Client Lua:

TriggerEvent('chat:addMessage', {
    templateId = 'success',
    args = { 'GARAGE', 'Your vehicle is ready.' }
})

Send a message using an inline template​

If you don't want to define a global template ID:

TriggerClientEvent('chat:addMessage', source, {
    template = '<div class="chat-message warning">{0}</div>',
    args = { 'Please contact a staff member.' }
})

For repeated messages, prefer a template ID defined in config.js.

Difference between TriggerEvent and TriggerClientEvent​

  • From a client script, use TriggerEvent('chat:addMessage', messageTable) for that player's UI.
  • From a server script, use TriggerClientEvent('chat:addMessage', target, messageTable) to send it to one or more clients.
  • Do not expect a server-side TriggerEvent('chat:addMessage', ...) to automatically display a message for clients.

9. Creating Chat Commands — Custom Integration Examples​

HSC Chat is the display and input system. To provide a command such as /ooc, register that command in your own script.

Example A: /ooc global out-of-character chat​

Create a separate server-side resource or add this to one of your existing server scripts:

RegisterCommand('ooc', function(source, args)
    if source <= 0 then return end

    local message = table.concat(args, ' '):sub(1, 256)
    if message == '' then
        TriggerClientEvent('chat:addMessage', source, {
            templateId = 'error',
            args = { 'OOC', 'Usage: /ooc <message>' }
        })
        return
    end

    TriggerClientEvent('chat:addMessage', -1, {
        templateId = 'ooc',
        args = {
            GetPlayerName(source),
            source,
            message
        }
    })
end, false)

This example creates a global OOC command. It is not a built-in command in HSC Chat. This example does not implement moderation or a cooldown.

Example B: /ad advertisement​

Server Lua:

RegisterCommand('ad', function(source, args)
    if source <= 0 then return end

    local message = table.concat(args, ' '):sub(1, 256)
    if message == '' then return end

    TriggerClientEvent('chat:addMessage', -1, {
        templateId = 'advert',
        args = { ('%s: %s'):format(GetPlayerName(source), message) }
    })
end, false)

This basic example is not a protected advertising system. Add spam prevention, cooldowns and appropriate moderation before offering unrestricted public ads.

Example C: Admin-only announcement with ACE​

Server Lua:

RegisterCommand('hscannounce', function(source, args)
    if source <= 0 then return end

    local message = table.concat(args, ' '):sub(1, 256)
    if message == '' then return end

    TriggerClientEvent('chat:addMessage', -1, {
        templateId = 'system',
        args = { 'STAFF ANNOUNCEMENT: ' .. message }
    })
end, true)

server.cfg:

add_ace group.admin command.hscannounce allow

The final true in RegisterCommand makes the FiveM command ACE-restricted. Your staff members must already be assigned to group.admin (or to an equivalent group you configure). Do not rely on hiding a suggestion as a security control.

Add a command to your resource correctly​

For a separate companion resource called my_chat_commands, the minimum structure is:

my_chat_commands/
├── fxmanifest.lua
└── server.lua

fxmanifest.lua:

fx_version 'cerulean'
game 'gta5'

server_script 'server.lua'

Place one or more RegisterCommand(...) examples into server.lua, then add ensure my_chat_commands after ensure hsc_chat in server.cfg.

10. Command Suggestions and Parameter Help​

Command suggestions can be automatically discovered from FiveM's registered commands. Custom help text and parameter descriptions can also be sent using chat:addSuggestion.

Add a suggestion​

Client Lua:

TriggerEvent('chat:addSuggestion', '/ooc',
    'Send an out-of-character message to everyone.',
    {
        { name = 'message', help = 'The message you want to send' }
    }
)

Other examples:

TriggerEvent('chat:addSuggestion', '/ad',
    'Post an advertisement.',
    {
        { name = 'message', help = 'Advertisement text' }
    }
)

TriggerEvent('chat:addSuggestion', '/911',
    'Contact emergency services (requires an external /911 command).',
    {
        { name = 'details', help = 'Describe your emergency' }
    }
)

A suggestion does not create the command. You must register /ooc, /ad, or /911 separately.

Remove a suggestion​

Client Lua:

TriggerEvent('chat:removeSuggestion', '/ooc')

Add suggestions from a server resource​

Server Lua:

TriggerClientEvent('chat:addSuggestion', source,
    '/ooc',
    'Out-of-character chat',
    {
        { name = 'message', help = 'Your OOC message' }
    }
)

Use a valid target player server ID or -1 when appropriate.

Why aren't my suggestions appearing?​

  • Confirm the underlying command is registered or the custom suggestion is being sent.
  • Ensure the suggestion executes after HSC Chat is ready. If your resource starts very early, resend it when HSC Chat starts or when your resource initializes for a client.
  • Check the script logs for errors.
  • Verify spelling and that the command matches what you're typing.
  • Check suggestionLimit in config.js.

Both slash-prefixed and non-slash suggestions may appear for known commands; that is deliberate in the supplied client implementation.

11. Clearing Chat​

Clear your own messages​

Enter:

/clearchat

The included command sends chat:clear only to the player who ran the command.

Clear chat for all players — custom integration​

Server Lua example:

RegisterCommand('clearallchat', function(source)
    if source <= 0 then return end

    TriggerClientEvent('chat:clear', -1)
end, true)

Add to server.cfg:

add_ace group.admin command.clearallchat allow

This is an optional command you add, not a built-in feature. It clears the visible local chat histories of all connected players. It does not delete external Discord, server, or database logs.

12. Changing the Welcome Message​

Open cl_chat.lua and locate the RegisterNUICallback('loaded', ...) function.

The shipped script includes:

SendNUIMessage({
    type = 'ON_MESSAGE',
    message = {
        templateId = 'hsc',
        args = {
            'Welcome to the server!'
        }
    }
})

Change the text, for example:

args = {
    'Welcome to Hotspot RP. Enjoy your stay!'
}

You can also choose another template ID (with a matching argument count). There is no separate welcome-text setting in the shipped config.js. This change requires editing cl_chat.lua and restarting the resource.

13. Normal Chat, Character Names, and RP Frameworks​

Default chat behavior​

When a player enters a normal message, HSC Chat sends it to the server. The server:

  1. Trims leading and trailing whitespace.
  2. Limits the message to 256 bytes using Lua's string.sub.
  3. Gets the player's real FiveM display name with GetPlayerName(source) rather than trusting a supplied author name.
  4. Fires the compatibility chatMessage server event.
  5. If the event was not canceled, broadcasts the message to everybody using the cnormal template.

Use an in-character name instead​

Not available as a configuration toggle in v1.0.1. By default the name shown is the player's FiveM name. To use QBCore, Qbox, or ESX character names, create or edit a server-side identity integration that obtains a validated character name and uses it in the broadcast.

For a QBCore-specific integration, an example of retrieving the character's name inside a server script is:

local QBCore = exports['qb-core']:GetCoreObject()

local player = QBCore.Functions.GetPlayer(source)
if player then
    local info = player.PlayerData.charinfo or {}
    local characterName = (
        (info.firstname or '') .. ' ' .. (info.lastname or '')
    ):gsub('^%s+', ''):gsub('%s+$', '')

    -- Use characterName in your server-authorized chat message.
end

This is an illustrative snippet, not a drop-in replacement for the existing global-chat handler. If you modify the original handler, maintain its source validation, message length limit, and chatMessage cancellation behavior. Check your framework version's APIs before integrating.

Make chat local/proximity-based​

The supplied normal chat is global. A local-OOC template does not automatically implement proximity filtering. A separate resource must check server-authoritative player positions, decide the recipients, and send chat:addMessage only to players within the intended range. On large servers, use efficient proximity logic rather than repeatedly broadcasting to everyone.

14. Integrating 911, 311, Reports, EMS, and Police Chat​

The resource includes visual templates for all these categories. To activate their gameplay behavior, connect them to the command, dispatch, job, or identification script you already use.

Example: Show a 911 call from an existing dispatch system​

Server Lua example:

local callNumber = 52
local location = 'Sandy Shores'
local description = 'Vehicle collision with injuries'

TriggerClientEvent('chat:addMessage', -1, {
    templateId = '911',
    args = {
        callNumber,
        location,
        description
    }
})

This only formats/displays a message. It does not create a dispatch ticket, track a call, or automatically notify a police or EMS job group. Integrate with your dispatch resource for those actions.

Example: Police-only or EMS-only messages​

Do not broadcast department-only messages to -1. Your server integration must first verify the sender's actual job/permissions and select authorized recipients.

-- Example after your server-side job/permission checks:
TriggerClientEvent('chat:addMessage', authorizedPlayerId, {
    templateId = 'police-chat',
    args = { 'Dispatch', 'Units respond to the latest call.' }
})

Replace authorizedPlayerId with each verified recipient ID. The chat UI does not provide those job checks for you.

Example: Display an ID card​

TriggerClientEvent('chat:addMessage', viewerId, {
    templateId = 'showid',
    args = {
        'Citizen ID',
        'A-1024',
        'Alex',
        'Morgan',
        '1999-05-12',
        'M',
        '180 cm'
    }
})

This is sample data for the display format. Use actual framework character data and your server's identity conventions in a real integration.

15. Filtering or Canceling Normal Chat​

HSC Chat triggers the standard server-side chatMessage event before broadcasting normal messages. Other server resources can subscribe to that event and use CancelEvent() to stop the default broadcast.

Example: block a specific test phrase (server-side custom integration):

AddEventHandler('chatMessage', function(playerId, playerName, message)
    if message:lower() == 'testblockedphrase' then
        CancelEvent()

        TriggerClientEvent('chat:addMessage', playerId, {
            templateId = 'warning',
            args = { 'CHAT', 'That message was blocked.' }
        })
    end
end)

This example is intentionally simple; it is not a complete antispam, profanity filter, or moderation system. For production moderation, include staff exemptions where appropriate, per-player limits, robust logging policies, and server-side permission checks.

16. Compatible Chat Events — Developer Reference​

These are the principal events supported by the supplied resource.

EventTypical callerBehavior
chat:addMessageClient event / server → clientDisplay a formatted message.
chat:addTemplateClient event / server → clientRegister an additional template dynamically.
chat:addSuggestionClient event / server → clientAdd one command suggestion with optional help and parameters.
chat:addSuggestionsClient event / server → clientAdd a list of suggestions.
chat:removeSuggestionClient event / server → clientRemove a suggestion.
chat:clearClient event / server → clientClear visible chat messages and local input history.
chatMessageServer compatibility eventFired for normal player messages; handlers may cancel it.
chat:initInternal client → serverRequests registered-command suggestions.
_chat:messageEnteredInternal client → serverSubmits a normal message; do not expose as a general-purpose external API.

Dynamic template registration​

Client Lua:

TriggerEvent('chat:addTemplate', 'custom-notice',
    '<div class="chat-message system">{0}</div>'
)

TriggerEvent('chat:addMessage', {
    templateId = 'custom-notice',
    args = { 'A custom notice has appeared.' }
})

If a template ID already exists in config.js, the UI will warn rather than replace it. For permanent templates, editing config.js is generally simpler.

Advanced: External chat themes​

The client checks started resources for FiveM chat_theme and chat_theme_extra resource metadata and forwards recognized themes to the NUI. Themes can supply additional style CSS, a stylesheet, and template overrides. This is intended for developers familiar with FiveM resource metadata. For routine branding changes, edit style.css and config.js instead.

17. Browser Preview and Testing​

You can inspect much of the UI without joining FiveM by opening html/index.html in a browser. The file includes a window.emulate testing helper.

With your browser's developer console open, run:

emulate('ON_SCREEN_STATE_CHANGE', { shouldHide: false });
emulate('ON_OPEN');
emulate('ON_MESSAGE', {
  message: {
    templateId: 'success',
    args: ['HSC', 'The UI preview is working.']
  }
});

Test an error:

emulate('ON_MESSAGE', {
  message: {
    templateId: 'error',
    args: ['ERROR', 'Example error message']
  }
});

Clear the preview:

emulate('ON_CLEAR');

Limitations: NUI fetch callbacks require FiveM, so browser previews can log expected callback errors. Use in-game testing to verify actual command execution, networking, focus, and keybind behavior.

18. Troubleshooting​

T does not open chat​

  • Confirm hsc_chat is started (ensure hsc_chat in server.cfg).
  • Check that the folder contains fxmanifest.lua at its root.
  • Ensure another chat resource is not conflicting.
  • Check the player's FiveM key binding for Open HSC Chat.
  • Run /chatopen to distinguish a keybind issue from a general UI issue.
  • Inspect the client F8 console and server console for errors.

Two chat interfaces appear​

Two chat UIs may be running. Keep HSC Chat as the active replacement and review any standard or third-party chat resources. Its manifest provides chat, but duplicate startup configurations can still create confusion.

Normal messages work but /ooc or /911 does not​

These commands are not built into HSC Chat. The templates exist, but the actual commands must be registered in a separate resource. Check that script and its startup order.

A command appears in suggestions but does nothing​

A suggestion alone does not create a command. Confirm the corresponding RegisterCommand code exists, the correct resource is running, and the player has any required ACE/framework permissions.

Unknown command appears when using 919 Admin​

In v1.0.1, unrecognized key-release commands such as -toggleNoClip or -toggleAdminMenu no longer generate HSC Chat's cosmetic unknown-command notification. If the error still appears:

  1. Confirm fxmanifest.lua specifies version '1.0.1'.
  2. Confirm the updated sv_chat.lua was installed.
  3. Restart the resource/server and reconnect.
  4. Check whether the notification is coming from a different chat script.

This fix does not repair broken 919 Admin functionality or register missing admin commands. If the admin menu or noclip itself does not work, investigate the admin resource separately.

Messages disappear too quickly​

Increase fadeTimeout in config.js (milliseconds). Example: fadeTimeout: 8000.

UI position or sizing looks wrong​

Check both config.js's style object and .chat-window, .chat-input, .chat-message, and textarea in style.css.

Colors do not change​

Confirm you edited html/css/style.css in the active resource directory. Some message types have fixed category-specific --message-accent settings, which override the default accent. Restart the resource and reconnect if cached assets do not refresh.

I changed config.default.js but nothing happened​

The editable config.js loads after the defaults, overwriting them. Edit config.js, not config.default.js.

Browser console reports vendor/latofonts.css missing​

The supplied index.html refers to vendor/latofonts.css, but that file is not included in the inspected v1.0.1 archive. The main CSS imports Saira/Salsa separately. If you see a missing-file warning, you can remove the unused <link rel="stylesheet" href="vendor/latofonts.css"> from index.html, or add an appropriately licensed local font stylesheet if you intend to use it.

A custom template shows {2} instead of actual text​

The template requested an argument you did not supply. For example, ooc expects three arguments: name, ID, and text. Check the argument table and placeholder indexes.

Player messages show FiveM names instead of character names​

This is the shipped behavior. The server's normal chat handler uses GetPlayerName(source). Character-name display requires a separate or modified server-authorized framework integration.

19. Updating HSC Chat Safely​

  1. Stop your server or stop hsc_chat during a maintenance window.
  2. Back up your existing resource, especially:
    • html/js/config.js
    • html/css/style.css
    • Any changes you made to cl_chat.lua, sv_chat.lua, or html/index.html.
  3. Extract the new release to a temporary folder.
  4. Compare the new version against your customized files.
  5. Merge new settings/templates into your existing config.js rather than overwriting your customizations blindly.
  6. Update script files and UI files as appropriate for that version's change log.
  7. Restart the resource/server.
  8. Test chat opening, normal messages, commands, custom templates, third-party integrations, and admin keybinds.

Changes specifically relevant to v1.0.1​

The supplied v1.0.1 patch modifies sv_chat.lua's fallback handling to suppress some unknown-command notifications generated by key releases. The package's fxmanifest.lua identifies the resource as v1.0.1. The rest of the chat behavior is intended to remain unchanged.

20. Production Checklist​

Before deploying HSC Chat to a public server:

  • Resource starts successfully and replaces the intended chat UI.
  • Normal chat is visible to the intended audience.
  • The default keybind works and can be reassigned.
  • /clearchat clears only the current user's chat.
  • Custom commands have matching registered handlers, not just templates or suggestions.
  • ACE/job checks are done server-side for restricted commands and channels.
  • Public advertisement and global OOC systems have moderation and spam safeguards if enabled.
  • Framework names/identity fields are validated on the server if customized.
  • config.js and CSS customizations are backed up.
  • Test the UI at multiple resolutions and aspect ratios.
  • Confirm the 919 Admin keybind notification fix does not mask separate admin-resource issues.
  • Confirm chat and related scripts are not emitting sensitive information to all players accidentally.

21. Frequently Asked Questions​

Does HSC Chat require QBCore?
No. It is standalone. Framework integrations can be added separately.

Does it work with Qbox or ESX?
The chat UI itself does not depend on a framework. Framework-specific roleplay commands need integrations appropriate to that framework.

Can I change the chat's colors?
Yes. Start with the CSS variables in html/css/style.css.

Can I add my own message type?
Yes. Add a template to html/js/config.js, optionally add a CSS class, and send messages using templateId.

Can I send a message to one person?
Yes. Use that player's server ID as the target of TriggerClientEvent('chat:addMessage', ...).

Can I broadcast to everyone?
Yes. Use -1 as the target from a server script.

Can I show an emergency call?
Yes, using the 911 or 311 template. The actual dispatch/command behavior comes from a separate integration.

Does /clearchat delete logs or other players' messages?
No. It clears the local chat UI and local input history for the player who uses it.

Can I rename the resource?
A rename can affect startup configuration and scripts that reference the resource by name. Keep hsc_chat unless you understand and update those references. The supplied NUI code can detect its parent resource name in FiveM.

Can I customize everything through one config file?
Not entirely. Most templates and display settings are in config.js; layout is in style.css, the startup welcome text is in cl_chat.lua, and server message behavior is in sv_chat.lua.

22. Support Information​

Publisher: Hotspot Creations
Resource: HSC Chat
Documented version: 1.0.1

When requesting support, include:

  1. Your HSC Chat version.
  2. Your framework (Standalone / QBCore / Qbox / ESX).
  3. The relevant client F8 error or server console error.
  4. The command, template, or feature affected.
  5. Whether the problem happens with other chat or admin resources disabled in a test environment.

Do not post passwords, API keys, license keys, or other sensitive credentials in support requests.

Documentation prepared for the HSC Chat v1.0.1 files supplied in this conversation. Always check later release notes before assuming a subsequent version has exactly the same interface or capabilities.