Quest Markers

Quest Markers are 3D floating displays that appear in the world to guide players to quest locations, objectives, and points of interest. Journey supports two marker systems:

Embedded Markers - Defined directly inside task configurations, automatically managed based on task state
Standalone Markers - Stored in config/journey/markers/, manually controlled via commands or scripts

Overview

Quest Markers provide:

Embedded in Tasks - Markers can be part of task/subtask definitions for automatic lifecycle management
Automatic Lifecycle - Appear/disappear automatically based on task state
3D Displays - Floating text, items, blocks, particles, or beacon beams
Animations - Bobbing, rotation, glowing effects
Visibility Control - Per-player visibility via MoLang conditions
Client-Side Rendering - Rendered by Journey Client

Two Systems

Embedded in tasks or standalone files

Auto-Managed

Show/hide automatically with task progress

6 Display Types

Text, items, blocks, particles, beacons

Per-Player

MoLang conditions for visibility control

How Markers Work

Markers are embedded in tasks using two fields:

Task Available Markers (`available_marker`)

Shows when a task is available but not started. Defined at the root of a task config.

Example: Quest giver with ”!” indicator

File: config/journey/tasks/intro_quest.json

{
  "id": "journey:intro_quest",
  "name": "Welcome to the Region",
  "description": "Speak with the Elder",
  "available_marker": {
    "position": {"x": 100.5, "y": 64.0, "z": 200.5},
    "dimension": "minecraft:overworld",
    "display_data": {
      "name": "§e§l! §rNew Quest",
      "description": "Speak with the Elder",
      "display_config": {
        "text": "§6§l!",
        "alignment": "CENTER",
        "scale": {"x": 3.0, "y": 3.0, "z": 3.0},
        "shadow": true,
        "see_through": true,
        "billboard": "CENTER"
      },
      "bobbing": true,
      "bobbing_speed": 1.0,
      "bobbing_height": 0.4
    },
    "visibility_condition": "1.0",
    "range": 64.0
  },
  "tasks": [...]
}

When visible: Task is available but player hasn’t accepted it yet.

Subtask Markers (`marker`)

Shows when a subtask is active. Defined inside a subtask object.

Example: Battle objective marker

File: config/journey/tasks/trainer_battle.json

{
  "id": "journey:trainer_battle",
  "name": "Defeat the Trainer",
  "tasks": [
    {
      "id": "find_trainer",
      "event": "ENTITY_INTERACT",
      "marker": {
        "position": {"x": 150.5, "y": 64.0, "z": 250.5},
        "dimension": "minecraft:overworld",
        "display_data": {
          "name": "§c§lTrainer Battle",
          "description": "Challenge the trainer!",
          "display_config": {
            "item": "minecraft:diamond_sword",
            "glowing": true,
            "scale": {"x": 2.0, "y": 2.0, "z": 2.0},
            "billboard": "CENTER"
          },
          "bobbing": true,
          "bobbing_speed": 1.5,
          "bobbing_height": 0.6
        },
        "visibility_condition": "1.0",
        "range": 96.0
      },
      "target": 1
    }
  ]
}

When visible: This subtask is active for the player.

Marker Structure

MarkerData Fields

Every marker object has exactly 5 fields:

Field	Type	Required	Default	Description
`position`	Vec3	Yes	-	World coordinates `{x, y, z}`
`dimension`	ResourceLocation	Yes	-	World/dimension identifier
`display_data`	MarkerDisplayData	Yes	-	Display configuration object
`visibility_condition`	String	No	`"1.0"`	MoLang expression for visibility
`range`	Double	No	`64.0`	Visible range in blocks

Example:

{
  "position": {"x": 100.5, "y": 64.0, "z": 200.5},
  "dimension": "minecraft:overworld",
  "display_data": {...},
  "visibility_condition": "1.0",
  "range": 64.0
}

Display Data

The display_data object configures how the marker appears visually.

MarkerDisplayData Fields

Field	Type	Required	Default	Description
`name`	String	Yes	-	Marker name (supports § color codes)
`description`	String	Yes	-	Marker description
`display_config`	DisplayConfig	Yes	-	Display type configuration
`rotation`	Vec2	No	`{x: 0, y: 0}`	Rotation as `{x: yaw, y: pitch}` in degrees
`bobbing`	Boolean	No	`false`	Enable bobbing animation
`bobbing_speed`	Double	No	`1.0`	Bobbing speed multiplier
`bobbing_height`	Double	No	`0.3`	Bobbing height in blocks

Rotation Clarification:

rotation.x = Yaw (horizontal/left-right rotation in degrees)
rotation.y = Pitch (vertical/up-down rotation in degrees)

Example:

{
  "name": "§e§lQuest Marker",
  "description": "Important location",
  "display_config": {...},
  "rotation": {"x": 45.0, "y": 0.0},
  "bobbing": true,
  "bobbing_speed": 1.0,
  "bobbing_height": 0.3
}

Display Types

Markers support 6 display types. Each has unique fields in display_config.

1. Text Display

Floating text with formatting.

Config Type: Object with text field

Fields:

Field	Type	Default	Description
`text`	String	-	Text to display (supports § color codes)
`alignment`	String	`"CENTER"`	Text alignment: `LEFT`, `CENTER`, `RIGHT`
`scale`	Vec3	`{1, 1, 1}`	Display scale
`shadow`	Boolean	`true`	Enable text shadow
`see_through`	Boolean	`false`	Visible through blocks
`billboard`	String	`"CENTER"`	Billboard mode (see below)
`line_spacing`	Double	`1.0`	Space between lines
`background_color`	Integer	`0`	Background color ARGB (0 = transparent)
`text_opacity`	Integer	`-1`	Text opacity (-1 = fully opaque)

Example:

{
  "display_config": {
    "text": "§6§l!",
    "alignment": "CENTER",
    "scale": {"x": 3.0, "y": 3.0, "z": 3.0},
    "shadow": true,
    "see_through": true,
    "billboard": "CENTER"
  }
}

Use Cases: Quest indicators, directional signs, instructions

2. Item Display

Floating item with optional glow effect.

Config Type: Object with item field

Fields:

Field	Type	Default	Description
`item`	ResourceLocation	-	Item ID to display
`scale`	Vec3	`{1, 1, 1}`	Display scale
`glowing`	Boolean	`false`	Enable glowing effect
`billboard`	String	`"CENTER"`	Billboard mode (see below)
`count`	Integer	`1`	Stack count (visual only)
`custom_model_data`	Integer	`null`	Custom model data

Example:

{
  "display_config": {
    "item": "minecraft:diamond_sword",
    "glowing": true,
    "scale": {"x": 2.0, "y": 2.0, "z": 2.0},
    "billboard": "CENTER"
  }
}

Use Cases: Quest objectives, collectibles, rewards, interactive points

3. Block Display

Floating block with optional glow effect.

Config Type: Object with block field

Fields:

Field	Type	Default	Description
`block`	ResourceLocation	-	Block ID to display
`scale`	Vec3	`{1, 1, 1}`	Display scale
`glowing`	Boolean	`false`	Enable glowing effect
`billboard`	String	`"CENTER"`	Billboard mode (see below)
`block_state`	Object	`{}`	Block state properties

Example:

{
  "display_config": {
    "block": "minecraft:lightning_rod",
    "glowing": true,
    "scale": {"x": 1.5, "y": 1.5, "z": 1.5},
    "billboard": "FIXED",
    "block_state": {}
  }
}

Use Cases: Building markers, area indicators, structures, landmarks

4. Particle Display (Vanilla)

Vanilla Minecraft particles spawned continuously.

Config Type: Object with ParticleVanillaConfig field

Fields:

Field	Type	Default	Description
`particle_type`	ResourceLocation	-	Vanilla particle ID (e.g., `minecraft:flame`)
`count`	Integer	`10`	Number of particles per spawn
`speed`	Double	`0.1`	Particle speed/spread
`spawn_rate`	Integer	`5`	Spawn interval in ticks

Example:

{
  "display_config": {
    "ParticleVanillaConfig": {
      "particle_type": "minecraft:end_rod",
      "count": 10,
      "speed": 0.1,
      "spawn_rate": 5
    }
  }
}

Common Particles:

minecraft:flame - Fire particles
minecraft:end_rod - White sparkles
minecraft:portal - Purple portal effect
minecraft:enchant - Enchantment glyphs
minecraft:heart - Heart particles

Use Cases: Magical locations, special effects, ambient markers

5. Particle Display (Snowstorm)

Cobblemon Snowstorm particle effects.

Config Type: Object with ParticleSnowstormConfig field

Fields:

Field	Type	Default	Description
`effect`	ResourceLocation	-	Snowstorm effect ID
`spawn_rate`	Integer	`5`	Spawn interval in ticks

Example:

{
  "display_config": {
    "ParticleSnowstormConfig": {
      "effect": "cobblemon:sparkle",
      "spawn_rate": 5
    }
  }
}

Use Cases: Cobblemon-themed quests, special effects

6. Beacon Display

Colored beacon beam extending upward.

Config Type: Object with BeaconConfig field

Fields:

Field	Type	Default	Description
`color`	Integer	-	Beam color as integer (RGB)
`height`	Integer	`64`	Beam height in blocks

Color Conversion: Convert hex color #RRGGBB to integer:

Red: (R << 16) | (G << 8) | B
Example: #FF0000 = 16711680

Example:

{
  "display_config": {
    "BeaconConfig": {
      "color": 16711680,
      "height": 64
    }
  }
}

Common Colors:

White: 16777215 (#FFFFFF)
Red: 16711680 (#FF0000)
Green: 65280 (#00FF00)
Blue: 255 (#0000FF)
Yellow: 16776960 (#FFFF00)
Purple: 8388736 (#800080)

Use Cases: Long-distance waypoints, area markers, event locations

Billboard Modes

The billboard field controls how displays rotate to face the player.

Modes:

Mode	Description
`FIXED`	No rotation - display stays in world orientation
`VERTICAL`	Rotates horizontally to face player (vertical axis locked)
`HORIZONTAL`	Rotates vertically to face player (horizontal axis locked)
`CENTER`	Full billboard - always faces player completely

Example:

{
  "display_config": {
    "text": "§6§l!",
    "billboard": "CENTER",
    "scale": {"x": 3.0, "y": 3.0, "z": 3.0}
  }
}

Recommendations:

Text/Items: Use CENTER for best readability
Blocks: Use FIXED to preserve block orientation
Directional Signs: Use VERTICAL for compass-like behavior

Animations

Bobbing Animation

Creates a floating up-and-down effect.

Fields:

{
  "bobbing": true,
  "bobbing_speed": 1.0,
  "bobbing_height": 0.3
}

Parameters:

bobbing_speed - Speed multiplier
- 0.5 = Slow, gentle floating
- 1.0 = Normal speed
- 2.0 = Fast bobbing
bobbing_height - Maximum height variation in blocks
- 0.2 = Subtle movement
- 0.5 = Noticeable movement
- 1.0 = Large movement

Rotation

Rotate the marker display in world space.

Format:

{
  "rotation": {"x": 45.0, "y": 0.0}
}

Parameters:

x = Yaw - Horizontal rotation in degrees (left/right)
y = Pitch - Vertical rotation in degrees (up/down)

Examples:

{x: 0, y: 0} - No rotation
{x: 90, y: 0} - 90° horizontal turn
{x: 45, y: 45} - Tilted and turned

Visibility Conditions

Control per-player visibility using MoLang expressions.

Always Visible

{
  "visibility_condition": "1.0"
}

Flag-Based

{
  "visibility_condition": "q.player.has_flag('quest_unlocked')"
}

Task-Based

{
  "visibility_condition": "q.player.has_completed_task('journey:previous_quest')"
}

Level-Based

{
  "visibility_condition": "q.player.levelable_level('trainer_rank') >= 10.0"
}

Combined Conditions

{
  "visibility_condition": "q.player.has_flag('chapter_2') && !q.player.has_completed_task('journey:final_quest')"
}

Complete Examples

Example 1: Quest Available Marker (Text)

Shows ”!” when quest is available.

File: config/journey/tasks/intro_quest.json

{
  "id": "journey:intro_quest",
  "name": "Welcome to the Region",
  "description": "Speak with the Elder to begin your journey",
  "available_marker": {
    "position": {"x": 100.5, "y": 64.0, "z": 200.5},
    "dimension": "minecraft:overworld",
    "display_data": {
      "name": "§e§l! §rNew Quest Available",
      "description": "Speak with the Elder",
      "display_config": {
        "text": "§6§l!",
        "alignment": "CENTER",
        "scale": {"x": 4.0, "y": 4.0, "z": 4.0},
        "shadow": true,
        "see_through": true,
        "billboard": "CENTER"
      },
      "rotation": {"x": 0.0, "y": 0.0},
      "bobbing": true,
      "bobbing_speed": 0.8,
      "bobbing_height": 0.4
    },
    "visibility_condition": "!q.player.has_completed_task('journey:intro_quest')",
    "range": 64.0
  },
  "tasks": [
    {
      "id": "talk_to_elder",
      "event": "ENTITY_INTERACT",
      "filter": "q.entity.uuid == 'your-villager-uuid-here'",
      "target": 1
    }
  ]
}

Example 2: Battle Objective Marker (Item)

Shows sword when battle subtask is active.

File: config/journey/tasks/trainer_battles.json

{
  "id": "journey:trainer_battles",
  "name": "Battle Challenge",
  "description": "Defeat the Gym Leader",
  "tasks": [
    {
      "id": "defeat_gym_leader",
      "event": "POKEMON_FAINT",
      "marker": {
        "position": {"x": 0.5, "y": 67.0, "z": 0.5},
        "dimension": "minecraft:overworld",
        "display_data": {
          "name": "§6§lBattle Arena",
          "description": "Gym Leader awaits!",
          "display_config": {
            "item": "minecraft:diamond_sword",
            "glowing": true,
            "scale": {"x": 2.5, "y": 2.5, "z": 2.5},
            "billboard": "CENTER"
          },
          "rotation": {"x": 0.0, "y": 0.0},
          "bobbing": true,
          "bobbing_speed": 1.2,
          "bobbing_height": 0.6
        },
        "visibility_condition": "1.0",
        "range": 128.0
      },
      "filter": "q.pokemon.species.identifier == 'cobblemon:charizard'",
      "target": 1
    }
  ]
}

Example 3: Landmark Marker (Block)

Shows lightning rod at ancient shrine location.

File: config/journey/tasks/discover_shrine.json

{
  "id": "journey:discover_shrine",
  "name": "Ancient Mystery",
  "description": "Find the Ancient Shrine",
  "tasks": [
    {
      "id": "reach_shrine",
      "event": "LOCATION_TRIGGER",
      "marker": {
        "position": {"x": 500.5, "y": 75.0, "z": -300.5},
        "dimension": "minecraft:overworld",
        "display_data": {
          "name": "§d§lAncient Shrine",
          "description": "A mysterious structure",
          "display_config": {
            "block": "minecraft:lightning_rod",
            "glowing": true,
            "scale": {"x": 3.0, "y": 3.0, "z": 3.0},
            "billboard": "FIXED",
            "block_state": {}
          },
          "rotation": {"x": 90.0, "y": 0.0},
          "bobbing": true,
          "bobbing_speed": 0.5,
          "bobbing_height": 0.3
        },
        "visibility_condition": "q.player.has_flag('ancient_map_discovered')",
        "range": 96.0
      },
      "target": 1
    }
  ]
}

Example 4: Particle Effect Marker (Vanilla)

Shows purple portal particles at magical location.

File: config/journey/tasks/magic_trial.json

{
  "id": "journey:magic_trial",
  "name": "The Magic Trial",
  "description": "Complete the magical challenge",
  "tasks": [
    {
      "id": "enter_portal",
      "event": "LOCATION_TRIGGER",
      "marker": {
        "position": {"x": 250.5, "y": 64.0, "z": -150.5},
        "dimension": "minecraft:overworld",
        "display_data": {
          "name": "§5§lMagical Portal",
          "description": "Step through to begin",
          "display_config": {
            "ParticleVanillaConfig": {
              "particle_type": "minecraft:portal",
              "count": 20,
              "speed": 0.2,
              "spawn_rate": 3
            }
          },
          "bobbing": false
        },
        "visibility_condition": "q.player.levelable_level('magic_level') >= 5.0",
        "range": 64.0
      },
      "target": 1
    }
  ]
}

Example 5: Beacon Marker

Shows red beacon beam at event location.

File: config/journey/tasks/festival_event.json

{
  "id": "journey:festival_event",
  "name": "Festival Time!",
  "description": "Join the festival celebration",
  "available_marker": {
    "position": {"x": 0.5, "y": 64.0, "z": 0.5},
    "dimension": "minecraft:overworld",
    "display_data": {
      "name": "§c§lFestival Location",
      "description": "The celebration awaits!",
      "display_config": {
        "BeaconConfig": {
          "color": 16711680,
          "height": 128
        }
      },
      "bobbing": false
    },
    "visibility_condition": "q.player.has_flag('festival_active')",
    "range": 256.0
  },
  "tasks": [
    {
      "id": "attend_festival",
      "event": "LOCATION_TRIGGER",
      "target": 1
    }
  ]
}

Best Practices

Marker Placement

✅ Eye Level - Place at Y=64-66 for best visibility

✅ Clear Space - Avoid placing inside blocks

✅ Centered Coordinates - Use .5 for block centers (e.g., 100.5, 64.0, 200.5)

✅ Reasonable Range - 64-128 blocks for most markers, 256+ for beacons

Display Selection

✅ Text for Indicators - Use ! or ? for quest availability

✅ Items for Objectives - Show what item/tool is needed

✅ Blocks for Structures - Mark buildings or static locations

✅ Particles for Effects - Magical or special locations

✅ Beacons for Distance - Long-range waypoints and events

Animations

✅ Subtle Bobbing - 0.3-0.5 height for gentle movement

✅ Faster for Action - 1.5+ speed for combat/urgent markers

✅ Rotation for Interest - 45° or 90° angles work well

✅ Glowing for Importance - Enable for key objectives

Performance

✅ Reasonable Range - Don’t set range too high unnecessarily

✅ Visibility Conditions - Hide markers when not needed

✅ Limit Particle Count - Keep particle displays moderate

✅ Strategic Placement - Don’t show dozens of markers simultaneously

Troubleshooting

Marker Not Visible

Check:

Journey Client is installed on the player
Player is within range distance
visibility_condition evaluates to true for the player
Marker is in correct dimension (player must be in same dimension)
Task is in correct state (available for available_marker, active for subtask marker)

Debug:

{
  "visibility_condition": "1.0"
}

Set to always visible to test.

Marker Appears at Wrong Location

Check:

Coordinates use .5 for centering on blocks
Y coordinate is at appropriate height (not underground)
Dimension matches player’s location
Position is where you expect in-game

Debug: Stand at the location and use F3 to verify coordinates.

Animation Not Working

Check:

bobbing is set to true
bobbing_height is greater than 0
bobbing_speed is greater than 0
Journey Client is up to date
Display type supports animations (text, item, block - not particles/beacons)

Marker Shows at Wrong Time

Check:

available_marker only shows when task is available (not started)
Subtask marker only shows when that specific subtask is active
Task state is what you expect (/journey task status command)
Visibility condition is correct for the intended behavior

Particle/Beacon Markers Not Spawning

Check:

spawn_rate is reasonable (5-20 ticks)
Particle type exists (vanilla) or effect exists (snowstorm)
Player is within render distance
Client has particle settings enabled

Task System - Define tasks with embedded markers and subtask objectives
Journey Client - Required for marker rendering
MoLang - Write visibility conditions
Zone System - Define quest areas with boundaries (separate from markers)

Quest Markers

Quest Markers

Overview

How Markers Work

Task Available Markers (available_marker)

Subtask Markers (marker)

Marker Structure

MarkerData Fields

Display Data

MarkerDisplayData Fields

Display Types

1. Text Display

2. Item Display

3. Block Display

4. Particle Display (Vanilla)

5. Particle Display (Snowstorm)

6. Beacon Display

Billboard Modes

Animations

Bobbing Animation

Rotation

Visibility Conditions

Always Visible

Flag-Based

Task-Based

Level-Based

Combined Conditions

Complete Examples

Example 1: Quest Available Marker (Text)

Example 2: Battle Objective Marker (Item)

Example 3: Landmark Marker (Block)

Example 4: Particle Effect Marker (Vanilla)

Example 5: Beacon Marker

Best Practices

Marker Placement

Display Selection

Animations

Performance

Troubleshooting

Marker Not Visible

Marker Appears at Wrong Location

Animation Not Working

Marker Shows at Wrong Time

Particle/Beacon Markers Not Spawning

Related Systems

Task Available Markers (`available_marker`)

Subtask Markers (`marker`)