nCore Chat – roleplay chat with proximity speech, 3D /me, 911 cards and emoji emotes documentation

Roleplay chat for FiveM that takes the place of the stock chat resource. Standalone, ESX, QBCore, QBox, ND_Core and ox_core.

nCore Development · intelnpc.com · Resource: ncore_chat · Version: see fxmanifest.lua

What it is#

nCore Chat replaces the stock chat with one made for roleplay. Speech goes by distance, /me and /do show above your head, private messages are threads, and a 911 call is a card the cops can answer.

It provides chat, so scripts that send lines to the stock chat still land in it. The server decides who hears what. A framework is optional, and oxmysql only adds saving.

Features#

Replacing the stock chat#

• Provides chat - the manifest has provide 'chat', and calls to exports['chat'] are answered on client and server. Remove the stock chat resource first.
• Stock messages - chat:addMessage, chat:addTemplate, chat:addSuggestion(s), chat:removeSuggestion and chat:clear work. Color codes ^0 to ^9 are read. Template HTML is cut down to <b>, <i>, <br> and colored spans, so nothing unsafe gets in.
• Cancellable chatMessage - the server fires chatMessage for every line before it goes out, and other scripts can cancel it.
• Unknown commands - a /command no resource handles shows a short translated toast instead of vanishing.
• What doesn't carry over - stock-style chat:addMode / registerMode tables are not turned into channels and stock updateMessage rewrites from hooks don't apply. Scripts that rely on those need a small change.

The panel#

• Open the chat - T (key mapping lrc_open, rebindable in the game's Key Bindings). Lands in IC, or in the last channel with Config.keybinds.openTo = 'last'. It won't open while the screen is faded out or the pause menu is up.
• Open straight to Global OOC - key mapping lrc_ooc, unbound by default (Config.keybinds.oocOpen).
• Tabs and rail - IC, Local OOC and Global OOC are tabs on top. Every other channel is an icon on the left rail, grouped Duty, Apps and Staff, with its own color and a short label. Order comes from order in config/channels.lua.
• Unread badges - count badges on tabs and rail icons (99+ cap). 911 always uses the alert style.
• Rail tooltip - hover an icon to see its name, Alt+N hotkey, reach, price and a short description.
• "Sending to" strip - above the input: the channel, how far it reaches, the speech-mode pills in IC, chips for read-only, slowmode and advert price, and up to 4 quick command buttons for the built-in channels.
• Bubbles or classic lines - phone-style bubbles with avatars by default. Config.messageStyle = 'plain' makes colored "Name: message" lines the server default, and players can switch in Settings > Appearance.
• Mode styling - me, do, OOC, radio, shout, whisper, low, staff, department and announcement lines each have their own look and a small chip.
• Distance fade - IC and Local OOC lines get fainter in three steps the closer the speaker was to the edge of range.
• Big emoji - a message of up to 3 emoji alone shows large.
• Grouping - Config.identity.nameEveryMessage = false groups lines from the same author and mode within 60 s under one name. On by default (every line has a name).
• Day separators and time chips - a time chip every 5 minutes. Players pick off, 12h or 24h.
• Repeat counter - the same line from the same player in the same channel within 30 s is posted with an xN counter.
• Instant send - your line shows at once as "sending", and turns "failed" if the server refuses it or nothing comes back in 10 s.
• Jump to new - scroll up and new lines don't pull you down. A button shows how many are waiting.
• Empty channels - a short explainer with buttons for the channel's commands.
• Search - Ctrl+F or the magnifier. This channel or all channels, live results grouped by channel with highlighted snippets and times, Enter opens the first hit. It searches the lines your client has loaded, up to Config.search.maxResults (200).
• Jump to a message - click a search hit or a pin: the chat switches channel, scrolls to it and flashes it.
• Drag and place - drag the header to move the panel. Nine position presets, an optional 8x5 snap grid, widths S / M / L (460 / 540 / 640 px), a UI scale slider (0.85 to 1.6) on top of an automatic scale for big screens, and a reset button. All in Settings > Window. Config.window.draggable = false locks it.
• Mouse look - off by default. Config.window.cameraLook = 'drag' turns the camera while the right mouse button is held, 'free' whenever the mouse is off the panel. Speed is cameraLookSensitivity.
• Close after send - the chat closes after each line you send. Players can turn that off in Settings > Chat.
• Keyboard - while typing: Tab / Shift+Tab cycle the tabs, Alt+1 to 9 jump by rail order, Alt+Up / Down change speech mode, Up / Down walk your input history, Enter sends (empty Enter closes), Shift+Enter adds a new line, Esc closes. Ctrl+, opens settings. A keyboard button under the input lists the shortcuts.
• Block players - /block [id], /unblock [id] or right-click a line. Their lines are hidden on your screen only. Staff, 911 and System channels are never hidden. The list with Unblock buttons is in Settings > Privacy.
• Clear your window - /clearchat empties your own panel.

Typing and sending#

• Command palette - type / in an empty input. Fuzzy ranked, with translated help for nCore commands, suggestions other scripts added, and the server and client commands you have access to. Up / Down to move, Tab or Enter to fill.
• Parameter chips - after a command word, its parameters show as chips. The one under the cursor is highlighted, filled ones get a tick, and the help line follows.
• @ autocomplete - type @ for the last authors in the channel, with their avatars. Picking one inserts the full name, and that player gets a mention badge and the notification pill.
• Emoji shortcodes - : plus a few letters completes about 90 shortcodes.
• Emoji picker - the smile button. 8 categories, search and a tab of emoji that make your character move, marked with a small star.
• Attach menu - the + button: share location (/loc), roll a die (/roll 6) or take a photo (/photo).
• Speech mode chip - in IC, a chip in the input. Click cycles whisper, low, say and shout, right-click opens a menu, and the pills above show each range in meters. The server checks the mode.
• Drafts and history - each channel keeps its unsent text while you switch. Up / Down recalls your last 50 lines per channel. Both live until you reconnect.
• Counter and slowmode - a character counter under the input (Config.window.maxLength, 500), and a countdown ring on the send button when a channel has slowmode.
• Typing dots - while you type in IC or Local OOC, dots show above your head for players near you (Config.typing.world3d). They're hidden while you aim. In PMs, radio, report and staff threads the other side sees an "is typing" row. Players can stop sharing it in Settings > Immersion.

Speech and roleplay verbs#

• Proximity IC - the server routes IC by distance: whisper 2.5 m (/w, /whisper), low 4 m (/low), say 8 m (/say or just type), shout 30 m (/s, /shout) with a 5 s cooldown for non-staff. Ranges are Config.modes.<mode>.radius.
• Vehicles and buckets - people in the same vehicle always hear each other. Players in another routing bucket never do.
• No proximity backlog - IC and Local OOC have no history on the server, so someone who joins late can't scroll back through what was said before they arrived.
• /me and /do - post an action or a scene line in IC and show it as 3D text above the speaker. Config.channels.autoFormatVerbs capitalizes the first letter and adds a full stop.
• /try - a card that says success or fail, rolled on the server. Odds are Config.modes.try.successChance (0.5).
• /roll and /coin - /roll rolls 1 to 6, /roll 20 rolls 1 to 20, capped at maxSides (1000). /coin flips a coin. Both post a card.

Text above heads#

• 3D /me and /do - shown above the speaker for players within range (8 m). Text scales with distance, fades near the edge and at the end of its life, and stacks up to 3 per player. A /me stays up longer when it's longer.
• Speech bubbles - IC lines also pop up above heads for 5 s, 2 per player. Shouts are in capitals, whispers are dimmed. Config.speechBubbles.enabled.
• Two renderers - Config.me3d.renderer = 'nui' (HTML bubbles with avatars, default) or 'native' (GTA draw-text).
• Behind walls - Config.me3d.occlusion hides text from a speaker you can't see, checked twice a second per text.
• Pinned /do - off by default. Config.do3d.anchors = true keeps a /do at the spot it was written for lifeMinutes (2), for the players who were in range. /undo_do takes yours down for players still nearby.
• Player toggles - Settings > Immersion: see other players' 3D text, show my own, speech bubbles above heads.
• Cap - Config.performance.max3dTexts (24) is the most texts drawn at once.

Avatars and names#

• Headshot avatars - every message shows the author's face, taken from their ped. Nearby players are generated locally, no extra resource needed.
• Your avatar stays current - it's retaken when your ped model changes, and after outfit events from illenium-appearance, fivem-appearance, esx_skin / skinchanger, qb-clothing, ncore_inventory and ncore_character. /mugshot retakes it by hand (60 s cooldown).
• Blank pictures - a blank or black headshot is detected and retried up to 3 times, then a fallback icon is used.
• Far away players - with loaf_headshot_base64 or MugShotBase64 running, players far away still see your avatar. With the database on, it's also stored.
• Fallback icon - masked, anonymous and system authors get an icon. Players can turn all avatars off, or only their own.
• Character names - names come from the framework character, never the FiveM account name. Until a character loads, and on standalone, the name is "Unknown".
• Badges - department members get a colored badge. Staff get a shield outside IC.
• Masks - a mask on the ped makes your lines show as "Masked #742", with no job, badge or avatar. The real character is still logged. The player's own client reports the mask, so a modified client can claim one it doesn't wear. Config.identity.maskItem makes the server also check for an item (ESX, QBCore, QBox and ox_core). Config.identity.maskDetection switches it.
• [id] in OOC - Config.identity.showIdInOOC puts the server ID in front of names in OOC and Local OOC.

Emoji that move your character#

• Emoji emotes - send an emoji alone (up to 3) or at the end of an IC line and your character plays a matching GTA animation. The server picks it from a pool and avoids repeating the last one.
• Moods - face emoji like 😄 🙂 😢 😡 😮 😴 only change the face for about 10 s.
• Cooldowns - 6 s per player and 10 s per emoji family, on the server (playerCooldown, perEmojiCooldown). A toast tells you the time left.
• When it skips - dead, cuffed, ragdolled, swimming, or in a vehicle. Seat-safe ones like 👋 👍 🤷 still play in a car.
• Handshake, hug, high five - 🤝 🤗 ✋ send an Accept / Decline card to the nearest player within 2 m. It lands in their System channel. If they accept within 10 s, both turn to face each other and play their side. Config.emojiEmotes.pairedConsent = false turns paired emotes off.
• Opt out - "Emoji trigger my character" in Settings > Immersion. Config.emojiEmotes.allowRude = false drops the 🖕 pool (on by default).
• Text emoticons - :D, xD, :), <3 and the rest of Config.emoticons.map turn into emoji when typed as a separate word.
• Your own map - which emoji plays which animation is in config/emoji_emotes.lua.
• Turn it off - Config.emojiEmotes.enabled = false.

Channels#

• Built in - IC, Local OOC, Global OOC, Radio, Adverts, Chirp, Darknet, 911 Dispatch, Staff, Announcements and System. Chirp and Darknet are off by default.
• Local OOC - /b or /looc, 20 m (Config.channels.oocLocal.radius).
• Global OOC - /ooc, server wide, 2 messages per 10 s per player (Config.moderation.rate.oocGlobal). Config.channels.oocGlobal.schedule = { start = 22, stop = 8 } opens it only between those hours, overnight works.
• Radio - /radio 445.5 tunes in and adds a MHz entry to the rail, /radio [message] transmits, /radio off (or leave) tunes out. Frequencies are rounded to 2 decimals, and you can tune to a new one every 3 s (Config.channels.radio.joinCooldown). When the last player leaves a frequency, its rail entry and history are gone. With pma-voice the chat also tunes to your voice radio channel.
• Departments - /pd, /ems, /doj for the jobs in Config.channels.departments, on duty only by default. Each has its own badge color and icon. Add more in the same table. Needs a framework that gives job and duty.
• Adverts - /ad or /advert posts a business card. Costs 250 and has a 120 s cooldown for non-staff (Config.channels.adverts). Paid through the framework. On standalone it's free and the console says so at start.
• Chirp - /chirp, a city social feed. With the database on, the newest posts come back after a restart.
• Darknet - /anon, posts under a random handle like viper_4821 that changes every restart. Players can't see who wrote it. Lines show blacked out until clicked. requireItem (default cryptostick) works on ESX, QBCore, QBox and ox_core. Set it to '' on other setups.
• 911 and 311 - /911 opens a numbered incident, /311 a non-emergency tip. On-duty responders (LRCDispatchJobs: police, sheriff, ambulance) get a live card with call number, priority, New / Responding timeline, caller, street, elapsed timer and attached units. Buttons: Respond (Acknowledge on 311), waypoint and a map blip that removes itself. The caller is told who's responding. A call nobody answered shows CLOSED after expirySeconds (600).
• Dispatch forwarding - with forwardResource = 'auto' each call also goes to ps-dispatch or cd_dispatch when one runs.
• Staff - /staff or /a posts to the staff-only channel. Staff is the framework admin group or the ACE lrc.staff.
• Announcements - /announce [text], optionally with --countdown=N for a live countdown card. Staff, the ACE lrc.announce or the server console (announce [text]). Staff can also type straight into the Announcements channel.
• System - join and leave lines are off (Config.channels.systemJoinLeave, or the stock chat_showJoins convar).
• Your own channels - add a table to config/channels.lua: reach (proximity, global, jobs, staff), jobs and duty, commands, cost, cooldown, read-only, ACE, icon, color and rail position. Players never see a channel they can't read.

Private messages#

• Threads - /pm [id] [message] opens a thread with its own rail entry, /r answers the last one.
• Receipts - your bubbles show Queued, Delivered or Read. Players can stop sending read receipts in Settings > Privacy, and Config.pm.receipts = false turns them off for everyone.
• Quick reply - Page Down (lrc_reply) opens a small box to answer the newest PM without opening the panel, for 300 s after it arrived (Config.pm.quickReplySeconds).

Cards#

• Polls - staff run /poll "question" option1 option2 ... (up to 6). Players vote and can change their vote, bars update live, and it closes after Config.channels.pollMinutes (10) or with /pollclose.
• Location - /loc posts your street and area into the current proximity channel. Readers see distance and direction from where they were when it arrived, plus waypoint and map blip buttons.
• Photos - /photo [caption] takes a screenshot with a shutter flash, uploads it and posts a photo card with a lightbox to players within 8 m. Needs screenshot-basic and an upload URL in the lrc:photoWebhook convar. The endpoint has to answer with the image URL (JSON url or attachments[1].url, or a plain link). 30 s cooldown, quality and size in Config.photos.
• Pins - staff, or players with the ACE lrc.pin, pin from the right-click menu. Up to 3 per channel, the bar shows who pinned and a 1/N counter, click to jump.
• Card buttons - each button carries a token that works once, for that player, until it expires. Forged or replayed clicks are dropped.

Moderation and staff#

• Send checks - every line goes through mute, slowmode, cooldowns and a rate limit on the server, then cleaning: control characters and reversed-text marks are removed, ALL CAPS is toned down, and the word filter runs.
• Rate limit - Config.moderation.rate sets it per class: ic for proximity channels, oocGlobal, pm, and default for every other channel. The Staff channel has none.
• Word filter - three lists in Config.moderation.extraWords: block refuses the line and counts a strike, mask turns the word into asterisks, flag only writes it to the log. Whole words only, and leetspeak is decoded before matching, so write your words in plain letters.
• Soft mutes - three violations within 60 s give an automatic mute of 10 s, then 60 s, then 300 s (Config.moderation.softMuteSteps).
• Mutes - /lrcmute [id] [seconds] [channel] and /lrcunmute [id]. A muted player sees a chip with a countdown. With the database on, mutes survive rejoin and restart.
• Slowmode and lock - /slowmode [seconds] [channel] (0 clears) and /lockchannel [channel]. They reset at restart.
• Wipe - /lrcclear [channel] clears a channel, or all of them, for everyone and drops the server history.
• Right-click tools - staff right-click any line: delete (leaves a "removed by staff" placeholder), mute 15 minutes, unmute, warn with a reason, the player's last messages, and copy IDs.
• Reports - /report [id] [reason] posts a numbered card in Staff. Claim opens a private Report #N thread (the button works for 5 minutes after the card arrives). /reportclose [id] closes it. A player can send one report every 60 s (Config.moderation.reportCooldown).
• Staff exemptions - staff skip slowmode, the shout and advert cooldowns, and can post in a locked channel.
• Staff toasts - with ncore_hud running, /report, /lrcmute and /lrcunmute also pop a toast for staff.
• Edit and unsend - right-click your own line within 120 s (Config.messageEdit.windowSeconds). Edits go through the word filter again and show "edited". Unsend leaves a placeholder. IC and 911 can't be edited or unsent (permanentChannels).

Closed chat and notifications#

• Mini chat - with the panel closed, recent lines fade in and out where the panel sits. 15 s and 8 lines by default (Config.window.ghostLifeSeconds, ghostMaxLines), players set 4 to 60 s and 3 to 14 lines.
• /hidechat - cycles the mini chat through all, important only (staff, 911, announcements) and hidden.
• Notification pill - a small pill at the top center for PMs, mentions, 911 and staff lines while the chat is closed. Avatar, name and a preview, a red outline for 911, click opens the channel. Config.notifications.island.
• Do Not Disturb - hides the pill for everything except 911 and staff.
• Channel mute - the bell button, or right-click a tab or rail icon, keeps that channel out of the mini chat and marks it with a bell.
• Game feed - System and announcement lines also go to the GTA feed above the minimap (Config.notifications.gameFeed).
• Pause menu - the mini chat, pill, quick reply and 3D text (NUI renderer) hide while the pause menu is open.
• Sounds - send, receive, mention, 911, staff, open, close and error. GTA frontend sounds by default (Config.notifications.soundEngine = 'native', remap them in nativeSounds), 'ui' for soft tones, 'off' for none. With native sounds the player's volume slider works as on and off.

Settings and looks#

• Settings sheet - the gear or Ctrl+, opens 7 tabs: Roleplay, Window, Appearance, Chat, Immersion, Notifications and Privacy. Saved per player on their PC.
• Five themes - Afterglow (default), Sunset, Dusk, Midnight and Daylight. Config.theme.default sets the default, allowPlayerChoice = false hides the picker.
• Locked settings - put pref keys in Config.lockedSettings (for example { 'theme' }) and every player gets your default. The row shows as "Server managed".
• Accessibility - text scale 0.85 to 1.4, compact density, animation speed, reduced motion (the OS setting is honored too), a solid panel option, a color-blind accent palette and dyslexia-friendly spacing.
• Streamer mode - Settings > Privacy. Removes the OOC, Local OOC and Chirp tabs and rail entries, blurs avatars in the feed, mini chat, pill and quick reply, and turns off the talking ring.
• Fonts and icons - bundled with the resource, nothing loads from the internet.
• Colors - theme palettes are CSS variables in web/css/tokens.css.
• Reset - Settings > Privacy > Reset all settings goes back to defaults, block list and window position included.

Profiles#

• RP mode - /chatmode text|voice|hybrid or the Roleplay tab. Each mode sets how long and how many lines the mini chat keeps (Config.rpModes). Config.rpModeDefault sets the default, and 'rpMode' in Config.lockedSettings locks it.
• Server profile - Config.profile = 'text' widens the ranges (say 12, whisper 3, low 5, shout 40 m), keeps 250 lines per channel instead of 150 and makes the mini chat stay longer. 'hybrid' keeps the voice ranges. 'voice' is the default. A player who hasn't picked an RP mode starts in the one the profile names, unless Config.rpModeDefault is set. The overrides per profile are in Config.profiles at the bottom of config/config.lua.

Voice and HUD#

• ncore_hud - with ncore_hud running, RP mode is shared with the HUD both ways and the HUD can lock it.
• Speech mode sets mic range - with ncore_hud or pma-voice, picking whisper, say or shout in the chat also sets your voice range, and a range change elsewhere moves the chat mode back (Config.integrations.voiceRange).
• Talking ring - in bubble style, avatars of players within 20 m who are talking pulse while the chat is open. Needs a voice resource where the game's talking check works, like pma-voice. Config.presence.voiceRing.

Localization#

• Six languages - English, German, Spanish, French, Hungarian and Brazilian Portuguese. Config.locale = 'auto' reads the usual locale convars (lr:locale, locale, ox:locale, esx:locale, txAdmin-locale). On the client it falls back to the game language, on the server to English.
• Add a language - copy locales/en.json to locales/<code>.json and translate it. Missing keys fall back to English.
• Not in the locale files - channel and department labels are in config/channels.lua and config/config.lua, so you rename those there.

Database and logs#

• Database - off by default. Config.logs.database = true with oxmysql creates 7 tables from sql/ncore_chat.sql at start. Adds: message archive (write only), saved Chirp, report numbers that keep counting, mutes that survive restarts and stored avatars.
• Log files - Config.logs.file (on) writes every message and staff action to logs/lrc-YYYY-MM-DD.jsonl in the resource folder, a new part every 2000 lines, and keeps going after a restart. Message lines have author, license, the position on proximity channels and the street on 911 and location cards. This includes private messages. Nothing is deleted on its own, retentionDays (30) only prints a reminder at start.
• Webhook logs - set the convars lrc:logWebhook (all channels, private messages included), lrc:logWebhookStaff (staff channel and staff actions) and lrc:logWebhook911. Lines are batched, up to 10 per request every 5 s (Config.logs.webhookBatchSeconds).
• Secrets stay on the server - webhook URLs are read from convars in config/config_server.lua, which only the server loads. A URL left in config/config.lua still works and prints a warning.
• Export and forget - in the server console, lrc_export <license> prints that player's lines from today's log. lrc_forget <license> [charId ...] deletes their saved settings, archived messages, Chirp posts, avatar and queued PMs from the database, and their lines from today's log file. When today's log has more than one part, export only sees the newest part plus the last 500 lines before it, and forget only cleans the newest part. Files from earlier days stay as they are, delete those by hand.
• Hidden character IDs - clients never get a player's license or real character ID. Each character gets a random ID like c_3f9a1c0e7b2d4a61, kept in the resource KVP so it stays the same after a restart. Copy IDs in the staff menu gives you that ID, and lrc_forget takes it too. The database and the log files keep the real ID.
• No phone home - the only outbound requests are your own webhooks and the /photo upload.

For developers#

• Server exports - Send, SendCard (up to 3 buttons that fire server events), RegisterChannel, RemoveChannel, RegisterCommandChannel, Mute, Unmute, ClearFor (pass a table of server IDs, or nil for everyone), SetSlowmode, OnMessage (rewrite or cancel a line, returns a hook ID), RemoveHook, GetHistory.
• Client exports - Open(channelId), Close(), IsOpen(), GetActiveChannel(), Notify(text or {kind, text}), PedSpeech(ped, text, kind, info) (a bubble over any ped, NPCs too), ClearPedSpeech(ped), GetChatRpMode(), SetChatRpMode(mode).
• Events - client lrc:onOpened, lrc:onClosed, lrc:onChannelChanged, lrc:onCardAction. lrc:advertContact on server and client.
• State bags - lrc_typing and lrc_masked on the player, for other resources to read.
• Shared focus - NUI focus and background blur are coordinated with ncore_hud, ncore_vibehud and ncore_devkit through the state bags lrNuiOwner and lrBlurDepth.

Requirements#

• FXServer build 6116 or newer.
• OneSync on.
• Optional: a framework (QBox, QBCore, ESX, ox_core or ND_Core) started before ncore_chat. Without one it runs standalone.
• Optional: oxmysql with Config.logs.database = true (MySQL 5.7.8+ or MariaDB 10.2.7+).
• Optional: screenshot-basic for /photo, pma-voice or ncore_hud for voice features, ps-dispatch or cd_dispatch for forwarding, loaf_headshot_base64 or MugShotBase64 for avatars of far away players.
• No ox_lib needed.

Keys and commands#

Configuration reference#

Every key in config/config.lua has a comment next to it. This is what each block covers:

Trying it on a test server#

Config.demoMode ships false. Set it to true on a test server and restart, then run /lrcdemo as staff (or lrcdemo <id> from the console). Ten scripted characters stand around you in three groups, 6, 12 and 18 m away, and talk to each other while every channel gets some traffic. Walk from one group to the next and you hear the ranges work. Only you see them and nothing goes into the real history or the logs. /lrcdemo stop removes them, and a scene nobody stops ends after 30 minutes.

/lrcshowcase is the cut I record videos with. It changes your ped model, your framework job, the time and the weather while it runs, so keep it to a test server. Set Config.demoMode back to false before you go live.

Troubleshooting#

Docs#

• INSTALLATION.md - setup step by step.
• CHANGELOG.md - what changed in each version. Updates don't install themselves: download the new version, keep your config/ folder and copy the other files over. The changelog lists new settings so you can copy them into your config.

Support#

Support is on intelnpc.com and I reply within 72 hours. It covers installing, configuring and bugs in the script as shipped. Send your framework, server build, the console error and your Tebex transaction ID.

nCore Chat is made by nCore Development. It is not approved, sponsored or endorsed by Rockstar Games.