Skip to content

Improved Chat

Jump to bottom
Person8880 edited this page Nov 4, 2023 · 8 revisions

Overview

The improved chat plugin allows for rich text messages to be displayed in the chat, and is required by the adverts and welcomemessages plugins if using rich text advert/join/leave messages.

It also allows attaching tags to chat messages from certain users/groups, which look like this (showing the most extreme case with command + rookie tags also):

chat_tags

In addition, it alters how chat is displayed, making new messages appear in a fixed position with old messages moving upwards and enforcing a limit on the number of messages on screen to avoid them going off screen entirely. The behaviour can be configured in the client configuration menu and the chatbox settings, including:

  • Configurable font size (automatic based on resolution, or a fixed size).
  • Configurable background opacity (where the background is a black gradient that fades out from left to right).
  • Configurable max messages to display before fading.
  • Configurable positioning behaviour, either moving old messages upwards (the default), or using the old vanilla behaviour where new messages appear after old ones (with all the downsides of that approach).

When using the new display mode and not using a custom chat position (due to moving the chatbox and setting it to position outer messages), the chat position adapts automatically to the various UI elements:

  • When playing as an alien, the chat avoids overlapping any status indicators.
  • When playing as a commander, the chat avoids overlapping both the minimap and control group icons.
  • When spectating, the chat avoids overlapping the minimap.

Config

The default config file should look something like this:

{
    "DisplayChatTagsInTeamChat": false,
    "LogLevel": "INFO",
    "ParseEmojiInChat": true,
    "__Version": "1.1"
}

The file should be called “ImprovedChat.json” and should be placed in the directory defined as your plugin config directory (default is config://shine/plugins).

Option Description
DisplayChatTagsInTeamChat Determines whether to display chat tags in team chat, or only global chat.
ParseEmojiInChat Determines whether emoji should be parsed and rendered in chat messages (see the emoji section below).

Chat Tags

To configure chat tags for users/groups, add a ChatTag table to a user/group in the user configuration file. For example:

{
    "Groups": {
        "Admin": {
            "ChatTag": {
                "Colour": [ 255, 255, 255 ],
                "Image": "ui/badges/wrench.dds",
                "Text": "[Admin]"
            }
        }
    }
}
Option Description
Colour Determines the colour of the chat tag's text.
Image An optional image to display behind the text. This must point to a valid texture, and will be resized to the same size as the text (as a square).
Text The text to display in the chat tag.

Emoji

The improved chat plugin adds support for named emoji in chat messages, similar to various other chat applications.

To add an emoji to a chat message, type the name surrounded by :, e.g.

Chat with emoji :thumbs_up:

The chatbox will automatically parse and render the emoji inline as rich text, as well as providing auto-completion:

rich_text_edit_emoji

In addition, an emoji picker is available to search for and insert emoji visually, remembering frequently used emoji:

emoji_picker

By default, a minimal set of common emoji are included which cover the basic unicode smileys, emoticons and hand gestures. However, the system is fully extensible and can be augmented with custom emoji.

Adding Emoji

To add additional emoji, create a JSON file under ui/shine/emoji/ with the following structure:

{
    // Define categories for your emoji to group them in the emoji picker.
    "Categories": [
		{
			"Name": "Example",
            // Language codes here should match the existing language codes used by the game.
			"Translations": {
				"enGB": "Example"
			}
		}
    ],
    "Emoji": [
        // Add a single emoji.
        {
            "Name": "example",
            "Texture": "ui/shine/emoji/example/some_emoji.tga",
            "Category": "Example"
        },
        // Add an emoji from a texture atlas, using UV-space texture co-ordinates.
        {
            "Name": "example_from_atlas",
            "Texture": "ui/shine/emoji/example/some_emoji_atlas.tga",
            "TextureCoordinates": [ 0, 0, 0.1, 0.1 ],
            "Category": "Example"
        },
        // Add an emoji from a texture atlas, using pixel-space texture co-ordinates.
        {
            "Name": "example_from_atlas_pixels",
            "Texture": "ui/shine/emoji/example/some_emoji_atlas.tga",
            "TexturePixelCoordinates": [ 0, 0, 32, 32 ],
            "Category": "Example"
        },
        // Add an entire folder of emoji, with each file name being the emoji's name.
        // Note that all files matching the given folder pattern will be consistency checked automatically to avoid client and server mismatches.
        {
            "Folder": "ui/shine/emoji/example/folder/*.tga",
            // Optionally, files may be excluded if some are unsuitable for use as emoji.
            "Exclude": [
                "ui/shine/emoji/example/folder/*_excluded.tga"
            ],
            "Category": "Example"
        }
    ]
}

Emoji definition files have two sections:

  • Categories provides a way to define groupings of emoji to show in the picker. You do not need to re-define existing categories, you only need to define categories if you are adding new ones.
  • Emoji provides the texture files and names for the emoji to add.

You can place the JSON file anywhere under ui/shine/emoji and it will be picked up automatically. Addons are recommended to place their definition file within their own unique folder that contains their emoji image(s), e.g.

ui/shine/emoji/my-emoji-pack/my-emoji-pack.json

Note

Emoji definition files (and any folders of emoji specified in a definition file) are consistency checked automatically to ensure client and server declare the exact same set of emoji (as networking logic relies on this). This means that clients cannot add their own emoji, the server must install them.

Restricting Emoji

By default, all emoji added to the server are available to all players. However, this can be restricted if desired by defining an AllowedEmoji list on a given group.

For example:

{
    "Groups": {
        "Example": {
            "AllowedEmoji": [
                // Allow all emoji starting with 'face_'.
                "face_*"
                // Allow all emoji with '_face_' in the middle.
                "*_face_*",
                // Allow all emoji ending with '_face'.
                "*_face",
                // Allow the entire 'Emoticons' category.
                "c:Emoticons",
                // Deny the use of the 'thinking_face' emoji.
                "!thinking_face"
            ]
        }
    }
}

The AllowedEmoji list is a list of emoji names, or category names (prefixed with c:), that the user can or cannot use. The list is processed in the order it's declared, so denying emoji (with the ! prefix) must come after an entry that allows it. Use * for wildcard matches of 0 or more characters on emoji names (not categories).

To set the default set of allowed emoji, add a restriction to the default group:

{
    "DefaultGroup": {
        // Allow all of the default categories for all users.
        "AllowedEmoji": [
            "c:Smilies",
            "c:Emoticons",
            "c:Hands"
        ]
    }
}

When inheriting, the allowed emoji lists are merged to apply the inherited group's list first.

For example, inheriting from the default group example above, and specifying:

{
    "Groups": {
        "Example": {
            "AllowedEmoji": [
                "!thinking_face"
            ],
            "InheritFromDefault": true
        }
    }
}

would allow all of the default emoji except thinking_face, essentially equivalent to specifying:

[
    "c:Smilies",
    "c:Emoticons",
    "c:Hands",
    "!thinking_face"
]
Clone this wiki locally