Guilds

A comprehensive guild and territory management plugin for Minecraft Paper servers, built with Guice DI, JDBC, and Brigadier commands.

Features

🏰 Guild System

• Create & manage guilds with custom names, colors, and descriptions
• Role hierarchy — owner, officers, and custom roles with configurable permissions
• Invite system with accept/decline flow
• Guild chat — private /gc, officer chat /oc, and ally chat /allychat
• Transfer ownership to another member

🗺️ Territory & Claiming

• Chunk-based claiming with auto-claim modes
• Visual map rendering with guild colors and symbols
• Entry/exit notifications when crossing territory borders
• Protection listener — block interaction, PvP, and item usage controls
• Outposts — claim secondary territory locations

📐 Subregions

• Nested regions within guild territory with independent permissions
• Region types with configurable volume limits per type
• Per-member region roles — fine-grained access control per subregion
• Visual selection tools for defining region boundaries

🌳 Skill Tree

• DAG-based skill tree with GUI (triumph-gui)
• Branch system — unlock paths organized by category
• Skill effects — buffs and perks applied on unlock
• Respec system — reset and reallocate skill points
• Layout engine — automatic node positioning for clean visualization

🏛️ Nations (new)

• Multi-guild nations with king, ministers, and member guilds
• Diplomacy — alliances and enemy declarations
• Tax system — configurable tax rate per nation
• Open/closed — control whether guilds can freely join
• 13 subcommands under /g nation

📐 Blueprints (new)

• Save building templates from WorldEdit selections
• Paste at any location via Bukkit block API
• Per-guild storage — each guild manages its own blueprints
• WorldEdit integration for selection-based saving

🎯 Guild Specializations (new)

• 5 specialization types: MINING, TRADE_HUB, MILITARY, ARCANE, AGRICULTURAL
• Per-guild perks — choose a specialization for your guild
• Level requirement to unlock specialization
• Reset to change specialization later

💼 Projects & Quests

• Project pool — rotating guild objectives with automatic refresh
• Quest progress — track contribution toward project goals
• LLM integration — AI-generated project names and descriptions (Groq, HuggingFace)
• Buff system — apply temporary buffs from completed projects
• Buff GUI — view active buffs with triumph-gui

📈 Progression

• XP-based leveling — earn XP from playtime and activities
• Level-up system with configurable costs and benefits
• Progression log — track guild history and milestones
• Material requirements — procedural cost generation for level-ups

🏦 Vault System

• Guild vault — shared storage accessible via multiblock structure
• Vault GUI — triumph-gui based inventory management
• Transaction logging — track deposits and withdrawals

🔧 Multiblock Structures

• Pattern-based detection — build structures that trigger functionality
• Guild vault multiblock — physical vault access in claimed territory
• Extensible registry — add custom multiblock patterns

Commands

All commands are under /g (alias: /guild).

Command	Description
/g create <name>	Create a new guild
/g join <guild>	Accept an invite to a guild
/g leave	Leave your current guild
/g disband	Disband your guild
/g invite <player>	Invite a player
/g accept	Accept a pending invite
/g decline	Decline a pending invite
/g kick <player>	Kick a guild member
/g info [guild]	View guild information
/g list	List all guilds
/g member <player>	View member info
/g role <player> <role>	Assign a role
/g owner	Display guild owner
/g color <color>	Change guild color
/g name <name>	Rename guild
/g description <text>	Set guild description
/g spawn	Teleport to guild spawn
/g setspawn	Set guild spawn point
/g claim	Claim a chunk
/g unclaim [all]	Unclaim chunks
/g auto [claim|unclaim|off]	Toggle auto-claim
/g map	View territory map
/g toggle	Toggle guild settings
/g ally <guild>	Form alliance
/g enemy <guild>	Declare enemy
/g neutral <guild>	Remove relationship
/g log	View guild log
/g skills	Open skill tree GUI
/g project [start|list|progress|contribute]	Manage projects
/g upgrade	Level up guild
/g vault	Open guild vault
/g outpost	Manage outposts

Region Commands

Command	Description
/region	Region management root
/region create <name>	Create a subregion
/region delete <name>	Delete a subregion
/region info <name>	View region info
/region list	List regions
/region type <name> <type>	Set region type
/region owner <name> <guild|member>	Set region owner
/region perm <name> <perm>	Set region permissions

Nation Commands (new)

Command	Description
/g nation create <name>	Create a nation
/g nation invite <guild>	Invite a guild
/g nation join <nation>	Join a nation
/g nation leave	Leave nation
/g nation list	List all nations
/g nation info [nation]	Show nation details
/g nation ally <nation>	Form alliance
/g nation enemy <nation>	Declare enemy
/g nation neutral <nation>	Remove relationship
/g nation kick <guild>	Kick a guild
/g nation set king <player>	Transfer kingship
/g nation set tax <rate>	Set tax rate
/g nation set open <true/false>	Toggle open/closed

Blueprint Commands (new)

Command	Description
/g blueprint save <name>	Save selection as blueprint
/g blueprint list	List guild blueprints
/g blueprint load <name>	View blueprint info
/g blueprint apply <name>	Paste at location
/g blueprint delete <name>	Delete blueprint

Specialization Commands (new)

Command	Description
/g specialize	View specializations
/g specialize <type>	Choose specialization
/g specialize reset	Remove specialization

Chat Commands

Command	Description
/gc <message>	Guild chat
/oc <message>	Officer chat
/allychat <message>	Alliance chat

Permissions

Node	Default	Description
guilds.use	true	Base guild command access
guilds.create	true	Create guilds
guilds.join	true	Join guilds
guilds.leave	true	Leave guilds
guilds.delete	true	Disband guilds
guilds.info	true	View guild info
guilds.list	true	List guilds
guilds.claim	true	Claim chunks
guilds.unclaim	true	Unclaim chunks
guilds.kick	true	Kick members
guilds.role	true	Manage roles
guilds.map	true	View map
guilds.spawn	true	Teleport to spawn
guilds.setspawn	true	Set spawn
guilds.ally	true	Manage alliances
guilds.enemy	true	Manage enemies
guilds.neutral	true	Remove relationships
guilds.description	true	Change description
guilds.name	true	Rename guild
guilds.chat	true	Use guild chat
guilds.levelup	true	Level up guild
guilds.admin	op	All guild permissions
guilds.admin.bypass	op	Bypass claim protections

Architecture

Technology Stack

• Java 21 — modern Java features
• Paper API 1.21.11 — latest Paper platform
• Guice — dependency injection
• Brigadier — command system via Paper lifecycle events
• JDBC — database access with HikariCP connection pooling
• Caffeine — in-memory caching
• triumph-gui — inventory GUIs
• OkHttp + Gson — HTTP and JSON

Project Structure

org.aincraft/
├── GuildsPlugin.java          # Main plugin class
├── Guild.java                 # Guild model
├── GuildService.java          # Core guild operations
├── GuildRole.java             # Role model
├── commands/                  # Brigadier commands
│   ├── GuildCommand.java      # Command router
│   └── components/            # Command handlers
├── service/                   # Business logic services
├── database/                  # Database layer
│   ├── SchemaManager.java     # Schema migration
│   └── repository/            # JDBC repositories
├── claim/                     # Territory claiming
├── subregion/                 # Nested regions
├── skilltree/                 # Skill tree system
├── nation/                    # Nation system
├── blueprint/                 # Blueprint system
├── specialization/            # Guild specializations
├── project/                   # Projects & quests
├── progression/               # XP & leveling
├── vault/                     # Guild vault
├── multiblock/                # Multiblock structures
├── role/                      # Role management
├── map/                       # Territory map rendering
├── chat/                      # Chat channels
├── listeners/                 # Event listeners
├── inject/                    # Guice module
├── config/                    # Configuration
└── util/                      # Utilities

Building

./gradlew build

Shadow JAR:

./gradlew shadowJar

Requirements

• Java 21+
• Paper 1.21.11+
• MariaDB or PostgreSQL (production)
• Mint API (message formatting)

License

Proprietary — see LICENSE file.