diff --git a/docs/modules/mechanics/actions-triggers.mdx b/docs/modules/mechanics/actions-triggers.mdx index 3f6a03de..4932217e 100644 --- a/docs/modules/mechanics/actions-triggers.mdx +++ b/docs/modules/mechanics/actions-triggers.mdx @@ -60,7 +60,9 @@ In the future, some features that are currently used in Kits may be transferred | `times` | The amount of time to repeat.
*Non-whole numbers will be rounded down. Negative numbers will cause no iterations.* | Expression | | `filter` | Filters when this loop should be active. This will be checked as many time as the loop is ran. | [Filter](/docs/modules/mechanics/filters) | -### Message Attributes +### Message + +#### Attributes | Attribute | Description | Value | Default | |---|---|---|---| @@ -72,39 +74,10 @@ In the future, some features that are currently used in Kits may be transferred | `stay` | How long the title and subtitle text will display for. | [Time Period](/docs/reference/misc/time-periods) | 3.5s | | `fade-out` | How long the title and subtitle text will fade out. | [Time Period](/docs/reference/misc/time-periods) | 1s | -#### Replacements - -| Element | Description | Value | -|---|---|---| -| `` | A list of replacements.
**Note:** In the future, more replacements will be supported. | Replacements Sub-elements | - -| Sub-element | Description | -|---|---| -| `` | A numerical placeholder. | -| `` | A player's name placeholder. | - -##### Decimal Attributes - -| Attribute | Description | Value | +#### Sub-elements +| Sub-element | Description | Value | |---|---|---| -| `id` | Unique identifier used to reference this decimal placeholder from other places in the XML. | String | -| `value` | RequiredThe variable this decimal should evaluate. It can be used with formulas. | Expression | -| `format` | Customize how the decimal should be displayed, e.g. `#.00`. | [Java DecimalFormat pattern](https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html) | - -##### Player Attributes - -| Attribute | Description | Value | Default | -|---|---|---|---| -| `id` | RequiredUnique identifier used to reference this player placeholder from other places in the XML. | String | -| `var` | RequiredThe exclusive player-scoped variable to check for. | [Variable](/docs/modules/mechanics/variables) | -| `style` | The style to display the player's name in. | `plain`, `color`,
`fancy`, `verbose` | `verbose` | -| `fallback` | If no player has been assigned this variable, set the text to display instead. | String | - -###### Style Examples - -| Description | Example | -|---|:---:| -| `plain` - no formatting at all.
`simple_color` **(discouraged)** - team color formatting without click-to-teleport hover.
`color` **(recommended for chat)** - the player's name with team color with click-to-teleport hover.
`fancy` - contains fancy formatting, flairs (prefix/suffix/etc), colors, and click-to-teleport hover.
`tab` **(discouraged)** - formatted as a tablist entry with team color, flairs, death status, self, etc.
`verbose` - like `fancy`, but includes full nickname of nicked users to server operators and friends. | ![Unnicked player placeholder in chat](/img/modules/player-replacement-action-chat-unnicked.png 'Unnicked player placeholder in chat')
![Server operator perspective of the player placeholder in chat](/img/modules/player-replacement-action-chat-op.png 'Server operator perspective of the player placeholder in chat') | +| `` | A list of replacements. They can be referred to in the message text using curly braces (`{replacement-id}`). | [Replacements](#replacements) | ### Sound Attributes @@ -268,6 +241,117 @@ _Example_ ``` +## Replacements + +export const ScopedBadge = () => Scoped + +### Replacement Types +| Type | Description | +|---|---| +| [``](#decimal-replacement) | A numerical placeholder. | +| [``](#player-replacement) | A player's name placeholder. | +| [``](#switch-replacement) | A switch-case replacement. | +| [``](#replacement-reference) | A reference to a replacement in the global registry. | + +### Global Replacement Registry +Replacements can be defined globally by including them in `` in the root `` element. In that case, defining a scope for scoped replacements is required: + +```xml + + + + + + + + + +``` + +Globally-defined replacements can be accessed in message actions using the [`` element](#replacement-reference). + +### Decimal Replacement +Displays a numerical value according to the provided format. + +#### Attributes + +| Attribute | Description | Value | +|---|---|---| +| `id` | Unique identifier used to reference this decimal placeholder from other places in the XML. | String | +| `value` | RequiredThe variable this decimal should evaluate. It can be used with formulas. | Expression | +| `format` | Customize how the decimal should be displayed, e.g. `#.00`. | [Java DecimalFormat pattern](https://docs.oracle.com/javase/8/docs/api/java/text/DecimalFormat.html) | + +### Player Replacement +Displays the name of a player who has an exclusive player-scoped variable assigned to them. + +#### Attributes + +| Attribute | Description | Value | Default | +|---|---|---|---| +| `id` | RequiredUnique identifier used to reference this player placeholder from other places in the XML. | String | +| `var` | RequiredThe exclusive player-scoped variable to check for. | [Variable](/docs/modules/mechanics/variables) | +| `style` | The style to display the player's name in. | [Player Replacement Style](#player-replacement-styles) | `verbose` | +| `fallback` | If no player has been assigned this variable, set the text to display instead. | String | + +#### Player Replacement Styles + +import PlayerComponent, { PlayerStyle } from "@site/src/components/PlayerComponent.tsx"; + +| Type | Description | Example | Example (server operator view) | +|---|---|---|---| +| `plain` | Displays the player name without any formatting. | | | +| `simple_color` | Displays the player name with team color formatting. **Using this style is discouraged.** | | | +| `color` | Displays the player name with team color, and a click-to-teleport action. **Recommended for chat messages.** | | | +| `fancy` | Displays the player name with team color, a click-to-teleport action, flairs (prefix, suffix, etc.), and fancy formatting. | | | +| `tab` | Displays the player name formatted as a tab list entry with team color, flairs, death status, self-highlighting, etc. **Using this style is discouraged.** | | | +| `verbose` | Displays the player name in a manner similar to `fancy`, along with an alternative nickname (if present) to server operators and friends of the player. | | | + +### Switch Replacement +Selects the first matching value from a list of candidate case branches. + +```xml + + + + + + + + +``` +#### Attributes +| Attribute | Description | Type | +|---|---|---| +| `id` | RequiredUnique identifier used to reference this switch replacement from other places in the XML. | String | +| `value` | PropertyAn optional value to match against in individual switch cases. Formulas are supported. | Expression | + +#### Sub-elements +| Sub-element | Description | Type | +|---|---|---| +| `` | Case branches to match against. | [Case Branch](#case-branch-properties) | +| `` | The fallback text to display if none of the `` branches match. Defaults to empty text. | Formatted Text | + +#### Case Branch Properties +A case branch describes the requirements for the text to be displayed. At least one of the `match` and `filter` properties must be specified. If both are specified, the filter acts as a "case guard" – meaning that the case branch will match only if the value matches the range specified by `match` and the `filter` allows. + +| Property | Description | Type | +|---|---|---| +| `match` | PropertyThe value to match against. | Number Range | +| `filter` | PropertyThe filter to match against.
Requiredif `value` is not specified in the parent `` element. | [Filter](/docs/modules/mechanics/filters) | +| `result` | PropertyRequiredThe text to display when matched. | Formatted Text | + +### Replacement Reference +Refers to a replacement in the global registry. Takes in an `id` attribute, which serves as the local identifier of the replacement to be used in message text, and the [global replacement ID](#global-replacement-registry) as an inner value. + +```xml + + + global-id +
+ +``` + + ## Examples ### Enabling Blitz Mode diff --git a/src/components/PlayerComponent.module.css b/src/components/PlayerComponent.module.css new file mode 100644 index 00000000..e1369fc0 --- /dev/null +++ b/src/components/PlayerComponent.module.css @@ -0,0 +1,11 @@ +.PlayerComponent span { + margin-right: 0; /* Remove the span padding in tables that comes from the main CSS */ +} + +.PlayerComponent--team-color { + color: var(--team-color); +} + +.PlayerComponent__rank { + color: var(--ifm-color-primary); +} diff --git a/src/components/PlayerComponent.tsx b/src/components/PlayerComponent.tsx new file mode 100644 index 00000000..cd336005 --- /dev/null +++ b/src/components/PlayerComponent.tsx @@ -0,0 +1,61 @@ +import clsx from "clsx"; +import styles from "./PlayerComponent.module.css"; + +export enum PlayerStyle { + Plain, + SimpleColor, + Color, + Fancy, + Tab, + Verbose, +} + +interface PlayerComponentProps { + /** The player style to display */ + style: PlayerStyle; + /** Whether to render the component from the view of the server operator */ + isOp?: boolean; + /** The username of the player */ + username?: string; + /** The alternative nickname of the player (shown only if isOp is true) */ + nickname?: string; + /** The flair to display */ + flair?: JSX.Element; + /** The team color of the player */ + teamColor?: string; +} + +declare module "csstype" { + interface Properties { + "--team-color"?: string; + } +} + +export default function PlayerComponent({ + style, + isOp = false, + username = "username", + nickname = "nickname", + flair = *, + teamColor = "var(--ifm-color-info-darkest)", +}: PlayerComponentProps = { + style: PlayerStyle.Color, +}) { + return (
= PlayerStyle.SimpleColor && styles["PlayerComponent--team-color"] + )} style={{ + "--team-color": teamColor, + }}> + {style >= PlayerStyle.Fancy && flair} + = PlayerStyle.Fancy && nickname ? "line-through" : undefined, + fontWeight: style === PlayerStyle.Tab ? "bold" : undefined, + }} + title={style >= PlayerStyle.Color && style !== PlayerStyle.Tab ? `Teleport to ${username}` : ""}> + {username} + + {isOp && style === PlayerStyle.Verbose && nickname && <> {nickname}} +
); +}