Adverts

Overview

The adverts plugin displays short messages in a defined interval.

An advert will look something like this:

Config

The default config looks something like this:

{
    "Adverts": [
        {
            "DefaultTemplate": "ChatNotification",
            "IntervalInSeconds": 60,
            "Loop": true,
            "Messages": [
                {
                  "Message": "Welcome to Natural Selection 2."
                },
                {
                  "Message": "This server is running the Shine administration mod."
                }
            ],
            "RandomiseOrder": false
        }
    ],
    "LogLevel": "Info",
    "Templates": {
        "ChatNotification": {
            "Colour": [ 255, 255, 255 ],
            "Prefix": "[Info]",
            "PrefixColour": [ 0, 200, 255 ],
            "Type": "chat"
        }
    },
    "TriggeredAdverts": {
        "START_OF_ROUND": [
            {
                "Message": "May the best team win!"
            }
        ],
        "SYSTEM_TIME": [
            {
                "Message": "It's 06:00!",
                "TriggerTimes": [ "06:00" ]
            }
        ]
    },
    "__Version": "2.4"
}

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

Option	Description
Adverts	A list of message cycles. See the cycle options below.
Templates	Defines named template adverts, whose values will be used on every advert with a matching Template value. Note that adverts may individually override template values.
TriggeredAdverts	Defines adverts that are triggered by certain events. These must be defined under a trigger name, which may be one of: COUNTDOWN START_OF_ROUND END_OF_ROUND MARINE_VICTORY ALIEN_VICTORY DRAW SYSTEM_TIME COMMANDER_LOGGED_IN MARINE_COMMANDER_LOGGED_IN ALIEN_COMMANDER_LOGGED_IN COMMANDER_LOGGED_OUT MARINE_COMMANDER_LOGGED_OUT ALIEN_COMMANDER_LOGGED_OUT COMMANDER_EJECTED MARINE_COMMANDER_EJECTED ALIEN_COMMANDER_EJECTED

Cycle Options

These options are available to cycles defined under Adverts.

Option	Description	Example
DefaultTemplate	Sets the default template to apply to all messages in the cycle. Avoids having to repeat the Template key on each message.	"DefaultTemplate": "ChatNotification"
InitialDelayInSeconds	Determines how long to delay the first message when the cycle is first started. This will only apply on the first loop of a cycle, once it repeats the message's normal delay will be used.	"InitialDelayInSeconds": 0
IntervalInSeconds	Determines how much time (in seconds) between messages by default. Individual messages may override this using DelayInSeconds.	"IntervalInSeconds": 60"
Messages	An array of messages to be displayed as part of the cycle. These will be displayed in order unless RandomiseOrder is set to true.
MaxPlayers	If the player count exceeds this value, the cycle will stop.	"MaxPlayers": 15
MinPlayers	If the player count is less than this value, the cycle will stop.	"MinPlayers": 5
RandomiseOrder	Sets whether messages should be displayed in a random order, or in sequence.	"RandomiseOrder": false
Loop	Sets whether to loop the message cycle, or run the cycle only once.	"Loop": true
StartedBy	An optional array of trigger names that will start this cycle. Available triggers are the same as those for TriggeredAdverts listed above, but also including STARTUP to indicate that the cycle should be automatically started.	"StartedBy": [ "START_OF_ROUND" ]
StartTriggerConfig	When using SYSTEM_TIME triggers, this should be a map of trigger type to its configuration.	"StartTriggerConfig": { "SYSTEM_TIME": { "TriggerTimes": [ "06:00" ] } }
StoppedBy	An optional array of trigger names that will stop this cycle. Triggers are the same as StartedBy.	"StoppedBy": [ "END_OF_ROUND" ]
StopTriggerConfig	Same as StartTriggerConfig, except providing configuration for stopping triggers.	"StopTriggerConfig ": { "SYSTEM_TIME": { "TriggerTimes": [ "06:05" ] } }

Player Count Restrictions

Note that the min/max player restrictions will automatically start/stop cycles with no triggers, but only automatically stop cycles that have triggers. When a cycle's trigger fires, the player count rules are evaluated too, meaning the cycle may not actually start.

Advert Options

Adverts should be a table with the keys listed below. Templates can be used to define the colours/prefix etc. for many adverts in one place. A template can provide any of the available options for an advert, but adverts may also override any of these values individually if desired.

For example:

{
    "Message": "Welcome to our awesome server!",
    "Colour": [ 255, 255, 255 ],
    "Type": "csay",
    "Position": "top",
    "GameState": [ "NotStarted", "WarmUp" ]
}

This would be an advert that is displayed at the top of the screen, rather than in the chat. Its colour is white, and it can only display when a round has not yet begun.

Available Options

Option	Description	Example
Message	The message to display. Some triggers will also provide placeholder values (see below). If the improved chat plugin is enabled, this can also be a list of colour/string pairs to create a rich text message (see below).	"Message": "This is an advert"
Colour	The (RGB) colour to give the message (not applicable if Message is rich text).	"Colour": [ 255, 255, 255 ]
Prefix	An optional prefix to display (not applicable if Message is rich text).	"Prefix": "[Info]"
PrefixColour	The colour to give the prefix (not applicable if Message is rich text).	"PrefixColour": [ 0, 200, 255 ]
ParseEmoji	Whether to parse emoji in the given message (only applicable if Message is rich text).	"ParseEmoji": true
Type	chat or csay. Only chat messages can use a prefix or be rich text.	"Type": "chat"
Position	If Type is csay, then one of bottom or top to control where on the screen the message displays.	"Position": "top"
Maps	A whitelist of maps that the advert can be displayed on.	"Maps": { "ns2_docking": true }
ExcludedMaps	A blacklist of maps that the message should not be displayed on.	"ExcludedMaps": { "ns2_docking": true }
GameState	The gamestate(s) to allow the message to display under. May be either a single state or a list of states, whose values may be: NotStarted WarmUp PreGame Countdown Started Team1Won Team2Won Draw	"GameState": [ "WarmUp", "NotStarted" ]
Team	The team(s) to display the message to. May be one of: MARINE ALIEN READY_ROOM SPECTATOR	"Team": [ "ALIEN", "MARINE" ]
MaxPlayers	If the player count exceeds this value, the advert will not be displayed.	"MaxPlayers": 15
MinPlayers	If the player count is less than this value, the advert will not be displayed.	"MinPlayers": 5
DelayInSeconds	The time to wait after the previous message has been displayed before displaying this message.	"DelayInSeconds": 30
TriggerTimes	When an advert is under SYSTEM_TIME in TriggeredAdverts, this is the list of dates/times to display the advert. The expected format for date/times is YYYY-MM-dd HH:mm:ss, and for times is HH:mm:ss, where seconds are optional.	"TriggerTimes": [ "06:00" ]

Player Count Restrictions

Triggered adverts will not display if their min/max player restrictions are not met. Adverts in a cycle that are not valid for the current player count will be skipped without causing a delay, and the cycle will keep skipping adverts until it finds one that is valid to display.

Placeholders

Some trigger events pass in values from the event that can be used in messages.

Trigger	Placeholders	Example
COMMANDER_LOGGED_IN	CommanderName	{CommanderName} is now the commander.
MARINE_COMMANDER_LOGGED_IN	CommanderName
ALIEN_COMMANDER_LOGGED_IN	CommanderName
COMMANDER_LOGGED_OUT	CommanderName	{CommanderName} is no longer the commander.
MARINE_COMMANDER_LOGGED_OUT	CommanderName
ALIEN_COMMANDER_LOGGED_OUT	CommanderName
COMMANDER_EJECTED	CommanderName	{CommanderName} was ejected.
MARINE_COMMANDER_EJECTED	CommanderName
ALIEN_COMMANDER_EJECTED	CommanderName

Rich Text Messages

When the improved chat plugin is enabled, advert messages can be defined as rich text, allowing for more than 2 colours.

For example, the following would display the given text in white, except the word "awesome" which would be green:

{
    "Message": [
        [ 255, 255, 255 ],
        "Welcome to our ",
        [ 0, 255, 0 ],
        "awesome",
        [ 255, 255, 255 ],
        "server!"
    ]
}

Each segment of text can use placeholders as with non-rich text messages.

If using a template, you can define a Message list in the template, and all of its values will be added to the start of every message that uses the template. For example, the following template will add a blue "[Info]" prefix to any rich text message:

"Templates": {
    "RichTextChatNotification": {
    	"Message": [ [ 0, 200, 255 ], "[Info] " ]
    }
}

To add emoji in messages, specify the ParseEmoji flag:

{
    "Message": [
        [ 255, 255, 255 ],
        "Welcome to our ",
        [ 0, 255, 0 ],
        "awesome",
        [ 255, 255, 255 ],
        "server! :waving_hand:"
    ],
    "ParseEmoji": true
}

This does not require ParseEmojiInChat to be enabled on the improved chat plugin.

Warning

Placeholders such as player names are applied before emoji is parsed. Be careful when enabling emoji on such messages as a player's name may contain text that will be parsed into an emoji.