Shadow_ME — Documentation

Overview#

SF-Me replaces the /me line lost in the chat with a message floating in 3D above the player, visible only to those close enough. It adds automatic messages triggered by context, an anti-spam cooldown, colour choice and a message history. It runs with ESX, QBCore, or completely standalone.

3D display

The message floats above the player and only shows within the configured distance.

Colour choice

Players pick their message colour from the allowed palette.

Automatic messages

Contextual messages triggered automatically, for example by the weapon being held.

Anti-spam

A configurable cooldown between two messages.

History

The last messages are kept and can be listed again.

Fade in and out

The message appears and disappears smoothly, with configurable durations.

Optional permissions

Restrict the command to an ACE group, or leave it open to everyone.

File logging

Optionally write every message to a log file.

Installation#

Drop the SF-Me folder into your server resources directory.
Add the ensure line below to your server.cfg.
Adjust the display distance, the duration and the colours in config.lua.
If you want to restrict the command, enable Config.UsePermissions and grant the ACE node.

server.cfg

ensure SF-Me

# Optional: restrict /me to a group
add_ace group.user command.me allow

Configuration#

Key	Default	What it does
`Config.DisplayDistance`	`10.0`	Distance in metres beyond which the message is no longer visible.
`Config.DisplayTime`	`8000`	How long the message stays on screen, in milliseconds.
`Config.TextHeight`	`1.0`	Height of the text above the player head.
`Config.Framework`	`'auto'`	Force esx, qbcore or none.
`Config.MeColor`	—	Default colour of the messages.
`Config.AvailableColors`	—	The colours a player is allowed to pick.
`Config.EnableCooldown`	—	Enables the anti-spam cooldown.
`Config.MeCooldown`	—	Delay in seconds between two messages.
`Config.UsePermissions`	—	Restricts the command to holders of the ACE node.
`Config.MePermission`	`'command.me'`	ACE node checked when permissions are enabled.
`Config.MePrefix`	—	Prefix shown in front of the message.
`Config.UseCharacterName`	—	Shows the character name instead of the account name.
`Config.EnableFadeEffect`	—	Enables the fade in and fade out effect.
`Config.FadeInDuration`	—	Duration of the fade in, in milliseconds.
`Config.FadeOutDuration`	—	Duration of the fade out, in milliseconds.
`Config.EnableAutoMessages`	—	Enables the automatic contextual messages.
`Config.AutoMessages`	—	The automatic messages and what triggers them.
`Config.AutoMessageColor`	—	Colour used by the automatic messages.
`Config.AutoMessageCooldown`	—	Delay between two automatic messages.
`Config.ValidWeapons`	—	Weapons that trigger an automatic message.
`Config.IgnoredWeapons`	—	Weapons that never trigger one.
`Config.WeaponFilterMode`	—	Whether the weapon list acts as an allow list or a deny list.
`Config.EnableMessageHistory`	—	Enables keeping the message history.
`Config.MaxHistorySize`	—	Maximum number of messages kept in the history.
`Config.EnableLogging`	—	Enables logging of the messages.
`Config.EnableFileLogging`	—	Also writes the messages to a file on the server.
`Config.Locale`	—	Language of the messages.

Commands#

Command	Permission	What it does
`/me [message]`	`command.me`	Display a roleplay message in 3D above your character.
`/mecolors`	—	List the colours you can use and pick one.
`/mehistory`	—	Show the recent message history.
`/shadow_me_reload`	`Admin`	Reload the configuration without restarting the resource.
`/shadow_me_clearhistory`	`Admin`	Clear the message history.
`/shadow_me_resetcooldown [id]`	`Admin`	Reset the cooldown of a player.

Permissions#

ACE node	Group	Allows
`command.me`	—	Allows the use of /me when Config.UsePermissions is enabled.

Exports#

Signature	Side	Returns
`exports['SF-Me']:SendMeMessage(message)`	client	Sends a /me message from your own resource.
`exports['SF-Me']:Display3DMessage(coords, text, duration)`	client	Displays any text in 3D at the given coordinates.
`exports['SF-Me']:AreAutoMessagesEnabled()`	client	Returns whether the automatic messages are enabled.
`exports['SF-Me']:ToggleAutoMessages(state)`	client	Enables or disables the automatic messages.
`exports['SF-Me']:GetTranslation(key)`	shared	Returns a translated string by key.

Good to know#

Display3DMessage is usable on its own: it is a generic 3D text helper you can reuse for anything.