itqop
/
hubmc_essentionals
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity
hubmc_essentionals/CLAUDE.md

13 KiB
Raw Blame History

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

./gradlew build              # Build the mod
./gradlew clean              # Clean build artifacts
./gradlew jar                # Create mod jar file

Running the Mod

./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

./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