Guilds

Guilds is the player-organization system for Eternal Empires. Players can found a guild, invite others to join, organize members into custom roles with fine-grained permissions, and pool money in a shared guild bank. Every ban, kick, invitation and bank transaction is written to an audit log so guild owners can see who did what.

What it does

A guild has a name, an optional description, an owner, and any number of custom roles beyond the built-in default role. Each role carries a set of permissions — INVITE_PLAYERS, KICK_PLAYERS, BAN_PLAYERS, UNBAN_PLAYERS, BANK_WITHDRAW, BANK_DEPOSIT, MANAGE_STATUS, MANAGE_DESCRIPTION, MANAGE_ACTIVITY, and role management itself (CREATE_ROLES, EDIT_ROLES, DELETE_ROLES, MANAGE_ROLES) — so an owner can, for example, give a "moderator" role the ability to kick and ban without also giving it access to the bank.

Membership works through invitations: a player with INVITE_PLAYERS permission invites someone, who then accepts to join. Guilds can also ban specific players outright, which prevents them from being invited again until unbanned. Everything that changes guild membership or the bank — bans, unbans, kicks, invitations created or revoked, joins, leaves, deposits, withdrawals — is recorded as a log entry against the guild, giving owners a full audit trail.

Commands

Command	Description	Permission
/guild	Show guild info/help for your own guild	guilds.command.guild
/guild create	Create a new guild	guilds.command.guild.create
/guild manage	Open guild management	guilds.command.guild.manage
/guild invite <player>	Invite a player to your guild	guilds.command.guild.invite
/guild join <name>	Accept an invitation to a guild	guilds.command.guild.join
/guild leave	Leave your current guild	guilds.command.guild.leave
/guild kick <player> [reason]	Kick a member from the guild	guilds.command.guild.kick
/guild ban <player> <reason>	Ban a player from the guild	guilds.command.guild.ban
/guild unban <player>	Lift a guild ban	guilds.command.guild.unban
/guild bank	Show the guild bank balance	guilds.command.guild.bank
/guild bank deposit <amount>	Deposit money into the guild bank	guilds.command.guild.bank.deposit
/guild bank withdraw <amount>	Withdraw money from the guild bank	guilds.command.guild.bank.withdraw

Each of the above also requires the relevant GuildRolePermission on the player's role within the guild, on top of the Bukkit permission.

The API

GuildProvider gives you a player's Guild (or looks one up by name). From a Guild you can read and change its name, description and status, manage its GuildRoles and their GuildRolePermissions, list members and bans, create and inspect invitations via GuildInvitation, and access the GuildBank. GuildPlayerProvider resolves a Bukkit player to the GuildPlayer used throughout the API. If you need to react to guild activity — a shop plugin taxing bank withdrawals, a stats plugin tracking kicks — the various GuildLog subtypes (GuildBanLog, GuildBankLog, GuildKickLog, GuildInvitationCreateLog, GuildInvitationRevokeLog, GuildPlayerJoinLog, GuildPlayerLeaveLog) describe every recorded event.

Modules

• api — public interfaces (Guild, GuildRole, GuildBank, GuildInvitation, GuildPlayer, the various log types) and enums. No implementation, published for other plugins to depend on.
• common — the MongoDB-backed implementation via Morphia (GuildModel, GuildPlayerModel, etc.), queried directly via an injected Datastore.
• paper — the Paper plugin itself: commands, wiring, and startup.

Requirements

Java 21, Paper 1.13 or newer, and a MongoDB instance. Guilds depends on multilanguage for all in-game messages, which needs to be installed alongside it.

Building

./gradlew build

To get a plugin jar, build the paper module's shadow jar:

./gradlew paper:shadowJar

The resulting jar is written to paper/build/libs/.

Configuration

On first run, database.yml is generated under plugins/guilds/, configuring the MongoDB connection used to store guilds, roles, bans, invitations and audit logs:

host: localhost
port: 27017
database: guilds
username: admin
password: 'my-password'   # leave blank if your MongoDB has no auth configured

Using the API from another plugin

If you're building a plugin that needs to read guild membership, roles, or bank data, depend on the guilds-api artifact rather than reimplementing anything:

repositories {
    maven {
        url 'https://packages.eternalempires.net'
    }
}

dependencies {
    compileOnly 'net.eternalempires:guilds-api:VERSION'
}

Replace VERSION with the release you want to target — see the Releases page for available versions.

License

See LICENSE.

Contributing

See CONTRIBUTING.md.