# PronounsAdvanced V2: Major Rework - Removed old AI Generated picture and description and code blocks! Doing it all manually as I've learned and grown more :) - **Requires Java 25** instead of Java 17. - **Targets Paper 26.3** instead of older 1.21.x versions. - Split into proper **`pronouns-api`** and **`pronouns-paper`** Maven modules. - Replaced `plugin.yml` with **Paper's `paper-plugin.yml` + bootstrap system**. - Removed **Cloud Command Framework**. - Commands now use **native Paper Brigadier commands**. - Cleaner player command structure: - `/pronouns view [player]` - `/pronouns set <preset>` - `/pronouns custom` - `/pronouns mode` - `/pronouns clear` - `/pronouns menu` - `/pronouns admin ...` - `/pn` remains available as the short alias. - Removed old extra aliases such as `/pnp` and `/pnpaper`. ## GUI & Player Experience - Added a full **inventory GUI** for managing pronouns. - GUI supports: - Preset selection - Multiple pronoun sets - Custom pronouns - Pronoun ordering - Save/cancel - Pagination - GUI changes are **staged until Save**. - Closing or cancelling the GUI does not modify the profile. - GUI detects **stale edits** and prevents overwriting newer changes. - Preset GUI supports **27 presets per page** with previous/next navigation. - Added optional **Paper Dialog API** input for Java players. - Added private **chat-based custom pronoun input**. - Custom pronoun chat input is not broadcast to other players. - Added optional **Floodgate detection**. - Bedrock players automatically use the safe chat-input fallback. - Native Floodgate forms are **not currently implemented**. ## Pronoun Profile System - Replaced the old `List<PronounSet>` model with a proper immutable **`PronounProfile`**. - Added explicit profile modes: - `SETS` - `ANY` - `ASK_ME` - `NAME_ONLY` - `UNSET` - `Any`, `Ask`, and `Unset` are no longer fake they/them pronoun sets. - Added entirely new **Name Only** mode. - Pronoun sets now explicitly store: - Subject - Object - Possessive determiner - Possessive pronoun - Reflexive - Singular/plural grammatical agreement - Display name - Stable preset ID - Replaced the old `plural` boolean concept with explicit: - `SINGULAR` - `PLURAL` ## Presets & Custom Pronouns - Built-in presets remain: - he/him - she/her - they/them - it/its - Added administrator-defined custom presets through **`presets.yml`**. - Custom presets automatically work with: - `/pronouns set` - Tab completion - Admin editing - GUI preset selection - Built-in presets cannot be overwritten by custom presets. - Existing profiles remain valid even if their preset is later removed. - Added configurable custom-pronoun policy: - Maximum sets - Maximum field length - Unicode allowed/disabled - Blocked values - Enable/disable custom pronoun creation - Existing custom profiles remain readable even if custom creation is later disabled. ## Parser & Validation - Completely redesigned the pronoun parser. - Invalid input now produces structured errors. - **No more silent partial saves**. - If one set in a multi-set input is invalid, the entire input fails. - Still supports familiar formats: - `she/her` - `they/them` - `she/they` - `she/her;they/them` - Five-part custom pronouns - `:p` for plural agreement - `:s` for explicit singular agreement - Added centralized custom-pronoun validation. - Rejects: - Blank required fields - Control characters - Invalid delimiters - Oversized fields - Unicode and non-English pronouns remain supported by default. - Player input is always treated as plain text. ## Storage - **SQLite is now the default storage backend**. - Old `.properties` storage is no longer the recommended production backend. - SQLite uses a structured relational schema. - Profiles are no longer stored as one serialized slash/semicolon string. - SQLite stores: - Player UUID - Profile mode - Revision - Ordered pronoun sets - Individual grammatical forms - Added schema versioning. - Added transactional storage operations. - Added safe database shutdown. ## MySQL / MariaDB - Completely rebuilt MySQL support. - Uses modern **HikariCP** connection pooling. - Includes the MySQL JDBC driver in the final plugin JAR. - Added unique random server-instance IDs. - Removed the old hardcoded `pronouns_plugin_instance`. - Added profile revisions. - Added compare-and-swap conflict protection. - Two servers can no longer silently overwrite the same profile revision. - Added revision-safe profile deletion. - Added deletion tombstones. - Stale servers cannot delete newer data. - Stale servers cannot resurrect profiles that were deleted more recently. - Added transactional **cross-server change logging**. - Added asynchronous network synchronization. - Remote cache changes are applied in sequence order. - Failed remote refreshes are retried. - Cross-server polling shuts down cleanly. - MySQL/MariaDB storage supports offline profiles. ## Caching & Concurrency - Added thread-safe immutable profile caching. - PlaceholderAPI only reads from memory. - Older async writes cannot overwrite newer changes. - Operations for each player are processed in submission order. - Failed persistence operations do not leave unsaved data in cache. - Storage conflicts reload the authoritative profile. - GUI saves use revision checks to avoid overwriting remote/admin changes. ## Migration - Old storage systems are now treated as **migration sources** instead of permanent production backends. - Supports migration from: - Legacy YAML - Legacy `.properties` - Legacy MySQL - PersistentDataContainer / PDC - Added migration dry-run support. - Migration does not delete or modify the old source data. - Migration reports: - Imported profiles - Skipped profiles - Invalid profiles - Warnings - Migration is designed to be safe to rerun. - Existing target profiles are protected from accidental overwrite. - Old `Any`, `Ask`, and `Unset` values convert into proper V2 profile modes. ## Export - Replaced the old `/dump` system with: - `/pronouns admin export` - Exports profiles to structured **JSON**. - Works regardless of whether SQLite or MySQL is being used. - Database credentials are never included. ## Commands - Replaced Cloud commands with native Paper Brigadier commands. - Player commands: - `/pronouns view [player]` - `/pronouns set <preset>` - `/pronouns custom [pronouns]` - `/pronouns mode <mode>` - `/pronouns clear` - `/pronouns menu` - Admin commands: - `/pronouns admin edit <player> ...` - `/pronouns admin export` - `/pronouns admin migrate` - `/pronouns admin reload` - `/pronouns admin debug` - Offline players can be administered by UUID or cached player name. - Removed the old `--player` editing system. - Removed dedicated `/list`, `/version`, `/update`, and `/dump` workflows where newer systems replace them. ## Permissions - New permission structure includes: - `pronouns.use` - `pronouns.view` - `pronouns.set` - `pronouns.custom` - `pronouns.mode` - `pronouns.admin` - `pronouns.admin.edit` - `pronouns.admin.export` - `pronouns.admin.migrate` - `pronouns.admin.reload` - `pronouns.admin.debug` - Admin permissions default to OP. - Normal player permissions default to enabled. - Existing V1 LuckPerms permissions may need updating. ## PlaceholderAPI - PlaceholderAPI support remains. - Placeholder resolution is **cache-only** and never directly queries SQLite/MySQL. - Added modern placeholders including: - `%pronouns_display%` - `%pronouns_mode%` - `%pronouns_subjective%` - `%pronouns_objective%` - `%pronouns_possessive%` - `%pronouns_possessive_pronoun%` - `%pronouns_reflexive%` - `%pronouns_be%` - `%pronouns_have%` - `%pronouns_count%` - `%pronouns_set_count%` - Supports modern indexed placeholders: - `%pronouns_2_subjective%` - Legacy indexed format remains supported: - `%pronouns_subjective_2%` - Legacy modifiers remain available: - `capital` - `uppercase` - `lowercase` - `nounset` - Legacy verb/conjugation placeholders remain supported. - Important change: - `%pronouns_possessive%` now returns `her/their` - `%pronouns_possessive_pronoun%` returns `hers/theirs` - Important change: - `%pronouns_all%` now returns readable display text instead of the full serialized five-part representation. - Placeholder behavior for `ANY`, `ASK_ME`, `NAME_ONLY`, and `UNSET` is configurable. ## Public Developer API - Added a dedicated **`pronouns-api`** module. - Added `PronounsService`. - API supports: - Cached profile reads - Async profile loads - Async profile saves - Async profile clears - API is registered using Bukkit's **ServicesManager**. - Added convenience API access through: - `PronounsApi.get()` - `PronounsApi.find()` - Storage implementation details are no longer exposed through the public API. - API models are immutable. ## Events - Added `PronounProfileChangeEvent`. - Added `PronounProfileChangedEvent`. - Before-change event can be cancelled by another plugin. - After-change event only fires after a successful storage mutation. - Profile clears also participate in the change-event system. - Other plugins can safely react to profile changes without depending on internal storage code. ## Configuration - Replaced `pronouns.cfg` with: - `config.yml` - `messages.yml` - `presets.yml` - Added schema versions to configuration files. - `/pronouns admin reload` reloads safe runtime settings. - Storage backend changes require a restart instead of being hot-swapped. - Invalid reloads keep the previous working configuration. - Added configuration for: - GUI - Custom pronouns - Dialog API - Floodgate detection - Metrics - Update checker - Placeholder fallback behavior - MySQL synchronization ## Messages - Most player-facing chat messages are customizable in **`messages.yml`**. - Uses MiniMessage for administrator-created templates. - Player names and pronoun values are inserted as plain text. - Player-controlled text cannot inject: - Colors - Click events - Hover events - MiniMessage tags - GUI copy is centralized, although the inventory GUI itself remains English-only. ## Security - Added centralized security rules for player input. - Protected against MiniMessage injection. - SQL uses prepared statements. - Database credentials are never logged. - Pronoun values are not written to normal plugin logs. - Migration warnings do not expose raw pronoun values. - GUI uses custom inventory holders rather than matching titles. - GUI protects against: - Shift-click - Number-key swaps - Offhand swaps - Double-click - Dragging - Creative clone actions - Item drops - Permissions are checked server-side rather than relying on GUI visibility. - Exports use internally generated paths to prevent path traversal. ## Update Checker - Update checks are now fully asynchronous. - Server startup is no longer blocked by HTTP requests. - Update checker performs actual version comparison. - Pre-release/version formatting is handled properly. - Old manual `/pronouns update` command is no longer needed. ## Lifecycle & Shutdown - Added explicit shutdown handling. - On shutdown V2: - Closes GUI sessions - Cancels custom-input sessions - Unregisters PlaceholderAPI - Unregisters the public API - Stops metrics - Stops MySQL synchronization - Flushes pending writes - Closes database pools - Stops executors - Clears caches - V1 did not have comparable complete shutdown handling. ## Important Upgrade Notes - **Java 25 is required.** - **Paper 26.3 is required.** - V1 configuration does not directly carry over to the new YAML configuration structure. - V1 permission nodes may need updating in LuckPerms. - V1's developer API has been replaced by the new V2 API. - Existing V1 data should be imported using the migration commands. - SQLite is now the recommended/default backend. - PDC/NBT is migration-only. - `%pronouns_possessive%` changed meaning. - `%pronouns_all%` changed output format. - `/pronouns get` became `/pronouns view`. - Raw custom values should use `/pronouns custom` instead of `/pronouns set`. - Editing another player's profile now uses `/pronouns admin edit`. - Native Bedrock forms are not implemented; Bedrock uses chat fallback. - V2 is a **major rewrite**, not a drop-in patch for V1.

First Publish!