Finalize EndCrystals v2 docs, translations, and MIT licensing

Author: mrfloris

LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 mrfloris
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

README.md

@@ -20,15 +20,15 @@ The produced jar is named:
 - Optionally blocks player projectiles from breaking protected crystals
 - Keeps The End configurable so dragon-fight style gameplay can stay intact if desired
 - Uses the normal Paper plugin data folder: `plugins/1MB-EndCrystals/config.yml`
-- Migrates the misplaced legacy home-folder config into the correct server-local folder on first startup
+- Uses locale-ready message files in `plugins/1MB-EndCrystals/Translations/`
 - Supports `/_endcrystals reload`
 - Supports `/_endcrystals toggle [setting] [true|false]` for live boolean config toggles
 - Supports `/_endcrystals debug` for runtime/build/config diagnostics
 - Supports configurable command aliases from `config.yml`
 - Uses MiniMessage formatting for plugin output
-- Uses strict permission nodes with op not automatically bypassing protection
+- Keeps protection enabled by default while admin and break access stay permission-driven
 - Targets Java `25` and modern Paper builds
-- Builds with Gradle from a fresh clone without requiring any private `/servers/` test setup
+- Builds with Gradle from a fresh clone
 
 ## Commands
 
@@ -54,20 +54,23 @@ If another plugin or the server already owns one of those names, 1MB-EndCrystals
 - `onembendcrystals.toggle`
 - `onembendcrystals.break`
 
-All of these permissions default to `false`, so being op alone does not grant them. `onembendcrystals.admin` grants the command permissions. `onembendcrystals.break` allows a player to break otherwise protected crystals.
+Protection is enabled by default through the config values under `protection.*`. By default, regular players and ops are both blocked from breaking protected crystals or using the management commands. `onembendcrystals.break` must be granted explicitly to allow a player to break otherwise protected crystals, and `onembendcrystals.admin` or the individual command nodes must be granted explicitly to allow management access.
 
 ## Config
 
 The plugin reads and writes its main config here:
 
 `plugins/1MB-EndCrystals/config.yml`
 
-Each Paper server gets its own local config folder, which is the normal Bukkit/Paper behavior.
+Locale files live here:
 
-If you are upgrading from an older build that wrote to `~/plugins/1MB-EndCrystals/config.yml`, the plugin will copy that legacy file into the server-local plugin folder on first startup if the new server-local config does not already exist.
+`plugins/1MB-EndCrystals/Translations/Locale_EN.yml`
+
+Each Paper server gets its own local config and translation folder, which is the normal Bukkit/Paper behavior.
 
 Important defaults:
 
+- `translations.locale: Locale_EN`
 - `commands.aliases: [endcrystals, ec]`
 - `protection.prevent-block-damage: true`
 - `protection.prevent-player-break: true`
@@ -88,23 +91,21 @@ This section summarizes the modernization work completed for the current refresh
 - Retargeted the plugin for modern Paper, validated against `1.21.11` and `26.1.2`
 - Standardized the shipped jar name to `1MB-EndCrystals-v2.0.1-021-v25-26.1.2.jar`
 - Reworked config storage to use the active server's `plugins/1MB-EndCrystals/config.yml`
-- Added one-time migration support for the old misplaced `~/plugins/1MB-EndCrystals/config.yml`
 - Added `/_endcrystals reload`
 - Added `/_endcrystals debug`
 - Added live config toggles through `/_endcrystals toggle [setting] [true|false]`
 - Moved command aliases into `config.yml` so they can be added or removed without editing `plugin.yml`
 - Kept `/_endcrystals` as the permanent primary command
-- Switched to explicit `onembendcrystals.*` permission nodes with `default: false`
+- Kept protection enabled by default while moving admin and crystal-break access onto explicit `onembendcrystals.*` permission nodes
 - Made crystal breaking permission-driven instead of implicitly allowing ops
 - Expanded protection beyond blocks to cover decorative and item entities
 - Added protection for minecart and boat-style entities that were still vulnerable on the legacy path
 - Improved debug output to show build/runtime info, config path, permissions, live toggles, and active commands
-- Moved plugin messages into config and formatted output with MiniMessage
-- Updated docs so public builds do not depend on any private local `/servers/` test directory
+- Split plugin messages into locale files under `Translations/` and formatted output with MiniMessage
 
 ## Build
 
-The public build does not depend on any local `servers/` directory. A normal checkout builds against the Paper API from the Paper Maven repository, and any repo-local test servers are strictly optional private development tooling.
+A normal checkout builds against the Paper API from the Paper Maven repository.
 
 Build with:
 
@@ -120,10 +121,23 @@ Output jar:
 
 1. Build the jar.
 2. Copy it into a Paper server's `plugins/` folder.
-3. Start the server once so the plugin creates `plugins/1MB-EndCrystals/config.yml`.
-4. Use `/_endcrystals debug` to verify runtime information.
+3. Start the server once so the plugin creates `plugins/1MB-EndCrystals/config.yml` and `plugins/1MB-EndCrystals/Translations/Locale_EN.yml`.
+4. Use `/_endcrystals debug` to verify runtime information, including the active locale file.
 5. Use `/_endcrystals reload` after editing the config.
 
+## Support
+
+If you run into a bug, want to request a feature, or need help using the plugin, please use the [GitHub Issues](https://github.com/mrfdev/EndCrystals/issues) section for this repository.
+
+## Credits
+
+- mrfloris ([GitHub: `mrfdev`](https://github.com/mrfdev)) for the original plugin, project direction, and the v2 refresh goals
+- OpenAI for helping modernize and ship the v2 update
+
+## License
+
+This project is licensed under the MIT License. See [LICENSE](LICENSE) for the full text.
+
 ## Testing Notes
 
-The plugin is meant to be testable without WorldGuard present. If an end crystal explodes near normal blocks, the explosion should still happen but the blocks should remain intact while the plugin is enabled. Any `/servers/` directory used in development is for private local testing only and is not part of the public build flow.
+The plugin is meant to be testable without WorldGuard present. If an end crystal explodes near normal blocks, the explosion should still happen but the blocks should remain intact while the plugin is enabled.

src/main/java/com/mrfloris/endcrystals/EndCrystalsCommand.java

@@ -86,6 +86,8 @@ private boolean handleDebug(CommandSender sender) {
                 .formatted(System.getProperty("java.version", "unknown")), false);
         plugin.sendRich(sender, "<gray>Config:</gray> <white>%s</white>"
                 .formatted(plugin.configManager().configPath()), false);
+        plugin.sendRich(sender, "<gray>Locale:</gray> <white>%s</white> <gray>|</gray> <white>%s</white>"
+                .formatted(config.localeName(), plugin.configManager().localePath()), false);
         plugin.sendRich(sender, "<gray>Commands:</gray> <white>%s</white>"
                 .formatted(plugin.commandSummary()), false);
         plugin.sendRich(sender, "<gray>Placeholders:</gray> <white>None</white>", false);

src/main/java/com/mrfloris/endcrystals/ExternalConfigManager.java

@@ -7,8 +7,8 @@
 import java.nio.file.Files;
 import java.nio.file.Path;
 import java.util.ArrayList;
-import java.util.LinkedHashSet;
 import java.util.LinkedHashMap;
+import java.util.LinkedHashSet;
 import java.util.List;
 import java.util.Map;
 import java.util.Objects;
@@ -17,34 +17,32 @@
 
 public final class ExternalConfigManager {
 
+    private static final String DEFAULT_LOCALE_FILE = "Locale_EN.yml";
+
     private final EndCrystalsPlugin plugin;
     private final Path configDirectory;
     private final Path configPath;
-    private final Path legacyConfigPath;
+    private final Path translationsDirectory;
 
     private YamlConfiguration yaml;
+    private YamlConfiguration localeYaml;
     private PluginConfig currentConfig;
+    private Path localePath;
 
     public ExternalConfigManager(EndCrystalsPlugin plugin) {
         this.plugin = plugin;
         this.configDirectory = plugin.getDataFolder().toPath().toAbsolutePath().normalize();
         this.configPath = this.configDirectory.resolve("config.yml");
-        this.legacyConfigPath = Path.of(System.getProperty("user.home"), "plugins", plugin.getName(), "config.yml")
-                .toAbsolutePath()
-                .normalize();
+        this.translationsDirectory = this.configDirectory.resolve("Translations");
     }
 
     public void initialize() {
         try {
             Files.createDirectories(configDirectory);
+            Files.createDirectories(translationsDirectory);
 
             if (Files.notExists(configPath)) {
-                if (Files.exists(legacyConfigPath)) {
-                    Files.copy(legacyConfigPath, configPath);
-                    plugin.getLogger().info("Copied legacy config from " + legacyConfigPath + " to " + configPath);
-                } else {
-                    copyEmbeddedConfig();
-                }
+                copyEmbeddedConfig();
             }
         } catch (IOException exception) {
             throw new IllegalStateException("Could not initialize config at " + configPath, exception);
@@ -68,7 +66,22 @@ public void reload() {
             throw new IllegalStateException("Could not merge default config values into " + configPath, exception);
         }
 
-        this.currentConfig = PluginConfig.from(yaml);
+        String resolvedLocaleFile = normalizeLocaleFileName(yaml.getString("translations.locale", DEFAULT_LOCALE_FILE));
+        this.localePath = translationsDirectory.resolve(resolvedLocaleFile);
+        initializeLocaleFile(resolvedLocaleFile);
+        this.localeYaml = YamlConfiguration.loadConfiguration(localePath.toFile());
+
+        try {
+            YamlConfiguration localeDefaults = loadEmbeddedLocaleDefaults(resolvedLocaleFile);
+            localeYaml.addDefaults(localeDefaults);
+            localeYaml.options().copyDefaults(true);
+            normalizeLocaleConfig(localeDefaults);
+            localeYaml.save(localePath.toFile());
+        } catch (IOException exception) {
+            throw new IllegalStateException("Could not merge default locale values into " + localePath, exception);
+        }
+
+        this.currentConfig = PluginConfig.from(yaml, localeYaml, resolvedLocaleFile);
     }
 
     public boolean toggle(String path, Boolean explicitValue) {
@@ -105,6 +118,11 @@ public Path configPath() {
         return configPath;
     }
 
+    public Path localePath() {
+        ensureLoaded();
+        return localePath;
+    }
+
     public Map<String, Boolean> liveToggleStates() {
         ensureLoaded();
 
@@ -124,6 +142,8 @@ public java.util.List<String> liveToggleKeys() {
     private void ensureLoaded() {
         Objects.requireNonNull(currentConfig, "Config has not been loaded yet.");
         Objects.requireNonNull(yaml, "Config has not been loaded yet.");
+        Objects.requireNonNull(localeYaml, "Locale has not been loaded yet.");
+        Objects.requireNonNull(localePath, "Locale has not been loaded yet.");
     }
 
     private void copyEmbeddedConfig() throws IOException {
@@ -146,17 +166,6 @@ private void normalizeConfig(YamlConfiguration defaults) {
         yaml.set("live-toggles", liveToggles);
 
         normalizeProtectedEntityTypes(defaults);
-
-        String legacyUsageSingular = "<yellow>Use <white>/_endcrystal debug</white>, <white>reload</white>, or <white>toggle &lt;setting&gt; [true|false]</white>.</yellow>";
-        String legacyUsagePlural = "<yellow>Use <white>/_endcrystals debug</white>, <white>reload</white>, or <white>toggle &lt;setting&gt; [true|false]</white>.</yellow>";
-        String legacyUsageBracket = "<yellow>Use <white>/_endcrystals debug</white>, <white>reload</white>, or <white>toggle [setting] [true|false]</white>.</yellow>";
-        String defaultUsage = defaults.getString("messages.command-usage");
-        String currentUsage = yaml.getString("messages.command-usage");
-        if ((legacyUsageSingular.equals(currentUsage)
-                || legacyUsagePlural.equals(currentUsage)
-                || legacyUsageBracket.equals(currentUsage)) && defaultUsage != null) {
-            yaml.set("messages.command-usage", defaultUsage);
-        }
     }
 
     private void normalizeProtectedEntityTypes(YamlConfiguration defaults) {
@@ -192,4 +201,74 @@ private Set<String> toUpperCaseSet(List<String> values) {
         }
         return normalized;
     }
+
+    private void initializeLocaleFile(String localeFileName) {
+        try {
+            if (Files.exists(localePath)) {
+                return;
+            }
+
+            YamlConfiguration localeDefaults = loadEmbeddedLocaleDefaults(localeFileName);
+
+            if (yaml.isConfigurationSection("messages")) {
+                for (String key : yaml.getConfigurationSection("messages").getKeys(true)) {
+                    localeDefaults.set("messages." + key, yaml.get("messages." + key));
+                }
+            }
+
+            localeDefaults.save(localePath.toFile());
+        } catch (IOException exception) {
+            throw new IllegalStateException("Could not initialize locale at " + localePath, exception);
+        }
+    }
+
+    private YamlConfiguration loadEmbeddedLocaleDefaults(String localeFileName) throws IOException {
+        String resourcePath = resolveEmbeddedLocaleResource(localeFileName);
+        try (InputStream resource = plugin.getResource(resourcePath)) {
+            if (resource == null) {
+                throw new IllegalStateException("Embedded locale resource was not found: " + resourcePath);
+            }
+
+            return YamlConfiguration.loadConfiguration(new InputStreamReader(resource, StandardCharsets.UTF_8));
+        }
+    }
+
+    private String resolveEmbeddedLocaleResource(String localeFileName) {
+        String requested = "Translations/" + localeFileName;
+        if (plugin.getResource(requested) != null) {
+            return requested;
+        }
+
+        if (!DEFAULT_LOCALE_FILE.equals(localeFileName)) {
+            plugin.getLogger().warning("Locale " + localeFileName + " was not bundled; falling back to " + DEFAULT_LOCALE_FILE);
+        }
+
+        return "Translations/" + DEFAULT_LOCALE_FILE;
+    }
+
+    private String normalizeLocaleFileName(String configuredLocale) {
+        String normalized = configuredLocale == null ? "" : configuredLocale.trim();
+        if (normalized.isBlank()) {
+            normalized = DEFAULT_LOCALE_FILE;
+        }
+
+        if (!normalized.toLowerCase(java.util.Locale.ROOT).endsWith(".yml")) {
+            normalized = normalized + ".yml";
+        }
+
+        return Path.of(normalized).getFileName().toString();
+    }
+
+    private void normalizeLocaleConfig(YamlConfiguration defaults) {
+        String legacyUsageSingular = "<yellow>Use <white>/_endcrystal debug</white>, <white>reload</white>, or <white>toggle &lt;setting&gt; [true|false]</white>.</yellow>";
+        String legacyUsagePlural = "<yellow>Use <white>/_endcrystals debug</white>, <white>reload</white>, or <white>toggle &lt;setting&gt; [true|false]</white>.</yellow>";
+        String legacyUsageBracket = "<yellow>Use <white>/_endcrystals debug</white>, <white>reload</white>, or <white>toggle [setting] [true|false]</white>.</yellow>";
+        String defaultUsage = defaults.getString("messages.command-usage");
+        String currentUsage = localeYaml.getString("messages.command-usage");
+        if ((legacyUsageSingular.equals(currentUsage)
+                || legacyUsagePlural.equals(currentUsage)
+                || legacyUsageBracket.equals(currentUsage)) && defaultUsage != null) {
+            localeYaml.set("messages.command-usage", defaultUsage);
+        }
+    }
 }

src/main/java/com/mrfloris/endcrystals/PluginConfig.java

@@ -12,6 +12,7 @@
 import org.bukkit.entity.EntityType;
 
 public record PluginConfig(
+        String localeName,
         List<String> commandAliases,
         boolean preventBlockDamage,
         boolean preventPlayerBreak,
@@ -82,21 +83,22 @@ public record PluginConfig(
             "SPRUCE_CHEST_BOAT"
     );
 
-    public static PluginConfig from(YamlConfiguration yaml) {
+    public static PluginConfig from(YamlConfiguration yaml, YamlConfiguration localeYaml, String localeName) {
         Map<String, String> messages = new LinkedHashMap<>();
-        messages.put("no-permission", yaml.getString("messages.no-permission", "<red>You do not have permission to do that.</red>"));
-        messages.put("reloaded", yaml.getString("messages.reloaded", "<green>Configuration reloaded from <white>%path%</white>.</green>"));
-        messages.put("toggle-updated", yaml.getString("messages.toggle-updated", "<green><white>%setting%</white> is now <white>%value%</white>.</green>"));
-        messages.put("unknown-setting", yaml.getString("messages.unknown-setting", "<red>Unknown toggle: <white>%setting%</white></red>"));
-        messages.put("command-usage", yaml.getString("messages.command-usage", "<yellow>Use <white>/_endcrystals debug</white>, <white>reload</white>, or <white>toggle [setting] [true|false]</white>.</yellow>"));
-        messages.put("player-break-blocked", yaml.getString("messages.player-break-blocked", "<red>These end crystals are protected.</red>"));
+        messages.put("no-permission", localeYaml.getString("messages.no-permission", "<red>You do not have permission to do that.</red>"));
+        messages.put("reloaded", localeYaml.getString("messages.reloaded", "<green>Configuration reloaded from <white>%path%</white>.</green>"));
+        messages.put("toggle-updated", localeYaml.getString("messages.toggle-updated", "<green><white>%setting%</white> is now <white>%value%</white>.</green>"));
+        messages.put("unknown-setting", localeYaml.getString("messages.unknown-setting", "<red>Unknown toggle: <white>%setting%</white></red>"));
+        messages.put("command-usage", localeYaml.getString("messages.command-usage", "<yellow>Use <white>/_endcrystals debug</white>, <white>reload</white>, or <white>toggle [setting] [true|false]</white>.</yellow>"));
+        messages.put("player-break-blocked", localeYaml.getString("messages.player-break-blocked", "<red>These end crystals are protected.</red>"));
 
         List<String> configuredProtectedTypes = yaml.getStringList("protection.protected-entity-types");
         if (configuredProtectedTypes.isEmpty()) {
             configuredProtectedTypes = DEFAULT_PROTECTED_ENTITY_TYPES;
         }
 
         return new PluginConfig(
+                localeName,
                 parseCommandAliases(yaml.isList("commands.aliases")
                         ? yaml.getStringList("commands.aliases")
                         : DEFAULT_COMMAND_ALIASES),
@@ -110,7 +112,7 @@ public static PluginConfig from(YamlConfiguration yaml) {
                 yaml.getBoolean("debug.log-crystal-breaks", false),
                 List.copyOf(yaml.getStringList("live-toggles").isEmpty() ? DEFAULT_LIVE_TOGGLES : yaml.getStringList("live-toggles")),
                 parseProtectedEntityTypes(configuredProtectedTypes),
-                yaml.getString("messages.prefix", "<gray>[<gold>1MB-EndCrystals</gold>]</gray> "),
+                localeYaml.getString("messages.prefix", "<gray>[<gold>1MB-EndCrystals</gold>]</gray> "),
                 Map.copyOf(messages)
         );
     }