From 7c7377171b0c2ea653b17a0a7d3338041f8b1b7b Mon Sep 17 00:00:00 2001 From: Pim van der Loos Date: Thu, 16 Jul 2026 11:28:14 +0200 Subject: [PATCH 1/5] test: drop deprecated-surface pins Goal: remove the entire @Deprecated(forRemoval = true) API surface from LightKeeper. Plan: (1) drop the tests that only pin the deprecated surface, (2) remove the v1 facade delegates, (3) remove the Vector3Di vocabulary, (4) remove CapturedEventSnapshot.data(), (5) refresh the README. This is step 1. Dropping these pins first keeps every subsequent removal commit green: nothing left references the deprecated members once the surface is gone. - Delete DeprecatedDelegateTest entirely: it exists solely to pin that each v1 default method delegates to its facet replacement. The facet behaviour itself is covered by the facade/facet tests, so no real coverage is lost. - Drop the deprecated-overload pins whose canonical BlockPos paths are already covered: WorldHandleTest (blockTypeAt/setBlockAt Vector3Di), PlayerHandleTest (leftClickBlock Vector3Di), HandleAssertionsTest (hasBlockAt Vector3Di). - Drop CapturedEventSnapshotTest.data(): pins the deprecated raw-string view; values()/value() coverage stays. - Remove the now-orphaned @SuppressWarnings("removal") and unused imports. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01P15FjGQzyNmX9T6Qmyq8Dn --- .../framework/CapturedEventSnapshotTest.java | 22 - .../framework/DeprecatedDelegateTest.java | 443 ------------------ .../framework/PlayerHandleTest.java | 16 - .../framework/WorldHandleTest.java | 30 -- .../assertions/HandleAssertionsTest.java | 13 - 5 files changed, 524 deletions(-) delete mode 100644 lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/DeprecatedDelegateTest.java diff --git a/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/CapturedEventSnapshotTest.java b/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/CapturedEventSnapshotTest.java index d1be32df..b54c7ed4 100644 --- a/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/CapturedEventSnapshotTest.java +++ b/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/CapturedEventSnapshotTest.java @@ -3,7 +3,6 @@ import nl.pim16aap2.lightkeeper.protocol.IProtocolValue; import org.junit.jupiter.api.Test; -import java.util.LinkedHashMap; import java.util.Map; import static org.assertj.core.api.Assertions.assertThat; @@ -42,27 +41,6 @@ void value_shouldReturnNullForUnknownAccessor() assertThat(result).isNull(); } - @Test - @SuppressWarnings("removal") // Intentionally exercises the deprecated-for-removal data() view. - void data_shouldRenderEachValueAsDisplayStringInCaptureOrder() - { - // setup - final Map values = new LinkedHashMap<>(); - values.put("getName", new IProtocolValue.PString("Steve")); - values.put("isCancelled", new IProtocolValue.PBool(false)); - values.put("getCount", new IProtocolValue.PNumber(3)); - final CapturedEventSnapshot snapshot = new CapturedEventSnapshot("event.Class", 1L, values); - - // execute - final Map rendered = snapshot.data(); - - // verify - assertThat(rendered).containsExactly( - Map.entry("getName", "Steve"), - Map.entry("isCancelled", "false"), - Map.entry("getCount", "3")); - } - @Test @SuppressWarnings("NullAway") // Intentionally crosses the non-null API boundary to verify default-on-null. void constructor_shouldDefaultToEmptyMapWhenValuesIsNull() diff --git a/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/DeprecatedDelegateTest.java b/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/DeprecatedDelegateTest.java deleted file mode 100644 index 8edf656c..00000000 --- a/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/DeprecatedDelegateTest.java +++ /dev/null @@ -1,443 +0,0 @@ -package nl.pim16aap2.lightkeeper.framework; - -import nl.pim16aap2.lightkeeper.protocol.CommandSource; -import org.junit.jupiter.api.Test; - -import java.nio.file.Path; -import java.time.Duration; -import java.util.List; -import java.util.Objects; -import java.util.UUID; - -import static org.assertj.core.api.Assertions.assertThat; -import static org.mockito.Mockito.mock; -import static org.mockito.Mockito.verify; -import static org.mockito.Mockito.when; - -/** - * Pins that every deprecated v1 method on {@link ILightkeeperFramework} delegates to its facet replacement. - * - *

Uses a hand-written facet-stub implementation so the deprecated default methods run against mocked facets; - * this keeps the delegation contract under test without touching {@code DefaultLightkeeperFramework}. - */ -@SuppressWarnings("removal") // Dedicated delegate test: it intentionally exercises the deprecated-for-removal API. -class DeprecatedDelegateTest -{ - @Test - void mainWorld_shouldDelegateToWorldsMain() - { - // setup - final IWorlds worlds = mock(IWorlds.class); - final WorldHandle expected = worldHandle(); - when(worlds.main()).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithWorlds(worlds); - - // execute - final WorldHandle result = framework.mainWorld(); - - // verify - assertThat(result).isSameAs(expected); - verify(worlds).main(); - } - - @Test - void newWorld_shouldDelegateToWorldsCreate() - { - // setup - final IWorlds worlds = mock(IWorlds.class); - final WorldHandle expected = worldHandle(); - when(worlds.create()).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithWorlds(worlds); - - // execute - final WorldHandle result = framework.newWorld(); - - // verify - assertThat(result).isSameAs(expected); - verify(worlds).create(); - } - - @Test - void newWorld_shouldDelegateToWorldsCreateWithSpec() - { - // setup - final IWorlds worlds = mock(IWorlds.class); - final WorldSpec spec = - new WorldSpec("w", WorldSpec.WorldType.NORMAL, WorldSpec.WorldEnvironment.NORMAL, 0L); - final WorldHandle expected = worldHandle(); - when(worlds.create(spec)).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithWorlds(worlds); - - // execute - final WorldHandle result = framework.newWorld(spec); - - // verify - assertThat(result).isSameAs(expected); - verify(worlds).create(spec); - } - - @Test - void newWorldFromTemplate_shouldDelegateToWorldsFromTemplate() - { - // setup - final IWorlds worlds = mock(IWorlds.class); - final WorldHandle expected = worldHandle(); - when(worlds.fromTemplate("template-a")).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithWorlds(worlds); - - // execute - final WorldHandle result = framework.newWorldFromTemplate("template-a"); - - // verify - assertThat(result).isSameAs(expected); - verify(worlds).fromTemplate("template-a"); - } - - @Test - void buildWorld_shouldDelegateToWorldsBuilder() - { - // setup - final IWorlds worlds = mock(IWorlds.class); - final IWorldBuilder expected = mock(IWorldBuilder.class); - when(worlds.builder()).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithWorlds(worlds); - - // execute - final IWorldBuilder result = framework.buildWorld(); - - // verify - assertThat(result).isSameAs(expected); - verify(worlds).builder(); - } - - @Test - void createPlayer_shouldDelegateToBotsJoin() - { - // setup - final IBots bots = mock(IBots.class); - final WorldHandle world = worldHandle(); - final PlayerHandle expected = playerHandle(); - when(bots.join("bot", world)).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithBots(bots); - - // execute - final PlayerHandle result = framework.createPlayer("bot", world); - - // verify - assertThat(result).isSameAs(expected); - verify(bots).join("bot", world); - } - - @Test - void createPlayer_shouldDelegateToBotsJoinWithUuid() - { - // setup - final IBots bots = mock(IBots.class); - final WorldHandle world = worldHandle(); - final UUID uuid = UUID.randomUUID(); - final PlayerHandle expected = playerHandle(); - when(bots.join("bot", uuid, world)).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithBots(bots); - - // execute - final PlayerHandle result = framework.createPlayer("bot", uuid, world); - - // verify - assertThat(result).isSameAs(expected); - verify(bots).join("bot", uuid, world); - } - - @Test - void buildPlayer_shouldDelegateToBotsBuilder() - { - // setup - final IBots bots = mock(IBots.class); - final IPlayerBuilder expected = mock(IPlayerBuilder.class); - when(bots.builder()).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithBots(bots); - - // execute - final IPlayerBuilder result = framework.buildPlayer(); - - // verify - assertThat(result).isSameAs(expected); - verify(bots).builder(); - } - - @Test - void executeCommand_shouldDelegateToServerExecuteCommand() - { - // setup - final IServerControl server = mock(IServerControl.class); - final CommandResult expected = new CommandResult(true, "ok"); - when(server.executeCommand(CommandSource.CONSOLE, "time set day")).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithServer(server); - - // execute - final CommandResult result = framework.executeCommand(CommandSource.CONSOLE, "time set day"); - - // verify - assertThat(result).isSameAs(expected); - verify(server).executeCommand(CommandSource.CONSOLE, "time set day"); - } - - @Test - void serverOutput_shouldDelegateToServerOutput() - { - // setup - final IServerControl server = mock(IServerControl.class); - final List expected = List.of("line one", "line two"); - when(server.output()).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithServer(server); - - // execute - final List result = framework.serverOutput(); - - // verify - assertThat(result).isSameAs(expected); - verify(server).output(); - } - - @Test - void platform_shouldDelegateToServerPlatform() - { - // setup - final IServerControl server = mock(IServerControl.class); - when(server.platform()).thenReturn(Platform.PAPER); - final ILightkeeperFramework framework = frameworkWithServer(server); - - // execute - final Platform result = framework.platform(); - - // verify - assertThat(result).isEqualTo(Platform.PAPER); - verify(server).platform(); - } - - @Test - void serverDirectory_shouldDelegateToServerDirectory() - { - // setup - final IServerControl server = mock(IServerControl.class); - final Path expected = Path.of("/tmp/lightkeeper/server"); - when(server.directory()).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithServer(server); - - // execute - final Path result = framework.serverDirectory(); - - // verify - assertThat(result).isSameAs(expected); - verify(server).directory(); - } - - @Test - void pluginDataDirectory_shouldDelegateToServerPluginDataDirectory() - { - // setup - final IServerControl server = mock(IServerControl.class); - final Path expected = Path.of("/tmp/lightkeeper/server/plugins/AnimatedArchitecture"); - when(server.pluginDataDirectory("AnimatedArchitecture")).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithServer(server); - - // execute - final Path result = framework.pluginDataDirectory("AnimatedArchitecture"); - - // verify - assertThat(result).isSameAs(expected); - verify(server).pluginDataDirectory("AnimatedArchitecture"); - } - - @Test - void crashServer_shouldDelegateToServerCrash() - { - // setup - final IServerControl server = mock(IServerControl.class); - final ILightkeeperFramework framework = frameworkWithServer(server); - - // execute - framework.crashServer(); - - // verify - verify(server).crash(); - } - - @Test - void stopServer_shouldDelegateToServerStop() - { - // setup - final IServerControl server = mock(IServerControl.class); - final ILightkeeperFramework framework = frameworkWithServer(server); - - // execute - framework.stopServer(); - - // verify - verify(server).stop(); - } - - @Test - void startServer_shouldDelegateToServerStart() - { - // setup - final IServerControl server = mock(IServerControl.class); - final ILightkeeperFramework framework = frameworkWithServer(server); - - // execute - framework.startServer(); - - // verify - verify(server).start(); - } - - @Test - void restartServer_shouldDelegateToServerRestart() - { - // setup - final IServerControl server = mock(IServerControl.class); - final ILightkeeperFramework framework = frameworkWithServer(server); - - // execute - framework.restartServer(); - - // verify - verify(server).restart(); - } - - @Test - void currentServerTick_shouldDelegateToServerCurrentTick() - { - // setup - final IServerControl server = mock(IServerControl.class); - when(server.currentTick()).thenReturn(123L); - final ILightkeeperFramework framework = frameworkWithServer(server); - - // execute - final long result = framework.currentServerTick(); - - // verify - assertThat(result).isEqualTo(123L); - verify(server).currentTick(); - } - - @Test - void serverErrors_shouldDelegateToServerErrors() - { - // setup - final IServerControl server = mock(IServerControl.class); - final ServerErrorsHandle expected = - FrameworkHandleFactory.serverErrorsHandle(mock(IFrameworkGatewayView.class)); - when(server.errors()).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithServer(server); - - // execute - final ServerErrorsHandle result = framework.serverErrors(); - - // verify - assertThat(result).isSameAs(expected); - verify(server).errors(); - } - - @Test - void captureEvents_shouldDelegateToEventsCapture() - { - // setup - final IEvents events = mock(IEvents.class); - final EventCaptureHandle expected = FrameworkHandleFactory.eventCaptureHandle( - mock(IFrameworkGatewayView.class), "org.bukkit.event.player.PlayerJoinEvent"); - when(events.capture("org.bukkit.event.player.PlayerJoinEvent")).thenReturn(expected); - final ILightkeeperFramework framework = frameworkWithEvents(events); - - // execute - final EventCaptureHandle result = framework.captureEvents("org.bukkit.event.player.PlayerJoinEvent"); - - // verify - assertThat(result).isSameAs(expected); - verify(events).capture("org.bukkit.event.player.PlayerJoinEvent"); - } - - private static ILightkeeperFramework frameworkWithServer(IServerControl server) - { - return new FacetStubFramework(server, mock(IWorlds.class), mock(IBots.class), mock(IEvents.class)); - } - - private static ILightkeeperFramework frameworkWithWorlds(IWorlds worlds) - { - return new FacetStubFramework(mock(IServerControl.class), worlds, mock(IBots.class), mock(IEvents.class)); - } - - private static ILightkeeperFramework frameworkWithBots(IBots bots) - { - return new FacetStubFramework(mock(IServerControl.class), mock(IWorlds.class), bots, mock(IEvents.class)); - } - - private static ILightkeeperFramework frameworkWithEvents(IEvents events) - { - return new FacetStubFramework(mock(IServerControl.class), mock(IWorlds.class), mock(IBots.class), events); - } - - private static WorldHandle worldHandle() - { - return FrameworkHandleFactory.worldHandle(mock(IFrameworkGatewayView.class), "w"); - } - - private static PlayerHandle playerHandle() - { - return FrameworkHandleFactory.playerHandle(mock(IFrameworkGatewayView.class), UUID.randomUUID(), "bot"); - } - - /** - * Minimal {@link ILightkeeperFramework} whose facet accessors return the supplied facets and whose deprecated - * default methods therefore delegate into them. - */ - private static final class FacetStubFramework implements ILightkeeperFramework - { - private final IServerControl server; - private final IWorlds worlds; - private final IBots bots; - private final IEvents events; - - private FacetStubFramework(IServerControl server, IWorlds worlds, IBots bots, IEvents events) - { - this.server = Objects.requireNonNull(server); - this.worlds = Objects.requireNonNull(worlds); - this.bots = Objects.requireNonNull(bots); - this.events = Objects.requireNonNull(events); - } - - @Override - public IServerControl server() - { - return server; - } - - @Override - public IWorlds worlds() - { - return worlds; - } - - @Override - public IBots bots() - { - return bots; - } - - @Override - public IEvents events() - { - return events; - } - - @Override - public void waitUntil(Condition condition, Duration timeout) - { - throw new UnsupportedOperationException("Not used by the delegate test."); - } - - @Override - public void close() - { - } - } -} diff --git a/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/PlayerHandleTest.java b/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/PlayerHandleTest.java index 507464fb..c6b2cc1f 100644 --- a/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/PlayerHandleTest.java +++ b/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/PlayerHandleTest.java @@ -287,22 +287,6 @@ void leftClickBlock_shouldDelegateToGatewayAndReturnInteractionResult() verify(frameworkGateway).leftClickBlock(PLAYER_UUID, position, "NORTH"); } - @Test - @SuppressWarnings("removal") - void leftClickBlock_shouldDelegateFromDeprecatedVector3DiOverload() - { - // setup - final Vector3Di position = new Vector3Di(1, 64, 2); - when(frameworkGateway.leftClickBlock(PLAYER_UUID, position.toBlockPos(), "NORTH")).thenReturn(true); - - // execute - final InteractionResult result = playerHandle.leftClickBlock(position, BlockFace.NORTH); - - // verify - assertThat(result).isEqualTo(new InteractionResult(true, true)); - verify(frameworkGateway).leftClickBlock(PLAYER_UUID, position.toBlockPos(), "NORTH"); - } - @Test void rightClickBlock_shouldDelegateToGatewayAndReturnInteractionResult() { diff --git a/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/WorldHandleTest.java b/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/WorldHandleTest.java index 31f9d57e..5ad830ef 100644 --- a/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/WorldHandleTest.java +++ b/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/WorldHandleTest.java @@ -72,22 +72,6 @@ void blockTypeAt_shouldDelegateToGateway() verify(frameworkGateway).getBlock("world", position); } - @Test - @SuppressWarnings("removal") - void blockTypeAt_shouldDelegateFromDeprecatedVector3DiOverload() - { - // setup - final Vector3Di position = new Vector3Di(1, 70, 2); - when(frameworkGateway.getBlock("world", position.toBlockPos())).thenReturn("STONE"); - - // execute - final String blockType = worldHandle.blockTypeAt(position); - - // verify - assertThat(blockType).isEqualTo("STONE"); - verify(frameworkGateway).getBlock("world", position.toBlockPos()); - } - @Test void setBlockAt_shouldDelegateToGateway() { @@ -101,20 +85,6 @@ void setBlockAt_shouldDelegateToGateway() verify(frameworkGateway).setBlock("world", position, "STONE"); } - @Test - @SuppressWarnings("removal") - void setBlockAt_shouldDelegateFromDeprecatedVector3DiOverload() - { - // setup - final Vector3Di position = new Vector3Di(1, 70, 2); - - // execute - worldHandle.setBlockAt(position, "STONE"); - - // verify - verify(frameworkGateway).setBlock("world", position.toBlockPos(), "STONE"); - } - @Test void loadChunk_shouldDelegateToGatewayAndReturnSelf() { diff --git a/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/assertions/HandleAssertionsTest.java b/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/assertions/HandleAssertionsTest.java index 446b7223..71181860 100644 --- a/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/assertions/HandleAssertionsTest.java +++ b/lightkeeper-framework-junit/src/test/java/nl/pim16aap2/lightkeeper/framework/assertions/HandleAssertionsTest.java @@ -13,7 +13,6 @@ import nl.pim16aap2.lightkeeper.framework.PlayerHandle; import nl.pim16aap2.lightkeeper.framework.ServerErrorSnapshot; import nl.pim16aap2.lightkeeper.framework.ServerErrorsHandle; -import nl.pim16aap2.lightkeeper.framework.Vector3Di; import nl.pim16aap2.lightkeeper.framework.WorldHandle; import org.bukkit.Material; import org.bukkit.inventory.ItemStack; @@ -331,18 +330,6 @@ void worldBlockAssert_shouldFailWhenMaterialDoesNotMatch() .hasMessageContaining("Expected block at (0,0,0)"); } - @Test - @SuppressWarnings("removal") - void hasBlockAt_shouldDelegateFromDeprecatedVector3DiOverload() - { - // setup - final WorldHandle handle = mock(WorldHandle.class); - when(handle.blockTypeAt(new BlockPos(1, 2, 3))).thenReturn("minecraft:stone"); - - // execute + verify - LightkeeperAssertions.assertThat(handle).hasBlockAt(new Vector3Di(1, 2, 3)).ofType(Material.STONE); - } - @Test void worldBlockAssert_withState_shouldPassWhenStateMatchesSpec() { From 9b96aeba0a3cd4a27bbe716c7aff12088aace0d3 Mon Sep 17 00:00:00 2001 From: Pim van der Loos Date: Thu, 16 Jul 2026 11:28:54 +0200 Subject: [PATCH 2/5] refactor!: remove v1 facade delegates Goal: remove the entire @Deprecated(forRemoval = true) API surface. Plan step 2: strip the flat v1 delegate methods from ILightkeeperFramework now that their pins are gone. Removes the 20 deprecated default methods that merely forwarded into the facet accessors: mainWorld, newWorld x2, newWorldFromTemplate, createPlayer x2, buildPlayer, buildWorld, executeCommand, serverOutput, platform, serverDirectory, pluginDataDirectory, crashServer, stopServer, startServer, restartServer, captureEvents, currentServerTick, and serverErrors. The facet accessors server()/worlds()/bots()/events() are the API now and stay, alongside waitUntil() and close(). DefaultLightkeeperFramework.currentServerTick() is retained untouched: it is the gateway seam mandated by IFrameworkGatewayView (consumed by ServerControlFacade), not the deprecated interface default. Drops the type-javadoc deprecation note and the imports orphaned by the removal. BREAKING CHANGE: the flat v1 methods on ILightkeeperFramework are removed; use the facet accessors (server()/worlds()/bots()/events()) instead. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01P15FjGQzyNmX9T6Qmyq8Dn --- .../framework/ILightkeeperFramework.java | 273 +----------------- 1 file changed, 1 insertion(+), 272 deletions(-) diff --git a/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/ILightkeeperFramework.java b/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/ILightkeeperFramework.java index d12d8f0e..78bced97 100644 --- a/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/ILightkeeperFramework.java +++ b/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/ILightkeeperFramework.java @@ -1,18 +1,12 @@ package nl.pim16aap2.lightkeeper.framework; -import nl.pim16aap2.lightkeeper.protocol.CommandSource; - -import java.nio.file.Path; import java.time.Duration; -import java.util.List; -import java.util.UUID; /** * LightKeeper end-to-end test framework entrypoint. * *

The framework surface is organised into facets, each returned by an accessor: {@link #server()}, - * {@link #worlds()}, {@link #bots()}, and {@link #events()}. Prefer these facet accessors: the flat v1 methods - * on this interface are deprecated for removal and delegate into the facets. + * {@link #worlds()}, {@link #bots()}, and {@link #events()}. */ public interface ILightkeeperFramework extends AutoCloseable { @@ -45,132 +39,6 @@ public interface ILightkeeperFramework extends AutoCloseable */ IEvents events(); - /** - * Gets the main world handle. - * - * @return The main world handle. - * @deprecated Use {@link IWorlds#main()} via {@link #worlds()}. - */ - @Deprecated(forRemoval = true) - default WorldHandle mainWorld() - { - return worlds().main(); - } - - /** - * Creates a new world using framework defaults. - * - * @return The created world handle. - * @deprecated Use {@link IWorlds#create()} via {@link #worlds()}. - */ - @Deprecated(forRemoval = true) - default WorldHandle newWorld() - { - return worlds().create(); - } - - /** - * Creates a new world from a world spec. - * - * @param worldSpec - * The world specification. - * @return The created world handle. - * @deprecated Use {@link IWorlds#create(WorldSpec)} via {@link #worlds()}. - */ - @Deprecated(forRemoval = true) - default WorldHandle newWorld(WorldSpec worldSpec) - { - return worlds().create(worldSpec); - } - - /** - * Loads a world from a pre-provisioned template folder. - * - * @param templateName - * The provisioned world folder's name. - * @return A handle for the loaded world. - * @deprecated Use {@link IWorlds#fromTemplate(String)} via {@link #worlds()}. - */ - @Deprecated(forRemoval = true) - default WorldHandle newWorldFromTemplate(String templateName) - { - return worlds().fromTemplate(templateName); - } - - /** - * Creates a synthetic player in a world at spawn. - * - * @param name - * Player name. - * @param world - * Target world. - * @return Created player handle. - * @deprecated Use {@link IBots#join(String, WorldHandle)} via {@link #bots()}. - */ - @Deprecated(forRemoval = true) - default PlayerHandle createPlayer(String name, WorldHandle world) - { - return bots().join(name, world); - } - - /** - * Creates a synthetic player in a world at spawn. - * - * @param name - * Player name. - * @param uuid - * Player UUID. - * @param world - * Target world. - * @return Created player handle. - * @deprecated Use {@link IBots#join(String, UUID, WorldHandle)} via {@link #bots()}. - */ - @Deprecated(forRemoval = true) - default PlayerHandle createPlayer(String name, UUID uuid, WorldHandle world) - { - return bots().join(name, uuid, world); - } - - /** - * Creates a player builder. - * - * @return A new player builder. - * @deprecated Use {@link IBots#builder()} via {@link #bots()}. - */ - @Deprecated(forRemoval = true) - default IPlayerBuilder buildPlayer() - { - return bots().builder(); - } - - /** - * Creates a world builder. - * - * @return A new world builder. - * @deprecated Use {@link IWorlds#builder()} via {@link #worlds()}. - */ - @Deprecated(forRemoval = true) - default IWorldBuilder buildWorld() - { - return worlds().builder(); - } - - /** - * Executes a command from the requested source. - * - * @param source - * The command source. - * @param command - * The command text. - * @return Command result. - * @deprecated Use {@link IServerControl#executeCommand(CommandSource, String)} via {@link #server()}. - */ - @Deprecated(forRemoval = true) - default CommandResult executeCommand(CommandSource source, String command) - { - return server().executeCommand(source, command); - } - /** * Waits until a condition is true or timeout expires. * @@ -181,145 +49,6 @@ default CommandResult executeCommand(CommandSource source, String command) */ void waitUntil(Condition condition, Duration timeout); - /** - * Gets a snapshot of captured Minecraft server output lines. - * - * @return Captured server output lines ordered oldest-to-newest. - * @deprecated Use {@link IServerControl#output()} via {@link #server()}. - */ - @Deprecated(forRemoval = true) - default List serverOutput() - { - return server().output(); - } - - /** - * Gets the server platform (e.g. PAPER, SPIGOT). - * - * @return Server platform. - * @deprecated Use {@link IServerControl#platform()} via {@link #server()}. - */ - @Deprecated(forRemoval = true) - default Platform platform() - { - return server().platform(); - } - - /** - * Gets the Minecraft server's working directory. - * - * @return The server directory. - * @deprecated Use {@link IServerControl#directory()} via {@link #server()}. - */ - @Deprecated(forRemoval = true) - default Path serverDirectory() - { - return server().directory(); - } - - /** - * Gets the data directory of a plugin inside the server's {@code plugins} directory. - * - * @param pluginName - * The plugin's name, as used for its data directory (usually the {@code name} from its - * {@code plugin.yml}). - * @return The plugin data directory. - * @deprecated Use {@link IServerControl#pluginDataDirectory(String)} via {@link #server()}. - */ - @Deprecated(forRemoval = true) - default Path pluginDataDirectory(String pluginName) - { - return server().pluginDataDirectory(pluginName); - } - - /** - * Crashes the Minecraft server immediately by force-killing the process. - * - * @deprecated Use {@link IServerControl#crash()} via {@link #server()}. - */ - @Deprecated(forRemoval = true) - default void crashServer() - { - server().crash(); - } - - /** - * Stops the Minecraft server gracefully, force-killing it only when it does not exit within the shutdown - * timeout. - * - * @throws IllegalStateException - * If the server is not running. - * @deprecated Use {@link IServerControl#stop()} via {@link #server()}. - */ - @Deprecated(forRemoval = true) - default void stopServer() - { - server().stop(); - } - - /** - * Starts the Minecraft server after a {@link #stopServer()} or {@link #crashServer()} call. - * - * @throws IllegalStateException - * If the server is already running. - * @deprecated Use {@link IServerControl#start()} via {@link #server()}. - */ - @Deprecated(forRemoval = true) - default void startServer() - { - server().start(); - } - - /** - * Restarts the Minecraft server. - * - * @deprecated Use {@link IServerControl#restart()} via {@link #server()}. - */ - @Deprecated(forRemoval = true) - default void restartServer() - { - server().restart(); - } - - /** - * Starts capturing Bukkit events of the specified type. - * - * @param eventClassName - * The full class name of the event to capture (e.g. "org.bukkit.event.player.PlayerMoveEvent"). - * @return A handle to manage the capture session. - * @deprecated Use {@link IEvents#capture(String)} via {@link #events()}. - */ - @Deprecated(forRemoval = true) - default EventCaptureHandle captureEvents(String eventClassName) - { - return events().capture(eventClassName); - } - - /** - * Gets the agent's monotonic tick counter, for correlating against {@link CapturedEventSnapshot#tick()} - * stamps. - * - * @return The monotonic, session-relative server tick. - * @deprecated Use {@link IServerControl#currentTick()} via {@link #server()}. - */ - @Deprecated(forRemoval = true) - default long currentServerTick() - { - return server().currentTick(); - } - - /** - * Gets a handle over the always-on server-error capture. - * - * @return A handle exposing the captured server errors. - * @deprecated Use {@link IServerControl#errors()} via {@link #server()}. - */ - @Deprecated(forRemoval = true) - default ServerErrorsHandle serverErrors() - { - return server().errors(); - } - @Override void close(); } From 92662344bbbd543eb4c4f3eaa39052f6003ab3aa Mon Sep 17 00:00:00 2001 From: Pim van der Loos Date: Thu, 16 Jul 2026 11:30:36 +0200 Subject: [PATCH 3/5] refactor!: remove Vector3Di vocabulary Goal: remove the entire @Deprecated(forRemoval = true) API surface. Plan step 3: drop the legacy Vector3Di block-coordinate type and every overload that only existed to accept it, now that BlockPos is the sole vocabulary. - Delete the Vector3Di record and its toBlockPos() bridge. - PlayerHandle: remove the four Vector3Di leftClickBlock/rightClickBlock overloads (single-arg and with BlockFace). - WorldHandle: remove the blockTypeAt(Vector3Di) and setBlockAt(Vector3Di, String) overloads. - WorldHandleAssert: remove hasBlockAt(Vector3Di) and its now-unused import. The canonical BlockPos overloads are unchanged and already carried the coverage. BREAKING CHANGE: Vector3Di and every overload accepting it are removed; use the BlockPos overloads instead. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01P15FjGQzyNmX9T6Qmyq8Dn --- .../lightkeeper/framework/PlayerHandle.java | 64 ------------------- .../lightkeeper/framework/Vector3Di.java | 31 --------- .../lightkeeper/framework/WorldHandle.java | 31 --------- .../assertions/WorldHandleAssert.java | 15 ----- 4 files changed, 141 deletions(-) delete mode 100644 lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/Vector3Di.java diff --git a/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/PlayerHandle.java b/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/PlayerHandle.java index a51aee79..4dfead89 100644 --- a/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/PlayerHandle.java +++ b/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/PlayerHandle.java @@ -179,21 +179,6 @@ public InteractionResult leftClickBlock(BlockPos position) return leftClickBlock(position, BlockFace.UP); } - /** - * Fires a left-click block interaction at a position in this player's current world. - * - * @param position - * Block coordinates. - * @return The interaction result; a real {@code PlayerInteractEvent} is always fired. - * @deprecated Use {@link #leftClickBlock(BlockPos)} instead. - */ - @Deprecated(forRemoval = true) - public InteractionResult leftClickBlock(Vector3Di position) - { - Objects.requireNonNull(position, "position may not be null."); - return leftClickBlock(position.toBlockPos()); - } - /** * Fires a left-click block interaction at a position in this player's current world. * @@ -213,23 +198,6 @@ public InteractionResult leftClickBlock(BlockPos position, BlockFace blockFace) return new InteractionResult(true, cancelled); } - /** - * Fires a left-click block interaction at a position in this player's current world. - * - * @param position - * Block coordinates. - * @param blockFace - * Clicked block face. - * @return The interaction result; a real {@code PlayerInteractEvent} is always fired. - * @deprecated Use {@link #leftClickBlock(BlockPos, BlockFace)} instead. - */ - @Deprecated(forRemoval = true) - public InteractionResult leftClickBlock(Vector3Di position, BlockFace blockFace) - { - Objects.requireNonNull(position, "position may not be null."); - return leftClickBlock(position.toBlockPos(), blockFace); - } - /** * Fires a right-click block interaction at a position in this player's current world. * @@ -258,21 +226,6 @@ public InteractionResult rightClickBlock(BlockPos position) return rightClickBlock(position, BlockFace.UP); } - /** - * Fires a right-click block interaction at a position in this player's current world. - * - * @param position - * Block coordinates. - * @return The interaction result; a real {@code PlayerInteractEvent} is always fired. - * @deprecated Use {@link #rightClickBlock(BlockPos)} instead. - */ - @Deprecated(forRemoval = true) - public InteractionResult rightClickBlock(Vector3Di position) - { - Objects.requireNonNull(position, "position may not be null."); - return rightClickBlock(position.toBlockPos()); - } - /** * Fires a right-click block interaction at a position in this player's current world. * @@ -292,23 +245,6 @@ public InteractionResult rightClickBlock(BlockPos position, BlockFace blockFace) return new InteractionResult(true, cancelled); } - /** - * Fires a right-click block interaction at a position in this player's current world. - * - * @param position - * Block coordinates. - * @param blockFace - * Clicked block face. - * @return The interaction result; a real {@code PlayerInteractEvent} is always fired. - * @deprecated Use {@link #rightClickBlock(BlockPos, BlockFace)} instead. - */ - @Deprecated(forRemoval = true) - public InteractionResult rightClickBlock(Vector3Di position, BlockFace blockFace) - { - Objects.requireNonNull(position, "position may not be null."); - return rightClickBlock(position.toBlockPos(), blockFace); - } - /** * Makes this player say a chat message, firing the real chat event (synchronously, as with any * plugin-triggered chat). diff --git a/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/Vector3Di.java b/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/Vector3Di.java deleted file mode 100644 index 84b1eb47..00000000 --- a/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/Vector3Di.java +++ /dev/null @@ -1,31 +0,0 @@ -package nl.pim16aap2.lightkeeper.framework; - -/** - * Integer 3D vector used for world block coordinates. - * - * @param x - * X coordinate. - * @param y - * Y coordinate. - * @param z - * Z coordinate. - * @deprecated Use {@link BlockPos} instead; this type only remains so existing tests keep compiling for one - * release and will be removed together with the rest of the v1 vocabulary. - */ -@Deprecated(forRemoval = true) -public record Vector3Di( - int x, - int y, - int z -) -{ - /** - * Converts this vector to the canonical {@link BlockPos} vocabulary. - * - * @return The equivalent block position. - */ - public BlockPos toBlockPos() - { - return new BlockPos(x, y, z); - } -} diff --git a/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/WorldHandle.java b/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/WorldHandle.java index 97331c49..85e091eb 100644 --- a/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/WorldHandle.java +++ b/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/WorldHandle.java @@ -85,21 +85,6 @@ public String blockTypeAt(BlockPos position) return frameworkGateway.getBlock(name, position); } - /** - * Retrieves the block type at a position. - * - * @param position - * Block coordinates. - * @return The block material name. - * @deprecated Use {@link #blockTypeAt(BlockPos)} instead. - */ - @Deprecated(forRemoval = true) - public String blockTypeAt(Vector3Di position) - { - Objects.requireNonNull(position, "position may not be null."); - return blockTypeAt(position.toBlockPos()); - } - /** * Sets the block type at a position. * @@ -114,22 +99,6 @@ public void setBlockAt(BlockPos position, String material) frameworkGateway.setBlock(name, position, material); } - /** - * Sets the block type at a position. - * - * @param position - * Block coordinates. - * @param material - * Material name. - * @deprecated Use {@link #setBlockAt(BlockPos, String)} instead. - */ - @Deprecated(forRemoval = true) - public void setBlockAt(Vector3Di position, String material) - { - Objects.requireNonNull(position, "position may not be null."); - setBlockAt(position.toBlockPos(), material); - } - /** * Loads a chunk, generating it if it does not exist yet. * diff --git a/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/assertions/WorldHandleAssert.java b/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/assertions/WorldHandleAssert.java index a1b12e9c..e9560563 100644 --- a/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/assertions/WorldHandleAssert.java +++ b/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/assertions/WorldHandleAssert.java @@ -1,7 +1,6 @@ package nl.pim16aap2.lightkeeper.framework.assertions; import nl.pim16aap2.lightkeeper.framework.BlockPos; -import nl.pim16aap2.lightkeeper.framework.Vector3Di; import nl.pim16aap2.lightkeeper.framework.WorldHandle; import org.assertj.core.api.AbstractAssert; import org.assertj.core.api.Assertions; @@ -51,20 +50,6 @@ public WorldBlockAssert hasBlockAt(BlockPos position) ); } - /** - * Starts an assertion chain for a block at the requested position. - * - * @param position - * Block position. - * @return Block assertion entrypoint. - * @deprecated Use {@link #hasBlockAt(BlockPos)} instead. - */ - @Deprecated(forRemoval = true) - public WorldBlockAssert hasBlockAt(Vector3Di position) - { - return hasBlockAt(position.toBlockPos()); - } - /** * Asserts that the world has the expected name. * From cd54d93915fd82e91723f0ccb43efaea9f0e106d Mon Sep 17 00:00:00 2001 From: Pim van der Loos Date: Thu, 16 Jul 2026 11:31:15 +0200 Subject: [PATCH 4/5] refactor!: remove deprecated CapturedEventSnapshot.data() view Goal: remove the entire @Deprecated(forRemoval = true) API surface. Plan step 4: drop the deprecated raw-string data() view now that its pin is gone. - Remove data(): the string-rendered view of the captured values. The typed values() map and value(String) lookup are the API and stay. - Repoint the tick javadoc from the removed ILightkeeperFramework#currentServerTick() to the canonical IServerControl#currentTick(). BREAKING CHANGE: CapturedEventSnapshot.data() is removed; use values() (typed) or value(String) instead. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01P15FjGQzyNmX9T6Qmyq8Dn --- .../framework/CapturedEventSnapshot.java | 17 +---------------- 1 file changed, 1 insertion(+), 16 deletions(-) diff --git a/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/CapturedEventSnapshot.java b/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/CapturedEventSnapshot.java index 3a70a674..9a7bc425 100644 --- a/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/CapturedEventSnapshot.java +++ b/lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/CapturedEventSnapshot.java @@ -19,7 +19,7 @@ * The full class name of the event. * @param tick * The server tick the event fired on, for correlating events with each other and with - * {@code ILightkeeperFramework#currentServerTick()}. + * {@code IServerControl#currentTick()}. * @param values * The captured event values keyed by accessor name (getter/is-method or record component). */ @@ -50,19 +50,4 @@ public record CapturedEventSnapshot( { return values.get(accessorName); } - - /** - * Gets the captured values rendered as display text. - * - * @return Accessor name to rendered value, in capture order. - * @deprecated Use {@link #values()} (typed) or {@link #value(String)} instead; this string view only - * remains so existing tests keep compiling for one release. - */ - @Deprecated(forRemoval = true) - public Map data() - { - final Map rendered = new LinkedHashMap<>(); - values.forEach((accessorName, value) -> rendered.put(accessorName, value.toDisplayString())); - return Collections.unmodifiableMap(rendered); - } } From 72820103e1951b2c41cff6973b9c82200fb4678a Mon Sep 17 00:00:00 2001 From: Pim van der Loos Date: Thu, 16 Jul 2026 11:31:31 +0200 Subject: [PATCH 5/5] docs: drop deprecated-API note from README Goal: remove the entire @Deprecated(forRemoval = true) API surface. Plan step 5: the README no longer needs to steer readers away from the removed flat method names, so replace the deprecation note with a plain facet-orientation pointer. Co-Authored-By: Claude Fable 5 Claude-Session: https://claude.ai/code/session_01P15FjGQzyNmX9T6Qmyq8Dn --- README.md | 3 +-- 1 file changed, 1 insertion(+), 2 deletions(-) diff --git a/README.md b/README.md index 684c3e7e..7909896c 100644 --- a/README.md +++ b/README.md @@ -221,8 +221,7 @@ class MyPluginIT ``` > The framework surface is organised into facets — `framework.server()`, `.worlds()`, `.bots()`, and -> `.events()`. The older flat method names (`mainWorld()`, `buildPlayer()`, `stopServer()`, …) are deprecated -> for removal; use the facet accessors instead. +> `.events()`. Use these facet accessors to reach the server, worlds, bots, and event-capture APIs. ## Core Features