Task Items

Task Items are items with embedded task progress tracking. They behave as portable quest holders, updating their progress through the same Journey event system that processes player tasks.

Overview

Task Items allow you to:

Embed Tasks in Items: Any item can hold a task with subtasks
Track Progress: Progress updates automatically via Journey events
Visual Feedback: Item name and lore show completion percentage
Flexible Completion: Choose what happens when completed (remove, keep, transform)
Event Integration: Uses the same 28 Journey event types as player tasks

Common Use Cases:

Quest items that track kills, captures, or exploration
Achievement tokens that progress over time
Collectible items with embedded challenges
Physical quest logs

How Task Items Work

Architecture

Task Items use Minecraft’s Data Component system with Polymer for server-side synchronization:

TaskItemComponent stores task ID, progress, and completion behavior
TaskItemManager handles lifecycle, progress updates, visual display
JourneyEvents processes both player tasks and task items in one pipeline
Same Task System: Uses the same Task and Subtask classes as player tasks

Event Flow

1. Player performs action (e.g., catches Pokémon)
2. JourneyEvents.processEvent() triggered
3. Processes player tasks (normal behavior)
4. Processes task items in player's inventory
5. Updates TaskItemComponent data
6. Updates item visual display (name/lore)
7. Handles completion if task finished

Creating Task Items

Command Usage

# Give a task item to a player
/journey taskitem give <player> <task_id> <item> [completion_behavior]

# Examples
/journey taskitem give @p journey:catch_5_pokemon minecraft:paper
/journey taskitem give @p journey:gym_challenge minecraft:diamond KEEP_ITEM
/journey taskitem give @p journey:exploration cobblemon:poke_ball REMOVE_ITEM

Parameters:

<player> - Target player selector
<task_id> - Resource location of existing task (must be registered)
<item> - Base item to use (e.g., minecraft:paper, cobblemon:poke_ball)
[completion_behavior] - Optional behavior on completion (default: REMOVE_ITEM)

Completion Behaviors

REMOVE_ITEM (Default)

Item is removed from inventory when task completes.

/journey taskitem give @p journey:daily_quest minecraft:paper REMOVE_ITEM

Use Cases:

Consumable quest items
Daily/weekly challenges
One-time completion items

KEEP_ITEM

Item remains in inventory, marked as completed.

/journey taskitem give @p journey:achievement minecraft:diamond KEEP_ITEM

Use Cases:

Achievement trackers
Progress souvenirs
Collectibles

Visual Display:

Item name shows “[COMPLETED]”
Lore shows “100% Complete”
Item remains in inventory

TRANSFORM_ITEM

Item transforms to reward item (via task rewards).

/journey taskitem give @p journey:evolving_quest cobblemon:poke_ball TRANSFORM_ITEM

Requirements:

Task must have item rewards configured
First item reward becomes the transformed item
Original item is replaced

Example Task with Transform:

{
  "name": "Evolving Challenge",
  "tasks": [...],
  "rewards": [
    {
      "type": "command",
      "data": {
        "command": "give {player} minecraft:diamond 1"
      }
    }
  ]
}

Task Item Data Structure

data class TaskItemComponent(
    val taskId: String,                                    // "namespace:task_id"
    val subtaskProgress: MutableMap<String, Double>,      // subtask_id -> progress
    val isCompleted: Boolean,                             // task completion state
    val completionBehavior: CompletionBehavior           // what happens on completion
)

public class TaskItemComponent {
    private final String taskId;                              // "namespace:task_id"
    private final Map<String, Double> subtaskProgress;        // subtask_id -> progress
    private final boolean isCompleted;                        // task completion state
    private final CompletionBehavior completionBehavior;      // what happens on completion

    public TaskItemComponent(
        String taskId,
        Map<String, Double> subtaskProgress,
        boolean isCompleted,
        CompletionBehavior completionBehavior
    ) {
        this.taskId = taskId;
        this.subtaskProgress = subtaskProgress;
        this.isCompleted = isCompleted;
        this.completionBehavior = completionBehavior;
    }

    // Getters
    public String getTaskId() { return taskId; }
    public Map<String, Double> getSubtaskProgress() { return subtaskProgress; }
    public boolean isCompleted() { return isCompleted; }
    public CompletionBehavior getCompletionBehavior() { return completionBehavior; }
}

Progress Tracking

Task items support all three sequential types:

SEQUENTIAL: Only first incomplete subtask is active

{
  "sequential": "sequential",
  "tasks": [
    {"id": "step1", "target": 1},
    {"id": "step2", "target": 1},
    {"id": "step3", "target": 1}
  ]
}

LINEAR: All subtasks active simultaneously

{
  "sequential": "linear",
  "tasks": [
    {"id": "catch_fire", "target": 3},
    {"id": "catch_water", "target": 3},
    {"id": "catch_grass", "target": 3}
  ]
}

RANDOMIZED: Random subset of subtasks selected

{
  "sequential": "randomized",
  "subtask_count": 3,
  "tasks": [
    {"id": "option1", "target": 1},
    {"id": "option2", "target": 1},
    {"id": "option3", "target": 1},
    {"id": "option4", "target": 1},
    {"id": "option5", "target": 1}
  ]
}

Visual Display

Task items automatically update their display based on progress:

In-Progress Item

§6[Quest] Catch 5 Pokémon
§7Progress: §e2/5 §7(§e40%§7)
§7Type: §aPokémon Capture
§8Click to view details

Completed Item (KEEP_ITEM)

§a[COMPLETED] Catch 5 Pokémon
§7Progress: §a5/5 §7(§a100%§7)
§7Type: §aPokémon Capture
§8Objective Complete!

Display is Updated:

When progress changes
When subtask completes
When entire task completes
Automatically, no manual refresh needed

Examples

Example 1: Simple Capture Quest

Task Configuration: (journey/tasks/capture_5.json)

{
  "name": "<gold>Catch 5 Pokémon",
  "description": ["<gray>Capture any 5 Pokémon"],
  "sequential": "linear",
  "rewards": [],
  "tasks": [
    {
      "id": "capture_5",
      "name": "Capture Pokémon",
      "event": "POKEMON_CAUGHT",
      "filter": "1.0",
      "target": 5,
      "rewards": []
    }
  ]
}

Command:

/journey taskitem give @p journey:capture_5 minecraft:paper REMOVE_ITEM

Result: Paper with task that tracks Pokémon captures, removed when 5 caught.

Example 2: Battle Achievement Tracker

Task Configuration: (journey/tasks/battle_achievement.json)

{
  "name": "<red>Battle Master",
  "description": ["<gray>Win 100 battles"],
  "sequential": "linear",
  "rewards": [
    {
      "type": "currency",
      "data": {
        "currency": "impactor:pokedollars",
        "amount": 5000
      }
    }
  ],
  "tasks": [
    {
      "id": "win_battles",
      "name": "Win Battles",
      "event": "BATTLE_VICTORY",
      "filter": "1.0",
      "target": 100,
      "rewards": []
    }
  ]
}

Command:

/journey taskitem give @p journey:battle_achievement minecraft:diamond KEEP_ITEM

Result: Diamond that tracks battle victories, kept after completion as trophy.

Example 3: Multi-Step Quest Item

Task Configuration: (journey/tasks/gym_quest.json)

{
  "name": "<blue>Gym Challenge",
  "description": ["<gray>Complete the gym challenge"],
  "sequential": "sequential",
  "rewards": [
    {
      "type": "command",
      "data": {
        "command": "give {player} cobblemon:gym_badge 1"
      }
    }
  ],
  "tasks": [
    {
      "id": "defeat_trainers",
      "name": "Defeat 3 Trainers",
      "event": "BATTLE_VICTORY",
      "filter": "q.battle.is_wild == 0.0",
      "target": 3,
      "rewards": []
    },
    {
      "id": "defeat_leader",
      "name": "Defeat Gym Leader",
      "event": "BATTLE_VICTORY",
      "filter": "q.entity.uuid == 'gym-leader-uuid'",
      "target": 1,
      "rewards": []
    }
  ]
}

Command:

/journey taskitem give @p journey:gym_quest cobblemon:poke_ball TRANSFORM_ITEM

Result: Poké Ball that transforms into Gym Badge after completion.

Example 4: Zone Exploration

Task Configuration: (journey/tasks/explore_regions.json)

{
  "name": "<green>Explorer",
  "description": ["<gray>Visit all major regions"],
  "sequential": "linear",
  "rewards": [],
  "tasks": [
    {
      "id": "visit_kanto",
      "name": "Visit Kanto",
      "event": "ENTER_ZONE",
      "filter": "q.zone.uuid == 'kanto-uuid'",
      "target": 1,
      "rewards": []
    },
    {
      "id": "visit_johto",
      "name": "Visit Johto",
      "event": "ENTER_ZONE",
      "filter": "q.zone.uuid == 'johto-uuid'",
      "target": 1,
      "rewards": []
    },
    {
      "id": "visit_hoenn",
      "name": "Visit Hoenn",
      "event": "ENTER_ZONE",
      "filter": "q.zone.uuid == 'hoenn-uuid'",
      "target": 1,
      "rewards": []
    }
  ]
}

Command:

/journey taskitem give @p journey:explore_regions minecraft:compass KEEP_ITEM

Result: Compass that tracks region visits.

Technical Details

Inventory Scanning

TaskItemManager automatically scans player inventories:

On player join
On inventory change
Registers active task items
Unregisters when item removed

Event Processing

Task items process the same events as player tasks:

POKEMON_CAUGHT, POKEMON_EVOLVE, POKEMON_LEVEL_UP
BATTLE_VICTORY, BATTLE_FLED, MOVE_USED
ENTER_ZONE, EXIT_ZONE, ENTER_ZONE_AREA
ITEM_PICKUP, BLOCK_PLACED, ENTITY_INTERACT
All 28 Journey event types supported

Performance

Task items only process events for active subtasks
Same optimization as player task processing
Minimal overhead (uses existing event pipeline)
Thread-safe progress updates

Limitations

What Task Items DO:

✅ Track progress for registered tasks ✅ Update via Journey event system ✅ Support all sequential types ✅ Support all event types and filters ✅ Visual progress display ✅ Completion behaviors

What Task Items DON’T Do:

❌ Create custom items with special abilities ❌ Add custom NBT or item properties ❌ Modify item behavior beyond task tracking ❌ Create soulbound or persistent items ❌ Add custom enchantments or attributes

Note: Task Items use existing Tasks. You must create the task configuration first, then give it as an item.

Best Practices

1. Use Appropriate Base Items

# Quest papers
/journey taskitem give @p journey:quest minecraft:paper

# Achievement tokens
/journey taskitem give @p journey:achievement minecraft:diamond

# Physical quest objects
/journey taskitem give @p journey:special_quest cobblemon:poke_ball

2. Choose Right Completion Behavior

REMOVE_ITEM: Daily quests, consumable challenges
KEEP_ITEM: Achievements, collectibles, trophies
TRANSFORM_ITEM: Progressive items, reward unlocks

3. Design Task Items for Inventory Use

Keep subtask counts reasonable (3-5 subtasks)
Use clear, concise descriptions
Target values that complete in reasonable time
Test visual display fits in lore space

4. Match Task Type to Use Case

SEQUENTIAL: Story progression, ordered steps
LINEAR: Collection challenges, parallel goals
RANDOMIZED: Daily challenges, variety quests

Troubleshooting

Task Item Not Updating

Check:

Task exists in config/journey/tasks/
Task ID matches exactly (including namespace)
Event type matches subtask event
Filter evaluates to true for the event
Item is in player’s inventory (not storage)

Debug:

# Verify task is registered
/journey task list

# Check task structure
cat config/journey/tasks/your_task.json

# Test with simple filter first
"filter": "1.0"

Item Not Removed After Completion

Check:

Completion behavior is REMOVE_ITEM
Task is actually completed (all subtasks done)
No errors in server log
Item has TaskItemComponent data

Progress Not Showing in Lore

This is normal. Progress updates happen:

When subtask progress changes
When subtasks complete
When task completes
Not every tick/second

Force update: Drop and pick up item.

Integration with Task System

Task Items use the existing task system:

Creating Tasks for Task Items

Same format as player tasks:

{
  "name": "Display Name",
  "description": ["Description"],
  "sequential": "linear",
  "rewards": [],
  "tasks": [/* subtasks */]
}

Place in: config/journey/tasks/your_task.json

Shared Event Processing

Both player tasks and task items:

Use same Task and Subtask classes
Process through JourneyEvents
Evaluate same filters
Support same event types
Use same reward system

Rewards

Task item rewards execute when completed:

Currency rewards: Given to player
Command rewards: Execute with player context
Script rewards: Run with player as context
Timeline rewards: Launch for player

This system provides a powerful way to create physical quest objects while reusing Journey’s existing task infrastructure.