Introduction

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 the configuration.

• Chat color customization
• Name color customization
• Callout customization
• Character naming with /name
• Status displays with /status
• Customization profiles for character/style switching
• Roleplay customization options
• Roleplay chat buffs
• Display of chat names in menus (Trading, Medical Check)
• /card, /roll, and /flip commands
• Emote animation shortcuts (.clap, .salute, .surrrender, etc.)
• Roleplay languages
• Typing indicators
• Configurable chat streams
• Configurable info text
• Customization of names, timestamps, all chat types, and more via powerful format strings
• Various admin commands
• Various other configuration options
• API for extension by other mods

Credits

Thank you to the translators!

• French: Inkredibehl
• Korean: 우로 (Ssaulabby)

If you’d like to see the mod translated into your language, please contribute!
Some features were inspired by buffy’s roleplay chat. The range indicator and /status were inspired by Wasteland’s RP 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 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 character 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 the Name Colors configuration 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, players can use the /yell color option.

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 options only show up if the Custom Shouts configuration option is enabled.

Character customization

If a server has character customization enabled, the customization submenu also includes quality of life 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

If the Built-In Macros configuration option includes Emotes, players can 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 at the beginning of the message, it must come after a space. This is to prevent accidentally including an emote after ending a sentence with an exclamation point.

Shortcut list

The following table contains the emotes that are available in the base mod.
Players can use the /emote list 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 the Admin Icon configuration option.

The view player data option can be used to open a menu 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.

/setname

Usage: /setname <username> <name>
Sets the chat name of a player.

/resetname

Usage: /resetname <username>
Resets the chat name of a player.

/clearnames

Resets all players’ chat names.

/seticon

Usage: /seticon <username> <icon>
Sets the chat icon for a player.

/reseticon

Usage: /reseticon <username>
Clears the chat icon for a player.

/iconinfo

Usage: /iconinfo <name>
Gets information about an icon. If provided a valid icon name or alias, it will display the icon.

See the partial list of icons for possible aliases.

/addlanguage

Usage: /addlanguage <username> <language>
Adds a known language to a player. The provided language must be one of the configured languages.

/resetlanguages

Usage: /resetlanguages <username>
Sets the known languages for a player to only the default language.

/setlanguageslots

Usage: /setlanguageslots <username> <amount>
Sets the language slots for a player. amount must be in [1, 50].

Mini Scoreboard

The “mini scoreboard” included in the admin menu will respect the options configured for In-Game Names.

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

Java Mods

The GitHub repository includes 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.

Warning

Java mods are likely to break between updates! If this happens, delete the .class files from where they were placed and wait for the updated files.

Functionality

The ChatMessage.class replacement cleans up the server-side chat log files by separating the chat text from the data included for mod functionality.

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 to remove mod data.

Installation

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 the zombie folder into the game directory (the directory which contains projectzomboid.jar).
   • Note that a zombie folder will likely not already be present unless you’ve already installed Java mods.

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 a single server, or an extension mod that adds default content for servers.

Note

These translations are not defined using the game’s usual translation system. See the information about contributing translations for details.

The comment ### @bundle OmiChat must be included at the top of translation files for them to be included.

Dialogue Tags

Custom dialogue tags can be specified for narrative style using the Dialogue Tag Format option.

When defining a custom dialogue tag, the string unknown-language-[tag] should also be defined. This is used when the player’s character doesn’t speak the language used for a message with the given tag. It must include the variables $name and $language.

A string for signed languages can also be specified with unknown-language-signed-[tag]. This will be used when the language is a signed language.

For example, if the dialogue tag mutters were used, the strings could be defined in English as:

### @bundle OmiChat

unknown-language-mutters = { $name } mutters something in { $language }.

unknown-language-signed-mutters = { $name } subtly signs something in { $language }.

# or, since it's the same as the built-in string for 'whispers':
unknown-language-signed-mutters = { unknown-language-signed-whispers }

If a string is not defined for the tag, it will default to the translation for says or signs, depending on whether the language is signed.

Roleplay Languages

Roleplay languages allow translations for language names. These can be defined with a language-[name] string. For example, language-english defines the translation used for the English roleplay language.

When retrieving translations, language names will be converted to lowercase and spaces will be replaced with hyphens. Translations for Haitian Creole, for example, should be defined using language-haitian-creole.

If the translation is absent, the language name will be used as-is regardless of a player’s language. Translations are provided by the mod for the following roleplay 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

Format Strings

Various configuration 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 configuration 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. Like functions, tokens are case-sensitive; $author is not the same as $Author.

The available tokens for a given option are documented in the in-game configuration menu.

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.

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. Like tokens, functions are case-sensitive.

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 pairs of backticks (`). A dollar-sign can be used to escape backticks within the enclosed text.

$Set(_token `hello world`)$_token → hello world
$Reverse(`)(`) → ()
$Len(`$``) → 1

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 non-whitespace character in s to its uppercase counterpart.

$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.

$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 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 characters .,!?:/-~ are used.

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

$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 the given string.

$StartsWith(this other)

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

$Str(...)

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

Many format strings are seeded with a constant value, to prevent changes when re-evaluating. 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

$AddTag(tag)

Adds a tag to the tags token. If there is no tags token or it is not an at-map, this does nothing.

$ColorActions(s options)

Wraps actions within s in color tags. Actions are delimited by a quote followed by an asterisk (" *).

This accepts the following options in the form of an at-map:

• colorTargetTag: if this is given, it will be used as the search tag for the stream to copy the color from. By default, this uses the appropriate tag based on existing tags.
• optionalAsterisks: if this is true, actions will begin when any quote is encountered, instead of requiring " *.

$ColorQuotes(s options)

Wraps quoted text within s in color tags.

This accepts the following options in the form of an at-map:

• colorTargetTag: if this is given, it will be used as the search tag for the stream to copy the color from. By default, this uses the appropriate tag based on existing tags.

$Default()

Returns the default content for a format string. If used outside of a valid format string, this returns the empty string.

$DisallowSignedOverRadio(options)

Checks that a message is not being sent with a signed language. Returns the empty string if it is.

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.

This accepts the following options in the form of an at-map:

• condition: if this is given and is not truthy, the function will return true without checking the language.
• suppressError: if this is truthy, the error token will not be set.

$FormatRadio(frequency)

Returns the default formatting for a radio message prefix.

$Fragmented(text)

Returns a partial quote representing a fragment of what a player character understood. This used for unknown language messages.

$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.

$HasTag(tag)

Checks whether a tag is present in the tags token.

$IsSigned(language)

Returns true if language is configured as a signed language.

$RemoveTag(tag)

Removes a tag from the tags token. If there is no tags token or it is not an at-map, this does nothing.

$StreamCategory(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 enables using at-maps to represent basic logic branches.

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 allowed.

@(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 character references, to make including uncommon characters a bit easier.

Escapes

The characters $@();: and ` 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

Although you can directly include characters like « and », 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, « $input » can be specified as « $input » or « $input ».

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

Configuration

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

OmiChat does not use sandbox options for configuration. A custom configuration menu can be accessed directly from the chat as an admin by clicking Open settings under Admin options.

• General Settings: feature flags, info text, and other basic features.
• Buffs: boosts to players’ stats based on chat messages.
• Callout Settings: shout ranges and formatting.
• Commands: chat commands for player names, statuses, and more.
• Compatibility Options: integrations and patches for other mods.
• Customization: player customization, such as name colors and custom shouts.
• Discord: formatting for Discord integration messages.
• Echo Messages: enabling and formatting echo messages.
• Formatting: formatting options and advanced customization.
• Language Settings: customization of available roleplay languages and related behavior.
• Macro Settings: configuration for macros available to players.
• Mentions: configuration for mentions.
• Narrative Style: options for displaying messages in a narrative format.
• Radio Settings: customization of messages sent over the radio.
• Server Message Settings: customization of server messages.
• Stream Settings: advanced chat stream customization, including stream creation.
• Typing Indicator: indicators for when players are typing in chat.
• Zombie Attraction: attracting zombies from chat messages.

General Settings

Options that don’t belong anywhere else. This includes feature flags, the admin icon, and info text.

Preset

Default: Buffy

The preset dropdown can be used to select built-in and custom presets to apply to all chat settings.

The following presets are built-in:

• Buffy: settings tailored to roleplay, based on buffy’s roleplay chat. This is the default preset.
• Omar: settings designed for lighter roleplay, with narrative style disabled. This is closer to the default settings from the legacy b41 version of OmiChat.
• Vanilla: settings designed to mimic vanilla, with many mod features disabled.

Always Show Chat

General.AlwaysShowChat
Default: false

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

Case-Insensitive Streams

General.CaseInsensitiveChatStreams
Default: true

If enabled, chat streams will be case-insensitive.

This means that /say and /SAY will be treated equivalently.

Range Indicator Button

General.IncludeRangeIndicatorButton
Default: false

If enabled, a button to display the range of ranged chats will be included.

Clear On Death

General.ClearOnDeath
Default: all

Information that is cleared when a player’s character dies.

Options:

• Icon: If enabled, chat icons will be cleared on death.
• Languages: If enabled, roleplay languages will be cleared on death.
• Chat Nickname (Nickname): If enabled, chat nicknames will be cleared on death.
• Status: If enabled, chat statuses will be cleared on death.

Admin Icon

General.AdminIcon
Default: Item_Hammer

The name of the texture used when an admin enables display of a chat icon. Defines the value of the adminIcon token in the icon format.

Info Text

General.InfoText
Information that can be accessed by clicking an info button on the chat window. If this is blank, the info button will not be available.

This can use rich text formatting to include different colors and fonts.

Variables

General.Variables
Arbitrary key-value pairs that can be used for providing information to extensions and integrations.

Currently, the mod does not use anything specified here.

Buffs

These options control buffs, which are configurable boosts to stats that are applied when messages are sent on certain streams.

By default, only roleplay streams (e.g., /me) apply buffs. Whether a stream applies buffs can be changed using the Allow Buffs option.

Enabled

Buffs.Enable
Default: true

Controls whether buffs are enabled for streams that allow them. Other buff options have no effect if this is off.

Cooldown

Buffs.Cooldown
Default: 15
Minimum: 0
Maximum: 1440

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

Boredom Reduction

Buffs.Boredom
Default: 0.2
Minimum: 0
Maximum: 1

The percentage that boredom is reduced by when a buff is applied.

Unhappiness Reduction

Buffs.Unhappiness
Default: 0.2
Minimum: 0
Maximum: 1

The percentage that unhappiness is reduced by when a buff is applied.

Hunger Reduction

Buffs.Hunger
Default: 0.1
Minimum: 0
Maximum: 1

The percentage that hunger is reduced by when a buff is applied.

Thirst Reduction

Buffs.Thirst
Default: 0.1
Minimum: 0
Maximum: 1

The percentage that thirst is reduced by when a buff is applied.

Fatigue Reduction

Buffs.Fatigue
Default: 0.1
Minimum: 0
Maximum: 1

The percentage that fatigue is reduced by when a buff is applied.

Cigarette Stress Reduction

Buffs.CigaretteStress
Default: 0.2
Minimum: 0
Maximum: 1

The percentage that stress from a lack of smoking is reduced by when a buff is applied.

Callout Settings

These options control features related to callouts (shouts).

Callout Format

Callouts.Format
Default: $Default()

Format used for the overhead text of callout messages.

Sneak Callout Format

Callouts.SneakFormat
Default: $Default()

Format used for the overhead text of sneak callout messages.

Callout Range

Callouts.Range
Default: 48
Minimum: 0
Maximum: 60

The maximum distance for callouts to be heard by players.

Sneak Callout Range

Callouts.SneakRange
Default: 6
Minimum: 0
Maximum: 60

The maximum distance for sneak callouts to be heard by players.

Commands

These options control various commands that are available in chat.

Name Commands

Commands.Name
Options related to commands to set character names.

Mode

Commands.Name.Mode
Default: /name sets chat nickname

Controls the behavior of the /name and /nickname commands.

If this is set to an option that sets the character’s forename or full name, players will not be able to reset their name with the /name command.

Options:

• Disable
• /name sets chat nickname (Nickname)
• /name sets character's forename (Forename)
• /name sets character's full name (Fullname)
• /name sets character's forename, /nickname sets chat nickname (Forename-Plus-Nickname)
• /name sets character's full name, /nickname sets chat nickname (Fullname-Plus-Nickname)

/status

Commands.Status
Options related to the /status command.

Enabled

Commands.Status.Enable
Default: true

If enabled, players will be able to set a status message visible to other players with the /status command.

Visibility Range

Commands.Status.Range
Default: 15
Minimum: 1
Maximum: 100

The range a player has to be within to see another player’s status.

/card

Commands.Card
Options that control the behavior and display of the /card command.

Global

Commands.Card.Global
Default: false

Controls whether the command should be global, similar to vanilla commands. This disables formatting options.

Overhead Format

Commands.Card.OverheadFormat
Default: $Default()

Defines the format of overhead speech bubbles for the command.

Card Items

Commands.Card.Items
List of items that players can use for the /card command.

If a player doesn’t have any of the items in the list, the command will fail. If this is blank, the command won’t require an item.

Default:

• CardDeck

Tags

Commands.Card.Tags
Tags that modify the appearance and behavior of messages associated with the command.

/roll

Commands.Roll
Options that control the behavior and display of the /roll command.

Global

Commands.Roll.Global
Default: false

Controls whether the command should be global, similar to vanilla commands. This disables formatting options.

Include Individual Dice Rolls

Commands.Roll.IncludeIndividualRolls
Default: true

If enabled, the result of each individual die included in a roll will be shown in the roll message.

Include Sum of Dice Rolls

Commands.Roll.IncludeSumOfRolls
Default: false

If enabled, the sum of all dice included in a roll will be shown in the roll message.

Overhead Format

Commands.Roll.OverheadFormat
Default: $Default()

Defines the format of overhead speech bubbles for the command.

Dice Items

Commands.Roll.Items
List of items that players can use for the /roll command.

If a player doesn’t have any of the items in the list, the command will fail. If this is blank, the command won’t require an item.

Defaults:

• Dice
• Dice_00
• Dice_4
• Dice_6
• Dice_8
• Dice_10
• Dice_12
• Dice_20

Tags

Commands.Roll.Tags
Tags that modify the appearance and behavior of messages associated with the command.

/flip

Commands.Flip
Options that control the behavior and display of the /flip command.

Global

Commands.Flip.Global
Default: false

Controls whether the command should be global, similar to vanilla commands. This disables formatting options.

Overhead Format

Commands.Flip.OverheadFormat
Default: $Default()

Defines the format of overhead speech bubbles for the command.

Coin Items

Commands.Flip.Items
List of items that players can use for the /flip command.

If a player doesn’t have any of the items in the list, the command will fail. If this is blank, the command won’t require an item.

Tags

Commands.Flip.Tags
Tags that modify the appearance and behavior of messages associated with the command.

Compatibility Options

These options control compatibility patches for other mods.

Note

Currently, mod compatibility patches are soft-removed. They may be reintroduced when the relevant mods are updated for b42.

Automatic Overrides

Compatibility.ApplyOverrides
Default: true

If enabled, chat functions called by other mods will be intercepted by this mod.

For example, if another mod sends a message directly to /say, this will attempt to apply the configured formatting.

Customization

These options control the customization options available to players.

Custom Shouts

Customization.AllowCustomShouts
Default: true

Allows players to set custom callout text.

Custom shouts can be configured via profiles, in the chat settings.

Name Colors

Customization.EnableNameColors
Default: true

If enabled, players’ speech colors will be used to color their name in chat.

Character Customization

Customization.EnableCharacterCustomization
Default: true

Enables quality of life options to change the character’s appearance.

Clean Character Effects

Customization.CleanEffects
Default: all

Controls the effects of the character customization option to clean blood & dirt.

If nothing is enabled, the option will be unavailable.

Options:

• Clean Body (Body)
• Clean Clothing (Clothing)

Discord

These options control the formatting of messages that come from Discord.

Chat Format

Discord.ChatFormat
Default: $Default()

Controls how messages from Discord appear in chat.

Default Message Color

Discord.DefaultColor
Default: 144,137,218

The default color used for messages from Discord.

Show Discord Color Option

Discord.ShowColorOption
Default: Respect server setting

Controls whether options to customize Discord message color are shown to the player.

The Respect server setting option checks if the Discord integration is enabled for the server.

Options:

• Yes
• No
• Respect server setting (Respect-Server-Setting)

Tags

Discord.Tags
Tags that modify the appearance and behavior of messages from Discord.

Defaults:

• OOC
• UseAuthorUsername

Echo Messages

These options control echo messages, which are messages sent on one stream that automatically send to another.

Enabled

EchoMessages.Enable
Default: true

Controls whether messages from /faction and /safehouse are echoed onto another chat.

Echoed messages will be sent to the stream with the EchoTarget tag.

Chat Format

EchoMessages.ChatFormat
Default: $Default()

Controls how echoed messages appear in chat.

Overhead Format

EchoMessages.OverheadFormat
Default: $Default()

Format used for overhead speech bubbles of echoed messages.

Tags

EchoMessages.Tags
Tags that modify the appearance and behavior of echoed messages.

Default:

• OverRadio

Formatting

This section includes options related to formatting, including various format strings which can be used for advanced customization.

All of the format strings default to $Default(), which gets the default content. The tokens and options that each format accepts are available in the in-game configuration menu.

Chat Text

Format.Chat
Format strings used to control how messages appear in chat.

Prefix Format

Format.Chat.Prefix
Default: $Default()

Defines the value of the prefix token in the final chat format.

Final Format

Format.Chat.Final
Default: $Default()

Format used for the final chat message, after all other format strings have been applied.

Overhead Text

Format.Overhead
Format strings used to control how ranged messages appear over characters’ heads.

Prefix Format

Format.Overhead.Prefix
Default: $Default()

Defines the value of the prefix token in the final overhead format.

Final Format

Format.Overhead.Final
Default: $Default()

Format used for the final overhead message, after all other format strings have been applied.

Perception Range Text

Format.PerceptionRange
Format strings for text to display when a message is out of range, but within range for perceiving that something was said.

Chat Format

Format.PerceptionRange.Chat
Default: $Default()

Defines how out-of-range perceived messages display in chat.

Overhead Format

Format.PerceptionRange.Overhead
Default: $Default()

Defines how out-of-range perceived messages display overhead.

Components

Format.Component
Format strings used to define specific values in other format strings.

Name

Format.Component.Name
Default: $Default()

Defines the values of the name and rawName tokens in other format strings.

Tag

Format.Component.Tag
Default: $Default()

Format used for chat tags when a player enables the relevant option. This controls the value of the tag token in other format strings.

Timestamp

Format.Component.Timestamp
Default: $Default()

Format used for timestamps when a player enables the relevant option. This controls the value of the timestamp token in other format strings.

Icon

Format.Component.Icon
Default: $Default()

Defines the value of the icon token in other format strings.

Language

Format.Component.Language
Default: $Default()

Defines the value of the language token in the final chat format.

Embedded Quotes

Format.Component.EmbeddedQuote
Default: $Default()

Defines the format used for quotes embedded in actions.

Embedded Actions

Format.Component.EmbeddedAction
Default: $Default()

Format used for actions embedded in text.

Filters

Format.Filter
Format strings used to control whether an input is allowed.

Chat Input Filter

Format.Filter.ChatInput
Default: $Default()

Filters chat input before sending it. If this results in the empty string or sets an error token, the input won’t be sent.

The default filter handles disallowing signed languages over the radio and truncation.

Name Filter

Format.Filter.Name
Default: $Default()

Filters names set with the /name and /nickname commands. If this results in the empty string or sets an error token, the command will fail.

Status Filter

Format.Filter.Status
Default: $Default()

Filters statuses set with the /status command. If this results in the empty string or sets an error token, the command will fail.

The default filter handles enforcing minimum and maximum length.

In-Game Names

Format.MenuName
Options that control how character names are displayed within in-game menus.

Trade Window

Format.MenuName.Trade
Default: $Default()

The format used for names in the item trading UI.

Medical Window

Format.MenuName.Medical
Default: $Default()

The format used for names in the medical check UI.

Mini-Scoreboard

Format.MenuName.MiniScoreboard
Default: $Default()

The format used for names in the admin mini-scoreboard.

Other

Format.Other
Other options related to formatting.

PM Parentheses

Format.Other.PMParentheses
Default: 2
Minimum: 0
Maximum: 5

The amount of parentheses to include around names in private messages.

Default Name Mode

Format.Other.DefaultNameMode
Default: name

The mode to use for the name format unless overridden by an argument.

The name mode uses the chat nickname, username uses the player username, and both includes both separated by a slash.

Options:

• name
• username
• both

Default Name Mode (Per Chat Type)

Format.Other.DefaultNameModeForChatType
The mode to use for the name format for a chat type unless overridden by an argument.

This maps chat types to options for Default Name Mode.

Defaults:

• admin = username
• whisper = both

Volume Indicator

Format.Other.VolumeIndicators
Text to use for volume indicators. Keys should be one of Loud, Quiet, or Whisper.

Default:

• Loud = Long

Language Settings

These options are related to roleplay languages. Players will be unable to fully understand messages sent in a language their character cannot speak.

Use Defaults

Language.UseDefaultList
Default: true

If this is enabled, the languages configured in the list will be ignored in favor of the default languages.

List

Language.List
The list of roleplay languages players can use.

Name

Language.List.Name
The name of the language.

Signed

Language.List.Signed
Default: false

If this is enabled, the language will be treated as a signed language.

Default Language Slots

Language.DefaultSlots
Default: 1
Minimum: 0
Maximum: 50

The number of language slots players have by default.

Players can use these slots to choose additional languages beyond the primary one that their character can speak.

Extra languages can also added using admin commands. This is necessary if the value of this option is less than 2.

Interpretation Rolls

Language.InterpretationRolls
Default: 2
Minimum: 0
Maximum: 10

The number of rolls to attempt to reveal a word in a message sent with a language the player doesn’t understand.

Interpretation Chance

Language.InterpretationChance
Default: 25
Minimum: 0
Maximum: 100

The percent chance for each interpretation roll to succeed.

Unknown Language Overhead Format

Language.UnknownLanguageOverhead
Default: $Default()

Controls how messages appear overhead when sent using a roleplay language the player’s character doesn’t speak.

Unknown Language Chat Format

Language.UnknownLanguageChat
Default: $Default()

Controls how messages appear in chat when sent using a roleplay language the player’s character doesn’t speak.

Unknown Language Chat Format (Radio)

Language.UnknownLanguageRadio
Default: $Default()

Controls how messages sent over the radio appear in chat when sent using a roleplay language the player’s character doesn’t speak.

Language Indicator Format

Language.PlaceholderFormat
Default: $Default()

Controls the language indicator text that displays as a placeholder for the chat entry. By default, the indicator only shows up for languages other than the default language.

Language Indicator Color

Language.PlaceholderColor
Default: 70,70,70

The color to use for the language indicator placeholder text.

Add Language Allowlist

Language.SelfAddAllowlist
The list of languages that should display in the menu for adding languages.

Add Language Blocklist

Language.SelfAddBlocklist
The list of languages that should not display in the menu for adding languages.

Macro Settings

These options control macros.

Currently, the only built-in macro is the one used for emote shortcuts.

Enabled

Macros.Enable
Default: true

Controls whether macros, including built-in macros, can be used.

Built-In Macros

Macros.BuiltIn
Default: all

Controls which built-in macros are enabled.

Options:

• Emotes (Emote): If enabled, players can use shortcuts in chat to trigger animations.

Mentions

These options control mentions.

Currently, these only display the mentioned user’s name color.

Enabled

Mentions.Enable
Default: true

Controls whether players can use @ to mention other players, which includes their name color in chat.

Always Use Name Colors

Mentions.AlwaysUseNameColors
Default: true

If this is enabled, the name color option on streams will be ignored for mentions.

Mention Suggestion Range

Mentions.Range
Default: 20
Minimum: 0
Maximum: 60

The range a player has to be within to have another player suggested for a mention. This has no effect on non-ranged streams and is ignored if set to zero.

Chat Format

Mentions.ChatFormat
Default: $Default()

Defines the format of mentions in the chat.

Overhead Format

Mentions.OverheadFormat
Default: $Default()

Defines the format of mentions in the overhead speech bubble.

Narrative Style

These options control narrative style. 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, a message sent with /yell Hey will be transformed to <Name> shouts, “Hey!”.

Enabled

NarrativeStyle.Enable
Default: true

Controls whether narrative style is enabled for streams that allow it.

Overhead Content Format

NarrativeStyle.OverheadContentFormat
Default: $Default()

Defines the format of the narrative style tag and quote in the overhead text.

Chat Content Format

NarrativeStyle.ChatContentFormat
Default: $Default()

Defines the format of the narrative style tag and quote in the chat.

Dialogue Tag Format

NarrativeStyle.DialogueTagFormat
Default: $Default()

Defines the dialogue tag used for a message sent in narrative style.

Input Filter

NarrativeStyle.InputFilter
Default: $Default()

Filters messages sent on a stream with narrative style enabled.

Radio Settings

These options control formatting of messages sent over the radio.

Chat Format

Radio.ChatFormat
Default: $Default()

Controls how radio messages appear in chat.

Overhead Format

Radio.OverheadFormat
Default: $Default()

Controls how radio messages appear in overhead speech bubbles.

Default Message Color

Radio.DefaultColor
Default: 178,178,178

The default color used for radio messages.

Tags

Radio.Tags
Tags that modify the appearance and behavior of radio messages.

Default:

• NoVolumeIndicator

Server Message Settings

These options control formatting of server messages.

Chat Format

ServerMessages.ChatFormat
Default: $Default()

Controls how server messages appear in chat.

Default Message Color

ServerMessages.DefaultColor
Default: 0,128,255

The default color used for server messages.

Tags

ServerMessages.Tags
Tags that modify the appearance and behavior of server messages.

Default:

• NoTimestamp

Stream Settings

These options control custom stream configuration. With the exception of Use Defaults and Global Tags, the options on this page are per-stream.

Use Defaults

Streams.UseDefaultList
Default: true

If this is enabled, the streams configured in the list will be ignored in favor of the default streams.

List

Streams.List
Configuration for chat streams. The options in this section are per-stream.

Some options are not available for certain chat types; if this is the case, they will not be editable in the configuration menu.

Enabled

Streams.List.Enable
Default: true

Controls whether this stream is enabled.

Stream Type

Streams.List.Stream
Default: custom

The type of the stream.

Using a value other than custom for this option disables some other options. These will be inherited from the stream type.

Options:

• custom
• say
• yell
• private
• faction
• safehouse
• general
• admin
• whisper
• low
• me
• meloud
• mequiet
• mewhisper
• do
• doloud
• doquiet
• dowhisper
• ooc
• narrate

Name

Streams.List.Name
The name of the stream.

Streams that have duplicate names or share a name with a stream type are ignored.

Other reserved names are server, discord, radio, and speech.

This option is only enabled if Stream Type is set to custom.

Command

Streams.List.Command
The primary command to use to send a message on the stream. Defaults to the name of the stream.

Short Command

Streams.List.ShortCommand
A short command that can be used to send a message on the stream.

Chat Type

Streams.List.ChatType
Default: say

The type of chat this stream sends messages over.

This option is only enabled if Stream Type is set to custom.

Options:

• say
• shout
• faction
• safehouse
• whisper
• general
• admin

Category

Streams.List.Category
Default: chat

The category of this stream.

This is used to categorize streams for retaining options.

This option is only enabled if Stream Type is set to custom.

Options:

• chat
• rp
• other

Default Message Color

Streams.List.DefaultColor
The default color used for messages sent over this stream.

Range

Streams.List.Range
Default: 30
Minimum: 1
Maximum: 60

The range of this stream.

This option is only enabled for ranged chat types.

Range (Signed)

Streams.List.RangeSigned
Default: 0
Minimum: 0
Maximum: 60

The range of this stream, when used with a signed language.

A value of 0 indicates that the non-signed range should be used.

This option is only enabled for ranged chat types.

Vertical Range

Streams.List.VerticalRange
Default: 2
Minimum: 1
Maximum: 32

The vertical range of this stream.

A value of 0 indicates that vertical levels should be ignored.

This option is only enabled for ranged chat types.

Vertical Range (Signed)

Streams.List.VerticalRangeSigned
Default: 1
Minimum: 0
Maximum: 60

The vertical range of this stream, when used with a signed language.

A value of 0 indicates that the non-signed range should be used.

This option is only enabled for ranged chat types.

Perception Range

Streams.List.PerceptionRange
Default: 0
Minimum: 0
Maximum: 60

The range in which an indicator that something was said out-of-range will send.

A value of 0 means nothing out-of-range will be perceived.

This option is only enabled for ranged chat types.

Perception Range (Signed)

Streams.List.PerceptionRangeSigned
Default: 0
Minimum: 0
Maximum: 60

The range in which an indicator that something was said out-of-range will send, when sent in a signed roleplay language.

A value of 0 means nothing out-of-range will be perceived.

This option is only enabled for ranged chat types.

Chat Format

Streams.List.ChatFormat
Default: $Default()

Controls how messages sent on this stream appear in chat.

Overhead Format

Streams.List.OverheadFormat
Default: $Default()

Format used for overhead speech bubbles.

This option is only enabled for ranged chat types.

Allow Buffs

Streams.List.AllowBuffs
Default: false

If this is enabled and buffs are turned on, sending a message on this stream will apply a buff.

Allow Mentions

Streams.List.AllowMentions
Default: false

If this is enabled, mentions will be allowed on this stream.

Allow RP Languages

Streams.List.AllowLanguages
Default: false

If this is enabled, this stream will use the player’s current language when sending messages.

Allow Typing Indicator

Streams.List.AllowTypingIndicator
Default: false

If this is enabled, typing on the stream will trigger the typing indicator.

Attract Zombies

Streams.List.AttractZombies
Default: false

If this is enabled and zombie attraction is enabled, messages on this stream can attract zombies.

This option is only enabled for ranged chat types.

Use Narrative Style

Streams.List.UseNarrativeStyle
Default: false

If this is enabled and narrative style is on, messages on this stream will use narrative style.

Tags

Streams.List.Tags
Tags that modify the appearance and behavior of the stream.

Aliases

Streams.List.Aliases
List of additional aliases that can be used to send messages on the stream.

Roles

Streams.List.Roles
List of roles that can use this stream. If the list is empty, the stream will not be limited to any roles.

Global Tags

Streams.GlobalTags
Additional tags to include in every stream.

Defaults:

• ActionAsterisks
• IncludeAdminIndicator

Typing Indicator

These options control the typing indicator.

Enabled

TypingIndicator.Enable
Default: true

Controls whether the typing indicator is enabled on streams that allow it.

Typing Format

TypingIndicator.Format
Default: $Default()

Defines the format of the typing indicator message when the typing indicator is enabled.

Name Format

TypingIndicator.NameFormat
Default: $Default()

Defines the format of names in the typing indicator message.

Zombie Attraction

These options control attraction of zombies from chat messages.

Chat Range Multiplier

ZombieAttraction.ChatRangeMultiplier
Default: 0
Minimum: 0
Maximum: 10

A multiplier that will be applied to chat ranges to determine zombie attraction range.

If this is zero, non-callout chat messages will not attract zombies.

Extending Format Strings

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

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

Warning

OmiChat does not perform error handling for interpolation functions. 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 also be treated as the empty string.

Example

A simple example which appends the length of the input:

-- $example(hello) → hello5
local OmiChat = require 'OmiChat/Client'
OmiChat.extension.registerInterpolatorFunction('example', function(_interpolator, str)
    if not str then
        return
    end

    return str .. #str
end)