Allows not generating initial home and requiring users to acquire one when they want.

Human-Tests.md

@@ -21,6 +21,7 @@ Use this checklist for behavior that depends on a real Paper world, player inter
 ### Join and plot allocation
 
 - Join as a new player. Confirm one home is allocated and the welcome message reports its actual bounds. Check the corresponding `h_1_<UUID>` region has the player as owner and its bounds match the configured plot size.
+- Set `plot.initial: 0` on a disposable server, restart, and join as a fresh player. Confirm no home is created until the player runs `/metropolis-home-acquire`; then verify the command creates the initial home and makes it active.
 - Join with a second new player. Confirm the new home is distinct, does not overlap the first home or spawn, and the City region grows to include it.
 - Join again as an existing player. Confirm the same home is selected and no duplicate region or plot is created.
 - Reserve an area before allocating another home. Confirm future allocations skip it. Repeat with reservations near the city edge and near existing roads to look for overlaps or gaps.

README.md

@@ -4,7 +4,7 @@ Metropolis expands a protected Minecraft city as players join. Each player can r
 
 ## Features
 
-- Assigns a protected home plot when a player joins and supports acquiring additional homes up to the configured player limit.
+- Assigns a protected home plot when a player joins by default and supports acquiring additional homes up to the configured player limit; set `plot.initial` to `0` to require `/metropolis-home-acquire` for the first home.
 - Supports per-player plot sizes and home limits through `userOverrides` or configurable permission tiers; acquired homes can be selected as the active home.
 - Expands the City region as plots are occupied, with optional spawn generation, world-spawn placement, floors, support blocks, signs, and perimeter walls.
 - Generates roads around plots with configurable width, level, material, clearance, and supports.
@@ -57,7 +57,7 @@ Copy `.env.example` to `.env` and configure the Paper version/build and server p
 
 ## Configuration
 
-`plugins/Metropolis/config.yml` controls plot dimensions and limits, floor and support generation, signs, road width/level/material/clearance, spawn behavior, wall generation, world name, and per-player overrides. `plot.multiplier` sets the default plot-size multiplier; `plot.maxPerPlayer` sets the default home limit.
+`plugins/Metropolis/config.yml` controls plot dimensions and limits, floor and support generation, signs, road width/level/material/clearance, spawn behavior, wall generation, world name, and per-player overrides. `plot.multiplier` sets the default plot-size multiplier; `plot.maxPerPlayer` sets the default home limit; `plot.initial` sets how many homes are auto-generated on join, and `0` requires `/metropolis-home-acquire` for the player's first home.
 
 Use `permissionOverrides` to assign plot size and home limits through any permission manager. Each permission node maps to a `priority`, `plotMultiplier`, and `maxPlots`; the matching node with the highest priority wins, and the last matching entry in YAML order wins ties. An explicit username entry in `userOverrides` takes precedence over permission rules. If no override matches, the global `plot.*` defaults apply. Permission rules are checked for online players; offline home generation uses username overrides or global defaults. For example:
 

TODO.md

@@ -33,7 +33,7 @@
 | GIT-007 | Planning | Allow buying and selling of homes via an ecnoomy plugin. |
 | GIT-006 |   Ready  | Add levels support. |
 | GIT-005 | Planning | Add the possibility to create multiple plot homes in shapes. |
-| GIT-004 | Planning | Add a command to request home allocation. |
+| GIT-004 | Done     | Add a command to request home allocation. |
 | GIT-003 |   Ready  | Add support for multiple homes. |
 | GIT-002 | Done     | Add a command to teleport to a reservation you are part of. |
 | GIT-001 | Done     | Add a command to move to a different home. |
@@ -68,14 +68,11 @@ On join, automatically allocate one home only when the player has no existing ho
 The alternative login allocation policies are tracked separately in MET-023 and MET-024; they are not part of the default policy in this task.
 
 # GIT-004 - Add a command to request home allocation.
-**Status:** Ready
+**Status:** Done
 **Depends On:** [GIT-003](#git-003---add-support-for-multiple-homes)
 **Description:**
 
-Add a command that users can type to get their first or subsequent homes.
+`/metropolis-home-acquire` gives players their next available home, including the first home when `plot.initial` is `0`. The command allocates the lowest unused positive home number, makes it active, and refuses requests once the player has reached their effective limit. The default policy remains automatic first-home generation, but servers can disable it by setting `plot.initial: 0` and requiring the command for new players.
-Add a config option to not generate any homes automatically, but to require this command to generate a user's first home.
-
-This could be used so that homes won't be generated until a user has read the server rules which would include telling them to type the command towards the end.
 
 # GIT-005 - Add the possibility to create multiple plot homes in shapes.
 **Status:** Planning

src/main/java/com/majinnaibu/bukkitplugins/metropolis/MetropolisPlugin.java

@@ -119,6 +119,7 @@ public class MetropolisPlugin extends JavaPlugin {
   private int wallHeight = 128;
   int _maxPlots = 1;
   int _plotMultiplier = 1;
+  private int initialHomeCount = 1;
 
   private Cuboid _spawnCuboid = null;
   private Cuboid _cityCuboid = null;
@@ -199,6 +200,7 @@ public class MetropolisPlugin extends JavaPlugin {
     worldName = safeGetStringFromConfig(config, "worldname");
     _plotMultiplier = safeGetIntFromConfig(config, "plot.multiplier");
     _maxPlots = safeGetIntFromConfig(config, "plot.maxPerPlayer");
+    initialHomeCount = normalizeInitialHomeCount(safeGetIntFromConfig(config, "plot.initial"));
 
     buildUserOverrides();
     _permissionOverrides =
@@ -556,6 +558,9 @@ public class MetropolisPlugin extends JavaPlugin {
         setHome(playerId, existingHome.getNumber());
         return existingHome;
       }
+      if (!shouldAutoGenerateInitialHome()) {
+        return null;
+      }
       if (DEBUG) {
         getLogger().info(String.format("Creating home for player %s", player.getName()));
       }
@@ -568,6 +573,26 @@ public class MetropolisPlugin extends JavaPlugin {
     return home;
   }
 
+  public static int normalizeInitialHomeCount(int count) {
+    return Math.max(0, count);
+  }
+
+  public static boolean shouldAutoGenerateInitialHome(int count) {
+    return count > 0;
+  }
+
+  public int getInitialHomeCount() {
+    return initialHomeCount;
+  }
+
+  public void setInitialHomeCount(int count) {
+    initialHomeCount = normalizeInitialHomeCount(count);
+  }
+
+  public boolean shouldAutoGenerateInitialHome() {
+    return shouldAutoGenerateInitialHome(initialHomeCount);
+  }
+
   private void generateFloor(Cuboid plotCuboid) {
     int x = 0;
     int y = roadLevel;

src/test/java/com/majinnaibu/bukkitplugins/metropolis/commands/MetropolisHomeAcquireTest.java

@@ -17,6 +17,7 @@ along with Metropolis. If not, see <https://www.gnu.org/licenses/agpl-3.0.txt>.
 
 package com.majinnaibu.bukkitplugins.metropolis.commands;
 
+import static org.junit.jupiter.api.Assertions.assertEquals;
 import static org.junit.jupiter.api.Assertions.assertFalse;
 import static org.junit.jupiter.api.Assertions.assertTrue;
 import static org.mockito.Mockito.mock;
@@ -64,4 +65,14 @@ class MetropolisHomeAcquireTest {
 
     verify(plugin, never()).acquireHome(player);
   }
+
+  @Test
+  void supportsDisablingAutomaticInitialHomeAllocation() {
+    assertEquals(1, MetropolisPlugin.normalizeInitialHomeCount(1));
+    assertTrue(MetropolisPlugin.shouldAutoGenerateInitialHome(1));
+
+    int zero = MetropolisPlugin.normalizeInitialHomeCount(0);
+    assertEquals(0, zero);
+    assertFalse(MetropolisPlugin.shouldAutoGenerateInitialHome(zero));
+  }
 }