Commands

Complete reference for all AnnouncementGUI commands.

📋 Command Overview

AnnouncementGUI provides a single main command with multiple subcommands:

Command	Description	Permission
/announcegui	Open the main GUI	announcegui.admin
/announcegui export [filename]	Export announcements to JSON	announcegui.admin
/announcegui import <filename> [mode]	Import announcements from JSON	announcegui.admin

🎮 Main Command

/announcegui

Description: Opens the Announcement Manager GUI.

Usage:

/announcegui

Permission: announcegui.admin

Examples:

/announcegui

What it does:

• Opens the main menu GUI

• Allows you to create, edit, or delete announcements

• Provides access to all announcement management features

Notes:

• Must be executed by a player (not console)

• Player must have the announcegui.admin permission

---

📤 Export Command

/announcegui export [filename]

Description: Exports all announcements to a JSON file in the plugin folder.

Usage:

/announcegui export [filename]

Permission: announcegui.admin

Parameters:

• [filename] (optional): Name of the output file

  • Default: announcements.json

  • Extension .json is recommended but not required

1

Export with default filename

Usage:

/announcegui export

Creates: plugins/AnnouncementGUI/announcements.json

2

Export with custom filename

Usage:

/announcegui export backup_2026_01_08.json

Creates: plugins/AnnouncementGUI/backup_2026_01_08.json

3

Export for migration

Usage:

/announcegui export migration_old_server.json

What it does:

• Exports all announcements from the database

• Saves to a JSON file in the plugin folder

• Includes all announcement data: name, messages, intervals, targets, status

• Can be used for backups or transferring announcements

Output Example:

[
  {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "name": "Welcome Message",
    "lines": [
      "<green>Welcome to our server!",
      "<yellow>Type /help for commands"
    ],
    "intervalSeconds": 300,
    "targetServerId": "ALL",
    "enabled": true
  },
  {
    "id": "6ba7b810-9dad-11d1-80b4-00c04fd430c8",
    "name": "Vote Reminder",
    "lines": [
      "&6Vote for the server at &evote.example.com"
    ],
    "intervalSeconds": 600,
    "targetServerId": "survival",
    "enabled": true
  }
]

Use Cases:

• Backup: Regular backups before making changes

• Migration: Moving announcements to a new server

• Testing: Export production data for testing environments

• Version Control: Track announcement changes over time

---

📥 Import Command

/announcegui import <filename> [mode]

Description: Imports announcements from a JSON file in the plugin folder.

Usage:

/announcegui import <filename> [mode]

Permission: announcegui.admin

Parameters:

1. <filename> (required): Name of the JSON file to import

   • Must exist in the plugin folder

   • Include the .json extension

2. [mode] (optional): Import mode

   • merge (default): Adds announcements to existing ones

   • replace: Deletes all existing announcements before importing

1

Import and merge (default)

Usage:

/announcegui import announcements.json

Adds announcements from the file to existing ones.

2

Import and merge (explicit)

Usage:

/announcegui import backup.json merge

Same as above, but explicitly specifies merge mode.

3

Import and replace

Usage:

/announcegui import fresh_start.json replace

Warning: Deletes all existing announcements first!

4

Import from backup

Usage:

/announcegui import backup_2026_01_08.json

5

Restore from backup (replace)

Usage:

/announcegui import backup_2026_01_08.json replace

What it does:

• Reads announcements from a JSON file

• Adds them to the database (merge mode)

• OR replaces all existing announcements (replace mode)

• Validates JSON format before importing

• Restarts announcement tasks as needed

Import Modes Explained:

Mode	Behavior	Use Case
merge	Adds new announcements, keeps existing	Importing additional announcements
replace	Deletes all, then imports	Fresh start, restoring from backup

JSON File Format:

The JSON file must be an array of announcement objects:

[
  {
    "id": "unique-id-here",
    "name": "Announcement Name",
    "lines": [
      "Line 1 of the message",
      "Line 2 of the message"
    ],
    "intervalSeconds": 300,
    "targetServerId": "server-1",
    "enabled": true
  }
]

Required Fields:

• id: Unique identifier (UUID or string)

• name: Display name

• lines: Array of message lines

• intervalSeconds: Interval in seconds (positive number)

• targetServerId: Target server ID or "ALL"

• enabled: Boolean (true/false)

Use Cases:

• Restore: Restore from a previous backup

• Migration: Move announcements from another server

• Deployment: Deploy pre-configured announcements

• Testing: Load test data

Error Messages (import/export)

"File not found"

Cause: File doesn't exist Solution: Check filename and location

"No announcements found"

Cause: Empty JSON file Solution: Verify file content

"Failed to parse JSON"

Cause: Invalid JSON format Solution: Validate JSON syntax

"Import interrupted"

Cause: Server issue Solution: Check server logs

---

🎯 Command Usage Scenarios

Scenario 1: Regular Backup

Create weekly backups:

# Monday morning
/announcegui export backup_monday.json

# Keep weekly backups
/announcegui export backup_week_52.json

Scenario 2: Server Migration

Moving to a new server:

# On old server
/announcegui export old_server_announcements.json

# Copy file to new server's plugin folder

# On new server
/announcegui import old_server_announcements.json replace

Scenario 3: Testing Changes

Test changes safely:

# 1. Export current state
/announcegui export before_changes.json

# 2. Make changes via GUI

# 3. If something goes wrong, restore:
/announcegui import before_changes.json replace

Scenario 4: Multi-Server Deployment

Deploy same announcements to all servers:

# On main server
/announcegui export network_announcements.json

# Copy file to all other servers

# On each server
/announcegui import network_announcements.json replace

Scenario 5: Merging Announcements

Combine announcements from two servers:

# Server A already has announcements

# Import from Server B
/announcegui import server_b_announcements.json merge

---

💡 Tips and Best Practices

Backup Strategy

1

Regular Exports

Export before major changes.

2

Naming Convention

Use dates in filenames (e.g., backup_2026_01_08.json).

3

External Storage

Copy backup files outside the plugin folder.

4

Version Control

Commit backups to Git for tracking changes.

Import Best Practices

1

Verify JSON

Validate JSON format before importing.

2

Test First

Import with merge mode first to test.

3

Backup First

Always export current state before importing.

4

Check IDs

Ensure announcement IDs are unique when merging.

Common Pitfalls to Avoid

• ❌ Don't: Use replace mode without backing up first ✅ Do: Export current state before using replace mode

• ❌ Don't: Edit JSON files manually without validation ✅ Do: Use a JSON validator before importing

• ❌ Don't: Import files with duplicate IDs ✅ Do: Ensure IDs are unique when merging

---

🔍 Command Aliases

Currently, there are no aliases for /announcegui. You must use the full command name.

---

🛠️ Command Permissions

All commands require the same permission:

Permission Node: announcegui.admin

Grant Permission:

Using LuckPerms:

/lp user <username> permission set announcegui.admin true

Using PermissionsEx:

/pex user <username> add announcegui.admin

Using GroupManager:

/manuaddp <username> announcegui.admin

Note: See the Permissions Guide for more details.

---

📞 Command Help

In-Game Help

If you forget command syntax, the plugin will show usage hints:

/announcegui import
> Usage: /announcegui import <filename> [replace|merge]

/announcegui export
> (Opens GUI or exports with default filename)

Console Usage

Note: The /announcegui command cannot be used from the console as it requires a player to open the GUI.

However, import/export operations could potentially be adapted for console use in future versions.

---

🐛 Troubleshooting Commands

Export Issues

Problem: "Failed to export announcements" Solutions:

• Check plugin folder write permissions

• Verify disk space available

• Check server logs for detailed error

Import Issues

Problem: "File not found"

Solutions: - Verify file is in `plugins/AnnouncementGUI/` folder - Check exact filename (including extension) - File names are case-sensitive on Linux

Problem: "Failed to parse JSON"

Solutions: - Validate JSON at https://jsonlint.com/ - Check for syntax errors (missing commas, brackets) - Ensure UTF-8 encoding without BOM

Problem: "No announcements found"

Solutions: - Verify JSON file contains an array: `[...]` - Check if array is empty: `[]` - Ensure proper JSON structure

---

Related Documentation:

• Permissions Guide - Detailed permission information

• GUI Guide - Using the graphical interface

• Configuration Guide - Plugin configuration

• Troubleshooting - Common issues and solutions