refactor: split the framework API into server/worlds/bots/events facets (D2/D3)

README.md

@@ -196,9 +196,10 @@ class MyPluginIT
     @Test
     void playerBots_shouldInteractWithTheServer(ILightkeeperFramework framework)
     {
+        // The API is organised into facets: framework.server(), .worlds(), .bots(), .events().
         // setup
-        final WorldHandle world = framework.mainWorld();
-        final PlayerHandle player = framework.buildPlayer()
+        final WorldHandle world = framework.worlds().main();
+        final PlayerHandle player = framework.bots().builder()
             .withName("lk_tester")
             .atSpawn(world)
             .withPermissions("minecraft.command.time")
@@ -218,6 +219,10 @@ 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.
+
 ## Core Features
 
 - Real server E2E tests (not mocks)
@@ -233,7 +238,7 @@ class MyPluginIT
 - Menu interaction and assertions; menu actions auto-wait for an open menu, and `clickItem("name")`
   clicks by item display name
 - World templates: provision world folders via `<worlds>` and load them with
-  `newWorldFromTemplate("name")` — typos fail loudly instead of silently creating a fresh world
+  `worlds().fromTemplate("name")` — typos fail loudly instead of silently creating a fresh world
 - Received-message assertions with AssertJ string chaining
 - Explicit retrying assertions: `eventually(timeout, () -> assertThat(...))` re-runs a live probe until it
   passes, and reports the attempt count, elapsed time, and last failure on timeout
@@ -253,10 +258,10 @@ class MyPluginIT
   burst so every snapshot shares one server tick
 - Diagnostics-on-failure: failed tests automatically get a bundle (test outcome, captured server errors,
   server console output) under `target/lightkeeper-reports/`
-- Graceful server lifecycle control from tests (`stopServer()`, `startServer()`, `restartServer()`), plus
-  `crashServer()` for hard-kill scenarios
-- Server directory access (`serverDirectory()`, `pluginDataDirectory(name)`) for seeding files while the
-  server is stopped
+- Graceful server lifecycle control from tests (`server().stop()`, `server().start()`, `server().restart()`),
+  plus `server().crash()` for hard-kill scenarios
+- Server directory access (`server().directory()`, `server().pluginDataDirectory(name)`) for seeding files
+  while the server is stopped
 
 ## World and Plugin Provisioning
 
@@ -345,9 +350,9 @@ class VaultIT
     void vaultInfo_shouldReportVaultVersion(ILightkeeperFramework framework)
     {
         // setup
-        final PlayerHandle player = framework.buildPlayer()
+        final PlayerHandle player = framework.bots().builder()
             .withName("vault_tester")
-            .atSpawn(framework.mainWorld())
+            .atSpawn(framework.worlds().main())
             .withPermissions("vault.admin")
             .build();
 

lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/IBots.java

@@ -0,0 +1,42 @@
+package nl.pim16aap2.lightkeeper.framework;
+
+import java.util.UUID;
+
+/**
+ * Bots facet of the framework: join synthetic players into a world, or configure one through a builder.
+ *
+ * <p>Obtained from {@link ILightkeeperFramework#bots()}.
+ */
+public interface IBots
+{
+    /**
+     * Joins a synthetic player into a world at spawn.
+     *
+     * @param name
+     *     Player name.
+     * @param world
+     *     Target world.
+     * @return The joined player handle.
+     */
+    PlayerHandle join(String name, WorldHandle world);
+
+    /**
+     * Joins a synthetic player into a world at spawn.
+     *
+     * @param name
+     *     Player name.
+     * @param uuid
+     *     Player UUID.
+     * @param world
+     *     Target world.
+     * @return The joined player handle.
+     */
+    PlayerHandle join(String name, UUID uuid, WorldHandle world);
+
+    /**
+     * Creates a player builder.
+     *
+     * @return A new player builder.
+     */
+    IPlayerBuilder builder();
+}

lightkeeper-framework-junit/src/main/java/nl/pim16aap2/lightkeeper/framework/IEvents.java

@@ -0,0 +1,18 @@
+package nl.pim16aap2.lightkeeper.framework;
+
+/**
+ * Events facet of the framework: capture Bukkit events for later inspection.
+ *
+ * <p>Obtained from {@link ILightkeeperFramework#events()}. Thin today; it grows as the event-driven APIs expand.
+ */
+public interface IEvents
+{
+    /**
+     * 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.
+     */
+    EventCaptureHandle capture(String eventClassName);
+}