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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```yaml
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:**
```snbt
{
  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:**
```snbt
{
  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:**
```yaml
# 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**