From 2613fb38b37d81e38f83d18fb2122dbb9d0c5630 Mon Sep 17 00:00:00 2001 From: tastybento Date: Thu, 19 Feb 2026 22:58:11 -0800 Subject: [PATCH 1/2] Add CLAUDE.md with build commands and architecture overview Co-Authored-By: Claude Sonnet 4.6 --- CLAUDE.md | 96 +++++++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 CLAUDE.md diff --git a/CLAUDE.md b/CLAUDE.md new file mode 100644 index 0000000..8bb5bd9 --- /dev/null +++ b/CLAUDE.md @@ -0,0 +1,96 @@ +# CLAUDE.md + +This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository. + +## Project Overview + +**Level** is a BentoBox add-on for Minecraft that calculates island levels based on block types and counts, maintains top-ten leaderboards, and provides competitive metrics for players on game modes like BSkyBlock and AcidIsland. + +## Build & Test Commands + +```bash +# Build +mvn clean package + +# Run all tests +mvn test + +# Run a single test class +mvn test -Dtest=LevelTest + +# Run a specific test method +mvn test -Dtest=LevelTest#testMethodName + +# Full build with coverage +mvn verify +``` + +Java 21 is required. The build produces a shaded JAR (includes PanelUtils). + +## Architecture + +### Entry Points +- `LevelPladdon` — Bukkit plugin entry point; instantiates `Level` via the `Pladdon` interface +- `Level` — main addon class; loads config, registers commands/listeners/placeholders, and hooks into optional third-party plugins + +### Lifecycle +`onLoad()` → `onEnable()` → `allLoaded()` + +`allLoaded()` is where integrations with other BentoBox add-ons (Warps, Visit) are established, since those may not be loaded yet during `onEnable()`. + +### Key Classes + +| Class | Role | +|---|---| +| `LevelsManager` | Central manager: island level cache, top-ten lists, database reads/writes | +| `Pipeliner` | Async queue; limits concurrent island calculations (configurable) | +| `IslandLevelCalculator` | Core chunk-scanning algorithm; supports multiple block stacker plugins | +| `Results` | Data object returned by a completed calculation | +| `ConfigSettings` | Main config bound to `config.yml` via BentoBox's `@ConfigEntry` annotations | +| `BlockConfig` | Block point-value mappings from `blockconfig.yml` | +| `PlaceholderManager` | Registers PlaceholderAPI placeholders | + +### Package Layout +``` +world/bentobox/level/ +├── calculators/ # IslandLevelCalculator, Pipeliner, Results, EquationEvaluator +├── commands/ # Player and admin sub-commands +├── config/ # ConfigSettings, BlockConfig +├── events/ # IslandPreLevelEvent, IslandLevelCalculatedEvent +├── listeners/ # Island activity, join/leave, migration listeners +├── objects/ # IslandLevels, TopTenData (database-persisted objects) +├── panels/ # GUI panels (top-ten, details, block values) +├── requests/ # API request handlers for inter-addon queries +└── util/ # Utils, ConversationUtils, CachedData +``` + +### Island Level Calculation Flow +1. A calculation request enters `Pipeliner` (async queue, default concurrency = 1) +2. `IslandLevelCalculator` scans island chunks using chunk snapshots (non-blocking) +3. Block counts are looked up against `BlockConfig` point values +4. An equation (configurable formula) converts total points → island level +5. Results are stored via `LevelsManager` and fired as `IslandLevelCalculatedEvent` + +### Optional Plugin Integrations +Level hooks into these plugins when present: WildStacker, RoseStacker, UltimateStacker (block counts), AdvancedChests, ItemsAdder, Oraxen (custom blocks), and the BentoBox Warps/Visit add-ons. + +## Testing + +Tests live in `src/test/java/world/bentobox/level/`. The framework is JUnit 5 + Mockito 5 + MockBukkit. `CommonTestSetup` is a shared base class that sets up the MockBukkit server and BentoBox mocks — extend it for new test classes. + +JaCoCo coverage reports are generated during `mvn verify`. + +## Configuration Resources + +| File | Location in JAR | Purpose | +|---|---|---| +| `config.yml` | `src/main/resources/` | Main settings (level cost formula, world inclusion, etc.) | +| `blockconfig.yml` | `src/main/resources/` | Points per block type | +| `locales/` | `src/main/resources/locales/` | Translation strings | +| `panels/` | `src/main/resources/panels/` | GUI layout definitions | + +## Code Conventions + +- Null safety via Eclipse JDT annotations (`@NonNull`, `@Nullable`) — honour these on public APIs +- BentoBox framework patterns: `CompositeCommand` for commands, `@ConfigEntry`/`@ConfigComment` for config, `@StoreAt` for database objects +- Pre- and post-events (`IslandPreLevelEvent`, `IslandLevelCalculatedEvent`) follow BentoBox's cancellable event pattern — fire both when adding new calculation triggers From ee1dd24822b4db0f933605fda89a29c75bd22f57 Mon Sep 17 00:00:00 2001 From: tastybento Date: Fri, 20 Feb 2026 10:07:39 -0800 Subject: [PATCH 2/2] Update Paper API to 1.21.11 to match MockBukkit MockBukkit dev-9b384aa is built against Paper API 1.21.11-R0.1-SNAPSHOT. Aligning the project's Paper dependency eliminates the version-mismatch warning and allows all 22 tests to pass cleanly. Co-Authored-By: Claude Sonnet 4.6 --- pom.xml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/pom.xml b/pom.xml index 7c9d7f4..961b3e7 100644 --- a/pom.xml +++ b/pom.xml @@ -56,7 +56,7 @@ 5.11.0 v1.21-SNAPSHOT - 1.21.10-R0.1-SNAPSHOT + 1.21.11-R0.1-SNAPSHOT 3.10.2 1.12.0