hubmc_essentionals/CLAUDE.md

# CLAUDE.md

This file provides guidance to Claude Code (claude.ai/code) when working with code in this repository.

## Developer Role

You are a Senior Java Minecraft NeoForge mod developer with deep expertise in:
- NeoForge mod development patterns and best practices
- Minecraft 1.21.1 game mechanics and APIs
- Java 21 features and modern Java development
- Event-driven architecture and registry systems
- Resource generation and data pack systems
- REST API integration and HTTP client implementations
- LuckPerms permission system integration

## Project Overview

HubmcEssentials is a Minecraft mod built with NeoForge for Minecraft 1.21.1. This is a server-side essentials mod that provides administrative and quality-of-life commands with tiered permissions (VIP, Premium, Deluxe) managed through LuckPerms.

**Key identifiers:**
- Mod ID: `hubmc_essentials` (note: lowercase with underscore)
- Package: `org.itqop.HubmcEssentials` (note: PascalCase in package name)
- Main class: `HubmcEssentials.java` with `@Mod(HubmcEssentials.MODID)`
- Java version: 21

## Architecture Overview

### HubGW API Integration

**Critical: All cooldowns are managed ONLY through HubGW API - no local caching.**

- **Base URL:** `/api/v1`
- **Authentication:** Header `X-API-Key` (configured via environment variable)
- **Timeouts:** 2s connection / 5s read
- **Retry Policy:** 2 retries on 429/5xx errors
- **Error Handling:** If HubGW is unavailable, **DENY the action** and show user a brief error message

### Cooldown System

All cooldowns are handled via HubGW:
- **Check cooldown:** `POST /cooldowns/check` with `player_uuid` and `cooldown_type`
- **Set/extend cooldown:** `POST /cooldowns/` with `player_uuid`, `cooldown_type`, and either `cooldown_seconds` or `expires_at`
- **No local cache** - every cooldown check must call the API

**Cooldown type naming conventions:**
- Kits: `kit|<name>` (e.g., `kit|vip`, `kit|premium`)
- Commands: `rtp`, `back`, `tp|<target>`, `tp|coords`, `heal`, `feed`, `repair`, `repair_all`, `near`, `clear`, `ec`, `hat`, `top`, `pot`, `time|day`, `time|night`, `time|morning`, `time|evening`

### Permission System

Uses LuckPerms with namespace `hubmc`:
- Base permissions: `hubmc.cmd.<command>`
- Tier permissions: `hubmc.tier.(vip|premium|deluxe)`
- Special permissions: `hubmc.cmd.tp.others`, `hubmc.cmd.tp.coords`, `hubmc.cmd.warp.create`, `hubmc.cmd.repair.all`

### Command Categories

**General (no tier required):**
- `/spec`, `/spectator` - Toggle spectator mode (local)
- `/sethome` - Save home via `PUT /homes/`
- `/home` - Teleport to home via `POST /homes/get`
- `/fly` - Toggle flight (local)
- `/vanish` - Hide player (local)
- `/invsee <nick>` - Open player inventory (local, online only)
- `/enderchest <nick>` - Open player enderchest (local, online only)
- `/kit <name>` - Claim kit with cooldown check
- `/clear` - Clear inventory (with cooldown)
- `/ec` - Open enderchest (with cooldown)
- `/hat` - Wear item as hat (with cooldown)

**VIP Tier:**
- `/heal`, `/feed`, `/repair`, `/near`, `/back`, `/rtp` - All with cooldowns
- `/kit vip` - VIP kit with cooldown

**Premium Tier:**
- `/warp create` - Create warp via `POST /warps/` (no cooldown)
- `/repair all` - Repair all items (with cooldown)
- `/workbench` - Open crafting table (no cooldown)
- `/kit premium`, `/kit storage` - Premium kits with cooldowns

**Deluxe Tier:**
- `/top` - Teleport to highest block (with cooldown)
- `/pot` - Apply potion effect (with cooldown)
- `/day`, `/night`, `/morning`, `/evening` - Set time (with cooldowns via `time|<preset>`)
- `/weather clear|storm|thunder` - Set weather (no cooldown)
- `/kit deluxe`, `/kit create`, `/kit storageplus` - Deluxe kits with cooldowns

**Custom `/goto` Command:**
- Replaces vanilla `/tp` with cooldowns and logging (vanilla `/tp` remains available for OP users)
- Supports: `/goto <player>`, `/goto <player1> <player2>`, `/goto <x> <y> <z>`
- Permissions: `hubmc.cmd.tp`, `hubmc.cmd.tp.others`, `hubmc.cmd.tp.coords`
- Cooldowns: `tp|<targetNick>` or `tp|coords` (configurable in config)
- **Automatically logs teleport history:** After successful TP, calls `POST /teleport-history/` with fields: `player_uuid`, `from_world`, `from_x/y/z`, `to_world`, `to_x/y/z`, `tp_type` (one of: `to_player`, `to_player2`, `to_coords`), `target_name`

## Build Commands

### Basic Build Tasks
```bash
./gradlew build              # Build the mod
./gradlew clean              # Clean build artifacts
./gradlew jar                # Create mod jar file
```

### Running the Mod
```bash
./gradlew runClient          # Launch Minecraft client with mod loaded
./gradlew runServer          # Launch dedicated server (nogui mode)
./gradlew runData            # Run data generators
./gradlew runGameTestServer  # Run automated game tests
```

### Testing
```bash
./gradlew test               # Run test suite
```

## Code Architecture

### Main Entry Point
The mod initializes through `HubmcEssentials.java` which:
- Registers configuration to mod container
- Subscribes to config load events
- Registers to the mod event bus for lifecycle events

### Implemented Components

**1. HTTP Client Service (`HubGWClient.java`)** ✅
- Singleton HTTP client with circuit breaker pattern
- Authentication via `X-API-Key` header from config
- Retry logic (2 retries on 429/5xx) with exponential backoff
- Configurable timeouts (2s connect / 5s read)
- Error throttling to prevent log spam

**2. Command System (25 commands)** ✅
- All commands registered via `CommandRegistry` using Brigadier
- LuckPerms integration for permission checks via NeoForge PermissionAPI
- 30 permission nodes defined in `PermissionNodes.java`
- Each command follows pattern: permission check → cooldown check → execute → set cooldown
- Russian language error messages via `MessageUtil`

**3. API Services (5 services)** ✅
- `CooldownService` - Check and create cooldowns
- `HomeService` - Create, get, and list homes
- `WarpService` - Create, get, and list warps
- `TeleportService` - Log teleport history
- `KitService` - Claim kits
- All services use async CompletableFuture with retry logic

**4. Configuration System (`Config.java`)** ✅
- ModConfigSpec-based type-safe configuration
- API settings: base URL, API key, timeouts, retries, debug logging
- 14 configurable cooldowns for all commands
- All values cached on load for fast access

**5. Teleport History Tracking** ✅
- Automatic logging after `/goto` commands
- Tracks: player UUID, from/to coordinates, from/to world, tp_type, target_name
- Uses `TeleportService.logTeleport()` with async fire-and-forget

**6. Utilities** ✅
- `MessageUtil` - Russian messages with formatting and cooldown display
- `LocationUtil` - Teleportation, safe location checking, world ID handling
- `PlayerUtil` - Player lookup and UUID management
- `RetryUtil` - Async retry with exponential backoff

**7. Storage** ✅
- `LocationStorage` - In-memory storage for `/back` functionality using ConcurrentHashMap

### Error Handling Strategy

**When HubGW API fails:**
- Show message: "Сервис недоступен, попробуйте позже" (Service unavailable, try later)
- **DENY the action** - do not allow command execution
- Log error for debugging

**When cooldown is active:**
- Show message: "Команда доступна через N сек." (Command available in N seconds)

**When home/warp not found:**
- Show message: "Дом не найден" (Home not found) or similar

### Resource Generation
- Metadata generation via `generateModMetadata` task processes templates from `src/main/templates/`
- Template variables are defined in `gradle.properties` and expanded into `neoforge.mods.toml`
- Generated resources output to `build/generated/sources/modMetadata/`
- Data generation outputs to `src/generated/resources/` (included in source sets)

## Important File Locations

- Main mod class: `src/main/java/org/itqop/HubmcEssentials/HubmcEssentials.java`
- Config class: `src/main/java/org/itqop/HubmcEssentials/Config.java`
- Mod metadata template: `src/main/templates/META-INF/neoforge.mods.toml`
- Mod properties: `gradle.properties`
- Assets: `src/main/resources/assets/hubmc_essentionals/` (note: old package name still used here)
- **Technical Specification:** `ТЗ.md` - Complete Russian specification with all commands and requirements
- **API Documentation:** `API_ENDPOINTS.md` - Complete HubGW API endpoint documentation

## API Endpoints Reference

See `API_ENDPOINTS.md` for complete details. Key endpoints:

**Cooldowns:**
- `POST /cooldowns/check` - Check if cooldown is active
- `POST /cooldowns/` - Create/extend cooldown

**Homes:**
- `PUT /homes/` - Create/update home
- `POST /homes/get` - Get specific home
- `GET /homes/{player_uuid}` - List all homes

**Warps:**
- `POST /warps/` - Create warp
- `POST /warps/get` - Get specific warp
- `POST /warps/list` - List warps with filters

**Teleport History:**
- `POST /teleport-history/` - Log teleport event
- `GET /teleport-history/players/{player_uuid}` - Get player's TP history

## Package Name Migration Note

The project is in the process of migrating from `hubmc_essentionals` (with 'o') to `hubmc_essentials` (with 'e'). Some resource paths still use the old naming. Be aware of this inconsistency when adding new features or assets.

## Development Notes

- The mod uses Parchment mappings for better parameter names
- ModDev plugin version: 2.0.113
- NeoForge version: 21.1.209
- Gradle is configured for parallel builds, caching, and configuration cache for better performance
- Run configurations include proper logging markers and debug level set to DEBUG
- **This is a server-side mod** - focus on server commands and backend integration
- All user-facing messages should be in Russian (as per ТЗ.md requirements)

## Implementation Summary

### Commands Implemented (25 total)

**General Commands (11):**
- `/spec`, `/spectator` - Toggle spectator mode (no cooldown)
- `/fly` - Toggle flight (no cooldown)
- `/vanish` - Toggle vanish mode (no cooldown)
- `/invsee <player>` - View player inventory (no cooldown)
- `/enderchest <player>` - View player ender chest (no cooldown)
- `/sethome [name]` - Save home location (no cooldown)
- `/home [name]` - Teleport to home (no cooldown)
- `/kit <name>` - Claim kit (cooldown via API)
- `/clear` - Clear inventory (cooldown: 300s default)
- `/ec` - Open ender chest (cooldown: 180s default)
- `/hat` - Wear item as hat (cooldown: 120s default)

**VIP Commands (6):**
- `/heal` - Heal player (cooldown: 300s default)
- `/feed` - Feed player (cooldown: 180s default)
- `/repair` - Repair held item (cooldown: 600s default)
- `/near [radius]` - List nearby players (cooldown: 60s default)
- `/back` - Return to previous location (cooldown: 120s default)
- `/rtp` - Random teleport (cooldown: 600s default)

**Premium Commands (3):**
- `/warp create <name> [description]` - Create warp (no cooldown)
- `/warp list` - List warps (no cooldown)
- `/warp <name>` - Teleport to warp (no cooldown)
- `/warp delete <name>` - Delete warp (no cooldown) ✅
- `/repair all` - Repair all items (cooldown: 1800s default)
- `/workbench`, `/wb` - Open crafting table (no cooldown)

**Deluxe Commands (4):**
- `/top` - Teleport to highest block (cooldown: 300s default)
- `/pot <effect> [duration] [amplifier]` - Apply potion effect (cooldown: 120s default)
- `/morning`, `/day`, `/evening`, `/night` - Set time (cooldown: 60s default each)
- `/weather <clear|storm|thunder>` - Set weather (no cooldown)

**Custom Commands (1):**
- `/goto <player>` - Teleport to player (cooldown: 60s default)
- `/goto <player1> <player2>` - Teleport player to player (no cooldown, admin only)
- `/goto <x> <y> <z>` - Teleport to coordinates (cooldown: 60s default)

### Configuration File

The mod creates `config/hubmc_essentials-common.toml` with the following settings:

**API Configuration:**
- `apiBaseUrl` - HubGW API base URL (default: `http://localhost:8000/api/v1`)
- `apiKey` - API authentication key (default: `your-api-key-here`)
- `connectionTimeout` - Connection timeout in seconds (default: 2, range: 1-30)
- `readTimeout` - Read timeout in seconds (default: 5, range: 1-60)
- `maxRetries` - Max retries on 429/5xx errors (default: 2, range: 0-10)
- `enableDebugLogging` - Enable debug logging (default: false)

**Cooldown Configuration (in seconds, range: 0-3600 or 0-7200):**
- `clear` - 300 (5 minutes)
- `ec` - 180 (3 minutes)
- `hat` - 120 (2 minutes)
- `heal` - 300 (5 minutes)
- `feed` - 180 (3 minutes)
- `repair` - 600 (10 minutes)
- `near` - 60 (1 minute)
- `back` - 120 (2 minutes)
- `rtp` - 600 (10 minutes)
- `repairAll` - 1800 (30 minutes)
- `top` - 300 (5 minutes)
- `pot` - 120 (2 minutes)
- `time` - 60 (1 minute)
- `goto` - 60 (1 minute)

### LuckPerms Permission Setup

All permissions use `hubmc` namespace:

**Tier Permissions:**
- `hubmc.tier.vip` - Grants access to all VIP commands
- `hubmc.tier.premium` - Grants access to all Premium commands (includes VIP)
- `hubmc.tier.deluxe` - Grants access to all Deluxe commands (includes Premium + VIP)

**Individual Command Permissions:**
- General: `hubmc.cmd.spec`, `hubmc.cmd.fly`, `hubmc.cmd.vanish`, `hubmc.cmd.invsee`, `hubmc.cmd.enderchest`, `hubmc.cmd.sethome`, `hubmc.cmd.home`, `hubmc.cmd.kit`, `hubmc.cmd.clear`, `hubmc.cmd.ec`, `hubmc.cmd.hat`
- VIP: `hubmc.cmd.heal`, `hubmc.cmd.feed`, `hubmc.cmd.repair`, `hubmc.cmd.near`, `hubmc.cmd.back`, `hubmc.cmd.rtp`
- Premium: `hubmc.cmd.warp.create`, `hubmc.cmd.repair.all`, `hubmc.cmd.workbench`
- Deluxe: `hubmc.cmd.top`, `hubmc.cmd.pot`, `hubmc.cmd.time`, `hubmc.cmd.weather`
- Teleport: `hubmc.cmd.tp`, `hubmc.cmd.tp.others`, `hubmc.cmd.tp.coords`