Global Tasks System

Global Tasks System

Global Tasks are server-wide or network-wide tasks where all players contribute to the same shared progress. Unlike personal tasks, global tasks track collective progress from every player on the server or across your entire network.

Overview

Global Tasks enable community-driven objectives where the entire playerbase works together toward common goals. Perfect for server events, seasonal challenges, and fostering collaborative gameplay.

Key Features

• Server-Wide Progress - All players contribute to the same task objectives
• Boss Bar Display - Progress shown via boss bars (not sidebar tracking)
• Cross-Server Sync - Progress syncs across all servers connected via NATS
• Manual Control - Admins manually start/stop global tasks with commands
• Separate Registry - Global tasks loaded from dedicated global_tasks folder

Differences from Personal Tasks

Feature	Personal Tasks	Global Tasks
Progress	Individual per player	Shared across all players
Display	Sidebar tracking	Boss bars
Starting	Automatic via sources	Manual via command
Tracking	/track command	Always visible when active
Registry	tasks folder	global_tasks folder
Cross-Server	No	Yes (via NATS)

---

Configuration

Journey Config

Edit config/journey/config.json:

{
  "global_tasks_enabled": true,
  "global_tasks_central_server": "survival",
  "is_global_tasks_central_server": false
}

Config Options:

• global_tasks_enabled - Enable/disable the global tasks system
• global_tasks_central_server - The server name that acts as the authoritative source
• is_global_tasks_central_server - Set to true on central server, false on others

Central Server Pattern

Designate one server as the “central server” to prevent conflicts:

On the central server (e.g., Survival):

{
  "global_tasks_enabled": true,
  "global_tasks_central_server": "survival",
  "is_global_tasks_central_server": true
}

On other servers:

{
  "global_tasks_enabled": true,
  "global_tasks_central_server": "survival",
  "is_global_tasks_central_server": false
}

Benefits:

• Prevents conflicts if admins start tasks on multiple servers simultaneously
• Ensures consistent task state across the network
• The central server’s task list is considered authoritative

---

Creating Global Tasks

🛠️ Visual Global Task Builder Create global task configurations with an easy-to-use visual interface

Global tasks are JSON files placed in config/journey/global_tasks/. They use the same schema as regular tasks with the "global": true flag.

Example: Server-Wide Pokemon Hunt

File: config/journey/global_tasks/server_wide_pokemon_hunt.json

{
  "name": "<gold>Server-Wide Pokemon Hunt",
  "description": [
    "<gray>Work together with all players on the server!",
    "<gray>Every Pokemon caught by anyone counts toward the goal."
  ],
  "global": true,
  "sequential": "linear",
  "repeat_type": "NONE",
  "repeat_interval": 0,
  "tasks": [
    {
      "id": "catch_pokemon",
      "name": "<yellow>Catch Pokemon Together",
      "description": "<gray>Everyone's catches count!",
      "event": "POKEMON_CAUGHT",
      "event_data": {},
      "filter": "1.0",
      "target": 100,
      "rewards": []
    },
    {
      "id": "win_battles",
      "name": "<yellow>Win Wild Pokemon Battles",
      "description": "<gray>Battle as a server!",
      "event": "BATTLE_VICTORY",
      "event_data": {},
      "filter": "q.battle.is_wild",
      "target": 50,
      "rewards": []
    }
  ],
  "rewards": [
    {
      "type": "currency",
      "data": {
        "currency": "impactor:pokedollars",
        "amount": 5000
      }
    }
  ],
  "icon": {
    "item_id": "minecraft:nether_star"
  }
}

Example: Daily Community Challenge

{
  "name": "<yellow>Community Daily Challenge",
  "description": [
    "<gray>A daily challenge for the entire server!",
    "<gray>Resets every day at midnight."
  ],
  "global": true,
  "repeat_type": "DAILY",
  "repeat_interval": 0,
  "sequential": "linear",
  "tasks": [
    {
      "id": "harvest_berries",
      "name": "<yellow>Harvest Berries Together",
      "description": "<gray>Gather berries across the server",
      "event": "BERRY_HARVESTED",
      "event_data": {},
      "filter": "1.0",
      "target": 200,
      "rewards": [
        {
          "type": "currency",
          "data": {
            "currency": "impactor:pokedollars",
            "amount": 100
          }
        }
      ]
    }
  ],
  "rewards": [
    {
      "type": "currency",
      "data": {
        "currency": "impactor:pokedollars",
        "amount": 1000
      }
    }
  ],
  "icon": {
    "item_id": "minecraft:clock"
  }
}

Important Configuration Notes

1. "global": true - Must be set for the task to be recognized as a global task
2. Events - Use the same event names as regular tasks (POKEMON_CAUGHT, BATTLE_VICTORY, etc.)
3. Filters - Use MoLang expressions or "1.0" for always-true filters
4. Text Formatting - Supports full MiniMessage formatting
5. Rewards - Use the data wrapper format for all reward types

---

Commands

/globaltask start <taskId>

Start a global task across the entire network.

Permission: journey.globaltask (level 2)

Example:

/globaltask start journey:server_wide_pokemon_hunt

Behavior:

• Starts the task on all servers connected via NATS
• Creates boss bars for all subtasks
• All online players see the boss bars immediately
• Players joining later automatically see active boss bars

/globaltask stop <taskId>

Stop a global task across the entire network.

Permission: journey.globaltask (level 2)

Example:

/globaltask stop journey:server_wide_pokemon_hunt

Behavior:

• Stops the task on all servers
• Removes all boss bars from all players
• Progress is cleared (does not persist after stopping)

/globaltask list

List all available global tasks with their status.

Permission: journey.globaltask (level 2)

Output:

===== Available Global Tasks =====
[ACTIVE] journey:server_wide_pokemon_hunt - Server-Wide Pokemon Hunt
[INACTIVE] journey:daily_community_challenge - Community Daily Challenge

/globaltask active

Show currently active global tasks with detailed progress.

Permission: journey.globaltask (level 2)

Output:

===== Active Global Tasks =====
● journey:server_wide_pokemon_hunt - Server-Wide Pokemon Hunt
  └─ Catch Pokemon Together: 45/100
  └─ Win Wild Pokemon Battles: 12/50
  └─ Hatch Eggs: 3/25

---

How Global Tasks Work

1. Admin starts a global task using /globaltask start <taskId>
2. Boss bars appear for all players showing each subtask’s progress
3. Any player action that matches a subtask’s event and filter contributes progress
4. Progress syncs in real-time across all servers via NATS
5. Boss bar colors change based on progress:
   • Blue: 0-50% complete
   • Yellow: 50-99% complete
   • Green: 100% complete
6. Rewards are distributed to all online players when subtasks/tasks complete
7. Task repeats automatically if configured with a repeat type

---

Boss Bar Display

Unlike personal tasks that use the sidebar, global tasks display progress via boss bars:

• One boss bar per subtask (up to 3 subtasks visible at once)
• MiniMessage formatting in boss bar titles
• Real-time progress updates as players contribute
• Automatic color changes based on completion percentage
• Persistent across deaths/dimension changes
• Visible to all players, even those who join after task starts

---

Cross-Server Sync

Global tasks require NATS messaging to work across multiple servers. See the Ceremony Integration guide for NATS setup.

How It Works

When you run /globaltask start journey:example_task on the Survival server:

1. Survival server broadcasts a GlobalTaskStartPacket via NATS
2. All connected servers receive the packet and start the task locally
3. Boss bars appear for all players on all servers
4. Any player action on any server contributes to the shared progress
5. Progress updates are broadcast via GlobalTaskProgressPacket
6. All servers update their boss bars in real-time

---

Best Practices

Task Design

✅ Use sparingly - Don’t have too many global tasks active at once (max 2-3 recommended)

✅ Set reasonable targets - Consider your total player count when setting targets

✅ Test on staging - Verify events and filters work before deploying to production

✅ Clear communication - Announce global tasks to players via Discord/in-game broadcasts

✅ Schedule appropriately - Use daily tasks for regular engagement, special tasks for events

Performance

If you have many global tasks active simultaneously:

1. Limit active global tasks - Stop tasks when not needed
2. Reduce subtask count - Fewer subtasks = fewer boss bars
3. Optimize NATS - Use a dedicated NATS server
4. Check filters - Complex MoLang filters in global tasks evaluate for every event

---

Troubleshooting

Global Tasks Not Syncing

Check:

1. NATS is running and accessible from all servers
2. All servers have matching cluster_name in Ceremony config
3. global_tasks_enabled: true in Journey config
4. Server logs show successful NATS connection
5. No firewall blocking port 4222

Test:

• Start a global task on Server A
• Check logs on Server B for “Started global task from network: …”
• If no message appears, NATS messages aren’t reaching Server B

Boss Bars Not Appearing

Check:

1. Task was started with /globaltask start, not just loaded
2. Player has boss bars enabled in their client settings
3. No other mods interfering with boss bars
4. Player joined after task started (rejoin to see boss bars)

---

Related Systems

• Party System - Form groups and share task progress
• Task System - Individual player tasks
• Ceremony Integration - NATS setup for cross-server sync