firefrost-operations-manual/docs/luckperms-structure.md

Firefrost Gaming: LuckPerms Structure

Version: 1.0
Created: February 8, 2026
Purpose: Permission group hierarchy for multi-server Minecraft network
Scope: 13+ servers (NC1 Charlotte, TX1 Dallas)
Implementation Status: Planning phase

---

Overview

LuckPerms manages all permission-based perks across the Firefrost Gaming network. This document defines the group hierarchy, inheritance structure, and specific permissions for each subscription tier.

---

Group Hierarchy

Inheritance Tree:

default (no subscription)
  └── awakened (Tier 1: $1 one-time)
      ├── fire_elemental (Tier 2 Fire: $5/mo)
      │   └── fire_knight (Tier 3 Fire: $10/mo)
      │       └── fire_master (Tier 4 Fire: $15/mo)
      │           └── fire_legend (Tier 5 Fire: $20/mo)
      │               └── founder (Tier 6: $499 lifetime)
      └── frost_elemental (Tier 2 Frost: $5/mo)
          └── frost_knight (Tier 3 Frost: $10/mo)
              └── frost_master (Tier 4 Frost: $15/mo)
                  └── frost_legend (Tier 5 Frost: $20/mo)
                      └── founder (Tier 6: $499 lifetime)

Note: Founder group inherits from BOTH fire_legend AND frost_legend, gaining all perks from both paths.

---

Permission Breakdown by Tier

Tier 0: Default (No Subscription)

Group Name: default
Subscription: None
Server Access: NONE (not whitelisted)

Permissions:

permissions:
  - essentials.list  # Can see who's online
  - essentials.motd  # Can see server MOTD

Purpose: Placeholder group for unsubscribed users. No actual server access.

---

Tier 1: The Awakened ($1 One-Time)

Group Name: awakened
Subscription: $1.00 one-time payment
Server Access: All 13+ servers (whitelisted)
Inherits From: default

Permissions:

permissions:
  # Home Management
  - ftbessentials.home.limit.1  # 1 home maximum
  - ftbessentials.sethome       # Can set home
  - ftbessentials.home          # Can teleport home
  
  # Chunk Claims
  - ftbchunks.max_claimed.0     # 0 claimed chunks
  - ftbchunks.max_force_loaded.0  # 0 force-loaded chunks
  
  # Random Teleport
  # NO /rtp access at this tier
  
  # Chat Formatting
  - luckperms.prefix.awakened

Chat Prefix:

prefix: "[The Awakened] "
color: "#FFFFFF"  # White

Purpose: Basic server access with minimal perks. Users explore and decide if they want to commit to a Path.

---

Tier 2: Elemental ($5/month) - FIRE PATH

Group Name: fire_elemental
Subscription: $5.00/month (Fire Path)
Server Access: All 13+ servers
Inherits From: awakened

Permissions:

permissions:
  # Home Management
  - ftbessentials.home.limit.5  # 5 homes (overrides awakened limit)
  
  # Chunk Claims
  - ftbchunks.max_claimed.25        # 25 claimed chunks
  - ftbchunks.max_force_loaded.0    # 0 force-loaded chunks
  
  # Random Teleport
  - ftbessentials.rtp               # /rtp access
  - ftbessentials.rtp.cooldown.3600 # 60 minute cooldown (3600 seconds)
  
  # Chat Formatting
  - luckperms.prefix.fire_elemental

Chat Prefix:

prefix: "[🔥 Fire Elemental] "
color: "#FF3D00"  # Deep Orange/Red (Fire Primary)

---

Tier 2: Elemental ($5/month) - FROST PATH

Group Name: frost_elemental
Subscription: $5.00/month (Frost Path)
Server Access: All 13+ servers
Inherits From: awakened

Permissions:

permissions:
  # Home Management
  - ftbessentials.home.limit.5  # 5 homes (overrides awakened limit)
  
  # Chunk Claims
  - ftbchunks.max_claimed.25        # 25 claimed chunks
  - ftbchunks.max_force_loaded.0    # 0 force-loaded chunks
  
  # Random Teleport
  - ftbessentials.rtp               # /rtp access
  - ftbessentials.rtp.cooldown.3600 # 60 minute cooldown (3600 seconds)
  
  # Chat Formatting
  - luckperms.prefix.frost_elemental

Chat Prefix:

prefix: "[❄️ Frost Elemental] "
color: "#00E5FF"  # Electric Cyan (Frost Primary)

Note: Fire and Frost Elemental have IDENTICAL mechanical permissions. Only prefix/color differ.

---

Tier 3: Knight ($10/month) - FIRE PATH

Group Name: fire_knight
Subscription: $10.00/month (Fire Path)
Inherits From: fire_elemental

Permissions:

permissions:
  # Home Management
  - ftbessentials.home.limit.10  # 10 homes (overrides elemental limit)
  
  # Chunk Claims
  - ftbchunks.max_claimed.49        # 49 claimed chunks
  - ftbchunks.max_force_loaded.4    # 4 force-loaded chunks
  
  # Random Teleport
  - ftbessentials.rtp.cooldown.1800 # 30 minute cooldown (1800 seconds)
  
  # Chat Formatting
  - luckperms.prefix.fire_knight

Chat Prefix:

prefix: "[🔥 Fire Knight] "
color: "#FF3D00"

---

Tier 3: Knight ($10/month) - FROST PATH

Group Name: frost_knight
Subscription: $10.00/month (Frost Path)
Inherits From: frost_elemental

Permissions:

permissions:
  # Home Management
  - ftbessentials.home.limit.10  # 10 homes
  
  # Chunk Claims
  - ftbchunks.max_claimed.49        # 49 claimed chunks
  - ftbchunks.max_force_loaded.4    # 4 force-loaded chunks
  
  # Random Teleport
  - ftbessentials.rtp.cooldown.1800 # 30 minute cooldown
  
  # Chat Formatting
  - luckperms.prefix.frost_knight

Chat Prefix:

prefix: "[❄️ Frost Knight] "
color: "#00E5FF"

---

Tier 4: Master ($15/month) - FIRE PATH

Group Name: fire_master
Subscription: $15.00/month (Fire Path)
Inherits From: fire_knight

Permissions:

permissions:
  # Home Management
  - ftbessentials.home.limit.20  # 20 homes
  
  # Chunk Claims
  - ftbchunks.max_claimed.100       # 100 claimed chunks
  - ftbchunks.max_force_loaded.9    # 9 force-loaded chunks
  
  # Random Teleport
  - ftbessentials.rtp.cooldown.900  # 15 minute cooldown (900 seconds)
  
  # Chat Formatting
  - luckperms.prefix.fire_master

Chat Prefix:

prefix: "[🔥 Fire Master] "
color: "#FF3D00"

---

Tier 4: Master ($15/month) - FROST PATH

Group Name: frost_master
Subscription: $15.00/month (Frost Path)
Inherits From: frost_knight

Permissions:

permissions:
  # Home Management
  - ftbessentials.home.limit.20  # 20 homes
  
  # Chunk Claims
  - ftbchunks.max_claimed.100       # 100 claimed chunks
  - ftbchunks.max_force_loaded.9    # 9 force-loaded chunks
  
  # Random Teleport
  - ftbessentials.rtp.cooldown.900  # 15 minute cooldown
  
  # Chat Formatting
  - luckperms.prefix.frost_master

Chat Prefix:

prefix: "[❄️ Frost Master] "
color: "#00E5FF"

---

Tier 5: Legend ($20/month) - FIRE PATH

Group Name: fire_legend
Subscription: $20.00/month (Fire Path)
Inherits From: fire_master

Permissions:

permissions:
  # Home Management
  - ftbessentials.home.limit.35  # 35 homes
  
  # Chunk Claims
  - ftbchunks.max_claimed.121       # 121 claimed chunks
  - ftbchunks.max_force_loaded.16   # 16 force-loaded chunks
  
  # Random Teleport
  - ftbessentials.rtp.cooldown.600  # 10 minute cooldown (600 seconds)
  
  # Chat Formatting
  - luckperms.prefix.fire_legend

Chat Prefix:

prefix: "[🔥 Fire Legend] "
color: "#FF3D00"

---

Tier 5: Legend ($20/month) - FROST PATH

Group Name: frost_legend
Subscription: $20.00/month (Frost Path)
Inherits From: frost_master

Permissions:

permissions:
  # Home Management
  - ftbessentials.home.limit.35  # 35 homes
  
  # Chunk Claims
  - ftbchunks.max_claimed.121       # 121 claimed chunks
  - ftbchunks.max_force_loaded.16   # 16 force-loaded chunks
  
  # Random Teleport
  - ftbessentials.rtp.cooldown.600  # 10 minute cooldown
  
  # Chat Formatting
  - luckperms.prefix.frost_legend

Chat Prefix:

prefix: "[❄️ Frost Legend] "
color: "#00E5FF"

---

Tier 6: Sovereign (Founder's) ($499 Lifetime)

Group Name: founder
Subscription: $499.00 lifetime
Inherits From: fire_legend AND frost_legend (both simultaneously)

Permissions:

permissions:
  # Home Management
  - ftbessentials.home.limit.50  # 50 homes
  
  # Chunk Claims
  - ftbchunks.max_claimed.225       # 225 claimed chunks
  - ftbchunks.max_force_loaded.81   # 81 force-loaded chunks
  
  # Random Teleport
  - ftbessentials.rtp               # /rtp access
  - ftbessentials.rtp.bypass        # NO COOLDOWN (bypass cooldown check)
  
  # Chat Formatting
  - luckperms.prefix.founder

Chat Prefix:

prefix: "[⚡ Founder] "
color: "#FFD600"  # Amber Gold

Special Note: Founder group inherits ALL permissions from BOTH fire_legend AND frost_legend, gaining complete access to both paths.

---

Discord Role → LuckPerms Sync

Mapping Table:

Discord Role	LuckPerms Group	Auto-Assign
🌅 The Awakened	awakened	✅
🔥 Fire Elemental	fire_elemental	✅
🔥 Fire Knight	fire_knight	✅
🔥 Fire Master	fire_master	✅
🔥 Fire Legend	fire_legend	✅
❄️ Frost Elemental	frost_elemental	✅
❄️ Frost Knight	frost_knight	✅
❄️ Frost Master	frost_master	✅
❄️ Frost Legend	frost_legend	✅
⚡ Founder	founder	✅

Implementation Method: DiscordSRV or custom Discord bot with LuckPerms API integration

Flow:

1. User subscribes via Paymenter/Ghost CMS
2. Stripe webhook triggers Discord role assignment
3. Discord bot detects role change
4. Bot calls LuckPerms API to assign corresponding group
5. User logs into any server → permissions instantly active

---

Multi-Server Implementation Strategy

Challenge:

13+ Minecraft servers need identical permission configurations

Recommended Solution: LuckPerms MySQL Backend

Architecture:

[MySQL Database] (Single source of truth)
       ↓
   ┌───┴───┬───────┬───────┐
   ↓       ↓       ↓       ↓
[Server1][Server2][Server3]...[Server13+]

Benefits:

• ✅ Single database for all servers
• ✅ Update once, applies everywhere instantly
• ✅ No config file syncing required
• ✅ Centralized management
• ✅ Real-time permission changes across network

Setup:

1. Install MySQL on Command Center (or dedicated database server)
2. Create firefrost_perms database
3. Configure each server's LuckPerms to use MySQL storage
4. All servers read/write from same database
5. Manage permissions from any server (or web interface)

Alternative: Config File Distribution (Not Recommended)

If MySQL not viable:

• Use Ansible/scripting to push LuckPerms configs via SSH
• Manual updates required
• Risk of desync between servers
• More maintenance overhead

Recommendation: Use MySQL backend for production. It's the industry standard for multi-server networks.

---

FTB Chunks Configuration

Per-Server Config File: config/ftbchunks/config.snbt

Key Settings:

{
  max_claimed_chunks: {
    default: 0,
    awakened: 0,
    fire_elemental: 25,
    frost_elemental: 25,
    fire_knight: 49,
    frost_knight: 49,
    fire_master: 100,
    frost_master: 100,
    fire_legend: 121,
    frost_legend: 121,
    founder: 225
  },
  
  max_force_loaded_chunks: {
    default: 0,
    awakened: 0,
    fire_elemental: 0,
    frost_elemental: 0,
    fire_knight: 4,
    frost_knight: 4,
    fire_master: 9,
    frost_master: 9,
    fire_legend: 16,
    frost_legend: 16,
    founder: 81
  }
}

Note: FTB Chunks reads LuckPerms groups directly. No separate permission nodes needed.

---

FTB Essentials Configuration

Per-Server Config File: config/ftbessentials.snbt

Key Settings:

{
  homes: {
    max_homes: {
      default: 0,
      awakened: 1,
      fire_elemental: 5,
      frost_elemental: 5,
      fire_knight: 10,
      frost_knight: 10,
      fire_master: 20,
      frost_master: 20,
      fire_legend: 35,
      frost_legend: 35,
      founder: 50
    }
  },
  
  rtp: {
    enabled: true,
    cooldown: {
      awakened: -1,  # Disabled (no /rtp access)
      fire_elemental: 3600,    # 60 minutes
      frost_elemental: 3600,   # 60 minutes
      fire_knight: 1800,       # 30 minutes
      frost_knight: 1800,      # 30 minutes
      fire_master: 900,        # 15 minutes
      frost_master: 900,       # 15 minutes
      fire_legend: 600,        # 10 minutes
      frost_legend: 600,       # 10 minutes
      founder: 0               # No cooldown
    }
  }
}

---

Chat Formatting (LuckPerms Prefixes)

Per-Group Prefix Configuration:

# awakened
meta:
  prefix: "&f[The Awakened] "  # White color

# fire_elemental
meta:
  prefix: "&#FF3D00[🔥 Fire Elemental] "  # Deep Orange/Red

# frost_elemental
meta:
  prefix: "&#00E5FF[❄️ Frost Elemental] "  # Electric Cyan

# fire_knight
meta:
  prefix: "&#FF3D00[🔥 Fire Knight] "

# frost_knight
meta:
  prefix: "&#00E5FF[❄️ Frost Knight] "

# fire_master
meta:
  prefix: "&#FF3D00[🔥 Fire Master] "

# frost_master
meta:
  prefix: "&#00E5FF[❄️ Frost Master] "

# fire_legend
meta:
  prefix: "&#FF3D00[🔥 Fire Legend] "

# frost_legend
meta:
  prefix: "&#00E5FF[❄️ Frost Legend] "

# founder
meta:
  prefix: "&#FFD600[⚡ Founder] "  # Amber Gold

Note: Hex color codes use &#RRGGBB format in LuckPerms.

---

Implementation Checklist

Phase 1: Database Setup

• Install MySQL on Command Center (or dedicated server)
• Create firefrost_perms database
• Create LuckPerms database user with appropriate permissions
• Document database credentials (store securely, not in Git)

Phase 2: LuckPerms Configuration

• Install LuckPerms on all 13+ servers
• Configure each server to use MySQL storage
• Verify all servers connect to same database
• Create all permission groups (awakened → founder)
• Set up group inheritance hierarchy
• Configure chat prefixes and colors

Phase 3: FTB Integration

• Configure FTB Chunks per-server (chunk limits)
• Configure FTB Essentials per-server (homes, /rtp)
• Test chunk claiming at each tier
• Test home limits at each tier
• Test /rtp cooldowns at each tier

Phase 4: Discord Integration

• Set up Discord bot with LuckPerms API access
• Configure Discord role → LuckPerms group mapping
• Test automatic group assignment on subscription
• Test group changes on tier upgrades
• Test Founder dual-inheritance (Fire + Frost)

Phase 5: Testing & Validation

• Create test accounts at each tier
• Verify permissions work correctly per tier
• Test across multiple servers (verify MySQL sync)
• Test tier upgrades (Elemental → Knight → Master)
• Test path switching (if implemented)
• Verify Founder gets all Fire + Frost perks

---

Troubleshooting

Common Issues:

Problem: Permissions not syncing across servers
Solution: Verify all servers connect to same MySQL database. Check config/luckperms/config.yml storage settings.

Problem: User has wrong permissions after subscription
Solution: Check Discord role assignment. Verify LuckPerms group matches Discord role. Use /lp user <name> info to debug.

Problem: /rtp cooldown not working correctly
Solution: FTB Essentials reads cooldown from config file, not LuckPerms permissions. Update ftbessentials.snbt directly.

Problem: Chunk claim limits not enforcing
Solution: FTB Chunks reads group names from LuckPerms. Verify group names match exactly (case-sensitive).

Problem: Chat prefixes not displaying colors
Solution: Verify hex color format (&#RRGGBB). Ensure chat plugin supports hex colors (MC 1.16+).

---

Security Considerations

MySQL Database:

• Use strong password for firefrost_perms user
• Restrict database access to Firefrost server IPs only
• Regular backups (daily recommended)
• Store credentials in .env file, NOT in Git

LuckPerms Web Editor:

• Enable only if needed
• Use strong authentication
• Restrict IP access if possible
• Disable after bulk edits complete

---

Maintenance

Regular Tasks:

Weekly:

• Review active groups and user counts
• Check for permission conflicts or issues

Monthly:

• Database backup verification
• Review group hierarchy for optimization
• Update documentation if structure changes

Per-Update:

• Test new Minecraft/mod versions for compatibility
• Verify FTB Chunks/Essentials still read LuckPerms correctly
• Update permission nodes if mods change

---

Future Enhancements

Potential Additions:

• Cosmetic perks - Particle effects, custom skins (when implemented)
• Quality-of-life commands - /workbench, /hat, etc. (when approved)
• WorldEdit permissions - For creative/technical builds (tier-specific limits)
• Flight permissions - Creative flight in claimed chunks (higher tiers)
• Additional modpack-specific perks - Per-server customization

Note: Only add perks that are actually implementable and tested. Don't promise features that don't exist yet.

---

Revision History

Version	Date	Author	Changes
1.0	2026-02-08	Michael	Initial LuckPerms structure documented. MySQL backend recommended. Complete group hierarchy defined.

---

END OF DOCUMENT