Initial Setup

This guide provides detailed information about setting up AoEM Historian for your empire. If you haven't already, complete the Quick Start Guide first.

Prerequisites

Before starting:

• The bot must be added to your Discord server
• You must have Administrator permission on the Discord server

---

Understanding /jumpstart

The /jumpstart command is the recommended way to set up your Discord server. Here's what it does in detail:

What Jumpstart Creates

Resource	Name	Purpose
Category	AOEM Historian	Container for all bot channels
Channel	#activities	Bot posts activity announcements here (members can't post)
Channel	#mge	MGE event announcements
Channel	#bot-chat	General player discussion and bot commands
Channel	#empire-leaders	Private channel for leader coordination
Role	AOEM Historian Leader	Assigned to all empire leaders

Channel Permissions

Jumpstart configures these permissions automatically:

#activities channel:

• Members can view and read history
• Members cannot post messages (bot-only)
• Members can interact with buttons (claim credits)
• Members can post in threads (for proof submissions)

#empire-leaders channel:

• Only visible to users with the Leader role
• Leaders can view and post
• Hidden from regular members

Player Role Validation

After setting up channels, jumpstart checks if your player role has the correct permissions:

🔐 Player Role Status
✅ Player role @Members has correct permissions

Or if there are issues:

🔐 Player Role Status
⚠️ Player role not configured!
Players won't be able to use bot commands until you set a role.
Use `/empire role @rolename` to set which role can interact with the bot.

Permissions checked for the player role:

• #activities: View Channel, Read Message History
• #mge: View Channel, Read Message History
• #bot-chat: View Channel, Send Messages, Read Message History

Running Jumpstart Multiple Times

Jumpstart is idempotent - safe to run repeatedly:

• Already exists? Skipped with "ℹ️ Already exists" message
• Missing? Created with "✅ Created" message
• Permissions wrong? Reports what needs fixing

Use jumpstart as a health check anytime to verify your setup is correct.

---

Configuring Your Empire

Empire Details

Run /empire config to configure:

Field	Description	Example
Empire Number	Your in-game empire number	847
Empire Name	Display name for messages	Dragon Warriors
Starting Credits	Credits new players receive	25 (default)

Setting the Player Role

The player role controls who can use the bot:

/empire role @YourMemberRole

Why this matters:

• Only members with this role can register
• Only members with this role can claim activities
• Prevents random Discord visitors from using the bot
• You control who gets access by assigning the Discord role

tip

If you already have a role like @Members or @Alliance Members, use that. You don't need to create a new role.

Viewing Current Configuration

Check your empire's current settings:

/empire status

Shows:

• Empire number and name
• Player and leader counts
• Total credits in the system
• Configured roles (Leader Role, Player Role)
• Configured channels

/empire config

Shows configuration details including:

• Empire number
• Starting credits
• Leader and Player roles
• Activity and MGE channels

---

Manual Setup (Alternative)

If you prefer to create channels manually or have an existing structure:

Step 1: Set Activity Channel

/empire activity-channel-set #your-activities-channel

This is where /activate posts activities for players to claim.

Step 2: Set MGE Channel

/empire mge-channel-set #your-mge-channel

Where MGE announcements are posted.

Step 3: Configure Channel Permissions

For the activities channel, set these permissions manually:

• @everyone: Deny "Send Messages"
• @everyone: Allow "View Channel", "Read Message History"
• Bot role: Allow "Send Messages", "View Channel"

---

Adding Leaders

By default, only the server owner is a leader. Add your R4s and officers:

/leader add @Username

This:

1. Adds them to the EmpireLeader database table
2. Assigns the AOEM Historian Leader Discord role
3. Grants access to #empire-leaders channel
4. Enables all leader commands

See Managing Leaders for more details.

---

Configuring Activities (Optional)

The bot includes default activity configurations. To customize credit values:

/activity config <activity>

This opens a modal where you can set credits, proof requirements, and anchor Sunday.

See Configuring Activities for details.

---

Post-Setup Checklist

Use this checklist to verify your setup is complete:

• /jumpstart run successfully
• /empire config completed with correct empire info
• Player role set with /empire role @YourRole
• /jumpstart shows "✅ Player role has correct permissions"
• Additional leaders added with /leader add
• Activity configurations reviewed (optional)
• Announcement posted to empire
• Leaders understand their commands

---

Troubleshooting

"Permission Denied"

Only Discord server administrators can run /empire config. Check that:

• You have Administrator permission on the server
• You're running the command in the correct server

/jumpstart Shows Permission Warnings

The bot validates its own permissions before creating resources:

❌ Bot is missing permissions: ManageChannels, ManageRoles

Fix by:

1. Going to Server Settings → Roles
2. Finding the bot's role
3. Enabling the missing permissions
4. Running /jumpstart again

Player Role Shows Missing Permissions

If jumpstart reports:

⚠️ #Bot Chat: Role @Members missing: Send Messages

Fix by:

1. Going to the channel settings
2. Adding a permission override for the player role
3. Enabling the missing permission
4. Running /jumpstart again to verify

Bot Not Responding

• Verify the bot is in your server
• Check that the bot has permissions to read and send messages
• Try in a different channel
• Verify the bot is online (green status in member list)

---

Changing Configuration

Update Empire Details

Run /empire config again. New values replace old ones.

Change Player Role

Run /empire role @NewRole. The new role immediately takes effect.

Change Channels

Use the appropriate command:

• /empire activity-channel-set #new-channel
• /empire mge-channel-set #new-channel

Or clear a channel setting:

• /empire activity-channel-clear
• /empire mge-channel-clear

---

Next: Managing Leaders to add your officer team.