diff --git a/content/docs/multification/advanced.mdx b/content/docs/multification/advanced.mdx new file mode 100644 index 00000000..20d1a9b4 --- /dev/null +++ b/content/docs/multification/advanced.mdx @@ -0,0 +1,112 @@ +--- +title: Advanced Features +description: i18n, custom formatters, and platform adapters +icon: Sparkles +sidebar_position: 6 +--- + +## Internationalization (i18n) + +```java +public class MyMultification extends PaperMultification { + private final Map translations; + + @Override + protected TranslationProvider translationProvider() { + return locale -> translations.getOrDefault(locale, translations.get(Locale.ENGLISH)); + } + + @Override + protected LocaleProvider localeProvider() { + return viewer -> viewer instanceof Player p ? p.locale() : Locale.ENGLISH; + } +} + +// Load translations +Map translations = new HashMap<>(); +translations.put(Locale.ENGLISH, loadConfig("messages_en.yml")); +translations.put(new Locale("pl"), loadConfig("messages_pl.yml")); +``` + + + Messages are automatically sent in player's language based on their client locale. + + +## Global Replacer + +Apply transformations to all messages: + +```java +@Override +protected Replacer globalReplacer() { + return (viewer, text) -> { + text = text.replace("{server}", "MyServer"); + + // PlaceholderAPI integration + if (viewer instanceof Player player) { + text = PlaceholderAPI.setPlaceholders(player, text); + } + + return text; + }; +} +``` + +## Custom Notice Types + + + + ```java + public class HologramContent implements NoticeContent { + private final String text; + private final Location location; + // ... + } + ``` + + + ```java + public class HologramResolver implements NoticeResolver { + private static final NoticeKey KEY = + new NoticeKeyImpl<>("hologram", HologramContent.class); + + @Override + public void send(Audience audience, ComponentSerializer serializer, HologramContent content) { + // Create hologram + } + + @Override + public NoticeSerdesResult serialize(HologramContent content) { ... } + + @Override + public Optional deserialize(NoticeSerdesResult result) { ... } + } + ``` + + + ```java + this.noticeRegistry.registerResolver(new HologramResolver()); + ``` + + + +## Performance Tips + +```java +// ✅ Batch sending +multification.create() + .players(playerList) + .notice(config -> config.message) + .send(); + +// ❌ Individual sends +for (UUID uuid : players) { + multification.create().player(uuid).notice(...).send(); +} + +// ✅ Async for heavy operations +multification.create() + .all() + .notice(config -> config.heavyMessage) + .sendAsync(); +``` diff --git a/content/docs/multification/api-reference.mdx b/content/docs/multification/api-reference.mdx new file mode 100644 index 00000000..7e8a5329 --- /dev/null +++ b/content/docs/multification/api-reference.mdx @@ -0,0 +1,108 @@ +--- +title: API Reference +description: Complete API documentation +icon: Book +sidebar_position: 7 +--- + +## Core Classes + +### Multification + +```java +public abstract class Multification +``` + +**Abstract methods (must override):** +- `viewerProvider()` – provides players/console +- `translationProvider()` – provides config for locale +- `audienceConverter()` – converts viewer to Adventure Audience + +**Optional overrides:** +- `serializer()` – default: `PlainComponentSerializer` (use MiniMessage) +- `globalReplacer()` – default: no-op +- `asyncExecutor()` – default: sync execution +- `localeProvider()` – default: `Locale.ROOT` + +### Notice + +```java +// Static factories +Notice.chat(String... messages) +Notice.title(String title, String subtitle) +Notice.actionbar(String message) +Notice.sound(String key, float volume, float pitch) +Notice.bossBar(BossBar.Color color, Duration duration, String message) +Notice.empty() + +// Builder +Notice.builder() + .chat("...") + .title("...", "...") + .actionBar("...") + .sound("...") + .bossBar(...) + .build() +``` + +### NoticeBroadcast + +```java +multification.create() + // Target + .player(UUID) + .players(Iterable) + .viewer(VIEWER) + .console() + .all() + .onlinePlayers() + .onlinePlayers(String permission) + + // Notice + .notice(Notice) + .notice(config -> config.message) + + // Placeholders + .placeholder("{key}", "value") + + // Formatters + .formatter(Formatter...) + + // Send + .send() + .sendAsync() +``` + +## Functional Interfaces + +```java +// Extract notice from config +NoticeProvider = translation -> Notice + +// Format text +Formatter = (viewer, text) -> String + +// Replace text globally +Replacer = (viewer, text) -> String + +// Get locale for viewer +LocaleProvider = viewer -> Locale + +// Convert viewer to Audience +AudienceConverter = viewer -> Audience + +// Get config for locale +TranslationProvider = locale -> T +``` + +## Serializers + +```java +// CDN +new MultificationNoticeCdnComposer(multification) +new MultificationNoticeCdnComposer(noticeRegistry) + +// Okaeri +new MultificationSerdesPack(multification) +new MultificationSerdesPack(noticeRegistry) +``` diff --git a/content/docs/multification/basic-usage.mdx b/content/docs/multification/basic-usage.mdx new file mode 100644 index 00000000..9d8b394c --- /dev/null +++ b/content/docs/multification/basic-usage.mdx @@ -0,0 +1,170 @@ +--- +title: Basic Usage +description: Learn the fundamentals of sending messages with Multification +icon: BookOpen +sidebar_position: 3 +--- + +## Creating Multification + + + + ```java + public class MyMultification extends PaperMultification { + private final MessagesConfig config; + + public MyMultification(MessagesConfig config) { + this.config = config; + } + + @Override + protected TranslationProvider translationProvider() { + return locale -> this.config; + } + + @Override + protected ComponentSerializer serializer() { + return MiniMessage.miniMessage(); + } + + @Override + protected AudienceConverter audienceConverter() { + return commandSender -> commandSender; // CommandSender IS Audience + } + } + ``` + + + ```java + public class MyMultification extends BukkitMultification { + private final MessagesConfig config; + private final AudienceProvider audienceProvider; + + public MyMultification(Plugin plugin, MessagesConfig config) { + this.config = config; + this.audienceProvider = BukkitAudiences.create(plugin); + } + + @Override + protected TranslationProvider translationProvider() { + return locale -> this.config; + } + + @Override + protected ComponentSerializer serializer() { + return MiniMessage.miniMessage(); + } + + @Override + protected AudienceConverter audienceConverter() { + return sender -> sender instanceof Player p + ? audienceProvider.player(p.getUniqueId()) + : audienceProvider.console(); + } + } + ``` + + + +## Creating Notices + + + This section shows the **Java API**. If you're configuring messages in YAML, jump to the [Configuration guide](/docs/multification/configuration) or the + [Format guide (for users)](/docs/multification/format). + + +```java +// Simple chat +Notice chat = Notice.chat("Hello!"); + +// Multiple lines +Notice lines = Notice.chat("Line 1", "Line 2"); + +// Title +Notice title = Notice.title("Welcome!", "Subtitle"); + +// ActionBar +Notice actionbar = Notice.actionbar("⚠ Warning!"); + +// Combined (builder) +Notice complex = Notice.builder() + .chat("You received a reward!") + .title("Reward", "Check inventory") + .actionBar("+$1000") + .sound("minecraft:entity.player.levelup") + .bossBar(BossBar.Color.GREEN, Duration.ofSeconds(5), "Reward claimed!") + .build(); +``` + +## Sending Messages + +```java +// Single player +multification.create() + .player(playerUUID) + .notice(config -> config.welcomeMessage) + .placeholder("{player}", player.getName()) + .send(); + +// All online players +multification.create() + .all() + .notice(config -> config.broadcast) + .send(); + +// Players with permission +multification.create() + .onlinePlayers("admin.notify") + .notice(config -> config.adminAlert) + .send(); + +// Console +multification.create() + .console() + .notice(config -> config.logMessage) + .send(); + +// CommandSender (viewer) +multification.create() + .viewer(sender) + .notice(config -> config.message) + .send(); + +// Async +multification.create() + .all() + .notice(config -> config.heavyMessage) + .sendAsync(); +``` + +## Placeholders & Formatters + +```java +// Placeholders +multification.create() + .player(uuid) + .notice(config -> config.message) + .placeholder("{player}", player.getName()) + .placeholder("{balance}", String.valueOf(balance)) + .send(); + +// Formatters +Formatter uppercase = (viewer, text) -> text.toUpperCase(); +multification.create() + .player(uuid) + .notice(config -> config.message) + .formatter(uppercase) + .send(); +``` + +## Config Example + +```java +public class MessagesConfig { + public Notice welcomeMessage = Notice.builder() + .chat("Welcome, {player}!") + .title("Welcome", "Enjoy your stay") + .sound("minecraft:entity.player.levelup") + .build(); +} +``` diff --git a/content/docs/multification/configuration.mdx b/content/docs/multification/configuration.mdx new file mode 100644 index 00000000..478c03b7 --- /dev/null +++ b/content/docs/multification/configuration.mdx @@ -0,0 +1,136 @@ +--- +title: Configuration +description: Store `Notice` objects in YAML config files using CDN or Okaeri serializers. +icon: Settings +sidebar_position: 4 +--- + +Configuring Multification is about **serializing `Notice` objects to YAML** so non-developers can edit messages safely. We ship serializers for two popular config libraries: + +- **CDN** – lightweight, YAML-like, great for quick configs. +- **Okaeri Configs** – rich features, comments, migration helpers. + +> If you only need a YAML reference for message shapes, see the [Format guide (for users)](/docs/multification/format). + +## Choosing a serializer + +- **Pick CDN** when you want minimal dependencies and fast drop-in setup. +- **Pick Okaeri** when you need comments preserved, migrations, or already use Okaeri in your project. +- Both serializers support the same `Notice` shape, so configs are interchangeable. + +## CDN + + + + ```java + Cdn cdn = CdnFactory.createYamlLike() + .getSettings() + .withComposer(Notice.class, new MultificationNoticeCdnComposer(multification)) + .build(); + ``` + + + ```java + MessagesConfig config = new MessagesConfig(); + cdn.load(Source.of(new File(dataFolder, "messages.yml")), config) + .orThrow(RuntimeException::new); + cdn.render(config, Source.of(file)) + .orThrow(RuntimeException::new); + ``` + + + ```java + cdn.load(Source.of(file), config).orThrow(RuntimeException::new); + ``` + + + +## Okaeri Configs + + + + ```java + MessagesConfig config = ConfigManager.create(MessagesConfig.class) + .withConfigurer(new MultificationSerdesPack(multification)) + .withConfigurer(new SerdesCommons(), new YamlSnakeYamlConfigurer()) + .withBindFile(new File(dataFolder, "messages.yml")) + .withRemoveOrphans(true) + .saveDefaults() + .load(true); + ``` + + + ```java + config.load(true); + ``` + + + +## Config Class Example + +```java +public class MessagesConfig { + @Description("# Welcome message") + public Notice welcomeMessage = Notice.builder() + .chat("Welcome, {player}!") + .title("Welcome", "Enjoy your stay") + .sound("minecraft:entity.player.levelup") + .build(); + + @Description("# Error messages") + public Notice noPermission = Notice.chat("No permission!"); + public Notice playerNotFound = Notice.chat("Player not found!"); +} +``` + +## Generated YAML + +```yaml +# Welcome message +welcomeMessage: + chat: + - "Welcome, {player}!" + title: + title: "Welcome" + subtitle: "Enjoy your stay" + sound: "minecraft:entity.player.levelup" + +# Error messages +noPermission: "No permission!" +playerNotFound: "Player not found!" +``` + + + Simple chat-only notices are serialized as single strings. Complex notices with multiple parts use structured YAML. + + +## More YAML patterns (drop into your config) + +```yaml +# Multi-line chat with placeholders +broadcast: + chat: + - "━━━━━━━━━━━━━━━━━━━━━" + - "{sender}: {message}" + - "━━━━━━━━━━━━━━━━━━━━━" + +# Actionbar + sound +healSuccess: + actionBar: "❤ Health restored" + sound: "minecraft:entity.player.levelup 1.0 1.2" + +# Title + subtitle + timing +warning: + title: "Warning!" + subtitle: "PvP enabled in this area" + times: "0.5s 3s 1s" + +# Bossbar example +bossInfo: + bossBar: + color: "GREEN" + text: "Objective updated" + progress: 0.6 +``` + +These YAML snippets map directly to the `Notice` fields your serializers handle, so you can paste them into `messages.yml` for CDN or Okaeri without Java changes. diff --git a/content/docs/multification/examples.mdx b/content/docs/multification/examples.mdx new file mode 100644 index 00000000..929bec2c --- /dev/null +++ b/content/docs/multification/examples.mdx @@ -0,0 +1,123 @@ +--- +title: Examples +description: Complete working examples +icon: Code +sidebar_position: 9 +--- + +## Welcome Message + +```java +@EventHandler +public void onJoin(PlayerJoinEvent event) { + multification.create() + .player(event.getPlayer().getUniqueId()) + .notice(config -> config.welcomeMessage) + .placeholder("{player}", event.getPlayer().getName()) + .send(); +} + +// Config +public Notice welcomeMessage = Notice.builder() + .chat("Welcome, {player}!") + .title("Welcome!", "Enjoy your stay") + .sound("minecraft:entity.player.levelup") + .build(); +``` + +## Command Feedback + +```java +@Command(name = "heal") +public void heal(@Context Player player) { + player.setHealth(20.0); + + multification.create() + .player(player.getUniqueId()) + .notice(config -> config.healSuccess) + .send(); +} + +public Notice healSuccess = Notice.builder() + .chat("You have been healed!") + .actionBar("❤ Health restored") + .sound("minecraft:entity.player.levelup", 1.0f, 1.2f) + .build(); +``` + +## Broadcast + +```java +@Command(name = "broadcast") +public void broadcast(@Context CommandSender sender, @Arg String message) { + multification.create() + .all() + .notice(config -> config.broadcast) + .placeholder("{message}", message) + .placeholder("{sender}", sender.getName()) + .send(); +} + +public Notice broadcast = Notice.builder() + .chat( + "━━━━━━━━━━━━━━━━━━━━━━━━━━━━", + "Broadcast from {sender}:", + "{message}", + "━━━━━━━━━━━━━━━━━━━━━━━━━━━━" + ) + .sound("minecraft:block.note_block.pling") + .build(); +``` + +## Economy Transaction + +```java +@Command(name = "pay") +public void pay(@Context Player sender, @Arg Player target, @Arg double amount) { + economy.withdraw(sender, amount); + economy.deposit(target, amount); + + // Sender + multification.create() + .player(sender.getUniqueId()) + .notice(config -> config.paySent) + .placeholder("{amount}", String.valueOf(amount)) + .placeholder("{player}", target.getName()) + .send(); + + // Receiver + multification.create() + .player(target.getUniqueId()) + .notice(config -> config.payReceived) + .placeholder("{amount}", String.valueOf(amount)) + .placeholder("{player}", sender.getName()) + .send(); +} +``` + +## Permission-Based + +```java +// All players +multification.create() + .all() + .notice(config -> config.announcement) + .send(); + +// Admins only +multification.create() + .onlinePlayers("admin.notify") + .notice(config -> config.adminNotify) + .send(); +``` + +## Complete Examples + + + + Complete Bukkit/Spigot plugin example. + + + Complete Paper plugin example. + + diff --git a/content/docs/multification/faq.mdx b/content/docs/multification/faq.mdx new file mode 100644 index 00000000..49c2cb99 --- /dev/null +++ b/content/docs/multification/faq.mdx @@ -0,0 +1,84 @@ +--- +title: FAQ & Troubleshooting +description: Common questions and solutions +icon: HelpCircle +sidebar_position: 8 +--- + +## Common Questions + + + **Paper 1.19.4+ with Java 21?** → `multification-paper` + **Bukkit/Spigot or older Java?** → `multification-bukkit` + + + + Use global replacer: + ```java + @Override + protected Replacer globalReplacer() { + return (viewer, text) -> viewer instanceof Player p + ? PlaceholderAPI.setPlaceholders(p, text) : text; + } + ``` + + + + Both work. CDN is simpler, Okaeri has more features. Pick one. + + +## Common Errors + + + **Cause:** Using Bukkit module on Paper or missing Adventure dependency + **Fix:** Use `multification-paper` on Paper, or add `adventure-platform-bukkit` for Bukkit + + + + **Cause:** Java version mismatch + **Fix:** Paper module needs Java 21, Bukkit works with Java 8+ + + + + **Cause:** Version conflict with other plugins + **Fix:** Relocate `net.kyori` in shadow jar + + + + **Possible causes:** + - Player offline + - Console receiving title (not possible) + - Empty notice + - Wrong serializer (use MiniMessage, not default) + + + + Check placeholder syntax matches: `{player}` in config = `"{player}"` in `.placeholder()` + + + + Override serializer: + ```java + @Override + protected ComponentSerializer serializer() { + return MiniMessage.miniMessage(); + } + ``` + + + + Register serializer: + ```java + // CDN + .withComposer(Notice.class, new MultificationNoticeCdnComposer(multification)) + + // Okaeri + .withConfigurer(new MultificationSerdesPack(multification)) + ``` + + +## Getting Help + +- [Discord](https://discord.gg/FQ7jmGBd6c) +- [GitHub Issues](https://github.com/EternalCodeTeam/multification/issues) +- [Examples](https://github.com/EternalCodeTeam/multification/tree/master/examples) diff --git a/content/docs/multification/format.mdx b/content/docs/multification/format.mdx new file mode 100644 index 00000000..b5aed01e --- /dev/null +++ b/content/docs/multification/format.mdx @@ -0,0 +1,118 @@ +--- +title: Format (For Users) +description: YAML reference for configuring Multification notices without touching Java code. +icon: FileText +sidebar_position: 6 +--- + +import { CodeTab, CodeTabs } from "../../../components/ui/mdx/CodeTabs"; +import { AlertBox } from "../../../components/ui/alert-box"; + +# Notice format (for config editors) + +This page is for people editing `messages.yml`. If you're coding in Java, see [Basic Usage](/docs/multification/basic-usage) instead. + + + 🎨 **Create stunning notifications instantly!** + Visit the **[Notification Generator](/notification-generator)** page for a step‑by‑step guide, live preview, and ready‑to‑copy examples. + + + + Multification uses [MiniMessage](https://docs.adventure.kyori.net/minimessage/format.html). Try the + [Adventure web viewer](https://webui.adventure.kyori.net/) to preview your text. + + +## Quick rules + +- ✨ **Quote strings** that contain `` or spaces. +- 📋 **Multi‑line chat** = YAML list (`- "line"`). +- ⏱️ **Times**: `times: "fadeIn stay fadeOut"` uses seconds, e.g. `"0.5s 3s 1s"`. +- 🧩 **Placeholders** like `{player}` are replaced by your plugin code. + +## Chat + + + + +```yaml +welcome: "Hello, {player}!" +``` + + + + +```yaml +welcome: + - "Hey {player}!" + - "Enjoy your stay" +``` + + + + +## Actionbar + +```yaml +healSuccess: + actionbar: "❤ Health restored" +``` + +## Title & Subtitle + +```yaml +warning: + title: "Warning!" + subtitle: "PvP enabled in this area" + times: "0.5s 3s 1s" # fade in, stay, fade out +``` + +## Bossbar + +```yaml +bossInfo: + bossBar: + color: "GREEN" + text: "Objective updated" + progress: 0.6 +``` + +## Sounds + + + + +```yaml +levelUp: + sound: "ENTITY_PLAYER_LEVELUP 2.0 1.0" # volume, pitch +``` + + + + +```yaml +levelUp: + # Sound categories: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/SoundCategory.html + sound: "PLAYER_LEVELUP WEATHER 2.0 1.0" +``` + + + + +## Combined example + + + Swap colors/placeholders freely. All sections are optional—remove what you don't need. + + +```yaml +advanced_notification: + chat: + - "Welcome to the server!" + - "Use /help for assistance." + actionbar: "You have 5 unread messages" + title: "WARNING!" + subtitle: "You are entering a PvP zone" + times: "0.5s 3s 1s" + sound: "ENTITY_ENDER_DRAGON_GROWL MASTER 1.0 0.8" + titleHide: true +``` diff --git a/content/docs/multification/index.mdx b/content/docs/multification/index.mdx new file mode 100644 index 00000000..bfe629e1 --- /dev/null +++ b/content/docs/multification/index.mdx @@ -0,0 +1,81 @@ +--- +title: Introduction +description: Powerful library for sending custom notifications based on Adventure API +icon: Zap +sidebar_position: 1 +--- + +import { Card } from "../../../components/ui/card.tsx"; +import { Callout } from "../../../components/ui/mdx/callout.tsx"; +import { CardGroup } from "../../../components/ui/mdx/card.tsx"; + + + + Multification is a state-of-the-art clean, type-safe API that easily allows sending chat messages, titles, actionbars, bossbars, and sounds – all from a single, configurable + `Notice` object. + + +## Features + + + + Define messages once, use everywhere with IDE support. + + + Chat, title, subtitle, actionbar, bossbar, sound in one Notice. + + + CDN and Okaeri Configs serializers included. + + + Built-in translation provider for multi-language support. + + + +## Supported platforms + +| Platform | Module | Java | Adventure | +| :--- | :--- | :--- | :--- | +| **Paper 1.19.4+** | `multification-paper` | 21 | Native | +| **Bukkit/Spigot** | `multification-bukkit` | 8+ | Adapter | +| **Custom** | `multification-core` | 8+ | DIY | + +## Quick Start + +```java +// 1. Extend platform class +public class MyMultification extends PaperMultification { + private final MessagesConfig config; + + @Override + protected TranslationProvider translationProvider() { + return locale -> config; + } + + @Override + protected ComponentSerializer serializer() { + return MiniMessage.miniMessage(); + } + + @Override + protected AudienceConverter audienceConverter() { + return new PaperAudienceConverter(); + } +} + +// 2. Send messages +multification.create() + .player(playerUUID) + .notice(config -> config.welcomeMessage) + .placeholder("{player}", player.getName()) + .send(); +``` + +## Next Steps + + + + + + + diff --git a/content/docs/multification/installation.mdx b/content/docs/multification/installation.mdx new file mode 100644 index 00000000..d35a5af7 --- /dev/null +++ b/content/docs/multification/installation.mdx @@ -0,0 +1,113 @@ +--- +title: Installation +description: How to add Multification to your project +icon: Download +sidebar_position: 2 +--- +import {CodeTab, CodeTabs} from "../../../components/ui/mdx/code-tabs.tsx"; +import {Callout} from "../../../components/ui/mdx/callout.tsx"; + +## Platform Modules + + + + + **Requirements:** Java 21, Paper 1.19.4+ + + + ```kotlin + repositories { + maven("https://repo.eternalcode.pl/releases") + } + + dependencies { + implementation("com.eternalcode:multification-paper:1.2.3") + // Latest version: https://github.com/EternalCodeTeam/multification/releases + } + ``` + + + Paper includes Adventure API out of the box — no extra dependencies required. + `CommandSender` already implements `Audience`. + + + + + + **Requirements:** Java 8, Bukkit/Spigot 1.13+ + + + ```kotlin + repositories { + maven("https://repo.eternalcode.pl/releases") + } + + dependencies { + implementation("com.eternalcode:multification-bukkit:1.2.3") + // Latest version: https://github.com/EternalCodeTeam/multification/releases + implementation("net.kyori:adventure-platform-bukkit:4.3.3") + implementation("net.kyori:adventure-text-minimessage:4.17.0") + } + ``` + + + Bukkit requires the Adventure platform adapter. + The Bukkit module also registers `SoundBukkitResolver` for the Bukkit `Sound` enum. + + + + + Use this module for custom or non-Minecraft platforms. + + ```kotlin + dependencies { + implementation("com.eternalcode:multification-core:1.2.3") + // Latest version: https://github.com/EternalCodeTeam/multification/releases + } + ``` + + + +## Config Serializers (Optional) + + + + ```kotlin + dependencies { + implementation("com.eternalcode:multification-cdn:1.2.3") + implementation("net.dzikoysk:cdn:1.14.9") + } + ``` + + + + ```kotlin + dependencies { + implementation("com.eternalcode:multification-okaeri:1.2.3") + implementation("eu.okaeri:okaeri-configs-yaml-snakeyaml:5.0.13") + } + ``` + + + +## Shadow / Relocation + + + + ```kotlin + shadowJar { + // Do NOT relocate Adventure on Paper + relocate("com.eternalcode.multification", "your.plugin.libs.multification") + } + ``` + + + + ```kotlin + shadowJar { + relocate("com.eternalcode.multification", "your.plugin.libs.multification") + relocate("net.kyori", "your.plugin.libs.kyori") // REQUIRED + } + ``` + + diff --git a/content/docs/multification/migration.mdx b/content/docs/multification/migration.mdx new file mode 100644 index 00000000..17c4f6ab --- /dev/null +++ b/content/docs/multification/migration.mdx @@ -0,0 +1,84 @@ +--- +title: Migration Guide +description: Migrate from legacy messaging systems to Multification +icon: ArrowRightCircle +sidebar_position: 10 +--- + +## From ChatColor + String Concatenation + + + + ```java + String msg = ChatColor.GREEN + "Welcome, " + player.getName() + "!"; + player.sendMessage(msg); + player.sendTitle(ChatColor.GOLD + "Welcome", "", 10, 70, 20); + player.playSound(player.getLocation(), Sound.ENTITY_PLAYER_LEVELUP, 1, 1); + ``` + + + ```java + multification.create() + .player(player.getUniqueId()) + .notice(config -> config.welcomeMessage) + .placeholder("{player}", player.getName()) + .send(); + + // In config: + public Notice welcomeMessage = Notice.builder() + .chat("Welcome, {player}!") + .title("Welcome") + .sound("minecraft:entity.player.levelup") + .build(); + ``` + + + +## From BukkitAudiences + + + + ```java + private BukkitAudiences audiences; + + @Override + public void onEnable() { + audiences = BukkitAudiences.create(this); + } + + @Override + public void onDisable() { + if (audiences != null) audiences.close(); + } + + void send(Player player, String msg) { + audiences.player(player).sendMessage(MiniMessage.miniMessage().deserialize(msg)); + } + ``` + + + ```java + private MyMultification multification; + + @Override + public void onEnable() { + multification = new MyMultification(new MessagesConfig()); + } + // No onDisable needed on Paper + + void send(Player player) { + multification.create() + .player(player.getUniqueId()) + .notice(config -> config.message) + .send(); + } + ``` + + + +## Quick Migration Steps + +1. **Add dependency:** `multification-paper` or `multification-bukkit` +2. **Create config class:** Define `Notice` fields +3. **Create Multification class:** Extend platform base class +4. **Replace calls:** `player.sendMessage(...)` → `multification.create()....send()` diff --git a/content/docs/multification/platform-comparison.mdx b/content/docs/multification/platform-comparison.mdx new file mode 100644 index 00000000..b0e7fc7f --- /dev/null +++ b/content/docs/multification/platform-comparison.mdx @@ -0,0 +1,83 @@ +--- +title: Platform Comparison +description: Differences between Paper and Bukkit modules +icon: GitCompare +sidebar_position: 6 +--- + +## Quick Comparison + +| Feature | Paper | Bukkit | +| :--- | :--- | :--- | +| **Java** | 21 | 8+ | +| **Minecraft** | 1.19.4+ | 1.13+ | +| **Adventure** | Native | Adapter required | +| **Dependencies** | None | `adventure-platform-bukkit` | +| **Performance** | Direct cast | Adapter overhead | + +## Architecture + + + + ```java + // CommandSender IS Audience - direct cast, zero overhead + public class PaperAudienceConverter implements AudienceConverter { + @Override + public Audience convert(CommandSender viewer) { + return viewer; // Direct! + } + } + + // Locale from player.locale() + public class PaperLocaleProvider implements LocaleProvider { + @Override + public Locale provide(CommandSender viewer) { + return viewer instanceof Player p ? p.locale() : Locale.ROOT; + } + } + ``` + + + ```java + // Needs adapter to convert CommandSender -> Audience + // Uses BukkitAudiences from adventure-platform-bukkit + @Override + protected AudienceConverter audienceConverter() { + return sender -> sender instanceof Player p + ? audienceProvider.player(p.getUniqueId()) + : audienceProvider.console(); + } + + // Locale from player.getLocale() (string) + public class BukkitLocaleProvider implements LocaleProvider { + @Override + public Locale provide(CommandSender sender) { + return sender instanceof Player p ? new Locale(p.getLocale()) : Locale.getDefault(); + } + } + ``` + + + +## When to Use + +| Use Paper When | Use Bukkit When | +| :--- | :--- | +| Running Paper 1.19.4+ | Running Bukkit/Spigot | +| Can use Java 21 | Need Java 8 compatibility | +| Want zero dependencies | Supporting older versions | +| Want best performance | Can't upgrade to Paper | + +## Common Issues + + + Using Bukkit module on Paper? Switch to `multification-paper`. + + + + Adventure version conflict? Relocate `net.kyori` in shadow jar. + + + + Forgot to close `AudienceProvider`? Call `audienceProvider.close()` in `onDisable()`. + diff --git a/content/docs/notification/notifications.mdx b/content/docs/notification/notifications.mdx deleted file mode 100644 index cbcfc198..00000000 --- a/content/docs/notification/notifications.mdx +++ /dev/null @@ -1,170 +0,0 @@ ---- -title: Notifications -icon: MessageSquare -sidebar_position: 1 ---- - -import { CodeTab, CodeTabs } from "../../../components/ui/mdx/CodeTabs"; -import { AlertBox } from "../../../components/ui/alert-box"; - -# 💬🔔 Notifications - -This plugin allows sending messages to different parts of Minecraft, including the chat, action bar, title, and subtitle. All messages can be formatted using [🔍 MiniMessages](https://docs.adventure.kyori.net/minimessage/format.html) or standard color codes. You can also use an online [🌐 message viewer](https://webui.adventure.kyori.net/) - - - Try our [interactive notification generator](/notification-generator) to create and preview your - notifications before adding them to your configuration! - - -### 📝 Example usage - -Syntax for sending notifications: - -#### Chat + Multiline chat - - - - -```yaml -# Displays a message in the chat. -example: "Hello world!" # <- Single one line text -``` - - - - -```yaml -# Displays multiple lines in the chat. -example2: - - "Hello" - - "world!" -``` - - - - -#### Actionbar - - - - -```yaml -# Displays a message in the action bar. -example: - actionbar: "Hello world!" -``` - - - - -#### Title - - - - -```yaml -# Displays a message in the title. -example: - title: "Hello world!" -``` - - - - -#### Subtitle - - - - -```yaml -# Displays a message in the subtitle. -example: - subtitle: "Hello world!" -``` - - - - -#### Title with times - - - - -```yaml -# Displays a message in the title or subtitle with specified times. -# THIS also working for subtitle -example: - title: "Hello world!" - times: "1s 2s 1s" # <- The first number is the time it takes to fade in, the second is the time it takes to stay on the screen, and the third is the time it takes to fade out. -``` - - - - -#### Sounds - - - - -```yaml -# Plays a sound with the specified volume and pitch. -example: - sound: "ENTITY_PLAYER_LEVELUP 2.0 1.0" # <- The first number is the volume, the second is the pitch. -``` - - - - -```yaml -# Plays a sound with the specified volume and pitch. -example: - # Sound categories: https://hub.spigotmc.org/javadocs/spigot/org/bukkit/SoundCategory.html - sound: "PLAYER_LEVELUP WEATHER 2.0 1.0" # <- The first number is the volume, the second is the pitch. - # If you want to play a sound in a certain category, for example if a player has the sound category "WEATHER" in the game settings set to 0%, the sound will not play. -``` - - - - ---- - -### Examples combining multiple notifications: - - - 👑 Unleash your creativity and design your own custom notifications without any limits! - - -Here's an example of an advanced notification that combines multiple notification types: - -```yaml -# Advanced notification example -advanced_notification: - # Chat message with multiple lines - chat: - - "Welcome to the server!" - - "Use /help for assistance." - - # Action bar notification - actionbar: "You have 5 unread messages" - - # Title and subtitle with custom times - title: "WARNING!" - subtitle: "You are entering a PvP zone" - times: "0.5s 3s 1s" # Fade in, stay, fade out - - # Sound effect with custom volume and pitch - sound: "ENTITY_ENDER_DRAGON_GROWL MASTER 1.0 0.8" - - # Clear any existing title/subtitle before showing this one - titleHide: true -``` - -This example demonstrates: - -- Multi-line chat messages with gradients and clickable elements -- Action bar notifications with gradients -- Title and subtitle with custom fade times -- Sound effects with custom volume and pitch -- Title clearing before showing new notifications - -You can mix and match these elements to create your own custom notifications! diff --git a/lib/generated-sidebar.json b/lib/generated-sidebar.json index 51dc8a3f..e8626592 100644 --- a/lib/generated-sidebar.json +++ b/lib/generated-sidebar.json @@ -342,15 +342,75 @@ ] }, { - "title": "notification", - "path": "/docs/notification", + "title": "multification", + "path": "/docs/multification", "children": [ { - "title": "Notifications", - "path": "/docs/notification/notifications", - "icon": "MessageSquare", + "title": "Introduction", + "path": "/docs/multification/index", + "icon": "Zap", "sidebar_position": 1 + }, + { + "title": "Installation", + "path": "/docs/multification/installation", + "icon": "Download", + "sidebar_position": 2 + }, + { + "title": "Basic Usage", + "path": "/docs/multification/basic-usage", + "icon": "BookOpen", + "sidebar_position": 3 + }, + { + "title": "Configuration", + "path": "/docs/multification/configuration", + "icon": "Settings", + "sidebar_position": 4 + }, + { + "title": "Advanced Features", + "path": "/docs/multification/advanced", + "icon": "Sparkles", + "sidebar_position": 6 + }, + { + "title": "Format (For Users)", + "path": "/docs/multification/format", + "icon": "FileText", + "sidebar_position": 6 + }, + { + "title": "Platform Comparison", + "path": "/docs/multification/platform-comparison", + "icon": "GitCompare", + "sidebar_position": 6 + }, + { + "title": "API Reference", + "path": "/docs/multification/api-reference", + "icon": "Book", + "sidebar_position": 7 + }, + { + "title": "FAQ & Troubleshooting", + "path": "/docs/multification/faq", + "icon": "HelpCircle", + "sidebar_position": 8 + }, + { + "title": "Examples", + "path": "/docs/multification/examples", + "icon": "Code", + "sidebar_position": 9 + }, + { + "title": "Migration Guide", + "path": "/docs/multification/migration", + "icon": "ArrowRightCircle", + "sidebar_position": 10 } ] } -] +] \ No newline at end of file diff --git a/package.json b/package.json index 150066b9..6f61c49a 100644 --- a/package.json +++ b/package.json @@ -87,4 +87,4 @@ "overrides": { "next": "$next" } -} +} \ No newline at end of file