OmiChat is a mod for Project Zomboid that extends chat functionality. It's available on the Steam workshop.

Features

This mod aims to be as extensible and configurable as possible. The vast majority of the features in the mod can be configured or completely disabled via sandbox options.

• Customization of names, timestamps, all chat types, and more via powerful chat formats
• Chat color customization
• Name color customization
• Speech bubble color customization
• Callout customization
• Character naming with /name
• Character customization (off by default)
• Chat buffs (off by default)
• Display of chat names in menus (Trading, Medical Check)
• Local /whisper chat
• Local /card and /roll
• Roleplay descriptions with /me and /do
• Range-based chat streams (/mequiet, /meloud, /doquiet, /doloud)
• Input suggestion box
• Emote animation shortcuts (.clap, .salute, .surrrender, etc.)
• Roleplay languages
• Compatibility with True Actions Act 3 - Dancing with /dance
• Chat range options
• Info text option
• Typing indicator (off by default)
• Various other options for chat customization
• API for extension by other mods

Credits

Thank you to the translators!

• French: Inkredibehl
• Korean: 우로

If you'd like to see the mod translated into your language, please contribute!
Some features were inspired by buffy's roleplay chat.

Chat Settings

In addition to the vanilla settings, OmiChat offers some new settings for players. With the exception of the roleplay language settings, these settings will persist across game servers. You can access the chat settings by clicking on the gear icon at the top right of the chat box.

Basic settings

Most of the settings within the basic “chat settings” submenu exist in vanilla. The existing settings work equivalently. There are two new options in this submenu.

The suggestions submenu can be used to control whether suggestions are offered based on chat box input and how those suggestions are accepted.

The retain commands submenu can be used to determine whether certain commands are “retained,” so that they are set as the initial input the next time the chat is used. The submenu contains three options: “Chat,” “RP,” and “Other.” The first option refers to streams such as /say, the second refers to streams like /me, and the third covers all other commands.

Customization

The customization settings can be used to tailor the chat to your preferences.

The enable/disable sign language emotes option is only shown when the player knows a signed language. This controls whether a random emote animation is played whenever they send a message.

The enable/disable name colors option allows players to toggle the appearance of name colors in their chat. This will only display if either the EnableSpeechColorAsDefaultNameColor option or the EnableSetNameColor option is enabled.

The manage profiles option is used to open the profile manager, which can be used to customize callouts and chat colors.

Color customization

The profile manager contains a number of options that allow players to control how the various chat streams display in their chat, as well as the color of their overhead chat messages.

For example, to use orange for messages sent with /yell, the /yell color option can be used.

The available color customization options depend on server configuration.

Callout customization

The profile manager also includes options that allow players to set custom messages for when they use callouts (bound to the Q key, by default). These rely on the EnableCustomShouts option.

Character customization

If a server has character customization enabled, the customization submenu also includes QoL character modification options. The available options are self-explanatory.

Language options

The Language submenu will only display for players that know multiple languages or can add new ones. From this menu, players can select the roleplay language that they want to use in chat. The currently selected language will be displayed with a checkmark. The option to add new languages will only be available if a player has more available language slots than languages.

Languages other than the default language will display an indicator for the language when used in chat. Players with characters that don't speak the language will see a chat message indicating that they don't understand it.

Emote Shortcuts

The EnableEmotes option allows players to use emote shortcuts in the form of .emote in local chats. These emote shortcuts cause a player's character to play the animation associated with the emote, but they don't show up in the chat message.

For example, sending the message Don't shoot! .surrender would result in the following:

This can be useful for text roleplay servers, since players can play an animation in sync with their message. The shortcuts can also be used without a message; sending .hi will play the animation without sending a message in chat.

Note: Unless the emote is the only thing sent, it must come after a space. This is to prevent accidentally including an emote after ending a sentence.

Shortcut list

The following table contains the emotes that are available in the base mod. Players can use the /emotes command to view a list in-game, or enter them using the suggestion box.

Admin Utilities

OmiChat offers some utilities for admins to use in-game.

Admin Menu

When the player has admin access, the gear button's context menu has an Admin options entry that offers toggles for mod-specific admin powers.

The chat icon used for the display chat icon option is controlled by FormatAdminIcon.

The view mod data option can be used to open a mod data viewer that displays data for all players, including those offline. It can also be used to modify mod data.

Commands

There are various commands to control player names, languages, and icons.

Mini Scoreboard

The “mini scoreboard” included in the admin menu will respect the FormatMenuName sandbox option.

By default, this will display players' chat names (as determined by FormatName) and usernames, in the format Username [Name]. Mousing over names will display more information. Admins can use this to determine the username associated with a chat name.

Java Mods

The GitHub repository includes three Java mod files that are optional and server-side only. The mod functions equivalently in-game without them, but the Java mods may be useful to server operators to address concerns about messages including invisible characters.

Functionality

The ChatServer.class replacement cleans up the server-side chat log files so that they don't include the invisible characters added by this mod. This makes reading these log files much easier.

The GeneralChat.class replacement is recommended for servers using the game's Discord integration. This cleans up messages sent from the in-game /all chat so they don't display extra characters surrounding the text on Discord. It also cleans up some log messages sent directly to the DebugLog file.

The ChatBase.class replacement handles cleaning up invisible characters in some other DebugLog log messages.

Installation

Before installation, you should create a backup of the three .class files. Installing should not be unsafe, but since the process involves replacing game files entirely, backups are recommended.

Note: Clients do not need to do this. The relevant methods are called on the server.

To install:

1. Unzip the java.zip included in a release.
2. Copy each file in the zombie folder into the corresponding subfolder within the zombie folder of the server's PZ game directory. This folder is likely within a java folder. If you're prompted to replace files, do so.

Presets

This page contains sandbox options presets to help server operators with configuration. The presets can be copied by clicking the button that appears the top right of the block on hover. You can paste them directly into your server's SandboxVars file, or use a preset as a base and tweak it.

These presets can also be applied from the in-game admin sandbox options menu.

Default

This preset contains the default settings of the mod.

OmiChat = {
    EnableCustomShouts = true,
    EnableEmotes = true,
    EnableSetNameColor = false,
    EnableSetSpeechColor = true,
    EnableSpeechColorAsDefaultNameColor = true,
    EnableFactionColorAsDefault = false,
    EnableCaseInsensitiveChatStreams = true,
    EnableCharacterCustomization = false,
    EnableAlwaysShowChat = false,
    EnableCleanCharacter = 3,
    EnableSetName = 2,
    EnableDiscordColorOption = 3,
    EnableCompatBuffyCharacterBios = 3,
    EnableCompatBuffyRPGSystem = 2,
    EnableCompatChatBubble = 3,
    EnableCompatSearchPlayers = 3,
    EnableCompatTAD = 3,
    CardItems = "CardDeck",
    CoinItems = "",
    DiceItems = "Dice",
    PatternNarrativeCustomTag = "",
    BuffCooldown = 15,
    BuffReduceBoredom = 0.2,
    BuffReduceUnhappiness = 0.2,
    BuffReduceHunger = 0.1,
    BuffReduceThirst = 0.1,
    BuffReduceFatigue = 0.1,
    BuffReduceCigaretteStress = 0.2,
    MaximumCustomShouts = 10,
    CustomShoutMaxLength = 50,
    MinimumCommandAccessLevel = 16,
    RangeCallout = 60,
    RangeSneakCallout = 6,
    RangeCalloutZombies = 30,
    RangeSneakCalloutZombies = 6,
    RangeMultiplierZombies = 0.0,
    RangeDo = 30,
    RangeDoLoud = 60,
    RangeDoQuiet = 3,
    RangeOoc = 30,
    RangeMe = 30,
    RangeMeLoud = 60,
    RangeMeQuiet = 3,
    RangeMeWhisper = 2,
    RangeSay = 30,
    RangeLow = 5,
    RangeWhisper = 2,
    RangeYell = 60,
    RangeVertical = "@($sneakCallout:1;$index(@(@(shout;meloud;doloud):3;@(whisper;low;mequiet;doquiet;mewhisper):1) $stream 2))",
    ColorDiscord = "144 137 218",
    ColorRadio = "178 178 178",
    ColorServer = "0 128 255",
    ColorAdmin = "255 255 255",
    ColorGeneral = "255 165 0",
    ColorDo = "130 130 130",
    ColorDoLoud = "255 51 51",
    ColorDoQuiet = "85 48 139",
    ColorFaction = "22 113 20",
    ColorOoc = "48 128 128",
    ColorMe = "130 130 130",
    ColorMeLoud = "255 51 51",
    ColorMeQuiet = "85 48 139",
    ColorMeWhisper = "85 48 139",
    ColorPrivate = "85 26 139",
    ColorSafehouse = "55 148 53",
    ColorSay = "255 255 255",
    ColorLow = "85 48 139",
    ColorWhisper = "85 48 139",
    ColorYell = "255 51 51",
    FilterChatInput = "$trim($input)",
    FilterNickname = "$sub($input 1 50)",
    FilterNarrativeStyle = "@($sneakCallout:$input;$capitalize($input))",
    PredicateEnableStream = "true",
    PredicateAllowChatInput = "true",
    PredicateAllowLanguage = "$has(@(say;shout;whisper;low;faction;safehouse) $stream)",
    PredicateApplyBuff = "",
    PredicateAttractZombies = "$has(@(say;shout;meloud;doloud) $stream)",
    PredicateClearOnDeath = "true",
    PredicateShowTypingIndicator = "",
    PredicateTransmitOverRadio = "$any($has(@(whisper;low) $customStream) $not($customStream))",
    PredicateUseNarrativeStyle = "",
    PredicateUseNameColor = "$eq($stream say)",
    AvailableLanguages = "English;French;Italian;German;Spanish;Danish;Dutch;Hungarian;Norwegian;Polish;Portuguese;Russian;Turkish;Japanese;Mandarin;Finnish;Korean;Thai;Ukrainian;ASL",
    SignedLanguages = "ASL",
    AddLanguageAllowlist = "",
    AddLanguageBlocklist = "",
    LanguageSlots = 1,
    InterpretationRolls = 2,
    InterpretationChance = 25,
    FormatAliases = "@(shout:shout;quiet:low)",
    FormatInfo = "",
    FormatName = "$ifelse($has(@(general;admin;whisper) $chatType) $username @($name;$forename))",
    FormatTag = "[$tag]",
    FormatTimestamp = "[$ifelse($eq($hourFormat 12) $h $HH):$mm]",
    FormatMenuName = "$ifelse($neq($menuType mini_scoreboard) $name $username  [ $name ])",
    FormatTyping = "$fmttyping($names $alt)",
    FormatCard = "draws $card",
    FormatRoll = "rolls $roll on a $sides-sided die",
    FormatFlip = "flips a coin and gets @($heads:heads;tails)",
    FormatAdminIcon = "Item_Sledgehamer",
    FormatIcon = "@($eq($stream card):Item_CardDeck;$any($buffyRoll $eq($stream roll)):Item_Dice;$has(@(say;shout;whisper;faction;safehouse;ooc;general) $stream):@($adminIcon;$icon))",
    FormatLanguage = "$if($all($language $not($unknownLanguage)) [$language]( <SPACE> ))",
    FormatOverheadPrefix = "$concats(( ) $index(@(low:[Low];whisper:[Whisper]) $stream) $if($languageRaw [$languageRaw]))&#32;",
    FormatChatPrefix = "$if($icon $icon <SPACE>)$if($neq($stream server) $timestamp)$tag$language$if($buffyCrit $buffyCrit ( <SPACE>))",
    FormatNarrativeDialogueTag = "@($sneakCallout:hisses;$eq($stream shout):shouts;$eq($stream whisper):whispers;$endswith($input ?):asks;$endswith($input !):exclaims;$endswith($input ..):says;$lt($len($input) 10):states;says)",
    FormatNarrativePunctuation = "$unless($sneakCallout @($eq($stream shout):!;.))",
    OverheadFormatFull = "$prefix$1",
    OverheadFormatDo = "",
    OverheadFormatDoLoud = "",
    OverheadFormatDoQuiet = "",
    OverheadFormatEcho = "(Over Radio) $1",
    OverheadFormatOoc = "(( $1 ))",
    OverheadFormatMe = "<< $1 >>",
    OverheadFormatMeLoud = "<< $1 >>",
    OverheadFormatMeQuiet = "<< $1 >>",
    OverheadFormatMeWhisper = "<< $1 >>",
    OverheadFormatLow = "$1",
    OverheadFormatWhisper = "$1",
    OverheadFormatCard = "<< $1 >>",
    OverheadFormatRoll = "<< $1 >>",
    OverheadFormatFlip = "<< $1 >>",
    OverheadFormatOther = "$1",
    ChatFormatFull = "$prefix$content",
    ChatFormatDiscord = "$author: <SPACE> $message",
    ChatFormatIncomingPrivate = "$fmtpmfrom($name 1): <SPACE> $message",
    ChatFormatOutgoingPrivate = "$fmtpmto($recipientName 1): <SPACE> $message",
    ChatFormatServer = "$message",
    ChatFormatRadio = "$fmtradio($frequency): <SPACE> $message",
    ChatFormatAdmin = "$name: <SPACE> $message",
    ChatFormatCard = "$fmtrp(<SPACE> $name <SPACE> $punctuate($fmtcard($card)) <SPACE>)",
    ChatFormatRoll = "$fmtrp(<SPACE> $name <SPACE> $punctuate($fmtroll($roll $sides)) <SPACE>)",
    ChatFormatFlip = "$fmtrp(<SPACE> $name <SPACE> $punctuate($fmtflip($heads)) <SPACE>)",
    ChatFormatDo = "$fmtrp(<SPACE> $punctuate($capitalize($trim($message))) <SPACE>)",
    ChatFormatDoLoud = "$fmtrp(<SPACE> $punctuate($capitalize($trim($message))) <SPACE>)",
    ChatFormatDoQuiet = "$fmtrp(<SPACE> $punctuate($capitalize($trim($message))) <SPACE>)",
    ChatFormatGeneral = "$name: <SPACE> $message",
    ChatFormatOoc = "$name: <SPACE> (( $message ))",
    ChatFormatMe = "$fmtrp(<SPACE> $name <SPACE> $punctuate($trimright($message)) <SPACE>)",
    ChatFormatMeLoud = "$fmtrp(<SPACE> $name <SPACE> $punctuate($trimright($message)) <SPACE>)",
    ChatFormatMeQuiet = "$fmtrp(<SPACE> $name <SPACE> $punctuate($trimright($message)) <SPACE>)",
    ChatFormatMeWhisper = "",
    ChatFormatSafehouse = "$name: <SPACE> $message",
    ChatFormatSay = "$name$unless($buffyRoll :) <SPACE> $message",
    ChatFormatFaction = "$name: <SPACE> $message",
    ChatFormatLow = "$name: <SPACE> $message",
    ChatFormatWhisper = "$name: <SPACE> $message",
    ChatFormatYell = "$name: <SPACE> $message",
    ChatFormatEcho = "",
    ChatFormatUnknownLanguage = "$fmtrp(<SPACE> $name <SPACE> $getunknownlanguagestring($languageRaw $stream) <SPACE>)",
    ChatFormatUnknownLanguageRadio = "$fmtradio($frequency): $fmtrp($getunknownlanguagestring($languageRaw $stream))",
}

Buffy

This preset is based on buffy's roleplay chat. It's designed to loosely mimic the style of that mod through various tweaks of default settings, such as enabling narrative style and changing the default colors.

Note that this is not a 1-to-1 correspondence; some things in this preset work differently than they do in buffy's mod. For example, the value for EnableSetName sets the chat nickname rather than the character's name.

OmiChat = {
    EnableCustomShouts = true,
    EnableEmotes = true,
    EnableSetNameColor = false,
    EnableSetSpeechColor = true,
    EnableSpeechColorAsDefaultNameColor = true,
    EnableFactionColorAsDefault = false,
    EnableCaseInsensitiveChatStreams = true,
    EnableCharacterCustomization = true,
    EnableAlwaysShowChat = false,
    EnableCleanCharacter = 2,
    EnableSetName = 2,
    EnableDiscordColorOption = 3,
    EnableCompatBuffyCharacterBios = 3,
    EnableCompatBuffyRPGSystem = 3,
    EnableCompatChatBubble = 3,
    EnableCompatSearchPlayers = 3,
    EnableCompatTAD = 3,
    CardItems = "CardDeck",
    CoinItems = "",
    DiceItems = "Dice",
    PatternNarrativeCustomTag = "",
    BuffCooldown = 5,
    BuffReduceBoredom = 0.2,
    BuffReduceUnhappiness = 0.2,
    BuffReduceHunger = 0.1,
    BuffReduceThirst = 0.1,
    BuffReduceFatigue = 0.1,
    BuffReduceCigaretteStress = 0.2,
    MaximumCustomShouts = 10,
    CustomShoutMaxLength = 50,
    MinimumCommandAccessLevel = 16,
    RangeCallout = 48,
    RangeSneakCallout = 6,
    RangeCalloutZombies = 30,
    RangeSneakCalloutZombies = 6,
    RangeMultiplierZombies = 0.0,
    RangeDo = 20,
    RangeDoLoud = 48,
    RangeDoQuiet = 4,
    RangeOoc = 20,
    RangeMe = 20,
    RangeMeLoud = 48,
    RangeMeQuiet = 4,
    RangeMeWhisper = 2,
    RangeSay = 16,
    RangeLow = 4,
    RangeWhisper = 2,
    RangeYell = 48,
    RangeVertical = "@($sneakCallout:1;$index(@(@(shout;meloud;doloud):3;@(whisper;low;mequiet;doquiet;mewhisper):1) $stream 2))",
    ColorDiscord = "144 137 218",
    ColorRadio = "178 178 178",
    ColorServer = "0 128 255",
    ColorAdmin = "255 255 255",
    ColorGeneral = "255 165 0",
    ColorDo = "128 0 128",
    ColorDoLoud = "128 0 128",
    ColorDoQuiet = "128 0 128",
    ColorFaction = "22 113 20",
    ColorOoc = "48 128 128",
    ColorMe = "128 0 128",
    ColorMeLoud = "128 0 128",
    ColorMeQuiet = "128 0 128",
    ColorMeWhisper = "128 0 128",
    ColorPrivate = "85 26 139",
    ColorSafehouse = "55 148 53",
    ColorSay = "177 210 187",
    ColorLow = "177 210 187",
    ColorWhisper = "177 210 187",
    ColorYell = "255 51 51",
    FilterChatInput = "$trim(@($eq($streamtype($stream) rp):$stripcolors($input);$input))",
    FilterNickname = "$sub($input 1 50)",
    FilterNarrativeStyle = "@($sneakCallout:$input;$capitalize($input))",
    PredicateEnableStream = "true",
    PredicateAllowChatInput = "$disallowSignedOverRadio($has(@(faction;safehouse) $stream))",
    PredicateAllowLanguage = "$has(@(say;shout;whisper;low;faction;safehouse) $stream)",
    PredicateApplyBuff = "$has(@(me;mequiet;meloud;mewhisper) $stream)",
    PredicateAttractZombies = "$has(@(say;shout;meloud;doloud) $stream)",
    PredicateClearOnDeath = "true",
    PredicateShowTypingIndicator = "",
    PredicateTransmitOverRadio = "$all($not($echo) $neq($customStream ooc))",
    PredicateUseNarrativeStyle = "$has(@(say;shout;whisper;low;faction;safehouse) $stream)",
    PredicateUseNameColor = "$not($has(@(general;faction;safehouse;admin;ooc) $stream))",
    AvailableLanguages = "English;French;Italian;German;Spanish;Danish;Dutch;Hungarian;Norwegian;Polish;Portuguese;Russian;Turkish;Japanese;Mandarin;Finnish;Korean;Thai;Ukrainian;ASL",
    SignedLanguages = "ASL",
    AddLanguageAllowlist = "",
    AddLanguageBlocklist = "",
    LanguageSlots = 1,
    InterpretationRolls = 2,
    InterpretationChance = 25,
    FormatAliases = "@(shout:shout;dolow:doquiet;dolong:doloud;melow:mequiet;melong:meloud)",
    FormatInfo = "",
    FormatName = "@($eq($chatType admin):$username;$if($eq($chatType whisper) $username ( / ))@($name;$forename))",
    FormatTag = "[$tag]$if($eq($chatType server) :<SPACE>)",
    FormatTimestamp = "[$ifelse($eq($hourFormat 12) $h $HH):$mm]",
    FormatMenuName = "$ifelse($neq($menuType mini_scoreboard) $name $username &#32;[ $name ])",
    FormatTyping = "$fmttyping($names $alt)",
    FormatCard = "draws $card.",
    FormatRoll = "rolls $roll on a $sides-sided die.",
    FormatFlip = "flips a coin and gets @($heads:heads;tails).",
    FormatAdminIcon = "Item_Hammer",
    FormatIcon = "@($eq($stream card):Item_CardDeck;$any($buffyRoll $eq($stream roll)):Item_Dice;$has(@(say;shout;whisper;faction;safehouse;ooc;general;low) $stream):@($adminIcon;$icon))",
    FormatLanguage = "$if($all($language $not($unknownLanguage)) [$language])",
    FormatOverheadPrefix = "$concats(( ) $if($languageRaw [$languageRaw]) $index(@(@(low;mequiet;doquiet):[Low];@(meloud;doloud):[Long];@(whisper;mewhisper):[Whisper]) $stream))&#32;",
    FormatChatPrefix = "$if($neq($stream server) $timestamp)$tag$language$index(@(@(low;mequiet;doquiet):[Low];@(meloud;doloud):[Long];@(whisper;mewhisper):$unless($sneakCallout [Whisper])) $stream)$unless($any($echo $not($icon) $has(@(faction;safehouse;admin) $stream)) $icon $if($admin $parens(Admin)))$buffyCrit",
    FormatNarrativeDialogueTag = "@($sneakCallout:whisper shouts;$eq($stream shout):shouts;$eq($stream whisper):whispers;$endswith($input ?):asks;$endswith($input !):exclaims;$endswith($input ..):says;$lt($len($input) 10):states;says)",
    FormatNarrativePunctuation = "$unless($sneakCallout @($eq($stream shout):!;.))",
    OverheadFormatFull = "$prefix$1",
    OverheadFormatDo = "** $capitalize($punctuate($1))",
    OverheadFormatDoLoud = "** $capitalize($punctuate($1))",
    OverheadFormatDoQuiet = "** $capitalize($punctuate($1))",
    OverheadFormatEcho = "(Over Radio) $1",
    OverheadFormatOoc = "(( $1 ))",
    OverheadFormatMe = "** $name $punctuate($1)",
    OverheadFormatMeLoud = "** $name $punctuate($1)",
    OverheadFormatMeQuiet = "** $name $punctuate($1)",
    OverheadFormatMeWhisper = "** $name $punctuate($1)",
    OverheadFormatLow = "$name $1",
    OverheadFormatWhisper = "$name $1",
    OverheadFormatCard = "** $name $1",
    OverheadFormatRoll = "** $name $1",
    OverheadFormatFlip = "** $name $1",
    OverheadFormatOther = "$name $1",
    ChatFormatFull = "$if($prefix $prefix <SPACE>)$content",
    ChatFormatDiscord = "$author: <SPACE> $message",
    ChatFormatIncomingPrivate = "$fmtpmfrom(<SPACE>$name 2): <SPACE> $message",
    ChatFormatOutgoingPrivate = "$fmtpmto(<SPACE>$recipientName 2): <SPACE> $message",
    ChatFormatServer = "$message",
    ChatFormatRadio = "$fmtradio($frequency): <SPACE> $if($all($name $not($has(@(do;doloud;doquiet) $customStream))) $name<SPACE>)$message",
    ChatFormatAdmin = "$name: <SPACE> $message",
    ChatFormatCard = "** <SPACE> $name <SPACE> $punctuate($fmtcard($card))",
    ChatFormatRoll = "** <SPACE> $name <SPACE> $punctuate($fmtroll($roll $sides))",
    ChatFormatFlip = "** <SPACE> $name <SPACE> $punctuate($fmtflip($heads))",
    ChatFormatDo = "** <SPACE> $colorquotes($punctuate($capitalize($message)))",
    ChatFormatDoLoud = "** $colorquotes($punctuate($capitalize($message)))",
    ChatFormatDoQuiet = "** $colorquotes($punctuate($capitalize($message)))",
    ChatFormatGeneral = "$name: <SPACE> (( $message ))",
    ChatFormatOoc = "$name: <SPACE> (( $message ))",
    ChatFormatMe = "** <SPACE> $name <SPACE> $colorquotes($punctuate($message))",
    ChatFormatMeLoud = "** <SPACE> $name <SPACE> $colorquotes($punctuate($message))",
    ChatFormatMeQuiet = "** <SPACE> $name <SPACE> $colorquotes($punctuate($message))",
    ChatFormatMeWhisper = "** <SPACE> $name <SPACE> $colorquotes($punctuate($message))",
    ChatFormatSafehouse = "(Safehouse Radio) <SPACE>$if($icon $icon <SPACE>) $name <SPACE> $coloractions($message)",
    ChatFormatSay = "$name <SPACE> $coloractions($message)",
    ChatFormatFaction = "(Faction Radio) <SPACE>$if($icon $icon <SPACE>) $name <SPACE> $coloractions($message)",
    ChatFormatLow = "$name <SPACE> $coloractions($message mequiet)",
    ChatFormatWhisper = "$name <SPACE> $coloractions($message mequiet)",
    ChatFormatYell = "$name <SPACE> $coloractions($message meloud)",
    ChatFormatEcho = "(Over Radio) <SPACE>$if($icon $icon <SPACE>) $name <SPACE> $coloractions($message mequiet)",
    ChatFormatUnknownLanguage = "**$if($echo $parens(Over Radio)) <SPACE> $getunknownlanguagestring($languageRaw $stream $name<SPACE> $dialogueTag)",
    ChatFormatUnknownLanguageRadio = "$fmtradio($frequency): <SPACE> $getunknownlanguagestring($languageRaw $stream $if($all($name $not($has(@(do;doloud;doquiet) $customStream))) $name<SPACE>) $dialogueTag)",
}

Vanilla

This preset is designed to mimic the vanilla chat. This disables many of the features of the mod, but still allows players to customize their chat colors.

Server operators can use this to start from the vanilla-style chat and turn on only the features that they're interested in.

OmiChat = {
    EnableCustomShouts = false,
    EnableEmotes = false,
    EnableSetNameColor = false,
    EnableSetSpeechColor = false,
    EnableSpeechColorAsDefaultNameColor = false,
    EnableFactionColorAsDefault = false,
    EnableCaseInsensitiveChatStreams = false,
    EnableCharacterCustomization = false,
    EnableAlwaysShowChat = false,
    EnableCleanCharacter = 3,
    EnableSetName = 1,
    EnableDiscordColorOption = 3,
    EnableCompatBuffyCharacterBios = 2,
    EnableCompatBuffyRPGSystem = 2,
    EnableCompatChatBubble = 2,
    EnableCompatSearchPlayers = 2,
    EnableCompatTAD = 2,
    CardItems = "CardDeck",
    CoinItems = "",
    DiceItems = "Dice",
    PatternNarrativeCustomTag = "",
    BuffCooldown = 15,
    BuffReduceBoredom = 0.2,
    BuffReduceUnhappiness = 0.2,
    BuffReduceHunger = 0.1,
    BuffReduceThirst = 0.1,
    BuffReduceFatigue = 0.1,
    BuffReduceCigaretteStress = 0.2,
    MaximumCustomShouts = 10,
    CustomShoutMaxLength = 50,
    MinimumCommandAccessLevel = 16,
    RangeCallout = 60,
    RangeSneakCallout = 6,
    RangeCalloutZombies = 30,
    RangeSneakCalloutZombies = 6,
    RangeMultiplierZombies = 0.0,
    RangeDo = 30,
    RangeDoLoud = 60,
    RangeDoQuiet = 3,
    RangeOoc = 30,
    RangeMe = 30,
    RangeMeLoud = 60,
    RangeMeQuiet = 3,
    RangeMeWhisper = 2,
    RangeSay = 30,
    RangeLow = 5,
    RangeWhisper = 2,
    RangeYell = 60,
    RangeVertical = "32",
    ColorDiscord = "144 137 218",
    ColorRadio = "178 178 178",
    ColorServer = "0 128 255",
    ColorAdmin = "255 255 255",
    ColorGeneral = "255 165 0",
    ColorDo = "130 130 130",
    ColorDoLoud = "255 51 51",
    ColorDoQuiet = "85 48 139",
    ColorFaction = "22 113 20",
    ColorOoc = "48 128 128",
    ColorMe = "130 130 130",
    ColorMeLoud = "255 51 51",
    ColorMeQuiet = "85 48 139",
    ColorMeWhisper = "85 48 139",
    ColorPrivate = "85 26 139",
    ColorSafehouse = "55 148 53",
    ColorSay = "255 255 255",
    ColorLow = "85 48 139",
    ColorWhisper = "85 48 139",
    ColorYell = "255 51 51",
    FilterChatInput = "$trim($input)",
    FilterNickname = "$sub($input 1 50)",
    FilterNarrativeStyle = "@($sneakCallout:$input;$capitalize($input))",
    PredicateEnableStream = "true",
    PredicateAllowChatInput = "true",
    PredicateAllowLanguage = "",
    PredicateApplyBuff = "",
    PredicateAttractZombies = "$has(@(say;shout;meloud;doloud) $stream)",
    PredicateClearOnDeath = "true",
    PredicateShowTypingIndicator = "",
    PredicateTransmitOverRadio = "true",
    PredicateUseNarrativeStyle = "",
    PredicateUseNameColor = "",
    AvailableLanguages = "",
    SignedLanguages = "",
    AddLanguageAllowlist = "",
    AddLanguageBlocklist = "",
    LanguageSlots = 1,
    InterpretationRolls = 0,
    InterpretationChance = 25,
    FormatAliases = "",
    FormatInfo = "",
    FormatName = "$username",
    FormatTag = "[$tag]$if($eq($chatType server) (: <SPACE> ))",
    FormatTimestamp = "[$ifelse($eq($hourFormat 12) $h $HH):$mm]",
    FormatMenuName = "",
    FormatTyping = "$fmttyping($names $alt)",
    FormatCard = "draws $card",
    FormatRoll = "rolls $roll on a $sides-sided die",
    FormatFlip = "flips a coin and gets @($heads:heads;tails)",
    FormatAdminIcon = "Item_Sledgehamer",
    FormatIcon = "@($eq($stream card):Item_CardDeck;$any($buffyRoll $eq($stream roll)):Item_Dice;$has(@(say;shout;whisper;faction;safehouse;ooc;general) $stream):@($adminIcon;$icon))",
    FormatLanguage = "",
    FormatOverheadPrefix = "",
    FormatChatPrefix = "$if($icon $icon <SPACE>)$if($neq($stream server) $timestamp)$tag$language$if($buffyCrit $buffyCrit ( <SPACE>))",
    FormatNarrativeDialogueTag = "@($sneakCallout:hisses;$eq($stream shout):shouts;$eq($stream whisper):whispers;$endswith($input ?):asks;$endswith($input !):exclaims;$endswith($input ..):says;$lt($len($input) 10):states;says)",
    FormatNarrativePunctuation = "$unless($sneakCallout @($eq($stream shout):!;.))",
    OverheadFormatFull = "$prefix$1",
    OverheadFormatDo = "",
    OverheadFormatDoLoud = "",
    OverheadFormatDoQuiet = "",
    OverheadFormatEcho = "(Over Radio) $1",
    OverheadFormatOoc = "(( $1 ))",
    OverheadFormatMe = "<< $1 >>",
    OverheadFormatMeLoud = "<< $1 >>",
    OverheadFormatMeQuiet = "<< $1 >>",
    OverheadFormatMeWhisper = "<< $1 >>",
    OverheadFormatLow = "$1",
    OverheadFormatWhisper = "$1",
    OverheadFormatCard = "<< $1 >>",
    OverheadFormatRoll = "<< $1 >>",
    OverheadFormatFlip = "<< $1 >>",
    OverheadFormatOther = "$1",
    ChatFormatFull = "$prefix$content",
    ChatFormatDiscord = "[$author]: <SPACE> $message",
    ChatFormatIncomingPrivate = "[$name]: <SPACE> $message",
    ChatFormatOutgoingPrivate = "[to $recipientName]: <SPACE> $message",
    ChatFormatServer = "$message",
    ChatFormatRadio = "$fmtradio($frequency): <SPACE> $message",
    ChatFormatAdmin = "[$name]: <SPACE> $message",
    ChatFormatCard = "",
    ChatFormatRoll = "",
    ChatFormatFlip = "",
    ChatFormatDo = "",
    ChatFormatDoLoud = "",
    ChatFormatDoQuiet = "",
    ChatFormatGeneral = "[$name]: <SPACE> $message",
    ChatFormatOoc = "",
    ChatFormatMe = "",
    ChatFormatMeLoud = "",
    ChatFormatMeQuiet = "",
    ChatFormatMeWhisper = "",
    ChatFormatSafehouse = "[$name]: <SPACE> $message",
    ChatFormatSay = "[$name]$unless($buffyRoll :) <SPACE> $message",
    ChatFormatFaction = "[$name]: <SPACE> $message",
    ChatFormatLow = "",
    ChatFormatWhisper = "",
    ChatFormatYell = "[$name]: <SPACE> $message",
    ChatFormatEcho = "",
    ChatFormatUnknownLanguage = "",
    ChatFormatUnknownLanguageRadio = "",
}

Token Contexts

Most sandbox options within the same category have access to the same tokens. This document serves as a reference for the tokens available to different types of options.

Chat

The tokens within this context can be used by all chat format strings, other than processed chats.

• $admin
• $author
• $authorRaw
• $buffyCrit
• $buffyCritRaw
• $buffyRoll
• $callout
• $dialogueTag
• $echo
• $language
• $languageRaw
• $icon
• $iconRaw
• $message
• $name
• $nameRaw
• $unstyled: The original content of a message sent in narrative style.
• $sneakCallout
• $stream

Overhead

The tokens within this context can be used by all overhead format strings.

• $1
• $callout
• $chatType
• $echo
• $input
• $language
• $languageRaw
• $name
• $sneakCallout
• $stream
• $username

Processed Chat

This context contains the tokens that can be used in ChatFormatFull and FormatChatPrefix.

• $admin
• $author
• $authorRaw
• $buffyCrit
• $buffyCritRaw
• $buffyRoll
• $content: The full chat message content, after other formatting has occurred.
• $dialogueTag
• $echo
• $icon
• $iconRaw
• $language: The result of the FormatLanguage option.
• $name
• $nameRaw
• $tag: The result of the FormatTag option.
• $timestamp: The result of the FormatTimestamp option.

Sandbox Options

In order to be as configurable as possible, this mod offers a lot of sandbox options. This section serves as an explanation of these options.

Many of the sandbox options accept format strings. The dollar-sign-prefixed tokens that these format strings accept are listed in their documentation.

• Basic Features: Feature flags and other basic options.
• Compatibility Features: Options to control compatibility with other mods.
• Chat Ranges: Options for distance ranges.
• Filters & Predicates: Logic override options.
• Default Colors: Default colors for chat streams.
• Roleplay Languages: Configuration of roleplay languages.
• Component Formats: Format strings used by other options.
• Overhead Formats: Format strings that control the overhead speech bubbles.
• Chat Formats: Format strings that control the text that appears in chat.

Basic Features

These options are used to control basic features of the mod.
Note: Custom chat streams can be disabled by clearing the contents of their relevant chat format.

BuffCooldown

Default: 15
Minimum: 0
Maximum: 1440

The cooldown for applying buffs, in real-time minutes.

BuffReduceBoredom

Default: 0.2
Minimum: 0.0
Maximum: 1.0

The amount that boredom will be reduced by when a buff is applied.

BuffReduceCigaretteStress

Default: 0.2
Minimum: 0.0
Maximum: 1.0

The amount that stress from lack of smoking will be reduced by when a buff is applied.

BuffReduceFatigue

Default: 0.1
Minimum: 0.0
Maximum: 1.0

The amount that fatigue will be reduced by when a buff is applied.

BuffReduceHunger

Default: 0.1
Minimum: 0.0
Maximum: 1.0

The amount that hunger will be reduced by when a buff is applied.

BuffReduceThirst

Default: 0.1
Minimum: 0.0
Maximum: 1.0

The amount that thirst will be reduced by when a buff is applied.

BuffReduceUnhappiness

Default: 0.2
Minimum: 0.0
Maximum: 1.0

The amount that unhappiness will be reduced by when a buff is applied.

CardItems

Default: CardDeck

A semicolon-separated list of items players can use for the /card command.

The /card command will only be available if the player has one of the items in this list in their inventory. If blank, the command won't require an item.

CoinItems

(blank by default)

A semicolon-separated list of items players can use for the /flip command.

The /flip command will only be available if the player has one of the items in this list in their inventory. If blank, the command won't require an item.

DiceItems

Default: Dice

A semicolon-separated list of items players can use for the /roll command.

The /roll command will only be available if the player has one of the items in this list in their inventory. If blank, the command won't require an item.

CustomShoutMaxLength

Default: 50
Minimum: 1
Maximum: 200

This option is deprecated and will be removed in a future version in favor of a hardcoded value. To apply length limits, use FilterChatInput.

The maximum length for individual custom shouts.

EnableAlwaysShowChat

Default: false

If enabled, players will be unable to close the chat.

EnableCaseInsensitiveChatStreams

Default: true

If enabled, chat streams such as /say will be case-insensitive. This will allow players to use /SAY or /Say for the equivalent effect.

EnableCharacterCustomization

Default: false

If enabled, this includes a set of QoL options in the chat settings that allow players to customize their character. This is intended for roleplay servers.

Customization options available:

• Clean blood & dirt from the character (configurable with EnableCleanCharacter)
• Change hair color
• Grow long hair
• Grow beard

EnableCleanCharacter

Default: 3 - Clean body and clothing

Determines the behavior of the “clean blood & dirt” option. This has no effect unless EnableCharacterCustomization is turned on.

• 1: Disable
• 2: Clean body only
• 3: Clean body and clothing

EnableCustomShouts

Default: true

This allows players to specify a list of custom shouts that are used when pressing the shout key (default Q). Players can configure custom shouts using an option in the chat settings.

EnableDiscordColorOption

Default: 3 - Respect server setting

Determines whether the option to change the color of Discord messages will be included in the chat settings. If this is set to 3, the DiscordEnable server option will be respected.

• 1: Yes
• 2: No
• 3: Respect server setting

EnableEmotes

Default: true

Allows players to use emote shortcuts in the form of .emote. These are enabled only in local chats.

EnableFactionColorAsDefault

Default: false

If enabled, players' faction tag colors will be used as the default color for /faction messages. This takes precedence over the ColorFaction setting.

EnableSetName

Default: 2 - /name sets chat nickname

Determines the behavior of the /name and /nickname chat commands. If /name is configured to set the character's name, the empty command cannot be used to reset it.

• 1: Disallow setting name
• 2: /name sets chat nickname
• 3: /name sets character's forename
• 4: /name sets character's full name
• 5: /name sets character's forename, /nickname sets chat nickname
• 6: /name sets character's full name, /nickname sets chat nickname

EnableSetNameColor

Default: false

Allows players to set their name color using the chat settings menu. Other players will be able to see chat name colors.

EnableSetSpeechColor

Default: true

Allows players to customize the color used for overhead speech bubbles. This affects the existing in-game option within the Multiplayer tab of the settings.

EnableSpeechColorAsDefaultNameColor

Default: true

If enabled, players' overhead speech color will be used as their default name color. This can be used alongside with or independently of EnableSetNameColor.

MaximumCustomShouts

Default: 10
Minimum: 1
Maximum: 20

The maximum number of custom shouts that players are allowed to define.

The maximums apply to regular and sneak shouts separately; a value of 10 means a player can specify 10 shouts and 10 sneak shouts.

This option is deprecated and will be removed in a future version in favor of a hardcoded value.

MinimumCommandAccessLevel

Default: 16

The minimum access level needed to execute admin commands such as /setname.

• Admin: 32
• Moderator: 16
• Overseer: 8
• GM: 4
• Observer: 2
• Player: 1

PatternNarrativeCustomTag

(blank by default)

The option used to determine a pattern for custom dialogue tags in narrative style. If blank, custom tag prefixes will be turned off.

For example, if this option is set to ^~(%l+)%s+(.+) and the other narrative style options are configured, players can input ~inquires What's your name? to get Jane inquires, “What's your name?”.

This option should be a Lua string pattern with two capture groups. If you're unsure about configuring this, start a discussion!

Compatibility Features

These options control compatibility patches for other mods.

All of these features have three possible values:

• 1: Enable the compatibility patch
• 2: Disable the compatibility patch
• 3: Enable the compatibility patch if the mod is enabled

The third option will check for the mod ID before applying the patch.

EnableCompatBuffyCharacterBios

Default: 3 - Enable if mod is enabled

Enables the compatibility patch for buffy's character bios.

This fixes an incompatibility that otherwise causes commands that update forenames to fail. It will also make bio update messages appear as server messages rather than /say messages.

EnableCompatBuffyRPGSystem

Default: 2 - Disable

Enables the compatibility patch for buffy's tabletop RPG system.

This reads messages that look like rolls from the mod and populates tokens accordingly. If this option is enabled, the $buffyRoll, $buffyCrit, and $buffyCritRaw tokens will be populated where appropriate.

EnableCompatChatBubble

Default: 3 - Enable if mod is enabled

Enables the compatibility patch for Chat Bubble v0.6.

This prevents chat bubble messages from showing up in chat when enabling timestamps or tags, by preventing adding them to chat at all. Chat bubbles still function as expected with this option enabled; they just won't affect the chat window.

EnableCompatSearchPlayers

Default: 3 - Enable if mod is enabled

Enables the compatibility patch for Search Players For Weapons.

This modifies the menu option added by the mod to respect FormatMenuName.

EnableCompatTAD

Default: 3 - Enable if mod is enabled

Enables the compatibility patch for True Actions Act 3 - Dancing.

This adds a /dance command that makes the player perform a random dance that they know. It also allows for selecting particular dances by name; a list of available dance names can be found by using /help dance or /dance list.

Chat Ranges

These options define distance maximums for chat messages.

RangeCallout

Default: 60
Minimum: 1
Maximum: 60

The maximum distance for a 'Q' callout to be heard by players.

RangeCalloutZombies

Default: 30
Minimum: 1
Maximum: 60

The maximum distance for a 'Q' callout to attract zombies.

RangeDo

Default: 30
Minimum: 1
Maximum: 30

The maximum distance between players for /do messages to be visible.

RangeDoLoud

Default: 60
Minimum: 1
Maximum: 60

The maximum distance between players for /doloud messages to be visible.

RangeDoQuiet

Default: 3
Minimum: 1
Maximum: 30

The maximum distance between players for /doquiet messages to be visible.

RangeLow

Default: 5
Minimum: 1
Maximum: 30

The maximum distance between players for /low messages to be visible.

RangeMe

Default: 30
Minimum: 1
Maximum: 30

The maximum distance between players for /me messages to be visible.

RangeMeLoud

Default: 60
Minimum: 1
Maximum: 60

The maximum distance between players for /meloud messages to be visible.

RangeMeQuiet

Default: 3
Minimum: 1
Maximum: 30

The maximum distance between players for /mequiet messages to be visible.

RangeMeWhisper

Default: 2
Minimum: 1
Maximum: 30

The maximum distance between players for /mewhisper messages to be visible.

RangeMultiplierZombies

Default: 0.0
Minimum: 0.0
Maximum: 10.0

The multiplier that will be applied to chat ranges to determine the zombie attraction range. If this is set to zero, chat messages (other than callouts) will not attract zombies.

RangeOoc

Default: 30
Minimum: 1
Maximum: 30

The maximum distance between players for /ooc messages to be visible.

RangeSay

Default: 30
Minimum: 1
Maximum: 30

The maximum distance between players for /say messages to be visible.

RangeSneakCallout

Default: 6
Minimum: 1
Maximum: 60

The maximum distance for a 'Q' callout performed while sneaking to be heard by players.

RangeSneakCalloutZombies

Default: 6
Minimum: 1
Maximum: 60

The maximum distance for a 'Q' callout performed while sneaking to attract zombies.

RangeVertical

Default: @($sneakCallout:1;$index(@(@(shout;meloud;doloud):3;@(whisper;low;mequiet;doquiet;mewhisper):1) $stream 2))
Minimum: 1
Maximum: 32

The maximum Y distance between players for chat messages to be visible.

This option can specify a format string to control the range per stream. If a number is not returned, messages will not take vertical range into account.

The default option specifies a range of three floors for loud streams, one floor for quiet streams, and two floors otherwise.

Tokens:

• $callout
• $sneakCallout
• $stream

RangeWhisper

Default: 2
Minimum: 1
Maximum: 30

The maximum distance between players for local /whisper messages to be visible.

This does not apply to the vanilla whisper chat.

RangeYell

Default: 60
Minimum: 1
Maximum: 60

The maximum distance between players for /yell messages to be visible.

Filters & Predicates

These options are used to define logic for mod functionality.

Filters are used to transform input values, whereas predicates are used to determine a yes/no value. For predicates, any value other than the empty string is considered a “yes”.

FilterChatInput

Default: $trim($input)

Filters messages before they're sent on a chat stream. If this returns the empty string, the command won't be sent to the chat stream.

Tokens:

• $callout
• $chatType
• $echo
• $input
• $name
• $sneakCallout
• $stream
• $username

FilterNarrativeStyle

Default: @($sneakCallout:$input;$capitalize($input))

Filters messages sent on a stream with narrative style enabled.

Tokens:

• $callout
• $chatType
• $echo
• $input
• $name
• $sneakCallout
• $stream
• $username

See also:

• FormatNarrativeDialogueTag
• FormatNarrativePunctuation

FilterNickname

Default: $sub($input 1 50)

Filters names set by players with /name or /nickname. The default option will limit names to 50 characters.

If the empty string is returned, or either error token is set, the command will fail.

Tokens:

• $input
• $target: If the name being set is the character name, name. Otherwise, nickname.

See also: EnableSetName.

PredicateAllowChatInput

Default: true

Determines whether chat input is allowed.

If either error token is set, the predicate will be considered a failure.

Tokens:

• $callout
• $chatType
• $echo
• $input
• $language
• $languageRaw
• $name
• $sneakCallout
• $stream
• $username

PredicateAllowLanguage

Default: $has(@(say;shout;whisper;low;faction;safehouse) $stream)

Determines whether roleplay languages can be used for a message.

Tokens:

• $callout
• $chatType
• $echo
• $input
• $name
• $sneakCallout
• $stream
• $username

PredicateApplyBuff

(blank by default)

Determines whether messages sent on a stream will apply buffs to a player. This is a QoL feature intended for roleplay servers.

Tokens:

• $callout
• $chatType
• $input
• $name
• $sneakCallout
• $stream
• $username

See also:

• BuffCooldown
• BuffReduceBoredom
• BuffReduceCigaretteStress
• BuffReduceFatigue
• BuffReduceHunger
• BuffReduceThirst
• BuffReduceUnhappiness

PredicateAttractZombies

Default: $has(@(say;shout;meloud;doloud) $stream)

Determines whether a message on a stream will attract zombies.

Tokens:

• $stream

See also: RangeMultiplierZombies.

PredicateClearOnDeath

Default: true

Determines what information is cleared when a player dies.

For example, if this is set to $neq($field languages), then roleplay languages will not be cleared when a player character dies.

Tokens:

• $field: The field to check. This will be one of icon, languages, or nickname.
• $username: The username of the player being checked.

PredicateEnableStream

Default: true

Determines whether a stream is enabled.

Tokens:

• $stream

PredicateShowTypingIndicator

(blank by default)

Determines whether input will trigger the typing indicator.

For example, to enable typing indicators for ranged streams only, set PredicateShowTypingIndicator to $isRanged.

If FormatMenuName does not resolve for the typing menu type, typing indicators will not display.

Tokens:

• $chatType
• $input
• $isRanged: Populated if the stream is a ranged stream.
• $range: The range of the chat stream. Not included if it's not a ranged stream.
• $stream

See also: FormatTyping.

PredicateTransmitOverRadio

Default: $any($has(@(whisper;low) $customStream) $not($customStream))

Determines whether a message should be transmitted over the radio.

This only controls whether messages that have already been transmitted will be visible. For faction/safehouse echo messages, use ChatFormatEcho.

Tokens:

• $admin
• $author
• $authorRaw
• $callout
• $customStream: The name of the custom stream the original message was sent over, if any. This has the same values as $stream, but will only be populated with custom streams.
• $dialogueTag
• $echo
• $language
• $languageRaw
• $icon
• $iconRaw
• $name
• $nameRaw
• $sneakCallout
• $stream

PredicateUseNameColor

Default: $eq($stream say)

Determines whether name colors are used for a message.

Tokens:

• $author
• $authorRaw
• $chatType
• $name
• $nameRaw
• $stream

See also:

• EnableSetNameColor
• EnableSpeechColorAsDefaultNameColor

PredicateUseNarrativeStyle

(blank by default)

Determines whether the narrative style is used for a message. If narrative style is used, messages will be enclosed in quotes and prefixed with a dialogue tag depending on the stream.

For example, with the default settings and a modified predicate, a message sent with /yell Hey will be transformed to shouts, “Hey!”. Note that the player name is not included; overhead and chat formats should include it as needed. See the buffy preset for examples.

Tokens:

• $callout
• $chatType
• $echo
• $input
• $language
• $languageRaw
• $name
• $sneakCallout
• $stream
• $username

See also:

• FilterNarrativeStyle
• FormatNarrativeDialogueTag
• FormatNarrativePunctuation

Default Colors

These options define the default colors for various chat types. Colors should be in RGB format, space- or comma-delimited.

These colors will be used unless overriden by a player's client-side chat color settings.

ColorAdmin

Default: 255 255 255

The default color used for /admin messages.

See also: ChatFormatAdmin.

ColorDiscord

Default: 144 137 218

The default color used for messages from Discord.

See also: ChatFormatDiscord.

ColorDo

Default: 130 130 130

The default color used for /do messages.

ColorDoLoud

Default: 255 51 51

The default color used for /doloud messages.

ColorDoQuiet

Default: 85 48 139

The default color used for /doquiet messages.

ColorFaction

Default: 22 113 20

The default color used for /faction messages.

See also: ChatFormatFaction.

ColorGeneral

Default: 255 165 0

The default color used for /all messages.

See also: ChatFormatGeneral.

ColorLow

Default: 85 48 139

The default color used for /low messages.

ColorMe

Default: 130 130 130

The default color used for /me messages.

ColorMeLoud

Default: 255 51 51

The default color used for /meloud messages.

ColorMeWhisper

Default: 85 48 139

The default color used for /mewhisper messages.

ColorMeQuiet

Default: 85 48 139

The default color used for /mequiet messages.

ColorOoc

Default: 48 128 128

The default color used for /ooc messages.

ColorPrivate

Default: 85 26 139

The default color used for private messages.

This applies to the vanilla /whisper, which is changed to /pm if local whisper is enabled.

See also:

• ColorWhisper
• ChatFormatIncomingPrivate
• ChatFormatOutgoingPrivate

ColorRadio

Default: 178 178 178

The default color used for radio messages.

See also: ChatFormatRadio.

ColorSafehouse

Default: 22 113 20

The default color used for /safehouse messages.

See also: ChatFormatSafehouse.

ColorSay

Default: 255 255 255

The default color used for /say messages.

See also: ChatFormatSay.

ColorServer

Default: 0 128 255

The default color used for server messages.

See also: ChatFormatServer.

ColorWhisper

Default: 85 48 139

The default color used for local /whisper messages. This does not apply to the vanilla whisper chat.

See also: ColorPrivate.

ColorYell

Default: 255 51 51

The default color used for /yell messages.

See also: ChatFormatYell.

Roleplay Languages

These options are used to configure roleplay languages.

With the default settings, admins must add languages to players manually with the /addlanguage command. To allow players to set additional languages themselves, the LanguageSlots option can be used.

AddLanguageAllowlist

(blank by default)

Semicolon-separated list of languages that should display in the “Add” menu for players whose language slots exceed their current number of known languages. If blank, all available languages will be available for adding.

This is recommended for servers that have a large amount of roleplay languages and allow players to add them, since showing only a subset of languages that can be manually added improves player experience. Admins can still add languages not in this list to players using the /addlanguage.

AddLanguageBlocklist

(blank by default)

Semicolon-separated list of languages that will not display in the “Add” menu for players whose language slots exceed their current number of known languages. If blank, no languages will be excluded unless an allowlist is configured.

AvailableLanguages

Default: English;French;Italian;German;Spanish;Danish;Dutch;Hungarian;Norwegian;Polish;Portuguese;Russian;Turkish;Japanese;Mandarin;Finnish;Korean;Thai;Ukrainian;ASL

The roleplay languages that players can use, separated by semicolons. Up to 1000 languages can be specified. The first language in the list will be treated as the default language player characters speak.

Server operators are encouraged to define translations for custom languages. See the language string customization guide for details and a list of languages for which the mod includes translations.

If there's a language that you believe would make sense to include in the base mod, please create a feature request!

InterpretationChance

Default: 25
Minimum: 0
Maximum: 100

The chance for each interpretation roll to succeed. This is used by the $getunknownlanguagestring function.

InterpretationRolls

Default: 2
Minimum: 0
Maximum: 100

The number of rolls to attempt to reveal a word in a message sent with a language the player doesn't understand. This is used by the $getunknownlanguagestring function.

LanguageSlots

Default: 1
Minimum: 1
Maximum: 50

The number of language slots players have by default.

Every player character will know the default language (the first language listed in AvailableLanguages) by default. The language selection option will only display if the player can add or select a language.

With only one language slot (the default), players will not have the option to add a language. In this case, admins can add languages to a player with /addlanguage or set a player's available language slots with /setlanguageslots.

SignedLanguages

Default: ASL

The languages in AvailableLanguages that should be treated as signed languages, separated by semicolons. If a value is included here that is not in AvailableLanguages, it will be ignored.

Component Formats

These options define string formats used in other format strings, or for purposes other than speech bubbles and chat messages.

FormatAliases

Default: @(shout:shout;quiet:low)

Specifies aliases for streams, in the form alias:stream. These will be usable in chat as /alias and will behave equivalently to the regular command. The normal command will also still be available.

This must return an at-map, or it will be ignored.

FormatAdminIcon

Default: Item_Sledgehamer [sic]

The format used to determine the value of $adminIcon in the FormatIcon format. This format expects a valid texture name. /iconinfo command can be used to determine an icon name for this format.

Tokens:

• $username

FormatCard

Default: draws $card

The format used for local /card overhead message content.

Tokens:

• $card: The card that was drawn, in English.
• $number: The number of the card, from 1 to 13. 1 is ace, 11 is jack, 12 is queen, and 13 is king.
• $suit: The suit of the card, from 1 to 4. 1 is clubs, 2 is diamonds, 3 is hearts, and 4 is spades.

FormatChatPrefix

Default: $if($icon $icon <SPACE>)$if($neq($stream server) $timestamp)$tag$language$if($buffyCrit $buffyCrit ( <SPACE>))
Token Context: Processed Chat

The format used to determine the value of the $prefix token in ChatFormatFull.

FormatFlip

Default: flips a coin and gets @($heads:heads;tails)

The format used for local /roll overhead message content.

Tokens:

• $heads: Populated if the result of the coin flip was heads.

FormatIcon

Default: @($eq($stream card):Item_CardDeck;$any($buffyRoll $eq($stream roll)):Item_Dice;$has(@(say;shout;whisper;faction;safehouse;ooc;general) $stream):@($adminIcon;$icon))

The format used to determine the value of $icon in other formats.

Tokens:

• $adminIcon: The icon determined by FormatAdminIcon. This is only populated when the player is an admin with the relevant option enabled.
• $buffyRoll
• $chatType
• $icon: The icon associated with the message, or set with /seticon.
• $stream

FormatInfo

(blank by default)

Information that can be accessed by clicking an info button on the chat. If blank, the info button will not be visible.

Tokens:

• $forename
• $name
• $surname
• $username

FormatLanguage

Default: $if($all($language $not($unknownLanguage)) [$language]( <SPACE> ))

The format used for displaying the roleplay language in which a message was sent. The default format will display as [Language].

This controls the value of $language in ChatFormatFull.

Tokens:

• $chatType
• $language
• $languageRaw
• $stream
• $unknownLanguage

FormatMenuName

Default: $ifelse($neq($menuType mini_scoreboard) $name $username  [ $name ])

The format used for displaying character names within in-game menus such as the trading window, medical check, and the admin mini-scoreboard. If blank, menus will not be affected.

Tokens:

• $forename
• $name: The character name without name colors applied.
• $surname
• $username
• $menuType: The type of menu in which the name will appear. One of:
  • medical
  • mini_scoreboard
  • search_player (see EnableCompatSearchPlayers)
  • trade
  • typing (see PredicateShowTypingIndicator)

FormatName

Default: $ifelse($has(@(general;admin;whisper) $chatType) $username @($name;$forename))

The format used to determine the values of $name and $nameRaw in other format strings.

Tokens:

• $chatType
• $forename
• $name: The name that was set with /name, if specified.
• $surname
• $username

FormatNarrativeDialogueTag

Default: @($eq($stream shout):shouts;$eq($stream whisper):whispers;$endswith($input ?):asks;$endswith($input !):exclaims;$endswith($input ..):says;$lt($len($input) 10):states;says)

The format used to determine the dialogue tag used in narrative style.

Tokens:

• $callout
• $chatType
• $input
• $name
• $sneakCallout
• $stream
• $username

FormatNarrativePunctuation

Default: $unless($sneakCallout @($eq($stream shout):!;.))

The format used to determine the punctuation used in narrative style if the input doesn't end with punctuation.

Tokens:

• $callout
• $chatType
• $dialogueTag
• $input
• $name
• $sneakCallout
• $stream
• $username

FormatTyping

Default: $fmttyping($names $alt)

The format used to determine the text used for typing indicators.

Tokens:

• $alt: Populated when requesting an alternative, shorter string. This is used when the content of the regular string was too long to fit the chat box.
• $names: An at-map containing the names of the people typing. Not populated when requesting an alternative string.

FormatOverheadPrefix

Default: $concats(( ) $index(@(low:[Low];whisper:[Whisper]) $stream) $if($languageRaw [$languageRaw])) 

The format used to determine the value of the $prefix token in OverheadFormatFull.

Tokens::

• $callout
• $chatType
• $input
• $language
• $languageRaw
• $name
• $sneakCallout
• $stream
• $username

FormatRoll

Default: rolls $roll on a $sides-sided die

The format used for local /roll overhead message content.

Tokens:

• $roll: The number that was rolled.
• $sides: The number of sides on the die that was rolled.

FormatTag

Default: [$tag]

The format used when Enable tags is selected in the chat settings menu. This describes the chat title that displays to the left of messages (e.g., [Local]).

Tokens:

• $chatType
• $stream
• $tag: The title of the chat type associated with the message.

FormatTimestamp

Default: [$ifelse($eq($hourFormat 12) $h $HH):$mm]

The format used when Enable timestamps is selected in the chat settings menu.

Tokens:

• $ampm: am or pm, based on the hour a message was sent.
• $AMPM: AM or PM, based on the hour a message was sent.
• $chatType
• $H: The hour the message was sent, in 24-hour format.
• $HH: The zero-padded hour the message was sent, in 24-hour format.
• $h: The hour the message was sent, in 12-hour format.
• $hh: The zero-padded hour the message was sent, in 12-hour format.
• $m: The minute the message was sent.
• $mm: The zero-padded minute the message was sent.
• $P: The hour the message was sent, in the hour format the player prefers.
• $PP: The zero-padded hour the message was sent, in the hour format the player prefers.
• $hourFormat: 12 if the user prefers 12-hour clock formats; otherwise, 24.
• $s: The second the message was sent.
• $ss: The zero-padded second the message was sent.
• $stream

Overhead Formats

These options control the content that displays in speech bubbles that appear over a character's head. In all of these formats, the $1 token must be included.

These formats can have an effect on chat formats. The original text will try to be extracted where possible, but modification of characters in these format will be reflected. For example, reversing the overhead text will result in the message content being reversed in chat.

OverheadFormatCard

Default: << $1 >>
Token Context: Overhead

The overhead format used for local /card messages. If blank, /card messages will not display overhead.

OverheadFormatDo

(blank by default)
Token Context: Overhead

Defines the format used for overhead speech bubbles of /do messages. If blank, /do messages will not display overhead.

OverheadFormatDoLoud

(blank by default)
Token Context: Overhead

Defines the format used for overhead speech bubbles of /doloud messages. If blank, /doloud messages will not display overhead.

OverheadFormatDoQuiet

(blank by default)
Token Context: Overhead

Defines the format used for overhead speech bubbles of /doquiet messages. If blank, /doquiet messages will not display overhead.

OverheadFormatEcho

Default: (Over Radio) $1
Token Context: Overhead

Defines the format used for overhead speech bubbles of echoed messages sent on the /faction or /safehouse streams.

OverheadFormatFlip

Default: << $1 >>
Token Context: Overhead

The overhead format used for local /flip messages. If blank, /flip messages will not display overhead.

OverheadFormatFull

Default: $prefix$1
Token Context: Overhead

The format used for the final overhead message, after all other formats have been applied.

Tokens:

• All tokens in overhead context.
• $prefix: The prefix determined by the FormatOverheadPrefix option.

OverheadFormatLow

Default: $1
Token Context: Overhead

Defines the format used for overhead speech bubbles of /low messages. If blank, /low messages will not display overhead.

OverheadFormatMe

Default: << $1 >>
Token Context: Overhead

Defines the format used for overhead speech bubbles of /me messages. If blank, /me messages will not display overhead.

OverheadFormatMeLoud

Default: << $1 >>
Token Context: Overhead

Defines the format used for overhead speech bubbles of /meloud messages. If blank, /meloud messages will not display overhead.

OverheadFormatMeQuiet

Default: << $1 >>
Token Context: Overhead

Defines the format used for overhead speech bubbles of /mequiet messages. If blank, /mequiet messages will not display overhead.

OverheadFormatMeWhisper

Default: << $1 >>
Token Context: Overhead

Defines the format used for overhead speech bubbles of /mewhisper messages. If blank, /mewhisper messages will not display overhead.

OverheadFormatOoc

Default: (( $1 ))
Token Context: Overhead

Defines the format used for overhead speech bubbles of /ooc messages. If blank, /ooc messages will not display overhead.

OverheadFormatOther

Default: $1
Token Context: Overhead

Defines the format used for overhead speech bubbles of messages not covered by other options.

OverheadFormatRoll

Default: << $1 >>
Token Context: Overhead

The overhead format used for local /roll messages. If blank, /roll messages will not display overhead.

OverheadFormatWhisper

Default: $1
Token Context: Overhead

Defines the format used for overhead speech bubbles of local /whisper messages. If blank, /whisper messages will not display overhead.

This does not apply to the vanilla whisper chat.

Chat Formats

These options determine the content that displays for chat messages.

ChatFormatAdmin

Default: $name: <SPACE> $message
Token Context: Chat

The format used for /admin messages in chat.

See also: ColorAdmin.

ChatFormatCard

Default: $fmtrp(<SPACE> $name <SPACE> $punctuate($fmtcard($card)) <SPACE>)
Token Context: Chat

The format used for local /card messages in chat. This respects the range and color options of /me.

If blank, /card messages will be global instead of local and related options will be ignored.

Tokens:

• All tokens in chat context.
• $card: The translated name of the card that was drawn.

See also:

• OverheadFormatCard
• ColorMe
• RangeMe

ChatFormatDiscord

Default: $author: <SPACE> $message
Token Context: Chat

The format used for messages from Discord in chat. Messages from Discord will not apply name colors.

See also: ColorDiscord.

ChatFormatDo

Default: $fmtrp(<SPACE> $punctuate($capitalize($trim($message))) <SPACE>)
Token Context: Chat

The format used for /do messages in chat. If blank, /do messages will be disabled.

Allows players to use /do to narrate events. With the default setting, /do the lights flicker will appear in chat as « The lights flicker. ».

See also:

• ColorDo
• RangeDo
• OverheadFormatDo
• ChatFormatMe

ChatFormatDoLoud

Default: $fmtrp(<SPACE> $punctuate($capitalize($trim($message))) <SPACE>)
Token Context: Chat

The format used for /doloud (/dl) messages in chat. If blank, /doloud messages will be disabled.

/doloud behaves similarly to /do, but has a larger range.

See also:

• ColorDoLoud
• RangeDoLoud
• OverheadFormatDoLoud

ChatFormatDoQuiet

Default: $fmtrp(<SPACE> $punctuate($capitalize($trim($message))) <SPACE>)
Token Context: Chat

The format used for /doquiet (/dq) messages in chat. If blank, /doquiet messages will be disabled.

/doquiet behaves similarly to /do, but has a smaller range.

See also:

• ColorDoQuiet
• RangeDoQuiet
• OverheadFormatDoQuiet

ChatFormatEcho

(blank by default)
Token Context: Chat

The format used for /safehouse and /faction messages echoed onto the /say or /low stream. If blank, echoing will not occur.

See also: OverheadFormatEcho

ChatFormatFaction

Default: $name: <SPACE> $message
Token Context: Chat

The format used for /faction messages in chat.

See also: ColorFaction.

ChatFormatFlip

Default: $fmtrp(<SPACE> $name <SPACE> $punctuate($fmtflip($heads)) <SPACE>)
Token Context: Chat

The format used for local /flip messages in chat. This respects the range and color options of /me.

If blank, /flip messages will be global instead of local and related options will be ignored.

Tokens:

• All tokens in chat context.
• $heads: Populated if the result of the flip was heads.

ChatFormatFull

Default: $prefix$content
Token Context: Processed Chat

The format used for the final chat message, after all other formats have been applied.

Tokens:

• All tokens in processed chat context.
• $prefix: The prefix determined by the FormatChatPrefix option.

ChatFormatGeneral

Default: $name: <SPACE> $message
Token Context: Chat

The format used for /all messages in chat.

See also: ColorGeneral.

ChatFormatIncomingPrivate

Default: $fmtpmfrom($name 1): <SPACE> $message
Token Context: Chat

The format used for incoming private messages in chat.

See also:

• ColorPrivate
• ChatFormatOutgoingPrivate

ChatFormatLow

Default: $name: <SPACE> $message
Token Context: Chat

The format used for /low messages in chat.

See also:

• ColorLow
• RangeLow
• OverheadFormatLow

ChatFormatMe

Default: $fmtrp(<SPACE> $name <SPACE> $punctuate($trimright($message)) <SPACE>)
Token Context: Chat

The format used for /me messages in chat. If blank, /me messages will be disabled.

/me messages allow players to describe their actions. With the default settings, if a player with a character named “Jane” uses /me smiles it will appear in chat as « Jane smiles. ».

See also:

• ColorMe
• RangeMe
• OverheadFormatMe
• ChatFormatDo

ChatFormatMeLoud

Default: $fmtrp(<SPACE> $name <SPACE> $punctuate($trimright($message)) <SPACE>)
Token Context: Chat

The format used for /meloud (/ml) messages in chat. If blank, /meloud messages will be disabled.

/meloud behaves similarly to /me, but has a larger range.

See also:

• ColorMeLoud
• RangeMeLoud
• OverheadFormatMeLoud

ChatFormatMeQuiet

Default: $fmtrp(<SPACE> $name <SPACE> $punctuate($trimright($message)) <SPACE>)
Token Context: Chat

The format used for /mequiet (/mq) messages in chat. If blank, /mequiet messages will be disabled.

/mequiet behaves similarly to /me, but has a smaller range.

See also:

• ColorMeQuiet
• RangeMeQuiet
• OverheadFormatMeQuiet

ChatFormatMeWhisper

(blank by default)
Token Context: Chat

The format used for /mewhisper (/mw) messages in chat. If blank, /mewhisper messages will be disabled.

/mewhisper behaves similarly to /me, but has a smaller range.

ChatFormatOoc

Default: $name: <SPACE> (( $message ))
Token Context: Chat

The format used for /ooc (local out-of-character) messages in chat.

See also:

• ColorOoc
• RangeOoc
• OverheadFormatOoc

ChatFormatOutgoingPrivate

Default: $fmtpmto($recipientName 1): <SPACE> $message
Token Context: Chat

The format used for outgoing private messages in chat.

Tokens:

• All tokens in chat context.
• $recipient: The username of the recipient of the message.
• $recipientRaw: The username of the recipient, without name colors.
• $recipientName: The chat name of the recipient of the message, as determined by FormatName.
• $recipientNameRaw: The chat name of the recipient, without name colors.

See also:

• ColorPrivate
• ChatFormatIncomingPrivate

ChatFormatRadio

Default: $fmtradio($frequency): <SPACE> $message
Token Context: Chat

The format used for radio messages in chat.

Tokens:

• All tokens in chat context.
• $customStream: The name of the custom stream the original message was sent over, if any. This has the same values as $stream, but will only be populated with custom streams.
• $frequency

See also: ColorRadio.

ChatFormatRoll

Default: $fmtrp(<SPACE> $name <SPACE> $punctuate($fmtroll($roll $sides)) <SPACE>)
Token Context: Chat

The format used for local /roll messages in chat. This respects the range and color options of /me.

If blank, /roll messages will be global instead of local and related options will be ignored.

Tokens:

• All tokens in chat context.
• $roll: The number that was rolled.
• $sides: The number of sides on the die that was rolled.

See also:

• OverheadFormatRoll
• ColorMe
• RangeMe

ChatFormatSafehouse

Default: $name: <SPACE> $message
Token Context: Chat

The format used for /safehouse messages in chat.

See also: ColorSafehouse.

ChatFormatSay

Default: $name$unless($buffyRoll :) <SPACE> $message
Token Context: Chat

The format used for /say messages in chat.

See also: ColorSay.

ChatFormatServer

Default: $message
Token Context: Chat

The format used for server messages in chat.

See also: ColorServer.

ChatFormatUnknownLanguage

Default: $fmtrp(<SPACE> $name <SPACE> $getunknownlanguagestring($languageRaw $stream) <SPACE>)
Token Context: Chat

The format used when a player character does not speak the language of a chat message.

With the default format, this will display as « Name says/shouts/whispers/signs something in Language. ».

ChatFormatUnknownLanguageRadio

Default: $fmtradio($frequency): $fmtrp($getunknownlanguagestring($languageRaw $stream))
Token Context: Chat

The format used when a player character does not speak the language of a chat message sent over the radio.

With the default format, this will display as Radio (100.0 MHz): « Something is said in Language. ».

Tokens:

• All tokens in chat context.
• $customStream: The name of the custom stream the original message was sent over, if any. This has the same values as $stream, but will only be populated with custom streams.
• $frequency

ChatFormatWhisper

Default: $name: <SPACE> $message
Token Context: Chat

The format used for local /whisper messages in chat.

If populated, the vanilla /whisper is changed to /pm, and /whisper is modified to act as local chat with a very short range. If blank, local whisper will be disabled and the vanilla /whisper will not be renamed.

See also:

• ColorWhisper
• RangeWhisper
• OverheadFormatWhisper

ChatFormatYell

Default: $name: <SPACE> $message
Token Context: Chat

The format used for /yell messages in chat.

See also: ColorYell.

Format Strings

Various sandbox options use a format string style designed to be flexible enough to satisfy most needs. These format strings can utilize a number of features, which are outlined in this section of the reference guide.

• Tokens: placeholders for values that will be replaced when the format string is used.
• Functions: used to include logic in format strings.
• At-Maps: multimaps which can be used for lists and logic branches.
• Escapes & References: escapes and references for special characters.

Tokens

The format strings that some sandbox options accept can include tokens, which are replaced with a relevant value when they're used. These are specified with a dollar sign followed by the name of the token. Unlike functions, tokens are case-sensitive; $author is not the same as $Author.

Tokens that are used by multiple sandbox options are documented below. Some tokens may take on different meanings in certain options; the documentation of an option will indicate if that is the case.

Error Tokens

The tokens $error and $errorID can be set in some format strings to display feedback to players. When set, the operation associated with the filter or predicate will be considered a failure. If errorID is used, it will be interpreted as a string ID, whereas error will be displayed as given.

$1

The $1 token is frequently used for the content wrapped in invisible special characters.

This is a special token; when it is used by a format string, it must be included. If it isn't, the format string will behave as if only $1 had been specified.

The invisible characters included in this token are used to encode information for mod functionality.

$admin

Only available in chat formats. Populated if the author of a message is an admin with the chat icon option enabled.

$author

The author of a message (usually a username). This may include the name color, if one is included.

$authorRaw

The same as $author, but does not include name colors.

$buffyCrit

If the EnableCompatBuffyRPGSystem option is enabled and the message is a critical roll, this will be formatted text to display the [CRITICAL SUCCESS/FAILURE!] text in green or red.

$buffyCritRaw

If the EnableCompatBuffyRPGSystem option is enabled, this will be populated with either success or failure for critical rolls.

$buffyRoll

If the EnableCompatBuffyRPGSystem option is enabled, this will be populated with the roll text (e.g., “rolled X: 5+1=6”) for roll messages.

$callout

Defined if the relevant message was a 'Q' callout. Unlike $sneakCallout, this is defined for both sneak callouts and regular callouts.

$chatType

The type of the chat in which a message was sent.

The value of this token will be one of:

• general
• whisper (refers to private messages, rather than local whispers)
• say
• shout
• faction
• safehouse
• radio
• admin
• server

$dialogueTag

The dialogue tag used for a message with narrative style applied.

$echo

Populated if this is an echo message.

Since echo messages will only be sent over /say or /low, this is relevant only to those streams and the “full” formats.

$forename

The relevant player character's forename.

$frequency

The radio frequency a message was sent on.

$icon

The <IMAGE> tag for the chat icon of a message, with a leading and trailing space.

$iconRaw

The name of the icon used for $icon.

$input

The input that was sent to a chat or command stream.

This is available for overhead formats, but should not be used in place of $1 in the final result. The invisible characters included in $1 are necessary for correctly interpreting messages.

$language

The translated roleplay language that a message was sent in. This will not be defined if the message was sent in the default language.

$languageRaw

The untranslated roleplay language that a message was sent in. This will not be defined if the message was sent in the default language.

$message

The content of a message.

$name

The chat name of the relevant player. This may include the name color, if one is included. Determined by the format specified by FormatName.

$nameRaw

The same as $name, but does not include name colors.

$sneakCallout

Like $callout, but defined only when the message was sent from a sneak callout.

$stream

The chat stream to which a message was or will be sent.

This can be extended by other mods. In the base mod, however, this will be one of:

• general
• private (vanilla whisper)
• say
• shout
• faction
• safehouse
• radio
• admin
• server
• discord
• ooc
• whisper (local whisper)
• do
• doloud
• doquiet
• me
• meloud
• mequiet
• mewhisper
• card
• roll

$surname

The relevant player character's forename.

$unknownLanguage

Equivalent to $language, but only populated if the language is not known by the player.

$username

The relevant player's username.

Functions

Advanced users have access to various format string functions. These are specified using a dollar sign before the function name and a set of parentheses to enclose arguments (e.g., $pi()). If invalid inputs are given, the convention of these functions is to return the empty string.

Functions can accept an arbitrary number of arguments, which are delimited by spaces. These arguments may be tokens, text, or the results of other functions. Unlike tokens, functions are case-insensitive.

If a function returns multiple values, it will return them as an at-map. Individual return values can be accessed using the $nthvalue(o n) function.

To include a literal space or multiple words in a single argument, text within functions can be enclosed within parentheses. Escapes will still function within parentheses, but they are only necessary to escape ).

$set(_token (hello world))$_token → hello world
$reverse( ($)$() ) → ()
$len(($@-sign)) → 6

Other mods can extend the list of available functions using the API.

$set(token ...)

This is a special function that can set the value of a token. It sets the value of the token with the name token to $concat(...) and returns the empty string.

This can be used to redefine existing tokens, or to define entirely new tokens within the string. To avoid collisions with tokens that may be added in the future, however, custom tokens require an underscore prefix.

$set(_value 2)$_value frog$if($gt($_value 1) s) → 2 frogs

String Functions

$byte(s i j)

Returns a list of character codes in s, from indices i (default 1) to j (default i).

$capitalize(s)

Converts the first character in s to its uppercase counterpart. If s is wrapped in invisible encoding characters (128–159 or 65535), this will capitalize the first visible character.

$char(...)

Returns a string made up of the characters with the integer character codes passed as arguments.

$concat(...)

Combines provided arguments into one string.

$concats(separator ...)

Combines provided arguments into one string, using separator as a separator.

$contains(this other)

Returns true if this contains other. Otherwise, returns the empty string.

$endswith(this other)

Returns true if this ends with other. Otherwise, returns the empty string.

$escaperichtext(...)

Escapes the input for use in rich text.

$first(s)

Returns the first character of a given string.

$gsub(s pattern repl n)

Replaces the first n copies of the pattern pattern in s with repl. Returns the result string, the number of matches that occurred, and any match groups that were captured. This behaves similarly to its Lua counterpart.

$index(s i default)

Returns the character at index i in s, or default if there is no such index.

$internal(s)

Returns the visible part of text wrapped in invisible encoding characters (128–159 or 65535), the invisible prefix, and the invisible suffix.

$last(s)

Returns the last character of a given string.

$len(s)

Returns the length of s.

$lower(s)

Converts given arguments into a lowercase string.

$match(s pattern init)

Looks for a match of pattern in s starting from init. Returns any captures from the pattern, or the entire match if none are specified. This behaves similarly to its Lua counterpart.

$punctuate(s punctuation chars)

Adds punctuation to the end of s if it isn't present. If s is wrapped in invisible encoding characters (128–159 or 65535), the last visible character will be considered the end.

If punctuation is provided, it will be used as the punctuation (default: .).

If chars is provided, the set of characters considered to be punctuation will be limited to the characters in this string. By default, the Lua pattern %p is used.

$punctuate(hi) → hi.
$punctuate(hello !) → hello!

$parens(...)

Returns the input wrapped in parentheses.

$rep(s n)

Returns a string made up of n concatenated copies of s.

Use with caution; large strings can take up a lot of memory.

$reverse(s)

Reverses a given string.

$startswith(this other)

Returns true if this starts with other. Otherwise, returns the empty string.

$str(s)

Converts given arguments into a single string.

$stripcolors(s)

Removes chat colors defined with <RGB> from the given string.

$sub(s i j)

Returns a substring of s from i (default 1) to j (default #s).

$trim(s)

Trims the beginning and end of a given string.

$trimleft(s)

Trims the beginning of a given string.

$trimright(s)

Trims the end of a given string.

$upper(s)

Converts given arguments into an uppercase string.

Boolean Functions

$all(...)

Returns the last argument if all provided arguments are not the empty string. Otherwise, returns the empty string.

$any(...)

Returns the first provided argument that's not the empty string, or the empty string if there are none.

$eq(this other)

Returns true if this is equivalent to other. Otherwise, returns the empty string.

$gt(this other)

Returns true if this is greater than other. Otherwise, returns the empty string. If both arguments are numbers, they will be compared numerically.

$gte(this other)

Returns true if this is greater than or equal to other. Otherwise, returns the empty string. If both arguments are numbers, they will be compared numerically.

$if(condition ...)

Returns $concat(...) if condition is anything other than the empty string.

$ifelse(condition yes ...)

Returns yes if condition is anything other than the empty string. Otherwise, returns $concat(...).

$lt(this other)

Returns true if this is less than other. Otherwise, returns the empty string. If both arguments are numbers, they will be compared numerically.

$lte(this other)

Returns true if this is less than or equal to other. Otherwise, returns the empty string. If both arguments are numbers, they will be compared numerically.

$neq(this other)

Returns true if this is not equivalent to other. Otherwise, returns the empty string.

$not(value)

Returns true if value is the empty string. Otherwise, returns the empty string.

$unless(condition ...)

Returns $concat(...) if condition is the empty string.

Math Functions

The majority of these functions map directly to their Lua counterparts.

$abs(x)

Returns the absolute value of x.

$acos(x)

Returns the arc cosine of x (in radians).

$add(x y)

Returns x + y.

$asin(x)

Returns the arc sine of x (in radians).

$atan(x)

Returns the arc tangent of x (in radians).

$atan2(y x)

Returns the arc tangent of y / x (in radians), but uses the signs of both parameters to find the quadrant of the result.

$ceil(x)

Returns the smallest integer larger than or equal to x.

$cos(x)

Returns the cosine of x (assumed to be in radians).

$cosh(x)

Returns the hyperbolic cosine of x.

$deg(x)

Returns the angle x (given in radians) in degrees.

$div(x y)

Returns x / y.

$exp(x)

Returns the value e^x.

$floor(x)

Returns the largest integer smaller than or equal to x.

$fmod(x y)

Returns the remainder of the division of x by y that rounds the quotient towards zero.

$frexp(x)

Returns m and e such that x = m2^e, e is an integer, and the absolute value of m is in the range [0.5, 1) (or zero when x is zero).

$int(x)

Returns the value of x converted to an integer.

$isnan(x)

Returns true if the string value of x is equivalent to the string value of NaN.

$ldexp(m e)

Returns m2^e (e should be an integer).

$log(x)

Returns the natural logarithm of x.

$log10(x)

Returns the base-10 logarithm of x.

$max(...)

Returns the maximum among its arguments. If all arguments are numeric, they are compared as numbers. Otherwise, they're compared as strings.

$min(...)

Returns the minimum among its arguments. If all arguments are numeric, they are compared as numbers. Otherwise, they're compared as strings.

$mod(x y)

Returns x % y.

$modf(x)

Returns two numbers, the integral part of x and the fractional part of x.

$mul(x y)

Returns x * y.

$num(x)

Returns the value of x converted to a number.

$pi()

Returns an approximate value of pi.

$pow(x y)

Returns x ^ y.

$rad(x)

Returns the angle x (given in degrees) in radians.

$sin(x)

Returns the sine of x (assumed to be in radians).

$sinh(x)

Returns the hyperbolic sine of x.

$subtract(x y)

Returns x - y.

$sqrt(x)

Returns the square root of x.

$tan(x)

Returns the tangent of x.

$tanh(x)

Returns the hyperbolic tangent of x.

At-Map Functions

These functions are related to working with at-maps.

$concat(o)

Concatenates the values in the at-map.

$concats(separator o)

Concatenates the values in the at-map, using separator as a separator.

$first(o)

Returns the value of the first entry in the at-map o.

$get(o key default)

Returns the first value associated with key, or default if there are none.

$has(o key)

Returns true if the at-map contains the key key. Otherwise, returns the empty string.

$index(s key default)

Returns a list of entries associated with key, or default if there are none.

$last(o)

Returns the value of the last entry in the at-map o.

$len(o)

Returns the number of entries in the at-map.

$list(...)

Creates an at-map with keys from 1 to N, where N is the number of provided arguments. If a single argument is provided and it is an at-map, its values will be used. Otherwise, the list is made up of all provided arguments.

$map(funcName o ...)

Maps elements of the at-map o onto the function funcName. Additional arguments will be passed to the map function as extra arguments.

$concat($map(upper @(a;b;c))) → ABC

$nthvalue(o n)

Returns the value of the nth entry in the at-map o.

$unique(o)

Returns an at-map with only the unique values in the at-map o.

Random Functions

These functions are related to generating pseudo-random values.

Note: Predicates (other than PredicateUseNameColor), filters, FormatCard, FormatRoll, and all overhead chat formats are seeded with a constant value. To get pseudo-random values for these, use $randomseed first.

$choose(...)

Selects and returns one of the inputs at random. If given a single at-map, returns one of its values.

$random(m n)

Returns a pseudo-random number in [m, n]. If n is excluded, returns a number up to m. If both are excluded, returns a random float number.

$randomseed(seed)

Seeds the randomizer with the given value.

Other Functions

$accesslevel()

Returns the access level of player 1, as a string.

$coloractions(s category includeAsterisk)

Wraps actions within s in the color category specified, or the me color if none is given. Actions are delimited by quote followed by an asterisk. If includeAsterisk is specified, the asterisk will be visible in the final string.

$colorquotes(s category)

Wraps quoted text within s in the color category specified, or the say color if none is given.

$cooldown(n key suppressError)

Checks and sets a cooldown associated with key. n is the number of seconds in the cooldown.

If the cooldown period has ended, returns true. Otherwise, returns the empty string.

Unless suppressError is passed, this also sets the error token to a message informing the player of the cooldown.

$cooldownset(key n)

Sets the value of the cooldown associated with key to n seconds from now.

$cooldownif(condition n key suppressError)

The same as $cooldown(...), but only if condition is truthy.

$cooldownunless(condition n key suppressError)

The same as $cooldown(...), but only if condition is falsy.

$cooldownremaining(key)

Returns the number of seconds remaining on a cooldown, or the empty string if there's no such cooldown.

$disallowsignedoverradio(condition suppressError)

Returns the empty string if condition is truthy and the message language is signed. Otherwise, returns true.

Unless suppressError is passed, this also sets the error token to a message that will inform the player that they cannot use a signed language over the radio.

$fragmented(text)

Gets random fragments of the words in a string, replacing other words with ellipses.

$fmtcard(...)

Returns the input formatted with the default formatting for /card.

$fmtflip(heads)

Returns the input formatted with the default formatting for /flip. If heads is the empty string, it's treated as a tails flip.

$fmtradio(frequency)

Returns the default formatting for a radio message prefix.

$fmtroll(roll sides)

Returns the input formatted with the default formatting for /roll.

$fmtrp(...)

Returns the default formatting for an RP emote.

$fmtpmfrom(name parenCount)

Returns the default formatting for an incoming PM prefix. parenCount specifies the number of parentheses to use for wrapping.

$fmtpmto(name parenCount)

Returns the default formatting for an outgoing PM prefix. parenCount specifies the number of parentheses to use for wrapping.

$gettext(s ...)

Returns a translation. The first argument must be the translation name. Subsequent arguments may be translation substitutions.

Due to a limitation of the underlying function, only up to 4 additional substitution arguments are allowed. Arguments beyond this limit will be ignored.

$gettextornull(s ...)

Behaves similarly to $gettext(), but returns the empty string for unknown translations instead of the translation name.

Due to a limitation of the underlying function, only up to 4 additional substitution arguments are allowed. Arguments beyond this limit will be ignored.

$getunknownlanguagestring(language stream author dialogueTag noQuoteColor)

Returns a string to use when the recipient of a message doesn't know the language used. author and dialogueTag are optional; if supplied, they apply a narrative style to the result.

If noQuoteColor is supplied, quotes in interpreted text won't use the /say color.

$isadmin()

Returns true if the current player is an admin.

$iscoophost()

Returns true if the current player is the coop host.

$issigned(language)

Returns true if language is configured as a signed language.

$streamtype(stream)

Returns 'chat', 'rp', or 'other' based on the type of the given stream. If the stream is unknown, returns the empty string.

At-Maps

At-maps are multimaps that can be declared and used in format strings. Their keys can be associated with multiple values.

When used with functions that accept at-maps, the objects are used directly. When converted to a string, at-maps use the stringified version of the first available value. This behavior allows use of at-maps to represent logic branches in a straightforward fashion.

For example, the following expressions have equivalent results:

$ifelse($token $token default)
@($token:$token;1:default)
@($token;default)

Defining At-Maps

At-maps are defined with an @ sign and enclosed by parentheses. Keys and values are separated by a colon, and entries are separated by a semicolon.

@()
An empty at-map. Evaluates to the empty string and—like the empty string—is treated as falsy in boolean operations.

@(key:value)
An at-map with a single key-value pair. Evaluates to value. If key is falsy or evaluates the empty string, it is not added to the at-map. Falsy values are possible.

@(value)
Specifies an at-map with value as both the key and value. For example, @(1) is equivalent to @(1:1).

@(A;B)
@(A;B:C)
@(A:B;C)
@(A:B;C:D)
Specifies an at-map with multiple values. The described syntaxes can be combined as desired.

@($_map:value)
(where $_map is an at-map) Specifies an at-map with all of the values of $_map mapped to value. For example, @(@(A;B):value) is equivalent to @(A:value;B:value).

Character Escapes & References

Format strings include special characters that need to be escaped in certain contexts. They also allow for character references, to make including uncommon characters a bit easier.

Escapes

The characters $@();: can be escaped by preceding the character with a dollar sign. This is useful to avoid using a function or token where you don't intend to.

For example, $$pi() would result in $pi().

References

While handling sandbox options, the game removes certain characters such as « and ». The $char function can be used to include these characters, but format strings also accept character references for ease-of-use.

Both named references and numeric references are supported. Numeric references behave similarly to the $char function; the character with the number specified will be used in place of the reference.

Using character references, « $1 » can be specified as « $1 » or « $1 ».

The available characters are limited to those in the ISO-8859-1 character set.

String Customization

Some mod features allow for custom string translations, so that players can see text in their preferred languages. These features expect strings of a certain format to be included in a separate mod. This could be an unlisted mod used by specifically a single server, or an extension mod that adds default content for servers.

Dialogue Tags

Custom dialogue tags can be specified for narrative style using the FormatNarrativeDialogueTag option.

Two translations should be specified per custom dialogue tag: UI_OmiChat_NarrativeTag_[Tag] and UI_OmiChat_UnknownLanguageNarrative_[Tag].

UI_OmiChat_NarrativeTag_[Tag] is used as the message content when the given dialogue tag is used. It requires the %1 substitution, which will be the message content.

UI_OmiChat_UnknownLanguageNarrative_[Tag] is used when a player doesn't know the language used for a message with the given tag, and the latter is used in other cases. It requires two substitutions: %1, the name of the speaker, and %2, the unknown language.

For example, if the dialogue tag gasps were defined, translations for UI_OmiChat_NarrativeTag_gasps and UI_OmiChat_UnknownLanguageNarrative_gasps should be specified. Otherwise, this will default to [Name] gasps, “[Content]” in all languages.

Roleplay Languages

Roleplay languages allow translations for language names. These can be defined with a UI_OmiChat_Language_[Language] string. For example, UI_OmiChat_Language_English defines the text used for the English language.

If the language has a space in it, the space will be replaced with an underscore when retrieving translations. Translations for Haitian Creole, for example, should be defined as UI_OmiChat_Language_Haitian_Creole.

If the translation is absent, the language name will be used as-is regardless of the in-game language. Translations are provided by the mod for the following languages:

• ASL
• Arabic
• Bengali
• Cantonese
• Catalan
• Danish
• Dutch
• English
• Finnish
• French
• German
• Gujarati
• Hausa
• Hawaiian
• Hindi
• Hungarian
• Italian
• Japanese
• Javanese
• Korean
• Latvian
• Malay
• Mandarin
• Marathi
• Norwegian
• Persian
• Polish
• Portuguese
• Punjabi
• Romanian
• Russian
• Shanghainese
• Spanish
• Tagalog
• Tamil
• Telugu
• Thai
• Turkish
• Ukrainian
• Urdu
• Vietnamese

Extending Format Strings

Format strings can be extended using the API. Additional functions or overrides of existing functions can be included by calling OmiChat.registerInterpolatorFunction.

OmiChat does not perform error handling while performing interpolation. Extensions should adhere to the convention of returning the empty string for invalid inputs rather than causing an error. Return values of nil or false will be treated as the empty string.

If you think your extension should instead be included in the mod, feel free to contribute!

Example

A simple example which appends the length of the input:

-- $example(hello) → hello5
local OmiChat = require 'OmiChat'
OmiChat.registerInterpolatorFunction('example', function(interpolator, s)
    if not s then
        return
    end

    return s .. #s
end)