From 789fc4eb8acfcd61e4876fdc638e246058a1ece5 Mon Sep 17 00:00:00 2001 From: TheMeinerLP Date: Wed, 28 Oct 2026 20:38:14 +0100 Subject: [PATCH 1/2] docs(openspec): propose polish-plugin-messages --- .../changes/polish-plugin-messages/design.md | 38 ++++++++++++++++ .../polish-plugin-messages/proposal.md | 44 +++++++++++++++++++ .../specs/velocity-plugin/spec.md | 33 ++++++++++++++ .../changes/polish-plugin-messages/tasks.md | 23 ++++++++++ 4 files changed, 138 insertions(+) create mode 100644 openspec/changes/polish-plugin-messages/design.md create mode 100644 openspec/changes/polish-plugin-messages/proposal.md create mode 100644 openspec/changes/polish-plugin-messages/specs/velocity-plugin/spec.md create mode 100644 openspec/changes/polish-plugin-messages/tasks.md diff --git a/openspec/changes/polish-plugin-messages/design.md b/openspec/changes/polish-plugin-messages/design.md new file mode 100644 index 0000000..faf41a1 --- /dev/null +++ b/openspec/changes/polish-plugin-messages/design.md @@ -0,0 +1,38 @@ +# Design + +## Context + +All player-facing texts are MiniMessage templates in `lang/messages_en.properties` and `lang/messages_de.properties`, +rendered by `i18n/Messages`, which chooses German for a `de` client locale and English otherwise. Placeholders are +filled as unparsed text, so player names can never inject formatting. + +## Decisions + +### 1. Palette as MiniMessage tags in the bundles + +Colours stay in the templates (no Java constants), so translations and operator overrides can restyle them. The +palette: brand gradient `#7c3aed → #db2777` (prefix, headers), commands `#c4b5fd`, arguments `#a78bfa`, text +`gray`, separators `dark_gray` (`»`, `•`), success `#86efac`, errors `#fca5a5`, hints `#fde68a`, leader `gold` with +`★`. A short colour guide at the top of the English bundle documents it. + +### 2. Clickable help + +Each help line uses `` and ``; the hover text is its own +key (`command.help..hover`), so it is translated with the rest. The help title gets a separator line. + +### 3. Locale resolution and overrides + +Bundles are looked up as `language_COUNTRY`, then `language`, then `en`. Built-in bundles come from the classpath; +files named `messages_.properties` in `plugins/quelea/lang/` (read once at start-up) are merged key by key over +the built-in bundle of the same tag or form a new language. A key missing in the chosen bundle falls back to the +English key, so a partial translation never shows a raw key. + +Rejected: Adventure's `GlobalTranslator` with `TranslatableComponent` (it renders on the server per viewer, but +MiniMessage placeholders and click events in translations need a custom translator anyway, and the existing +per-locale rendering already does the job); hot reload of override files (a proxy restart is the normal way to apply +template changes). + +## Risks / Trade-offs + +- Operators can break a message with invalid MiniMessage in an override; the plugin logs the key and falls back to + the built-in English text instead of sending nothing. diff --git a/openspec/changes/polish-plugin-messages/proposal.md b/openspec/changes/polish-plugin-messages/proposal.md new file mode 100644 index 0000000..aedb7cd --- /dev/null +++ b/openspec/changes/polish-plugin-messages/proposal.md @@ -0,0 +1,44 @@ +# Proposal + +**Ships as:** `feat(velocity)`: one code pull request `feat(velocity): give party messages colour, clickable help and open translations`. + +## Why + +The first test on the team proxy showed that the party messages work but look flat: the help is a grey wall of +text, commands cannot be clicked, and success, failure and hints look alike. Players should see at a glance what +happened and be able to click a command instead of typing it. + +Translations are fixed to English and German inside the jar. Adding a language or adjusting a colour needs a new +release, although the texts are plain MiniMessage templates that operators could adapt in the proxy template. + +## What Changes + +- **A consistent palette** across all messages: the existing violet-to-pink brand gradient for headers and the + prefix, light violet for commands, grey for explanations, green for success, red for errors, amber for hints, + gold with a star for the leader. +- **Clickable help:** every line of `/party` help suggests its command on click and explains it on hover; arguments + are shown in a second colour. +- **Richer feedback:** invites with hover texts on [Accept] and [Deny], the member list with leader marker and + online hint, the party chat with its own prefix and a coloured sender name. +- **Open translations:** the plugin picks the bundle for the client locale (`de_DE` → `de` → `en`) from any + `messages_.properties` it ships or finds in `plugins/quelea/lang/`; a file there overrides single keys of + the built-in bundle, missing keys fall back to English. Operators can add a language or recolour a message + without a release. + +## Capabilities + +### New Capabilities +None. + +### Modified Capabilities +- `velocity-plugin`: message presentation and translations. + +## Out of Scope + +- Redirecting normal chat into the party chat with a prefix (`@`) or a toggle. It needs SignedVelocity on the + proxies and a Minestom implementation of its backend part, and comes as its own change. +- New languages beyond English and German in the jar. + +## Impact + +- Plugin only: message bundles, the `Messages` loader, command help and event handler rendering, tests. diff --git a/openspec/changes/polish-plugin-messages/specs/velocity-plugin/spec.md b/openspec/changes/polish-plugin-messages/specs/velocity-plugin/spec.md new file mode 100644 index 0000000..57cb01e --- /dev/null +++ b/openspec/changes/polish-plugin-messages/specs/velocity-plugin/spec.md @@ -0,0 +1,33 @@ +# Spec Delta + +## Purpose +The proxy side: commands, messages, presence reporting and the event consumer. + +## ADDED Requirements + +### Requirement: Clickable help +The plugin SHALL render every `/party` help line so that clicking it suggests the command in the chat input and hovering explains it in the player's language. + +#### Scenario: Click on invite +- **WHEN** a player clicks the help line of `/party invite` +- **THEN** their chat input contains `/party invite ` + +### Requirement: Message palette +The plugin SHALL colour messages by meaning: the brand gradient for the prefix and headers, green for successful actions, red for errors and problems, amber for hints, and gold with a star for the party leader. + +#### Scenario: Problem shown in red +- **WHEN** a command fails with `party-full` +- **THEN** the player reads the translated problem text in red after the party prefix + +### Requirement: Translations from bundles and overrides +The plugin SHALL choose the message bundle for the client locale by language and country, then language, then English, SHALL merge `messages_.properties` files from `plugins/quelea/lang/` over the built-in bundles key by key, and SHALL fall back to the English text for any key missing in the chosen bundle or whose template cannot be parsed. + +#### Scenario: Operator adds French +- **GIVEN** `plugins/quelea/lang/messages_fr.properties` translates only `party.joined` +- **WHEN** a player with locale `fr_FR` sees a join and a disband +- **THEN** the join is French and the disband is English + +#### Scenario: Override recolours a message +- **GIVEN** `plugins/quelea/lang/messages_de.properties` overrides `prefix` +- **WHEN** a German player receives any message +- **THEN** it starts with the overridden prefix and the other texts are the built-in German ones diff --git a/openspec/changes/polish-plugin-messages/tasks.md b/openspec/changes/polish-plugin-messages/tasks.md new file mode 100644 index 0000000..12a3144 --- /dev/null +++ b/openspec/changes/polish-plugin-messages/tasks.md @@ -0,0 +1,23 @@ +# Tasks + +## 1. Translations + +- [ ] 1.1 `Messages`: locale resolution `language_COUNTRY` → `language` → `en`, per-key fallback to English, override + directory `plugins/quelea/lang/` merged over built-in bundles, invalid templates fall back with one log line. +- [ ] 1.2 Tests with a `@TempDir` override directory (new language, partial override, broken template). + +## 2. Presentation + +- [ ] 2.1 Palette applied to all keys in `messages_en.properties` and `messages_de.properties`, with a colour guide + comment. +- [ ] 2.2 Clickable and hoverable help lines (`command.help..hover` keys). +- [ ] 2.3 Invite buttons with hover, member list with leader star, party chat format. +- [ ] 2.4 Bundle tests: every bundle has the English key set, every template parses, help lines carry click events. + +## 3. Documentation + +- [ ] 3.1 README: how to add a language or override a message in the proxy template. + +## 4. Pull request + +- [ ] 4.1 Open the code pull request `feat(velocity): give party messages colour, clickable help and open translations`. From 4ba31af457a7009cfdccbb2ac3f611e97ff96d98 Mon Sep 17 00:00:00 2001 From: TheMeinerLP Date: Wed, 28 Oct 2026 20:38:38 +0100 Subject: [PATCH 2/2] docs(openspec): avoid duplicate messages in polish-plugin-messages --- .../changes/polish-plugin-messages/proposal.md | 3 +++ .../specs/velocity-plugin/spec.md | 16 ++++++++++++++++ openspec/changes/polish-plugin-messages/tasks.md | 14 ++++++++++---- 3 files changed, 29 insertions(+), 4 deletions(-) diff --git a/openspec/changes/polish-plugin-messages/proposal.md b/openspec/changes/polish-plugin-messages/proposal.md index aedb7cd..e2daf7c 100644 --- a/openspec/changes/polish-plugin-messages/proposal.md +++ b/openspec/changes/polish-plugin-messages/proposal.md @@ -20,6 +20,9 @@ release, although the texts are plain MiniMessage templates that operators could are shown in a second colour. - **Richer feedback:** invites with hover texts on [Accept] and [Deny], the member list with leader marker and online hint, the party chat with its own prefix and a coloured sender name. +- **One message per outcome:** today the actor reads both the command answer and the event ("Party created" plus + "X created the party", "You joined the party" twice). The actor gets the command answer only; a second click on an + old [Accept] says "already in this party". - **Open translations:** the plugin picks the bundle for the client locale (`de_DE` → `de` → `en`) from any `messages_.properties` it ships or finds in `plugins/quelea/lang/`; a file there overrides single keys of the built-in bundle, missing keys fall back to English. Operators can add a language or recolour a message diff --git a/openspec/changes/polish-plugin-messages/specs/velocity-plugin/spec.md b/openspec/changes/polish-plugin-messages/specs/velocity-plugin/spec.md index 57cb01e..90670c2 100644 --- a/openspec/changes/polish-plugin-messages/specs/velocity-plugin/spec.md +++ b/openspec/changes/polish-plugin-messages/specs/velocity-plugin/spec.md @@ -31,3 +31,19 @@ The plugin SHALL choose the message bundle for the client locale by language and - **GIVEN** `plugins/quelea/lang/messages_de.properties` overrides `prefix` - **WHEN** a German player receives any message - **THEN** it starts with the overridden prefix and the other texts are the built-in German ones + +### Requirement: One message per outcome +The plugin SHALL tell the player who ran a command about its outcome exactly once: the command's own answer goes to the actor, and the matching party event SHALL NOT notify the actor again; other members are notified by the event only. + +#### Scenario: Create +- **WHEN** a player creates a party +- **THEN** they read one confirmation with the invite hint and no second "created the party" line + +#### Scenario: Accept +- **WHEN** a player accepts an invite +- **THEN** they read "You joined the party." once, and the other members read that the player joined + +#### Scenario: Accept again +- **GIVEN** a player already joined the party that invited them +- **WHEN** they click the old [Accept] button again +- **THEN** they read that they are already in that party instead of "no pending invites" diff --git a/openspec/changes/polish-plugin-messages/tasks.md b/openspec/changes/polish-plugin-messages/tasks.md index 12a3144..15c6623 100644 --- a/openspec/changes/polish-plugin-messages/tasks.md +++ b/openspec/changes/polish-plugin-messages/tasks.md @@ -14,10 +14,16 @@ - [ ] 2.3 Invite buttons with hover, member list with leader star, party chat format. - [ ] 2.4 Bundle tests: every bundle has the English key set, every template parses, help lines carry click events. -## 3. Documentation +## 3. Duplicates -- [ ] 3.1 README: how to add a language or override a message in the proxy template. +- [ ] 3.1 The actor of `create`, `accept`, `deny`, `leave`, `kick`, `promote`, `disband` gets only the command answer; + event notifications skip the actor (handler tests with fakes). +- [ ] 3.2 A repeated accept for the party the player is already in answers "already in this party". -## 4. Pull request +## 4. Documentation -- [ ] 4.1 Open the code pull request `feat(velocity): give party messages colour, clickable help and open translations`. +- [ ] 4.1 README: how to add a language or override a message in the proxy template. + +## 5. Pull request + +- [ ] 5.1 Open the code pull request `feat(velocity): give party messages colour, clickable help and open translations`.