Reorganizes docs.

docs/TODO.md

@@ -0,0 +1,135 @@
+# Modernize Metropolis Plugin: Implementation Tasks
+
+|   ID    |  Status  | Title |
+|:-------:|:--------:|:------|
+| MET-001 |   Done   | Initialize Gradle in the project root, add the Gradle wrapper, and create the project build file. |
+| MET-002 |   Done   | Set Gradle project metadata and configure a Java toolchain compatible with the target modern Paper version. |
+| MET-003 |   Done   | Configure repositories and compatible PaperMC, WorldEdit, WorldGuard, and other required or optional dependencies; add build plugins such as Shadow only if needed. |
+| MET-004 |   Done   | Move or verify plugin.yml under src/main/resources, configure Gradle resource processing, and update its Paper api-version, dependencies, commands, permissions, and required fields. |
+| MET-005 |   Done   | Add JUnit 5 test infrastructure and keep the default Gradle `test` task server-free. Use an in-memory Paper harness such as MockBukkit for Bukkit/Paper behavior and mocks or test doubles for WorldEdit, WorldGuard, and narrow API boundaries where appropriate. |
+| MET-006 |   Done   | Build the initial Gradle project and run its tests; resolve build setup issues before removing the existing Maven build. |
+| MET-007 |   Done   | Update .gitignore for Gradle and remove obsolete Maven and Eclipse project files after the Gradle build succeeds. |
+| MET-008 |   Done   | Analyze Java sources for deprecated or removed Bukkit/Paper APIs and legacy patterns, including logging, event registration, configuration, player lookup, and player-keyed storage. |
+| MET-009 |   Done   | Review custom scripts and resources for required updates to the Gradle build and modern Paper server workflow. |
+| MET-010 |   Done   | Refactor plugin logging to use JavaPlugin.getLogger(). |
+| MET-011 |   Done   | Refactor event listeners and registration to use Listener, @EventHandler, and the modern plugin manager API. |
+| MET-012 |   Done   | Replace deprecated configuration APIs with the modern Bukkit/Paper configuration API, including load, save, and reload behavior. |
+| MET-013 |   Done   | Replace Player-keyed storage with UUID-based storage wherever player identity is persisted or tracked. |
+| MET-014 |   Done   | Review player lookup logic and use exact or otherwise explicit name-matching behavior where appropriate. |
+| MET-015 |   Done   | Refactor remaining code that uses deprecated or removed Bukkit, Spigot, or Paper APIs so it is compatible with the target Paper API. |
+| MET-016 |   Done   | Add fast unit tests for plot and home allocation, reservation validation, player lookup and UUID-based ownership, configuration persistence, command validation, and event behavior. Keep domain rules independent of a running Minecraft server and mock external plugin boundaries as needed. |
+| MET-017 |   Done   | Add a separate Gradle `integrationTest` source set/task for tests requiring an actual Paper server and compatible WorldGuard/WorldEdit plugins. Verify plugin loading, command registration and dispatch, region-backed reservations and home allocation, and persistence across a server restart. Run it only when explicitly requested; keep it out of the normal `test` and `build` tasks. |
+| MET-018 |   Done   | Build the plugin with Gradle and use the provided server scripts to smoke-test it on modern Paper with its required plugins installed. |
+| MET-019 |   Done   | Address bugs and incompatibilities found by unit tests, integration tests, or modern Paper server testing. |
+| MET-020 |   Done   | Adopt the git-sensitive semantic versioning Gradle plugin used by MobScores and ScoreKeeper, using the existing 0.5-SNAPSHOT version as the migration baseline; verify version/tag behavior and enable the Gradle configuration cache when compatible. |
+| MET-021 |   Done   | Update README.md, CONTRIBUTING.md, other documentation, and project scripts with the Gradle build, test, versioning, and modern Paper server workflow. |
+| MET-022 | Planning | (Optional) Add new features, quality-of-life improvements, or CI configuration after the modernization and documentation tasks are complete. |
+| MET-023 | Planning | Add an optional home-allocation policy that grants all remaining homes up to a player's limit when they join. |
+| MET-024 | Planning | Add an optional home-allocation policy that grants at most one additional home per login until the player's limit is reached. |
+| MET-025 | Planning | Add a configuration option to choose the plot-allocation traversal algorithm: concentric rectangles/cuboids or concentric rings that prefer a free location near the center. |
+| MET-026 | Planning | Research a world-conversion option for existing Metropolis worlds, including how to safely adapt existing regions and generated roads/plots. |
+| GIT-009 | Planning | i have three reserve plots and one just got overwritten when a new player joined. |
+| GIT-008 |   Ready  | Implement multiple plot sizes by granting multiple plots around each other. 
+| GIT-007 | Planning | Allow buying and selling of homes via an ecnoomy plugin. |
+| GIT-006 |   Done   | Add levels support. |
+| GIT-005 | Planning | Add the possibility to create multiple plot homes in shapes. |
+| 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. |
+
+# GIT-001 - Add a command to move to a different home.
+**Status:** Done
+**Depends On:** [GIT-003](#git-003---add-support-for-multiple-homes)
+**Description:**
+
+`/metropolis-home-move <homeNumber> [playerName]` selects one of a player's existing homes as active. Without a player name, the command acts on the player who ran it; console and authorized administrators can specify an online or cached offline player. Reject non-positive or malformed numbers, unknown players, nonexistent homes, and extra arguments with clear feedback. Persist the selection by player UUID and confirm the change to the sender and, when online, the target player.
+
+# GIT-002 - Add a command to teleport to a reservation you are part of.
+**Status:** Done
+**Depends On:** [GIT-003](#git-003---add-support-for-multiple-homes)
+**Description:**
+
+`/metropolis-plot-go [playerName]` teleports the sender, or the specified online player, to a Metropolis WorldGuard cuboid reservation where that player is an owner or member. If the player belongs to more than one reservation, report the available region names and require an explicit choice with `/metropolis-plot-go <reservationName> [playerName]`. The explicit-name form only permits destinations where the target is a member/owner, unless the sender has `metropolis.plot.go`. Remove the command-level permission gate so reservation members can use self-service teleportation; enforce admin-only target and membership bypass checks in the command. Report unknown players, missing membership, ambiguous reservations, and reservations without a safe teleport location. Do not report success unless teleportation succeeds.
+
+### Comments
+
+Or better yet just use uhome or create your own, integrated that records the home location at the height set in the configuration file, but on the road next to the plot. Using existing plugins to insert into SQL say uhome, would allow privatization and minimal work on your end.
+
+# GIT-003 - Add support for multiple homes
+
+**Status:** Done
+**Description:**
+
+Add a top-level `permissionOverrides` map keyed by permission node. Each rule defines `priority`, `plotMultiplier`, and `maxPlots`; any permission manager can grant the boolean nodes to groups or individual players. For online players, the matching rule with the highest priority wins, with the last matching entry in YAML order breaking ties. An explicit `userOverrides` entry takes precedence over permission rules. Without either override, use `plot.multiplier` and `plot.maxPerPlayer`. Offline-player generation uses username overrides or global defaults because permissions are only queried for online players.
+
+On join, automatically allocate one home only when the player has no existing home, and restore a valid existing home as active if the saved selection is missing. Additional homes must be explicitly requested with `/metropolis-home-acquire`, up to the player's effective limit. Acquisition allocates the first unused positive home number and makes the new home active.
+
+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:** Done
+**Depends On:** [GIT-003](#git-003---add-support-for-multiple-homes)
+**Description:**
+
+`/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.
+
+# GIT-005 - Add the possibility to create multiple plot homes in shapes.
+**Status:** Planning
+**Depends On:** [GIT-006](#git-006---add-levels-support), [MET-025](#met-025---add-a-configuration-option-to-choose-the-plot-allocation-traversal-algorithm-concentric-rectanglescuboids-or-concentric-rings-that-prefer-a-free-location-near-the-center)
+**Description:**
+
+Add the possibility to create multiple plot homes in contiguous shapes.
+
+* Line all plots in a line x, y, or z.
+* Rectangle with width (x), height(y), and length (z).
+* Sphere closest to a point.
+
+# GIT-006 - Add levels support.
+**Status:** Done
+**Description:**
+
+Add multiple vertical levels to the city. Use the existing `road.level` as the base Y: the bottom of a ground-level plot is at that Y, and `plot.sizeY` defines the full plot height. For example, a five-block-high plot includes its floor at road level, three usable blocks, and a roof block; all five blocks belong to the plot region. Use the same plot-dimension-plus-road-spacing grid pitch vertically as horizontally; when road width is zero, adjacent plot volumes may touch. Do not allocate a plot if its full extent would exceed the world's buildable area. If the search cannot find any valid plot, log an allocation error and do not create the plot or region. The current config example is not intended for a multilevel world; request an updated `config.yml` before implementation. Existing `plot.offsetX`, `plot.offsetY`, and `plot.offsetZ` nudge the grid; `plot.multiplier`, `userOverrides[username].plotMultiplier`, and future `permissionOverrides[permission_name].plotMultiplier` affect plot size.
+
+Add a maximum-level config value. If unset, default to 1; administrators can increase it to enable more levels. Allocate plots in X, Z, Y axis order: scan X from negative to positive, then increment Z, and only after scanning the X/Z area increment Y to the next level (Y outermost, Z middle, X innermost). For equal-distance candidates, use the same negative-to-positive X ordering. The selectable X/Z traversal shapes are tracked separately in MET-025.
+
+Streets run along X and avenues run along Z. Streets remain level; avenues connect levels with stairs placed beside plots at a configurable cadence. Add `stairs.*`, `road.streets.*`, and `road.avenues.*` configuration. The street and avenue sections should each contain the current `road.*` settings plus `generateStairs`. Configure stair material, width, and `everyNBlocks`; this cadence is measured in plot-sized avenue blocks, so 3 means stairs beside every third plot along an avenue. Allow stairs to be configured independently for each direction, including different widths. Validate each enabled direction against its corresponding road width; if its stairs are not thinner than that road, log an error but continue plugin startup.
+
+Keep spawn on its current level. Add independent X, Y, and Z spawn-size multipliers, each expressed as a multiple of the corresponding plot dimension and road spacing so roads line up with differently sized plots. The Y multiplier controls spawn's vertical height upward from `road.level`.
+
+When allocating plots in an existing world, treat saved WorldGuard regions as occupied: never overwrite a region or create a new region that overlaps an existing one, even if avoiding overlaps leaves irregular gaps between plots and roads. Document this behavior so users know to expect it. Research a possible world-conversion option separately under MET-026; conversion requires further investigation.
+
+This intentionally breaks the existing config schema: do not add a legacy `road.*` fallback or automatic migration. Document the config changes in release notes and make the breaking change in the 0.6.x release line.
+
+# GIT-007 - Allow buying and selling of homes via an ecnoomy plugin.
+**Status:** Blocked
+**Blockers:** Figure out how to integrate with economy plugins.
+**Description:**
+
+Allow buying and selling of homes via an ecnoomy plugin. Include decent real estate support including wtb and wts listings as well as an auction facility.
+
+This should also support not giving free plots to users with none. This way one would have to go out and mine to earn money which could be spent to purchase a plot.
+
+# GIT-008 - Implement multiple plot sizes by granting multiple plots around each other.
+**Status:** Ready
+**Description:**
+
+a= user a
+x= empty plot
+s= spawn
+
+user a get's a small plot which is defined as 1 plot
+a x x
+x s x
+x x x
+
+user b gets a large plot which is defined as 4 plots
+x x b b x
+x a b b x
+x x s x x
+x x x x x
+x x x x x
+
+# MET-025 - Add a configuration option to choose the plot-allocation traversal algorithm: concentric rectangles/cuboids or concentric rings that prefer a free location near the center.
+**Status:** Planning
+**Depends On:** [MET-023], [MET-024]

docs/human-tests.md

@@ -0,0 +1,111 @@
+# Metropolis Human Testing
+
+Use this checklist for behavior that depends on a real Paper world, player interactions, or the installed WorldGuard and WorldEdit plugins. Automated tests cover some isolated logic, but they do not establish that the complete in-game workflows behave correctly.
+
+## Test Environment
+
+- Use a disposable Paper 26.2 or 26.3 server with Java 25+, WorldGuard 7.0.19, WorldEdit 7.4.5, and Metropolis installed.
+- Back up the server before testing. Home generation, reservations, and configuration can change world blocks and WorldGuard regions.
+- Use at least two non-operator player accounts for ownership and protection checks. Operators can bypass protection and hide permission problems.
+- Keep a server console open and check it for errors after startup, commands, joins, and restarts.
+- Record the Metropolis config, world name, test player UUIDs, command output, and any unexpected region bounds or block changes.
+
+## Human Checklist
+
+### Startup and world setup
+
+- Start with the required plugins enabled. Confirm Metropolis enables without errors and its commands are registered. Also confirm startup fails clearly if a required dependency or configured world is missing, then restore the valid setup.
+- On a fresh test world, inspect the `City` and `Spawn` WorldGuard regions. Check their bounds, flags, and priority; verify the configured spawn generation and world-spawn location.
+- Restart once with existing regions. Confirm Metropolis recognizes them instead of duplicating or resetting them, and that existing city bounds and player homes remain intact.
+
+### 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.
+- Start from a disposable world configured with `plot.sizeY` and `plot.maxLevels` from the multi-level example. Confirm the level count is honored, the city does not exceed the world's build height, and upper plots are only allocated above footprints fully supported at every lower level. With a 1×1 spawn and a 2×2 home size, confirm a new home is allocated at base level rather than above the partially supported spawn.
+- Generate homes at base and elevated levels, then verify each full home cuboid is inside the WorldGuard `City` region. Add a home/reservation extending the city bounds and confirm City expands without shrinking its existing bounds or flags.
+- Set positive and negative `plot.offsetX`, `plot.offsetY`, and `plot.offsetZ` values on a disposable world. Verify plot regions, road bands, stair flights, and Spawn share the shifted grid origin; allocate multiple plots across negative coordinates and confirm logical-cell spacing stays consistent. Confirm changing offsets does not move existing saved regions; Metropolis-managed homes and reservations should retain their bounds and remain recognized. Treat automatic conversion of other saved regions as unverified.
+- Set `spawn.sizeX`, `spawn.sizeY`, and `spawn.sizeZ` to distinct positive values on a fresh disposable world. Confirm the Spawn region spans the corresponding plot-plus-road logical cells horizontally and the configured plot-height multiple vertically. Check blocks outside those bounds remain unchanged; configure a height exceeding the world's build limit and confirm startup rejects it clearly.
+- 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.
+- Create an unrelated saved WorldGuard region in the next candidate area, then allocate a home and confirm it is skipped. Repeat with a non-cuboid region and verify the full bounding cuboid is avoided; confirm `City` itself does not prevent allocation.
+- Set a small WorldBorder in a disposable world, occupy or reserve the remaining valid grid cells, and request another home. Confirm search grows beyond 256 rings but never places a plot/road footprint outside the border; when no supported cell remains, check the error log and confirm no region is created.
+- Test a user override that grants a different plot multiplier or home limit. Confirm the generated bounds and allowed number of homes match the override, and that the configured global defaults still apply to other players.
+
+### Generated blocks and geometry
+
+- Inspect a newly allocated home and adjoining roads. Check road width, level, material, clearance, plot floor, support blocks, and optional sign against the active config.
+- Generate one plot in a disposable world and confirm each adjoining road is fully paved to the configured width. Generate a plot directly beside it: confirm already-correct shared road blocks are untouched, any missing half-width legacy section is filled, and stair treads/openings remain intact.
+- Configure streets and avenues with different widths, materials, clearances, and support settings. Verify streets along X use only the street options and avenues along Z use only avenue options.
+- Enable stairs for both sections with different widths/cadences, each narrower than its road. Generate a plot on a level below `plot.maxLevels`; verify street stairs ascend along positive X at north/south borders and avenue stairs ascend along positive Z at east/west borders. Confirm lower roads remain unchanged, the first treads start one block above and forward from the road-level landing, connected treads use inverted backing, and top treads reach the upper road Y. Check each upper road leaves exactly three blocks open before its top tread only across that stair width. For a 2-plot-wide/long home with cadence 1, confirm two centered runs along each eligible edge. Repeat with higher levels to confirm existing flights remain open.
+- Test generation over varied terrain, including water, caves, uneven ground, and existing structures. Confirm generated floors and roads do not leave unsafe gaps or erase blocks outside their intended area.
+- Enable and disable optional floor, support, sign, spawn, world-spawn, and perimeter-wall settings one at a time on a disposable world. Confirm each setting changes only its intended behavior.
+- Allocate plots in several directions and near the world origin. Check road joins, plot dimensions, City region expansion, and boundary coordinates for symmetry and off-by-one errors.
+
+### Reservations and protection
+
+- Reserve one plot with explicit coordinates. Then make a WorldEdit selection and reserve a second plot using `/metropolis-plot-reserve <name>`.
+- Try invalid coordinates, a duplicate region name, and bounds that intersect a home or another reservation. Confirm the command reports a useful failure and does not silently overwrite an existing region.
+- Check `/metropolis-home-list` and `/metropolis-plot-go <plotName>` for both occupied homes and reservations; confirm teleport destinations are safe and inside the requested plot.
+- As the home owner, build and interact inside the home. As another non-op player, try the same actions. Verify ownership and protection behave as intended in homes, reservations, City, and Spawn.
+- Verify representative protection flags in-game, including PvP, mob damage/spawning, explosions, and fire/lava behavior where applicable. Run `/metropolis-flag-reset` and confirm the expected flags are restored without changing region bounds or ownership.
+- Restart the server and confirm reservations and their protection are still present in WorldGuard and remain excluded from home allocation.
+- Add a non-op test player as a WorldGuard member of a Metropolis reservation. Run `/metropolis-plot-go` and confirm they arrive inside that reservation at a safe location; repeat with an owner.
+- Confirm a player who is neither owner nor member cannot use a reservation name to teleport there. Check that a region they own/member outside homes, City, and Spawn is treated as expected by the Metropolis reservation lookup.
+- Add a player to two reservations. Confirm the no-argument form reports both names without teleporting, then specify one reservation and verify the chosen destination.
+- As an authorized admin, target another online member with `/metropolis-plot-go <playerName>`. Confirm the target receives a notification. Repeat without `metropolis.plot.go` and verify targeting another player is denied.
+- Test a reservation with no safe destination. Confirm the command reports failure and does not claim teleportation succeeded. Also test console use with an online player name and an unknown/offline name.
+
+### Commands, permissions, and player state
+
+- For a new player with no overrides, join and confirm exactly one `h_1_<UUID>` home is created. Rejoin and confirm no additional home is created.
+- Configure two `permissionOverrides` tiers in `plugins/Metropolis/config.yml`, then restart. Grant each permission node to a test user and to a test group through the server's permission manager. Confirm the player's effective `plotMultiplier` and `maxPlots` match the granted rule.
+- Give one player multiple configured permission nodes with different priorities. Confirm the highest-priority rule controls both values; then give two matching rules the same priority and confirm the last matching YAML entry wins.
+- Give a player both a permission tier and a matching `userOverrides` entry. Confirm the username override wins. Remove both overrides from another player and confirm `plot.multiplier` and `plot.maxPerPlayer` are used as defaults.
+- Change or revoke a permission while the player is online, then acquire another home. Confirm the next acquisition uses the currently granted tier without requiring a restart.
+- With plot multipliers of 1 and 2, acquire homes and inspect their WorldGuard bounds. Confirm size follows the tier, a larger footprint does not overlap an existing home, and the multiplier is applied to the X and Z footprint only once.
+- Exercise `/metropolis-home-acquire` below and at each effective home limit. Confirm every successful request creates a distinct next-numbered home, creates none beyond the limit, and does not change other players' homes.
+- After acquiring a second home, verify it becomes active: check the player's selected home in `plugins/Metropolis/currentHomes.yml` and use `/metropolis-home-go` to confirm travel to that home. Switch homes with `/metropolis-home-move` and verify the selection changes as expected.
+- Run `/metropolis-home-move <homeNumber>` as a player with multiple homes. Verify the command confirms the selected home, updates `currentHomes.yml`, and `/metropolis-home-go` now travels to it.
+- Run `/metropolis-home-move <homeNumber> <playerName>` as an authorized administrator, then repeat from console. Check an online target is notified and a cached offline target uses the selected home on their next join.
+- Try zero, negative, non-numeric, nonexistent home numbers, unknown player names, and extra arguments. Confirm each request is rejected with useful feedback and does not change the stored active home.
+- Restart after acquiring multiple homes. Confirm all home regions remain owned by the player, the active home selection persists, and joining does not allocate another first home.
+- Generate a home for an offline player administratively. Confirm permission tiers are not assumed for offline players; the username override or global settings determine plot size and limit.
+- Exercise `/metropolis-home-go` with a safe bed spawn inside the home and with no such bed spawn. Confirm teleportation chooses a valid location inside the home and reports a clear failure if no safe location exists.
+- Exercise `/metropolis-home-move` for a player with multiple homes. Confirm the selected home persists across reconnect and restart; reject nonexistent home numbers.
+- As an administrator, test `/metropolis-home-generate`, `/metropolis-home-evict`, and `/metropolis-home-list` with online and previously seen offline players. Confirm the intended region ownership changes, persistence, and subsequent allocation behavior.
+- Test commands as console, permitted player, and player without the relevant permission. Check player-only commands, target-player arguments, unknown names, malformed arguments, and permission denials for useful feedback and no unintended changes.
+- If upgrading an existing server, verify a legacy name-keyed `currentHomes.yml` entry resolves to the right UUID and the player's selected home is retained.
+
+## Existing Automated Coverage
+
+Run `./gradlew test` for the server-free JUnit suite. It has 62 tests covering:
+
+- `AvenueStairwayLayoutTest`: centered per-segment street and avenue flights, both border directions, independent cadence, top-tread alignment, inverted backing plan, exact-width openings, and invalid-fit rejection.
+- `PlotLevelSupportTest`: rejection of upper plots with missing logical support cells and complete coverage requirements across all lower levels.
+- `CityRegionBoundsTest`: City bounds expand to include elevated plots and Spawn without shrinking existing protection bounds.
+- `PlotGridLayoutTest`: zero-offset compatibility, offsets on X/Y/Z, axis-specific spacing, and negative logical-index recovery.
+- `WorldGuardRegionOccupancyTest`: arbitrary saved-region bounds are excluded while City/global regions are treated as non-occupying envelopes.
+- `PlotWorldBorderBoundsTest`: search bounds follow WorldBorder size/center and require the full candidate footprint inside it.
+- `SpawnLayoutTest`: default one-cell bounds, independent multipliers, and build-height validation.
+- `AvenueStairwayBuilderTest`: configured stair material and facing/half data for avenue and street directions, upside-down backing stairs, exact upper-road AIR placements, and no block writes at lower-road Y.
+- `RoadLayoutTest`: independently sized street/avenue bands, correct road-type tagging, non-overlapping corners, and disabled roads at zero width.
+- `RoadBlockWriterTest`: no-op writes for existing roads, filling missing road blocks, and preserving stair treads.
+- `CuboidTest`: WorldEdit bound conversion, vector ordering/null handling, touching intersections, and point containment.
+- `CurrentHomesStoreTest`: UUID-based persistence and resolving a legacy player-name key.
+- `PlayerJoinListenerTest`: the welcome bounds message when a home is supplied by a mock.
+- `PlayerLookupTest`: case-insensitive full-name matching and rejection of prefix matching.
+- `PlayerHomeTest`: UUID-based region identity and display-name retention.
+- `HomePermissionOverrideTest`: dotted permission-node parsing, priority and tie resolution, invalid entries, and username/permission/default precedence.
+- `HomeNumberAllocatorTest`: choosing the first unused positive home number.
+- `MetropolisHomeMoveCommandTest`: selecting a sender's home, selecting an offline target's home, and rejecting invalid requests.
+- `PlotReservationLookupTest`: owner/member matching, exclusion of homes/City/Spawn, legacy reservation markers, and region-name aliases.
+- `MetropolisPlotGoCommandTest`: self and target teleportation, ambiguous memberships, absent membership, and unsafe-destination feedback.
+- `MetropolisPlotReserveCommandTest`: parsing six coordinates and rejecting malformed coordinates.
+- `MetropolisHomeAcquireTest`: acquisition below the limit and refusal at the limit.
+- `MetropolisDebugGenerateTestHomesCommandTest`: asynchronous tick-queued generation, one home per interval, no overlapping batches, and continuing test-player names across repeated runs.
+
+The two opt-in tests in `src/integrationTest` require a running Paper server and RCON. They check that Metropolis appears in `/plugins` and that a coordinate reservation is persisted by WorldGuard. They do not currently verify restart persistence, join allocation, WorldEdit-selection reservations, permissions, teleports, generated blocks, protection behavior, or the other command workflows above. Run them with the environment variables documented in `README.md`; use a disposable server because the reservation test changes its WorldGuard data.
+
+The integration scope described in `TODO.md` is broader than the tests currently present. Treat the scenarios in this guide as unverified until a human has run them on the target Paper and plugin versions.

docs/modrinth-description.md

@@ -0,0 +1,48 @@
+**Metropolis**
+
+Metropolis grows a protected Minecraft city as players join. It assigns home plots connected by roads, expands the protected city region, and lets players and administrators manage homes and reserve plots.
+
+## Requirements
+
+- Paper 26.2 or 26.3.
+- Java 25 or newer.
+- WorldGuard 7.0.19 and WorldEdit 7.4.5.
+
+WorldGuard and WorldEdit are required dependencies. Install all three plugins in the server's `plugins` directory.
+
+Metropolis targets Paper only; Bukkit and Spigot servers are not supported.
+
+## Features
+
+- Automatically assigns a protected home plot when a player joins.
+- Allows players to acquire additional homes up to their effective limit, configured globally, per user, or through permission-manager groups.
+- Supports permission-based plot-size and home-limit tiers with configurable priorities; explicit per-user overrides take precedence.
+- Lets players and authorized administrators select an existing home as active; selections persist by player UUID across restarts.
+- Expands the protected city region as plots are occupied.
+- Configures plot dimensions, roads, floors, supports, signs, spawn behavior, and perimeter walls.
+- Reserves named plots by coordinates or a WorldEdit selection.
+- Lets WorldGuard owners and members teleport to reservations they belong to, with a named choice when they have multiple.
+- Tracks home ownership and selected homes by player UUID.
+- Supports home and plot teleportation, administration, and WorldGuard protection flags.
+
+## Configuration
+
+Metropolis creates `plugins/Metropolis/config.yml` on first startup. Configure plot limits and dimensions, roads, floors and supports, signs, spawn behavior, walls, world name, and per-player overrides. Use Bukkit material names; legacy numeric material IDs are also accepted for existing configurations.
+
+## Commands
+
+- `/metropolis` - Displays the plugin version.
+- `/metropolis-home-acquire` - Acquires another available home plot.
+- `/metropolis-home-generate <playerName>` - Generates a home for a known online or cached offline player.
+- `/metropolis-home-list` - Lists occupied and reserved plots.
+- `/metropolis-home-go [playerName]` - Teleports to a home.
+- `/metropolis-home-move <homeNumber> [playerName]` - Selects an existing home as active. The player name defaults to the sender; authorized administrators and console can target online or cached offline players.
+- `/metropolis-home-evict <playerName>` - Removes a player's ownership from their selected home region.
+- `/metropolis-plot-reserve <name> <minX> <minY> <minZ> <maxX> <maxY> <maxZ>` - Reserves a region by coordinates; players can use `/metropolis-plot-reserve <name>` with a WorldEdit selection.
+- `/metropolis-plot-go [playerName]` - Teleports to the sender's or an online player's reservation. Specify a reservation name to choose among multiple memberships; `metropolis.plot.go` allows targeting others or bypassing membership.
+- `/metropolis-flag-reset` - Reapplies Metropolis protection flags.
+- `/metropolis-debug-generatetesthomes <count>` - Generates test homes; intended for development servers.
+
+## Build
+
+Run `./gradlew build` from the project directory. The plugin jar is created in `build/libs/`.

docs/modrinth.json

@@ -0,0 +1,13 @@
+{
+  "name": "Metropolis",
+  "url": "https://modrinth.com/plugin/metropolis-builder",
+  "summary": "Grow a protected Minecraft city with automatic UUID-owned homes, configurable roads, WorldGuard protection, and reserved plots.",
+  "visibility": "public",
+  "links": {
+    "issueTracker": "https://github.com/headhunter45/Metropolis/issues",
+    "sourceCode": "https://github.com/headhunter45/Metropolis",
+    "wikiPage": null,
+    "discordInvite": null,
+    "donationLinks": []
+  }
+}

docs/project-description.json

@@ -0,0 +1,23 @@
+{
+  "id": "metropolis",
+  "title": "Metropolis",
+  "description": "A Paper 26.2/26.3 city-planning plugin that turns player onboarding into procedural urban growth with protected UUID-owned homes, roads, reservations, and configurable infrastructure.",
+  "docId": "Metropolis",
+  "image": {
+    "url": "Pixel-art aerial view of a growing Minecraft city planned in a square grid, small player home plots connected by pale roads, a protected central spawn, blocky green landscape, subtle WorldGuard-inspired boundary lines, warm daylight, clean game-plugin thumbnail composition, no words or logos.",
+    "alt": "Pixel-art aerial view of a Minecraft city with player home plots and connecting roads",
+    "prompt": "Pixel-art aerial view of a growing Minecraft city planned in a square grid, small player home plots connected by pale roads, a protected central spawn, blocky green landscape, subtle WorldGuard-inspired boundary lines, warm daylight, clean game-plugin thumbnail composition, no words or logos.",
+    "width": 0,
+    "height": 0,
+    "backgroundClassName": "bg-surface"
+  },
+  "url": "/projects/metropolis",
+  "tags": ["open-source"],
+  "source": {
+    "type": "github",
+    "url": "https://github.com/headhunter45/Metropolis"
+  },
+  "feedback": {
+    "url": "https://github.com/headhunter45/Metropolis/issues"
+  }
+}

docs/project-description.md

@@ -0,0 +1,5 @@
+# Metropolis
+
+Metropolis turns player onboarding into city planning. As players arrive, the Paper plugin finds the next available plot, builds the surrounding roads and infrastructure, and extends a WorldGuard-protected city that feels designed rather than randomly generated.
+
+The project combines procedural spatial logic, persistent UUID-based ownership, configurable construction rules, WorldEdit-assisted reservations, and a command suite for acquiring and selecting multiple homes. Home limits and plot sizes can be assigned per user or through permission-manager groups using configurable permission tiers. Reservation owners and members can teleport to their reserved plots, with explicit selection when they belong to multiple reservations. Active-home selections persist across reconnects and server restarts. It is also a modernization case study: a legacy plugin brought forward to Paper 26.2 and 26.3 with Gradle, focused unit tests, and opt-in live-server integration tests. Bukkit and Spigot servers are outside the support target.