Add the hidden Blood Magic path

ADMIN-COMMANDS.md

@@ -78,3 +78,32 @@ semantics. `tools/dev-admin-values.cjs` exercises both this plugin and the
 RPCharacters Focus commands on TFMCDev01 through its existing Dev bot helpers.
 It uses only the dedicated `AdminValueProbe` character, removes its temporary
 operator status, resets its test values and clears its test inventory afterward.
+
+## Blood path
+
+Staff tools for the hidden blood magic progression (`bloodmagic.yml`). Player
+targets must be online on the character being edited. Records and altars are
+saved under `data/bloodmagic/`.
+
+```text
+/magic blood list
+/magic blood info <player>
+/magic blood stage <player> <none|whispered|animal|choice|hunt|final|ascended>
+/magic blood path <player> <none|devotee|true>
+/magic blood give <player> <altar|ritual_knife|blood_knife>
+/magic blood whisper <player> [amount]
+/magic blood voice <player>
+/magic blood target <player> <list|reroll|skip|set <character name>>
+/magic blood bonds <player>
+/magic blood altar <info|tp|refresh|purify> <player|altar id>
+/magic blood reset <player>
+```
+
+`whisper` without an amount wakes the voices at once; with an amount it adds to
+the hidden meter. `voice` speaks the next line now. `target` manages the final
+sacrifices: `reroll` drops the named target for a fresh pick, `set` names a living
+character, `skip` counts the named target as done without a death. `bonds` lists
+the character's ten closest bonds with their hidden scores. Altars cannot be
+broken by anyone; `altar purify` removes one and puts back every block it
+corrupted, and an altar purifies itself when its owner character dies. `reset`
+purifies the altar and clears the whole path; items already handed out stay.

pom.xml

@@ -13,7 +13,7 @@
         <project.build.sourceEncoding>UTF-8</project.build.sourceEncoding>
         <maven.compiler.proc>full</maven.compiler.proc>
         <interactiblefurniture.version>0.2.0</interactiblefurniture.version>
-        <rpcharacters.version>2.16.0</rpcharacters.version>
+        <rpcharacters.version>2.31.0</rpcharacters.version>
         <tlibs.version>2.6.0</tlibs.version>
     </properties>
 
@@ -88,6 +88,16 @@
                 </exclusion>
             </exclusions>
         </dependency>
+        <!-- NBT-API's NBT class references authlib; mocking it in tests needs the type. -->
+        <dependency>
+            <groupId>com.mojang</groupId>
+            <artifactId>authlib</artifactId>
+            <version>7.0.61</version>
+            <scope>test</scope>
+            <exclusions>
+                <exclusion><groupId>*</groupId><artifactId>*</artifactId></exclusion>
+            </exclusions>
+        </dependency>
         <!-- TLibs' ItemSkinPreserver needs NBTAPI types; the NBTAPI plugin provides them at runtime. -->
         <dependency>
             <groupId>local</groupId>
@@ -143,13 +153,35 @@
                 </exclusion>
             </exclusions>
         </dependency>
+        <!-- Optional at runtime: softdepend in plugin.yml. Blood altars refuse WorldGuard regions. -->
+        <dependency>
+            <groupId>com.sk89q.worldguard</groupId>
+            <artifactId>worldguard-bukkit</artifactId>
+            <version>7.0.9</version>
+            <scope>provided</scope>
+        </dependency>
+        <!-- WorldGuard references metrics classes omitted from its published POM. -->
+        <dependency>
+            <groupId>org.bstats</groupId>
+            <artifactId>bstats-bukkit</artifactId>
+            <version>3.0.1</version>
+            <scope>test</scope>
+        </dependency>
     </dependencies>
 
     <repositories>
         <repository>
             <id>papermc</id>
             <url>https://repo.papermc.io/repository/maven-public/</url>
         </repository>
+        <repository>
+            <id>enginehub</id>
+            <url>https://maven.enginehub.org/repo/</url>
+        </repository>
+        <repository>
+            <id>minecraft-libraries</id>
+            <url>https://libraries.minecraft.net/</url>
+        </repository>
     </repositories>
 
     <build>

src/main/java/net/tfminecraft/magic/Magic.java

@@ -22,6 +22,7 @@
 import net.tfminecraft.magic.artifact.shrine.ShrineChargeService;
 import net.tfminecraft.magic.attunement.ArtifactDisplayIndex;
 import net.tfminecraft.magic.attunement.AuraLog;
+import net.tfminecraft.magic.blood.BloodMagic;
 import net.tfminecraft.magic.listener.ArtifactFillChestListener;
 import net.tfminecraft.magic.listener.ArtifactListener;
 import net.tfminecraft.magic.listener.CastDriftListener;
@@ -157,6 +158,7 @@ public void onEnable() {
             MagicTickService.register(ctx -> SpellModifierApplyService.syncChangedOnline(
                     resonanceGuiManager.getSessionManager()));
         }
+        BloodMagic.start(this);
         MagicTickService.start();
         getServer().getScheduler().runTask(this, ArtifactDisplayIndex::rebuildFromSaved);
         getServer().getScheduler().runTask(this, GearStationStore::load);
@@ -197,6 +199,7 @@ public void onDisable() {
         shutdownStep("fill chests", ArtifactFillChestService::clearAll);
         shutdownStep("shrine charges", ShrineChargeService::clearAll);
         shutdownStep("sacrifice rites", SacrificeRiteService::clearAll);
+        shutdownStep("blood magic", BloodMagic::stop);
         shutdownStep("spell modifiers", () -> {
             if (isMmoStackPresent()) {
                 SpellModifierApplyService.clearAll();
@@ -277,6 +280,7 @@ private boolean loadConfigs() {
         ok &= chargesLoader.loadSafe(new File(getDataFolder(), "charges.yml"));
         ok &= gearLoader.loadFolder(new File(getDataFolder(), "gear"));
         ok &= ArtifactConfigLoader.loadFolder(new File(getDataFolder(), "artifacts"));
+        ok &= BloodMagic.loadConfig(getDataFolder(), getLogger());
         AuraLog.configure(Cache.loggingEnabled, Cache.wipeLog, getDataFolder());
         if (ok) {
             getLogger().info("[Magic] Configs loaded.");
@@ -304,6 +308,7 @@ private void createFolders() {
         mkdir("artifacts");
         mkdir("gear");
         mkdir("data/characters");
+        mkdir("data/bloodmagic/characters");
     }
 
     private void mkdir(String relativePath) {
@@ -320,6 +325,16 @@ private void createConfigs() {
             "gui.yml",
             "skills.yml",
             "charges.yml",
+            "wildmagic/bloodmagic/settings.yml",
+            "wildmagic/bloodmagic/items.yml",
+            "wildmagic/bloodmagic/voices.yml",
+            "wildmagic/bloodmagic/animals.yml",
+            "wildmagic/bloodmagic/corruption.yml",
+            "wildmagic/bloodmagic/choice.yml",
+            "wildmagic/bloodmagic/armour.yml",
+            "wildmagic/bloodmagic/artefacts.yml",
+            "wildmagic/bloodmagic/fx.yml",
+            "wildmagic/bloodmagic/messages.yml",
             "gear/archetypes.yml",
             "gear/part-types.yml",
             "gear/parts.yml",

src/main/java/net/tfminecraft/magic/Messages.java

@@ -38,9 +38,44 @@ public static void loadFromResources() {
         }
     }
 
+    /**
+     * Lays a module's own message file over messages.yml: its live keys win over the main file, and its
+     * bundled copy (resourcePath in the jar) backs them up the same way messages.yml's does.
+     */
+    public static void overlay(File file, String resourcePath) {
+        FileConfiguration part = readResource(resourcePath);
+        if (part != null) {
+            bundled = copyInto(part, bundled);
+        }
+        if (file == null || !file.isFile()) {
+            return;
+        }
+        FileConfiguration live = new YamlConfiguration();
+        try {
+            live.load(file);
+            config = copyInto(live, config);
+        } catch (IOException | InvalidConfigurationException ex) {
+            Magic.plugin.getLogger().severe("[Magic] Failed to load " + file.getName() + ": " + ex.getMessage());
+        }
+    }
+
+    private static FileConfiguration copyInto(FileConfiguration from, FileConfiguration to) {
+        FileConfiguration target = to != null ? to : new YamlConfiguration();
+        for (String key : from.getKeys(true)) {
+            if (!from.isConfigurationSection(key)) {
+                target.set(key, from.get(key));
+            }
+        }
+        return target;
+    }
+
     private static FileConfiguration readBundled() {
+        return readResource("messages.yml");
+    }
+
+    private static FileConfiguration readResource(String name) {
         try {
-            InputStream resource = Magic.plugin.getResource("messages.yml");
+            InputStream resource = Magic.plugin.getResource(name);
             if (resource == null) {
                 return null;
             }
@@ -50,7 +85,7 @@ private static FileConfiguration readBundled() {
                 return loaded;
             }
         } catch (Exception ex) {
-            Magic.plugin.getLogger().warning("[Magic] Failed to load bundled messages.yml: " + ex.getMessage());
+            Magic.plugin.getLogger().warning("[Magic] Failed to load bundled " + name + ": " + ex.getMessage());
             return null;
         }
     }

src/main/java/net/tfminecraft/magic/blood/AltarCandles.java

@@ -0,0 +1,146 @@
+package net.tfminecraft.magic.blood;
+
+import java.util.ArrayList;
+import java.util.List;
+import java.util.Locale;
+import java.util.Random;
+import java.util.function.BiConsumer;
+
+import org.bukkit.Location;
+import org.bukkit.Particle;
+import org.bukkit.configuration.ConfigurationSection;
+import org.bukkit.entity.Player;
+import org.bukkit.plugin.Plugin;
+import org.bukkit.scheduler.BukkitTask;
+
+/**
+ * The flames on the altar's candles are vanilla's own candle particles (fx.yml candles:): every few
+ * ticks a small flame on each wick of the altar's model, now and then a wisp of smoke, only while a
+ * player is near. The wick positions are in the model's pixels and follow the altar's facing and scale.
+ */
+public final class AltarCandles {
+
+    /** A wick top in model pixels, and the highest altar level that still has that candle. */
+    record Wick(double x, double y, double z, int maxLevel) {}
+
+    private static boolean enabled;
+    private static int everyTicks;
+    private static double smokeChance;
+    private static double viewRange;
+    private static float yawOffset;
+    private static Particle flame;
+    private static List<Wick> wicks = List.of();
+    private static BukkitTask task;
+    private static long ticks;
+    static Random random = new Random();
+
+    static {
+        reset();
+    }
+
+    private AltarCandles() {}
+
+    static void reset() {
+        enabled = false;
+        everyTicks = 8;
+        smokeChance = 0.1;
+        viewRange = 24;
+        yawOffset = 180;
+        flame = Particle.SMALL_FLAME;
+        wicks = List.of();
+    }
+
+    static void load(ConfigurationSection section, java.util.logging.Logger log) {
+        reset();
+        if (section == null) {
+            return;
+        }
+        enabled = section.getBoolean("enabled", true);
+        everyTicks = Math.max(1, section.getInt("every_ticks", 8));
+        smokeChance = Math.max(0, Math.min(1, section.getDouble("smoke_chance", 0.1)));
+        viewRange = Math.max(1, section.getDouble("view_range", 24));
+        yawOffset = (float) section.getDouble("yaw_offset", 180);
+        String name = section.getString("particle", "SMALL_FLAME");
+        try {
+            flame = Particle.valueOf(name.trim().toUpperCase(Locale.ROOT));
+        } catch (IllegalArgumentException ex) {
+            log.warning("[Magic] blood magic config fx.candles.particle: unknown particle '" + name + "'");
+        }
+        List<Wick> out = new ArrayList<>();
+        for (Object raw : section.getList("wicks", List.of())) {
+            if (raw instanceof List<?> list && list.size() >= 3 && list.get(0) instanceof Number x
+                    && list.get(1) instanceof Number y && list.get(2) instanceof Number z) {
+                int max = list.size() > 3 && list.get(3) instanceof Number m ? m.intValue() : Integer.MAX_VALUE;
+                out.add(new Wick(x.doubleValue(), y.doubleValue(), z.doubleValue(), max));
+            } else {
+                log.warning("[Magic] blood magic config fx.candles.wicks: '" + raw + "' is not [x, y, z, max_level]");
+            }
+        }
+        wicks = List.copyOf(out);
+    }
+
+    static void startTicking(Plugin plugin) {
+        stop();
+        task = plugin.getServer().getScheduler().runTaskTimer(plugin, AltarCandles::tick, 20L, 1L);
+    }
+
+    static void stop() {
+        if (task != null) {
+            task.cancel();
+            task = null;
+        }
+    }
+
+    /** Every tick; flames go up every every_ticks for altars with a player in view. */
+    static void tick() {
+        if (!enabled || wicks.isEmpty() || ++ticks % everyTicks != 0) {
+            return;
+        }
+        for (BloodAltar altar : BloodAltars.all()) {
+            Location center = altar.center();
+            if (center == null || !center.getWorld().isChunkLoaded(altar.getX() >> 4, altar.getZ() >> 4)
+                    || !watched(center)) {
+                continue;
+            }
+            for (Wick wick : wicks) {
+                if (altar.getLevel() <= wick.maxLevel()) {
+                    light(position(center, altar.getYaw(), wick));
+                }
+            }
+        }
+    }
+
+    private static void light(Location at) {
+        spawner.accept(flame, at);
+        if (random.nextDouble() < smokeChance) {
+            spawner.accept(Particle.SMOKE, at.clone().add(0, 0.05, 0));
+        }
+    }
+
+    /** Puts one particle at a spot for the players around it. */
+    static BiConsumer<Particle, Location> spawner = (particle, at) -> at.getWorld().spawnParticle(particle, at, 1, 0, 0, 0, 0);
+
+    private static boolean watched(Location center) {
+        for (Player player : center.getWorld().getPlayers()) {
+            if (player.getLocation().distanceSquared(center) <= viewRange * viewRange) {
+                return true;
+            }
+        }
+        return false;
+    }
+
+    /**
+     * Where a wick of the model is in the world: the model is centred on the altar's block, scaled by
+     * altar.display_scale and turned by the altar's yaw (plus yaw_offset for how item displays face).
+     */
+    static Location position(Location center, float yaw, Wick wick) {
+        double scale = BloodConfig.displayScale();
+        double x = (wick.x() - 8) / 16 * scale;
+        double y = (wick.y() - 8) / 16 * scale;
+        double z = (wick.z() - 8) / 16 * scale;
+        double angle = Math.toRadians(-(yaw + yawOffset));
+        double cos = Math.cos(angle);
+        double sin = Math.sin(angle);
+        return center.clone().add(x * cos + z * sin, y, -x * sin + z * cos);
+    }
+}