Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions CHANGELOG.md
Original file line number Diff line number Diff line change
@@ -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.
Expand Down
4 changes: 4 additions & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
Expand Down
2 changes: 1 addition & 1 deletion build.gradle.kts
Original file line number Diff line number Diff line change
Expand Up @@ -3,7 +3,7 @@ plugins {
}

group = "com.extantape"
version = "0.6.0"
version = "0.7.0"

java {
toolchain.languageVersion.set(JavaLanguageVersion.of(25))
Expand Down
5 changes: 5 additions & 0 deletions docs/decisions.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.

11 changes: 11 additions & 0 deletions docs/test-audit.md
Original file line number Diff line number Diff line change
Expand Up @@ -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.
2 changes: 2 additions & 0 deletions src/main/java/com/extantape/mobsquad/MobSquadPlugin.java
Original file line number Diff line number Diff line change
Expand Up @@ -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);
Expand Down
9 changes: 9 additions & 0 deletions src/main/java/com/extantape/mobsquad/Squads.java
Original file line number Diff line number Diff line change
Expand Up @@ -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<String> 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;
}
Expand Down
69 changes: 69 additions & 0 deletions src/main/java/com/extantape/mobsquad/api/Api.java
Original file line number Diff line number Diff line change
@@ -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<CritterInfo> critters(Player player) {
if (player == null || !player.isOnline()) return List.of();
long now = System.currentTimeMillis();
List<CritterInfo> 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));
}
}
10 changes: 10 additions & 0 deletions src/main/java/com/extantape/mobsquad/api/CritterInfo.java
Original file line number Diff line number Diff line change
@@ -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) {}
8 changes: 8 additions & 0 deletions src/main/java/com/extantape/mobsquad/api/CritterStats.java
Original file line number Diff line number Diff line change
@@ -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) {}
41 changes: 41 additions & 0 deletions src/main/java/com/extantape/mobsquad/api/MobSquadApi.java
Original file line number Diff line number Diff line change
@@ -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<CritterInfo> 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);
}
54 changes: 54 additions & 0 deletions src/test/java/com/extantape/mobsquad/api/ApiTest.java
Original file line number Diff line number Diff line change
@@ -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());
}
}
Loading