Guild

Guilds with roles, invitations, a shared bank and a GUI menu, synced across servers.

Privatev0.1.0Social

RequiresTypeWriter0.9.0-beta-177 (BTC build)GUI (TypeWriter extension)MySQL (TypeWriter extension)optionalNumericalStorage (TypeWriter extension)optionalRedis or Valkeyoptional

Built for the BornToCraft network. This extension is documented for reference and is not distributed.

Support

Overview

Guild lets players found a guild, invite others, manage ranks and share a bank. Everything works with /guild commands, and you can add a menu built in the web panel so players never need to type. A guild has one leader and any number of officers, members and recruits.

All guilds are stored in a single Guild Artifact and kept in memory for fast reads. With the MySQL bridge and Redis, every change is broadcast to the other servers of the network, and the guild bank is a separate row in the database, so two servers can never spend the same coins twice.

The menu is a GUI menu. You design its layout and screens, mark items as guild buttons, and the extension adds the member heads and invitation banners.

Features

• Guilds and roles — leader, officer, member and recruit, with create, invite, kick, promote, transfer and disband.
• Invitations — invite by name, join with /guild join, accept or decline from the menu with a search box.
• Guild menu — one entry carries every screen, with member heads, pagination and tabs.
• State-aware buttons — buttons that cannot apply to the player (create while in a guild, disband when not leader) are removed from the layout.
• Guild bank — deposit and withdraw using the player's NumericalStorage balance, with atomic database rows.
• Cross-server sync — creation, membership, roles, bank and removal reach every server of the group.
• Placeholders — name, role, leader, size, online count, bank, member names and a lookup by player.
• Admin commands — list guilds, inspect one, disband or kick on behalf of a leader.

Installation

1. Install the GUI extension, which draws the menu.
2. Install the NumericalStorage extension if players should use the bank. It supplies the balance that deposits and withdrawals use.
3. Optional, for several servers: install the MySQL extension, enable Redis (or Valkey), and set the same redis.group-id on every server. The guild bank also requires the MySQL extension, see Guild bank.
4. Put the Guild JAR in plugins/Typewriter/extensions/ and restart the server.
5. Create a Guild Artifact on a static page and publish it.

guild.use is given to everyone by default and guild.admin to operators.

Getting started

Build a guild menu that opens with /guild:

1. In the TypeWriter web panel, add a Guild Artifact on a static page. Keep artifactId as btc_guild_data.
2. Add a Guild Menu entry. /guild opens the first Guild Menu found.
3. Set inventoryTitle, inventoryRows and guiType, build the layout in layoutPool and set mainLayoutId. See the GUI guides.
4. Declare your screens in views (for example main, members, join). Put the ids of the screens that list members in memberListViewIds, and the id of the screen that lists pending invitations in joinListViewIds.
5. Add items and set buttonType to guild buttons: GUILD_MEMBERS and GUILD_BANK open screens, GUILD_LEAVE and GUILD_DISBAND run immediately, and PAGE_NAV pages through a list.
6. For buttons that need a typed name (create, invite, kick, promote, transfer), give the item an input dialog whose onInputCommands runs the command, for example guild create {input}.
7. Publish and run /guild.

The join screen

A screen with the id join is what GUILD_JOIN and GUILD_PENDING_INVITES open. Add join to views and to joinListViewIds, and give it an item with an input dialog running guild joinsearch {input} to let players filter the invitations by guild name.

How it works

Guilds are loaded into memory at start. After each change the guild is saved to the artifact in the background and broadcast to other servers, which replace their copy. Pending invitations are kept in memory only and are not saved.

Menus

The Guild Menu is a GUI menu with these guild-specific behaviours.

Content panel. On a screen listed in memberListViewIds, each member is a player head, leader first, with their role and online status. If you are the leader, left click promotes a member and right click kicks them. On a screen listed in joinListViewIds, each pending invitation is a banner: left click joins, right click declines. The panel is placed with contentX, contentY, contentColumns and contentRows.

Buttons. These buttonType values work out of the box:

buttonType	Click
GUILD_MEMBERS	Open the members screen (guild open members).
GUILD_BANK	Open the bank screen (guild open bank).
GUILD_ALLIANCES, GUILD_WARS	Open the allies or wars screens (see the note below).
GUILD_LEAVE	Leave the guild.
GUILD_DISBAND	Disband the guild (leader only).
GUILD_JOIN, GUILD_PENDING_INVITES	Switch to the join view of the same menu.
NAV_BACK, NAV_CLOSE	Go back, close the menu.
PAGE_NAV	Left click forward, right click back; the name shows the page counter. Hidden when one page is enough.

These values attach no action. They are meant for items you configure yourself (display text, or an input dialog that runs the matching command): GUILD_INFO, GUILD_MEMBER_MANAGE, GUILD_INVITE, GUILD_CREATE, GUILD_KICK, GUILD_PROMOTE, GUILD_DEMOTE, GUILD_TRANSFER, GUILD_ALLY_ADD, GUILD_ALLY_REMOVE, GUILD_WAR_DECLARE, GUILD_WAR_END, GUILD_BANK_DEPOSIT, GUILD_BANK_WITHDRAW, GUILD_ACCEPT_INVITE, GUILD_DECLINE_INVITE.

Hidden buttons. Items are removed from the layout when they do not apply: GUILD_CREATE and GUILD_JOIN once the player has a guild; GUILD_INVITE unless the player is leader or officer; GUILD_LEAVE, GUILD_MEMBERS, GUILD_BANK, GUILD_ALLIANCES and GUILD_WARS without a guild; GUILD_DISBAND unless the player is leader.

Slot commands. Items can run guild open [view], guild page next|prev|<number>, guild create <name>, guild invite <name>, guild join <guild>, guild declineinvite <guild>, guild joinsearch <text>, guild leave, guild disband, guild kick <name>, guild promote <name> and guild transfer <name>. They run as the player who clicked.

Alliances, wars and demotion

Guilds store an ally list, an enemy list and a level, and the placeholders expose them, but no command or button in this version changes them: the level stays at 1, and there is no demote command. The allies and wars screens only exist if you build them.

Language

Default menu texts (title "Guilde", head lore) are in French and guild admin replies are in French. Chat messages for players are in English. Override menu text in your layout.

Guild bank

The bank works on the guild's balance in the table btc_guild_bank (the name does not follow table-prefix), created automatically in the MySQL database. Each operation is atomic, so deposits and withdrawals from different servers cannot overdraw the bank.

• /guild deposit <amount> takes coins from the player's balance in NumericalStorage and adds them to the bank. Any member can deposit.
• /guild withdraw <amount> moves coins from the bank to the player. Only the leader and officers can withdraw.
• If the bank cannot be reached, a deposit is refunded and the player is told the storage is temporarily unavailable.

Without the MySQL extension enabled, or without NumericalStorage, the bank cannot be used.

Commands

All commands need guild.use. Aliases: /g, /guilde. The bare command opens the first Guild Menu and prints nothing when none exists.

Command	Description
/guild	Open the guild menu.
/guild create <name>	Create a guild. The name must be 3 to 16 letters or digits.
/guild invite <player>	Invite a player (leader or officer).
/guild join <guild>	Join a guild you were invited to.
/guild leave	Leave your guild. A leader with members must transfer or disband first.
/guild kick <player>	Kick a member (leader, or officer for non-officers).
/guild promote <player>	Recruit to member, member to officer (leader only).
/guild transfer <player>	Hand over leadership. The former leader becomes officer.
/guild deposit <amount>	Put coins in the guild bank.
/guild withdraw <amount>	Take coins from the bank (leader or officer).
/guild info	Print your guild's leader, member count, level and bank.
/guild disband	Disband your guild (leader only).
/guild admin list	List all guilds (requires guild.admin).
/guild admin info <guild>	Show one guild.
/guild admin disband <guild>	Disband a guild. Its leader must be online.
/guild admin kick <guild> <player>	Kick a member. The guild's leader must be online.

Permissions

Permission	Default	Grants
guild.use	Everyone	Every /guild command. Menu clicks run the same actions without checking it.
guild.admin	Operators	The /guild admin commands.

Placeholders

MiniPlaceholders tags for MiniMessage text, such as <guild_name>.

Placeholder	Returns
<guild_in_guild>	1 when the player is in a guild, else 0.
<guild_name>	Guild name, empty without a guild.
<guild_role>	LEADER, OFFICER, MEMBER or RECRUIT.
<guild_leader>	Name of the leader.
<guild_size>, <guild_members>	Number of members (both return the same value).
<guild_online_count>	Members online on this server.
<guild_level>	Guild level (always 1 at present), 0 without a guild.
<guild_bank>	Bank balance as stored on this server.
<guild_allies_count>, <guild_enemies_count>	Number of allies and enemies.
<guild_list>	Member names separated by a comma.
<guild_member_name:index>	Member name at that position, starting at 0.
<guild_of:name>	Guild of the named player, empty when none.

Entries

2 entries, generated from the extension source.

Actions1

• Guild MenuGuild Menu

Artifacts1

• Guild ArtifactArtifact for storing guild data

Troubleshooting

Guilds are gone after a restart. No Guild Artifact is published, so nothing is saved. Add it on a static page and publish.

/guild create answers "Guild name must be alphanumeric and between 3-16 characters." Names accept only letters and digits, no spaces, no underscore.

/guild prints nothing. There is no Guild Menu entry. Create and publish one. Subcommands such as /guild info work without it.

Deposits fail with "Insufficient funds". The deposit reads the player's NumericalStorage balance. Install NumericalStorage, and check that the player has enough coins there.

"Guild bank storage is temporarily unavailable." The bank table could not be reached. Enable the MySQL extension (mysql.enabled: true) and check the database connection in the logs. The deposit is refunded.

A guild created on one server is missing on the other. Each server needs the same redis.group-id, a unique redis.server-name, and mysql.enabled: true so the artifact is shared. Without a group-id nothing is broadcast.

Member heads or invitation banners do not appear. The active screen is not listed in memberListViewIds or joinListViewIds. When views is empty the menu uses view: set it to members or join.

Related extensions

• MySQL — Redis messaging and the database behind the guild bank.
• GUI — layouts, views and input dialogs used by the guild menu.
• NumericalStorage — the player balance used by the bank.
• Friend and Party — the other social systems.