feat: probabilistic stone charging with harmonic decay via ender pearls

Author: Dean904

src/main/java/bor/samsara/questing/SamsaraFabricQuesting.java

@@ -23,13 +23,10 @@
 import net.fabricmc.fabric.api.event.player.UseEntityCallback;
 import net.fabricmc.fabric.api.event.player.UseItemCallback;
 import net.fabricmc.fabric.api.networking.v1.ServerPlayConnectionEvents;
-import net.minecraft.entity.LivingEntity;
-import net.minecraft.entity.damage.DamageSource;
 import net.minecraft.server.command.CommandManager;
 import net.minecraft.server.command.ServerCommandSource;
 import net.minecraft.server.network.ServerPlayerEntity;
 import org.apache.commons.lang3.StringUtils;
-import org.jetbrains.annotations.NotNull;
 import org.slf4j.Logger;
 import org.slf4j.LoggerFactory;
 

src/main/java/bor/samsara/questing/hearth/HearthStoneEventRegisters.java

@@ -114,9 +114,17 @@ public static CommandRegistrationCallback createHearthstone() {
             if (isHearthstone(stack)) {
 
                 if (player.getOffHandStack().isOf(Items.ENDER_PEARL)) {
-                    Sounds.toOnlyPlayer((ServerPlayerEntity) player, SoundEvents.BLOCK_BEACON_POWER_SELECT);
+                    if (isMaxCharged(stack)) {
+                        player.sendMessage(Text.literal("The stone cannot hold more charges.").styled(s -> s.withColor(Formatting.YELLOW)), true);
+                        return ActionResult.CONSUME;
+                    }
                     player.getOffHandStack().decrement(1);
-                    adjustCharges(stack, +1);
+                    if (rollCharge(stack)) {
+                        Sounds.toOnlyPlayer((ServerPlayerEntity) player, SoundEvents.BLOCK_BEACON_POWER_SELECT);
+                    } else {
+                        Sounds.toOnlyPlayer((ServerPlayerEntity) player, SoundEvents.ITEM_WOLF_ARMOR_REPAIR);
+                        player.sendMessage(Text.literal("The pearl dissolved... no charge gained.").styled(s -> s.withColor(Formatting.GRAY)), true);
+                    }
                     return ActionResult.CONSUME;
                 }
 

src/main/java/bor/samsara/questing/hearth/SoulStoneEventRegisters.java

@@ -103,9 +103,17 @@ public static UseItemCallback useSoulstone() {
 
             if (isSoulStone(stack)) {
                 if (player.getOffHandStack().isOf(Items.ENDER_PEARL)) {
-                    Sounds.toOnlyPlayer((ServerPlayerEntity) player, SoundEvents.BLOCK_TRIAL_SPAWNER_OMINOUS_ACTIVATE);
+                    if (isMaxCharged(stack)) {
+                        player.sendMessage(Text.literal("The stone cannot hold more charges.").styled(s -> s.withColor(Formatting.YELLOW)), true);
+                        return ActionResult.CONSUME;
+                    }
                     player.getOffHandStack().decrement(1);
-                    adjustCharges(stack, +1);
+                    if (rollCharge(stack)) {
+                        Sounds.toOnlyPlayer((ServerPlayerEntity) player, SoundEvents.BLOCK_TRIAL_SPAWNER_OMINOUS_ACTIVATE);
+                    } else {
+                        Sounds.toOnlyPlayer((ServerPlayerEntity) player, SoundEvents.ITEM_OMINOUS_BOTTLE_DISPOSE.value());
+                        player.sendMessage(Text.literal("The pearl dissolved... no charge gained.").styled(s -> s.withColor(Formatting.GRAY)), true);
+                    }
                     return ActionResult.CONSUME;
                 }
                 if (player.getMovement().equals(Vec3d.ZERO)) {

src/main/java/bor/samsara/questing/hearth/WarpStone.java

@@ -21,6 +21,10 @@
 public abstract class WarpStone {
 
     protected static final String STONE_CHARGES = "stoneCharges";
+    protected static final int MAX_CHARGES = 64;
+    // p(c) = ALPHA/(c+ALPHA) — harmonic decay, so cost-per-charge grows linearly with c (log-scale).
+    // ALPHA chosen so Σ(c=0..63) (c+ALPHA)/ALPHA = 864: ALPHA = 2016/(864-64) = 2.52
+    private static final double CHARGE_ALPHA = 2.52;
 
     static final ExecutorService executor = Executors.newThreadPerTaskExecutor(runnable -> new Thread(runnable, "HearthStoneEvent-Thread"));
     static final Map<String, TeleportTask> playerTeleportTasks = new ConcurrentHashMap<>();
@@ -63,11 +67,26 @@ protected static void adjustCharges(ItemStack stack, int amount) {
         stack.set(DataComponentTypes.LORE, new LoreComponent(lines));
     }
 
+    protected static int getCharges(ItemStack stack) {
+        return stack.get(DataComponentTypes.CUSTOM_DATA).copyNbt().getInt(STONE_CHARGES, 0);
+    }
+
     protected static boolean isCharged(ItemStack stack) {
-        NbtComponent customData = stack.get(DataComponentTypes.CUSTOM_DATA);
-        NbtCompound nbt = customData.copyNbt();
-        int charges = nbt.getInt(STONE_CHARGES, 0);
-        return charges > 0;
+        return getCharges(stack) > 0;
+    }
+
+    protected static boolean isMaxCharged(ItemStack stack) {
+        return getCharges(stack) >= MAX_CHARGES;
+    }
+
+    /** Consumes one charge attempt. Returns true if the pearl succeeded, false if it fizzled. */
+    protected static boolean rollCharge(ItemStack stack) {
+        int c = getCharges(stack);
+        if (Math.random() < CHARGE_ALPHA / (c + CHARGE_ALPHA)) {
+            adjustCharges(stack, +1);
+            return true;
+        }
+        return false;
     }
 
     static double jitter(double d) {