Quest Markers

Quest markers are 3D floating displays that appear in the world to guide players toward objectives. A glowing ”!” over a quest giver, a beacon beam at a distant event, a floating sword showing where to fight — markers make your quests feel like a real adventure.

Two Ways to Use Markers

1. Embedded in Tasks (Automatic)

Markers defined inside task configs appear and disappear automatically based on task state:

available_marker on a task — Shows when the task is available but not started
marker on a subtask — Shows when that subtask is active

2. Standalone (Manual)

Markers stored in config/journey/markers/ are controlled manually via commands or scripts.

Marker Structure

Every marker has 5 fields:

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

Field	Type	Default	Description
`position`	Object	Required	World coordinates `{x, y, z}`
`dimension`	String	Required	Dimension ID (e.g., `"minecraft:overworld"`)
`display_data`	Object	Required	How the marker looks (see below)
`visibility_condition`	String	`"1.0"`	Molang expression controlling per-player visibility
`range`	Number	`64.0`	Maximum distance (in blocks) at which the marker is visible

Display Data

The display_data object controls the marker’s visual appearance:

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

Field	Type	Default	Description
`name`	String	Required	Marker name (supports color codes)
`description`	String	Required	Description text
`display_config`	Object	Required	Display type configuration
`rotation`	Object	`{x: 0, y: 0}`	Rotation in degrees (x=yaw, y=pitch)
`bobbing`	Boolean	`false`	Enable floating up/down animation
`bobbing_speed`	Number	`1.0`	Animation speed multiplier
`bobbing_height`	Number	`0.3`	How far up/down it bobs (in blocks)

Display Types

Text Display

Floating text — great for quest indicators like ”!” or ”?”:

{
  "display_config": {
    "text": "\u00a76\u00a7l!",
    "alignment": "CENTER",
    "scale": {"x": 3.0, "y": 3.0, "z": 3.0},
    "shadow": false,
    "see_through": true,
    "billboard": "CENTER"
  }
}

Field	Default	Description
`text`	Required	Text to display
`alignment`	`"CENTER"`	`LEFT`, `CENTER`, or `RIGHT`
`scale`	`{1,1,1}`	Size multiplier
`shadow`	`true`	Text shadow
`see_through`	`false`	Visible through blocks
`billboard`	`"CENTER"`	How it faces the player

Item Display

Floating item — show swords, pokeballs, quest items:

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

Block Display

Floating block:

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

Vanilla Particle Display

Continuously spawning Minecraft particles:

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

Common particles: minecraft:flame, minecraft:end_rod, minecraft:portal, minecraft:enchant, minecraft:heart

Snowstorm Particle Display

Cobblemon particle effects:

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

Beacon Display

Colored beacon beam — visible from far away:

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

Common colors: White 16777215, Red 16711680, Green 65280, Blue 255, Yellow 16776960, Purple 8388736

Billboard Modes

Controls how the display rotates to face the player:

Mode	Description
`FIXED`	No rotation — stays in world orientation
`VERTICAL`	Rotates horizontally to face player
`HORIZONTAL`	Rotates vertically to face player
`CENTER`	Always fully faces the player

Use CENTER for text and items, FIXED for blocks.

Visibility Conditions

Control who can see the marker using Molang:

"visibility_condition": "1.0"

Always visible.

"visibility_condition": "q.player.has_flag('map_unlocked')"

Only visible to players with the flag.

"visibility_condition": "q.player.has_completed_task('journey:intro') && !q.player.has_completed_task('journey:chapter_2')"

Only visible between two quests.

Complete Examples

Quest Giver ”!” Marker

Shows a floating ”!” when a quest is available:

{
  "available_marker": {
    "position": {"x": 100.5, "y": 66.0, "z": 200.5},
    "dimension": "minecraft:overworld",
    "display_data": {
      "name": "New Quest Available",
      "description": "Speak with the Elder",
      "display_config": {
        "text": "\u00a76\u00a7l!",
        "alignment": "CENTER",
        "scale": {"x": 4.0, "y": 4.0, "z": 4.0},
        "shadow": false,
        "see_through": true,
        "billboard": "CENTER"
      },
      "bobbing": true,
      "bobbing_speed": 0.8,
      "bobbing_height": 0.4
    },
    "visibility_condition": "!q.player.has_completed_task('journey:intro_quest')",
    "range": 64.0
  }
}

Battle Objective Marker

Shows a glowing sword when a battle subtask is active:

{
  "marker": {
    "position": {"x": 150.5, "y": 67.0, "z": 250.5},
    "dimension": "minecraft:overworld",
    "display_data": {
      "name": "Gym Leader Battle",
      "description": "Challenge the Gym Leader!",
      "display_config": {
        "item": "minecraft:diamond_sword",
        "glowing": true,
        "scale": {"x": 2.5, "y": 2.5, "z": 2.5},
        "billboard": "CENTER"
      },
      "bobbing": true,
      "bobbing_speed": 1.2,
      "bobbing_height": 0.6
    },
    "visibility_condition": "1.0",
    "range": 128.0
  }
}

Event Beacon

Visible from far away at an event location:

{
  "available_marker": {
    "position": {"x": 0.5, "y": 64.0, "z": 0.5},
    "dimension": "minecraft:overworld",
    "display_data": {
      "name": "Festival 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
  }
}

Tips

Text + CENTER billboard for quest indicators (always readable)
Items + glowing for objectives (visually distinct)
Beacons for long-distance waypoints (visible from 256+ blocks)
Bobbing makes markers feel alive — use it on most markers
Visibility conditions prevent clutter — only show markers when relevant
Use see_through: true on important text markers so they’re visible through terrain