From cfeed8716a7f8f113f7f93c694a6bfe988918ccb Mon Sep 17 00:00:00 2001 From: Michael Gilardi <11632652+mgilardi@users.noreply.github.com> Date: Sun, 15 Nov 2026 23:33:26 -0700 Subject: [PATCH 1/2] Add an API for other plugins, for MobShowdown MobShowdown builds its battles on MobSquad (brief). The API reads a player's critters, checks whether one is out, sends them home, keeps MobSquad off in a private world and gives a critter's strength at a level. It can't change critters, and MobSquad's safety rules are untouched because arena fights use MobShowdown's own mobs. Unit tests for the stats and the read-only view; the services-manager wiring is exercised by MobShowdown's bot tests, not yet run. Co-Authored-By: Claude Opus 5.5 --- CHANGELOG.md | 7 ++ README.md | 4 ++ build.gradle.kts | 2 +- docs/decisions.md | 5 ++ .../extantape/mobsquad/MobSquadPlugin.java | 2 + .../java/com/extantape/mobsquad/Squads.java | 9 +++ .../java/com/extantape/mobsquad/api/Api.java | 69 +++++++++++++++++++ .../extantape/mobsquad/api/CritterInfo.java | 10 +++ .../extantape/mobsquad/api/CritterStats.java | 8 +++ .../extantape/mobsquad/api/MobSquadApi.java | 41 +++++++++++ .../com/extantape/mobsquad/api/ApiTest.java | 54 +++++++++++++++ 11 files changed, 210 insertions(+), 1 deletion(-) create mode 100644 src/main/java/com/extantape/mobsquad/api/Api.java create mode 100644 src/main/java/com/extantape/mobsquad/api/CritterInfo.java create mode 100644 src/main/java/com/extantape/mobsquad/api/CritterStats.java create mode 100644 src/main/java/com/extantape/mobsquad/api/MobSquadApi.java create mode 100644 src/test/java/com/extantape/mobsquad/api/ApiTest.java diff --git a/CHANGELOG.md b/CHANGELOG.md index 7ee5583..35824a1 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -1,5 +1,12 @@ # Changelog +## 0.7.0 + +An API for other plugins, for MobShowdown. + +- **MobSquadApi**, from Bukkit's services manager: a player's critters (read-only), whether they have one out, sending them home, whether MobSquad is on in a world, keeping it off in another plugin's private world until the server stops, and a critter's strength at a level. Nothing in it lets another plugin add, remove or change a critter. +- Nothing changes for players. + ## 0.6.0 Wranglin' in AuraSkills. diff --git a/README.md b/README.md index e3ad6e2..6424f45 100644 --- a/README.md +++ b/README.md @@ -56,6 +56,10 @@ Settings are in `plugins/MobSquad/config.yml`: worlds where MobSquad is off, the `/ms` works too. Permissions: `mobsquad.use` (everyone) and `mobsquad.admin` (ops). +## For other plugins + +MobSquad registers `com.extantape.mobsquad.api.MobSquadApi` with Bukkit's services manager. Another plugin can read a player's critters, check whether one is out, send them home, ask whether MobSquad is on in a world, keep it off in its own private world, and get a critter's health, damage and speed at a level. It can't add, remove or change critters. MobShowdown uses it for its battles. Call it on the main thread, and check `version()` before using anything newer than version 1. + ## Tests `test/suite.mjs` builds a throwaway Paper server on 127.0.0.1 from downloaded jars and drives it with bots. See the top of the file for what it can and can't check. diff --git a/build.gradle.kts b/build.gradle.kts index c739650..4d5cfc4 100644 --- a/build.gradle.kts +++ b/build.gradle.kts @@ -3,7 +3,7 @@ plugins { } group = "com.extantape" -version = "0.6.0" +version = "0.7.0" java { toolchain.languageVersion.set(JavaLanguageVersion.of(25)) diff --git a/docs/decisions.md b/docs/decisions.md index b4eff25..282b82b 100644 --- a/docs/decisions.md +++ b/docs/decisions.md @@ -35,3 +35,8 @@ Dated decisions for this repo, newest last. - 2026-11-15: until the Waystation hook exists, a sidekick never goes into the Bunkhouse on a player's say. It still leaves the world like any critter when its owner leaves, the server stops, or it's tuckered out, and comes back on its own when it can. A disabled world or a locked tier keeps it home. - 2026-11-15: the brief's "later" parts of four specials unlock at level 25, the first milestone, and grow at the next ones: speedy eggs (first one 30 seconds after going out, then every 5 minutes, a minute sooner per later milestone; Speed II, III from level 75), the glowing sting (10 seconds, 5 more per later milestone), the pounce (a leap of up to 6 blocks at a mob not targeting the fox, double damage on the first hit, every 8 seconds, a second sooner per later milestone) and shared arrows (two every 2 minutes while carrying a bow or crossbow, one more and 20 seconds sooner per later milestone). - 2026-11-15: speedy eggs can be picked up only by the chicken's owner and are used, never thrown, so they can't hatch chickens. + +## 2026-11-15 + +- **API for MobShowdown (K605):** MobSquad exposes a read-only API through Bukkit's services manager, so MobShowdown builds on it as the brief says ("MobShowdown: battles, built on MobSquad's API"). Arena fights use MobShowdown's own stand-in mobs, so MobSquad's safety rules (critters fight hostile mobs only, never players) stay exactly as they are, and MobSquad stays off in the arena world. Released as 0.7.0. + diff --git a/src/main/java/com/extantape/mobsquad/MobSquadPlugin.java b/src/main/java/com/extantape/mobsquad/MobSquadPlugin.java index 0894f12..a442b13 100644 --- a/src/main/java/com/extantape/mobsquad/MobSquadPlugin.java +++ b/src/main/java/com/extantape/mobsquad/MobSquadPlugin.java @@ -61,6 +61,8 @@ public void onEnable() { } Posse posse = new Posse(this, o -> {}); squads.posse(posse); + getServer().getServicesManager().register(com.extantape.mobsquad.api.MobSquadApi.class, + new com.extantape.mobsquad.api.Api(squads), this, org.bukkit.plugin.ServicePriority.Normal); bunkhouses = new Bunkhouses(this); dinnerbell = new Dinnerbell(this, squads); Coaxing coaxing = new Coaxing(squads); diff --git a/src/main/java/com/extantape/mobsquad/Squads.java b/src/main/java/com/extantape/mobsquad/Squads.java index dc41dae..05da205 100644 --- a/src/main/java/com/extantape/mobsquad/Squads.java +++ b/src/main/java/com/extantape/mobsquad/Squads.java @@ -38,9 +38,18 @@ public void posse(Posse posse) { } public void settings(Settings settings) { + settings.disabledWorlds().addAll(keptOff); this.settings = settings; } + private final java.util.Set keptOff = new java.util.HashSet<>(); + + /** Keeps MobSquad off in a world until the server stops, for another plugin's private world (API). */ + public void keepOff(String world) { + keptOff.add(world); + settings.disabledWorlds().add(world); + } + public Settings settings() { return settings; } diff --git a/src/main/java/com/extantape/mobsquad/api/Api.java b/src/main/java/com/extantape/mobsquad/api/Api.java new file mode 100644 index 0000000..d080a6a --- /dev/null +++ b/src/main/java/com/extantape/mobsquad/api/Api.java @@ -0,0 +1,69 @@ +package com.extantape.mobsquad.api; + +import com.extantape.mobsquad.Squads; +import com.extantape.mobsquad.model.Critter; +import com.extantape.mobsquad.model.Growth; +import com.extantape.mobsquad.model.Species; +import java.util.ArrayList; +import java.util.List; +import org.bukkit.World; +import org.bukkit.entity.Player; + +/** MobSquad's own answer to {@link MobSquadApi}. */ +public final class Api implements MobSquadApi { + /** The skeleton's arrow, before growth; kept equal to Fights' arrow. */ + static final double ARROW = 2.0; + private final Squads squads; + + public Api(Squads squads) { + this.squads = squads; + } + + @Override + public List critters(Player player) { + if (player == null || !player.isOnline()) return List.of(); + long now = System.currentTimeMillis(); + List list = new ArrayList<>(); + for (Critter c : squads.get(player).critters) list.add(info(c, now)); + return List.copyOf(list); + } + + static CritterInfo info(Critter c, long now) { + return new CritterInfo(c.id(), c.species().id(), c.species().entity, c.name(), c.level(), c.resting(now), fights(c.species())); + } + + static boolean fights(Species s) { + return s != Species.ALLAY; + } + + @Override + public boolean hasCritterOut(Player player) { + return player != null && !squads.posse().of(player.getUniqueId()).isEmpty(); + } + + @Override + public void sendHome(Player player) { + if (player != null) squads.posse().backAll(player.getUniqueId()); + } + + @Override + public boolean enabledIn(World world) { + return world != null && squads.settings().enabledIn(world.getName()); + } + + @Override + public void keepOff(String worldName) { + if (worldName != null && !worldName.isBlank()) squads.keepOff(worldName); + } + + @Override + public CritterStats stats(String species, int level) { + return statsFor(Species.byId(species), level); + } + + static CritterStats statsFor(Species s, int level) { + if (s == null) return new CritterStats(1, 0, 1); + double base = !fights(s) ? 0 : s == Species.SKELETON ? ARROW : s.attack; + return new CritterStats(Growth.health(level), base * Growth.attack(level), Growth.speed(level)); + } +} diff --git a/src/main/java/com/extantape/mobsquad/api/CritterInfo.java b/src/main/java/com/extantape/mobsquad/api/CritterInfo.java new file mode 100644 index 0000000..ecf4179 --- /dev/null +++ b/src/main/java/com/extantape/mobsquad/api/CritterInfo.java @@ -0,0 +1,10 @@ +package com.extantape.mobsquad.api; + +import java.util.UUID; + +/** + * One critter, read-only. {@code species} is MobSquad's id ("iron_golem"), {@code entityType} the Minecraft entity + * ("IRON_GOLEM"). {@code resting} is true while it's tuckered out. {@code fights} is false for a critter that never + * fights (the allay). + */ +public record CritterInfo(UUID id, String species, String entityType, String name, int level, boolean resting, boolean fights) {} diff --git a/src/main/java/com/extantape/mobsquad/api/CritterStats.java b/src/main/java/com/extantape/mobsquad/api/CritterStats.java new file mode 100644 index 0000000..5b1fa5d --- /dev/null +++ b/src/main/java/com/extantape/mobsquad/api/CritterStats.java @@ -0,0 +1,8 @@ +package com.extantape.mobsquad.api; + +/** + * A critter's strength at a level. {@code healthScale} multiplies the mob's normal max health and {@code speedScale} + * its speed. {@code damage} is what one hit or shot does: its close-up attack, or the skeleton's arrow, both grown + * with level; 0 for a critter that never fights. + */ +public record CritterStats(double healthScale, double damage, double speedScale) {} diff --git a/src/main/java/com/extantape/mobsquad/api/MobSquadApi.java b/src/main/java/com/extantape/mobsquad/api/MobSquadApi.java new file mode 100644 index 0000000..ff9554a --- /dev/null +++ b/src/main/java/com/extantape/mobsquad/api/MobSquadApi.java @@ -0,0 +1,41 @@ +package com.extantape.mobsquad.api; + +import java.util.List; +import java.util.UUID; +import org.bukkit.World; +import org.bukkit.entity.Player; + +/** + * MobSquad for other plugins, such as MobShowdown. Get it from Bukkit's services manager: + * {@code Bukkit.getServicesManager().load(MobSquadApi.class)}. Call it on the main thread. + * Nothing here lets another plugin change a player's critters: it can read them and send them home. + */ +public interface MobSquadApi { + /** Bumped when a method is added or changes; check it before relying on anything newer. */ + int VERSION = 1; + + default int version() { + return VERSION; + } + + /** A player's Bunkhouse, in their own order. Empty for a player who isn't online. */ + List critters(Player player); + + /** Whether the player has a critter out with them right now, sidekick included. */ + boolean hasCritterOut(Player player); + + /** Sends every critter the player has out back to their Bunkhouse, sidekick included. */ + void sendHome(Player player); + + /** Whether MobSquad is on in this world. */ + boolean enabledIn(World world); + + /** + * Keeps MobSquad off in a world until the server stops, as if it were listed under disabled-worlds, without + * touching config.yml. For a plugin's own private world, such as MobShowdown's arena. + */ + void keepOff(String worldName); + + /** How strong a critter of this species is at this level, for a plugin that stages its own fights. */ + CritterStats stats(String species, int level); +} diff --git a/src/test/java/com/extantape/mobsquad/api/ApiTest.java b/src/test/java/com/extantape/mobsquad/api/ApiTest.java new file mode 100644 index 0000000..27461fc --- /dev/null +++ b/src/test/java/com/extantape/mobsquad/api/ApiTest.java @@ -0,0 +1,54 @@ +package com.extantape.mobsquad.api; + +import com.extantape.mobsquad.model.Critter; +import com.extantape.mobsquad.model.Growth; +import com.extantape.mobsquad.model.Species; +import org.junit.jupiter.api.Test; + +import static org.junit.jupiter.api.Assertions.*; + +class ApiTest { + @Test + void theAllayNeverFightsAndEveryOtherCritterDoes() { + for (Species s : Species.values()) { + CritterStats st = Api.statsFor(s, 50); + if (s == Species.ALLAY) assertEquals(0, st.damage(), s.id()); + else assertTrue(st.damage() > 0, s.id()); + assertEquals(s != Species.ALLAY, Api.fights(s), s.id()); + } + } + + @Test + void statsGrowWithLevelTheSameWayAsInTheWorld() { + CritterStats one = Api.statsFor(Species.FOX, 1), top = Api.statsFor(Species.FOX, 100); + assertEquals(1, one.healthScale(), 1e-9); + assertEquals(Species.FOX.attack, one.damage(), 1e-9); + assertEquals(Growth.health(100), top.healthScale(), 1e-9); + assertEquals(Species.FOX.attack * Growth.attack(100), top.damage(), 1e-9); + assertEquals(Growth.speed(100), top.speedScale(), 1e-9); + } + + @Test + void theSkeletonsDamageIsItsArrow() { + assertEquals(Api.ARROW, Api.statsFor(Species.SKELETON, 1).damage(), 1e-9); + } + + @Test + void anUnknownSpeciesIsHarmless() { + CritterStats st = Api.statsFor(null, 40); + assertEquals(0, st.damage()); + assertEquals(1, st.healthScale()); + } + + @Test + void infoCopiesTheCritterAndSaysWhenItsResting() { + Critter c = Critter.fresh(Species.IRON_GOLEM).withXp(Growth.xpFor(30)).tuckered(5_000); + CritterInfo i = Api.info(c, 1_000); + assertEquals(c.id(), i.id()); + assertEquals("iron_golem", i.species()); + assertEquals("IRON_GOLEM", i.entityType()); + assertEquals(30, i.level()); + assertTrue(i.resting()); + assertFalse(Api.info(c, 6_000).resting()); + } +} From 6da704f59776ff4d41f9f614fcd1a442bf297d3a Mon Sep 17 00:00:00 2001 From: Michael Gilardi <11632652+mgilardi@users.noreply.github.com> Date: Sun, 15 Nov 2026 23:33:40 -0700 Subject: [PATCH 2/2] Add the API to the test audit Co-Authored-By: Claude Opus 5.5 --- docs/test-audit.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/docs/test-audit.md b/docs/test-audit.md index 8d54308..5565679 100644 --- a/docs/test-audit.md +++ b/docs/test-audit.md @@ -56,3 +56,14 @@ Kept by this repo's owning session, per `~/Code/CLAUDE.md`, "Test self-audits". - Covered: none yet. - Gaps added: none. - Gaps skipped (and why): none. + +## 2026-11-15: API (0.7.0) + +| Promise | Test | +| --- | --- | +| The allay never fights; every other critter has damage | unit `theAllayNeverFightsAndEveryOtherCritterDoes` | +| Stats grow the same way as in the world | unit `statsGrowWithLevelTheSameWayAsInTheWorld`, `theSkeletonsDamageIsItsArrow` | +| An unknown species does no damage | unit `anUnknownSpeciesIsHarmless` | +| The critter view is a read-only copy with the resting state | unit `infoCopiesTheCritterAndSaysWhenItsResting` | + +**Gaps:** the services-manager registration, `sendHome` and `keepOff` on a running server. MobShowdown's bot tests cover them, since they're what calls them.