Alliances

The Alliances module manages alliances in the Dark War Survival game: creation, deletion, membership with rank hierarchy (R1–R5), tags, Discord role integration, and optionally integration with the Reaction Roles module.

Enabling the Module

1. Dashboard → Your server → toggle Alliances
2. Click Edit to configure module options
3. Save changes

Configuration

Option	Type	Default	Description
max_alliances	number	10	Maximum number of alliances per server
max_members	number	50	Maximum number of members per alliance
auto_reaction_role	boolean	false	Automatic sync with Reaction Roles
reaction_role_index	number / null	null	Reaction roles panel index to sync with
management_roles	list	[]	Roles that can manage alliances (besides admins)
r5_roles	list	[]	Additional roles for R5 leaders
r4_roles	list	[]	Additional roles for R4 officers

Rank System

Rank	Name	Permissions
R5	Leader	Everything: create (when R5 in any alliance), invite, kick (all), promote, demote, transfer
R4	Officer	Invite, kick (only R1–R3)
R3	—	No management permissions
R2	—	No management permissions
R1	—	No management permissions (default rank for new members)

Tag System

Each alliance has a short tag (1–5 alphanumeric characters):

• User provides: KNS
• System stores: [KNS]
• Discord role: [KNS] Alliance Name

Tags must be unique within the server.

Dashboard — Configuration

The Alliances edit panel in the dashboard contains:

• List view — cards of all alliances with information
• Detail view — after clicking an alliance: member list, ranks, actions
• Configuration — max alliances, max members, management roles, auto-reaction-role

Commands

/alliance create

Creates a new alliance.

Parameter	Required	Description
name	✅	Alliance name (2–32 characters: letters, numbers, spaces, hyphens)
tag	✅	Short tag (1–5 alphanumeric characters)
color	❌	Role hex color (default #5865F2)

Requirements: Administrator, management_roles, or R5 in any alliance.

Flow:

1. Validates name and tag
2. Checks alliance limit
3. Checks for name and tag duplicates
4. Inserts record into DB (with placeholder role_id)
5. Creates Discord role [TAG] Name with the specified color
6. Updates record with role_id
7. Adds creator as R5
8. Assigns role to creator
9. Optional sync with Reaction Roles
10. Log + response

Rollback

If Discord role creation fails, the database record is automatically deleted (DB-first approach with rollback).

/alliance delete

Deletes an alliance (Administrator only).

Parameter	Required	Description
name	✅	Alliance name to delete

Deletes: DB record + alliance_members (CASCADE) + Discord role + cleanup reaction roles.

/alliance invite

Invites a user to your alliance (R4/R5).

Parameter	Required	Description
member	✅	User to invite

Adds with rank R1. User cannot be in another alliance.

/alliance kick

Kicks a user from your alliance (R4/R5).

Parameter	Required	Description
member	✅	User to kick

R4 can only kick R1–R3. R5 can kick everyone except themselves.

/alliance leave

Leaves your current alliance.

R5 cannot leave without a prior /alliance transfer.

/alliance promote

Promotes a member by 1 rank (R5 only, max to R4).

Parameter	Required	Description
member	✅	User to promote

/alliance demote

Demotes a member by 1 rank (R5 only, min R1).

Parameter	Required	Description
member	✅	User to demote

/alliance transfer

Transfers leadership to another alliance member (R5 only).

Parameter	Required	Description
member	✅	New leader

New leader → R5, old leader → R4. Executed in a single DB transaction.

/alliance info

Displays alliance information with member list grouped by ranks.

Parameter	Required	Description
name	❌	Alliance name (default: user's own alliance)

/alliance list

Lists all active alliances on the server with member count and leader.

Listened Events

Event	Action
on_member_remove	Removal from alliance + R5 auto-succession
on_member_update	Integration with Reaction Roles (adding/removing alliance role)

Auto-succession (on_member_remove)

When the leader (R5) leaves the server:

1. Removed from alliance_members
2. If other members remain → highest-ranked (R4 > R3 > R2 > R1, seniority by joined_at) is promoted to R5
3. If no members remain → alliance marked as is_active = FALSE

Reaction Roles Integration (on_member_update)

When auto_reaction_role = true and a user gains/loses an alliance role through Reaction Roles:

Role added:

• If in another alliance → role removed, log "rejected"
• If in the same alliance → idempotent, ignored
• If not in any alliance → added as R1

Role removed:

• Removed from alliance_members

Logging

Actions logged by Logs under the alliances category:

• ⚔️ Alliance Created
• 🗑️ Alliance Deleted
• ➕ Member Added / Invited
• ➖ Member Removed / Kicked
• ⬆️ Member Promoted
• ⬇️ Member Demoted
• 👑 Leadership Transferred
• 🚪 Member Left / Departed Guild
• 💤 Alliance Deactivated
• 🚫 Reaction Role Rejected (multi-alliance conflict)

Database

Table	Description
alliances	id, guild_id, name, tag, role_id, color, is_active, created_at
alliance_members	id, alliance_id, user_id, rank, joined_at

Tips

Best practices

• Set max_members appropriately for your server size
• Enable auto_reaction_role so users can join alliances themselves
• Tags should be short and recognizable (e.g., KNS, DWS, ARC)
• Regularly check if R5 leaders are active — inactive ones can block alliances

warning

Deleting an alliance is irreversible — the Discord role and all member records are permanently deleted.