GroupeZ Docs
Configurations

Waypoints & Holograms

Guide players with waypoints and holograms in zQuests

zQuests can display holograms and waypoints to guide players to quest objectives. These features require a compatible plugin like zEssentials.

Requirements

To use waypoints and holograms, you need:

  • zEssentials or another compatible hologram/waypoint provider

Global Configuration

Both features can be defined globally in dedicated files and referenced by quests.

Holograms

Create plugins/zQuests/holograms.yml:

holograms:
  - name: MINING_AREA
    location: "world,100,65,200"
    texts:
      - "&6&lMining Quest"
      - "&7Break ores in this area"
      - "&aFollow the beacon!"
    scale: 1.5
    billboard: VERTICAL

  - name: NPC_QUEST
    locations:
      - "world,50,70,100"
      - "world,-50,70,-100"
    text: "&e&lTalk to the villager"
    scale: 1.2

Hologram Options

OptionDescriptionDefault
nameUnique identifier (required)-
locationSingle location world,x,y,z-
locationsMultiple locations-
textSingle line text-
textsMultiple lines-
billboardRotation mode: CENTER, FIXED, HORIZONTAL, VERTICALCENTER
scaleSize multiplier (single value or x,y,z)1
translation-xX offset0
translation-yY offset0
translation-zZ offset0
brightness-blockBlock light level15
brightness-skySky light level15
shadow-radiusText shadow size0
shadow-strengthText shadow darkness1.0
visibility-distanceMax visible distance-1 (default)
text-backgroundBackground color (hex, name, transparent, default)-
text-alignmentText alignment: CENTER, LEFT, RIGHTCENTER
text-shadowEnable text shadowfalse
see-throughVisible through blocksfalse

Waypoints

Create plugins/zQuests/waypoints.yml:

waypoints:
  - name: MINING_AREA
    location: "world,100,65,200"
    texture: quest_marker
    color: gold

  - name: FARM_LOCATION
    location: "world,200,70,150"
    texture: farm_icon
    color: green

Waypoint Options

OptionDescriptionDefault
nameUnique identifier (required)-
locationTarget location world,x,y,z-
textureIcon texture name-
colorBeacon color (name or hex)white

Using in Quests

Reference Global Definitions

Reference globally defined holograms and waypoints by name:

quests:
  - type: BLOCK_BREAK
    name: "mining-quest"
    display-name: "Mining Quest"
    goal: 100
    actions:
      - material: STONE
    hologram: MINING_AREA
    waypoint: MINING_AREA

Inline Definitions

Define holograms and waypoints directly in the quest:

quests:
  - type: CUBOID
    name: "find-village"
    display-name: "Find the Village"
    goal: 1
    actions:
      - cuboid: "world,100,60,100,200,100,200"
    hologram:
      location: "world,150,80,150"
      texts:
        - "&6&lVillage Quest"
        - "&7Find the hidden village"
        - "&aLook for the beacon!"
      scale: 2
      billboard: VERTICAL
      see-through: true
    waypoint:
      location: "world,150,65,150"
      texture: village_marker
      color: "#FFD700"

Multiple Locations

Display holograms at multiple locations:

quests:
  - type: ENTITY_KILL
    name: "skeleton-hunt"
    display-name: "Skeleton Hunt"
    goal: 50
    actions:
      - entity: SKELETON
    hologram:
      locations:
        - "world,100,65,100"
        - "world,-100,65,100"
        - "world,100,65,-100"
        - "world,-100,65,-100"
      texts:
        - "&c&lDanger Zone"
        - "&7Skeletons spawn here"

Configuration in config.yml

Control hologram and waypoint updates:

# Update holograms when quest state changes
update-hologram: true

# Update waypoints when quest state changes
update-waypoint: true

Hologram Examples

Simple Quest Marker

hologram:
  location: "world,100,70,200"
  text: "&e&l! Quest Here"
  scale: 1.5

Detailed Quest Info

hologram:
  location: "world,100,72,200"
  texts:
    - "&6&lMining Master"
    - ""
    - "&7Break 500 stone blocks"
    - "&7in this area to complete"
    - "&7the quest!"
    - ""
    - "&a↓ Start here ↓"
  scale: 1.2
  billboard: CENTER
  text-alignment: CENTER

NPC Interaction Point

hologram:
  location: "world,50,73,100"
  texts:
    - "&e&l? Talk to Me"
    - "&7I have a quest for you!"
  scale: 1.0
  translation-y: 2.5  # Float above NPC
  billboard: CENTER

Resource Pack Integration

hologram:
  location: "world,100,70,200"
  text: "%img_quest_marker%"  # ItemsAdder/Oraxen image
  scale: 3
  text-background: transparent

Waypoint Examples

Simple Beacon

waypoint:
  location: "world,100,65,200"
  color: blue

Custom Icon

waypoint:
  location: "world,100,65,200"
  texture: quest_diamond
  color: "#00FFFF"

Refresh Command

If holograms or waypoints don't update properly:

/zquests refresh-hologram

This forces a refresh of all active holograms and waypoints.

Visibility

Holograms and waypoints are only visible when:

  1. The quest is active for the player
  2. The quest is not completed
  3. The player is within visibility-distance (if set)

Once a quest is completed, associated holograms and waypoints automatically disappear.

Best Practices

  1. Use meaningful names - Name global definitions clearly (e.g., MINING_QUEST_MARKER)
  2. Consistent heights - Place holograms at consistent heights above ground
  3. Don't overuse - Too many holograms can be distracting
  4. Test visibility - Check holograms from player perspective
  5. Consider performance - Many holograms can impact server performance

Troubleshooting

Holograms Not Showing

  1. Verify zEssentials is installed and enabled
  2. Check location coordinates are correct
  3. Ensure the quest is active for the player
  4. Try /zquests refresh-hologram

Waypoints Not Working

  1. Confirm waypoint provider is installed
  2. Verify location format is correct
  3. Check that the quest is started

Holograms at Wrong Position

  1. Use translation-y to adjust height
  2. Verify world name matches exactly
  3. Check for typos in coordinates

Next Steps

Inventories

Configure quest inventories using zMenu

config.yml

Main configuration file for zQuests

On this page

RequirementsGlobal ConfigurationHologramsHologram OptionsWaypointsWaypoint OptionsUsing in QuestsReference Global DefinitionsInline DefinitionsMultiple LocationsConfiguration in config.ymlHologram ExamplesSimple Quest MarkerDetailed Quest InfoNPC Interaction PointResource Pack IntegrationWaypoint ExamplesSimple BeaconCustom IconRefresh CommandVisibilityBest PracticesTroubleshootingHolograms Not ShowingWaypoints Not WorkingHolograms at Wrong PositionNext Steps
GroupeZ MCP

Documentation in your AI

MCP lets your AI search GroupeZ documentation and read current examples to help you configure your plugins.

Read-only · No documentation API key needed

1. Copy the server URL

Transport: HTTP (Streamable HTTP). Authentication: none. Your tool uses its own model and subscription limits.

  1. Open Plugins in ChatGPT on the web, then + → Add custom MCP server.
  2. Name it ‘GroupeZ Documentation’, paste the URL above and choose ‘No authentication’. Create and install the plugin.
  3. In a conversation, type @ and select the plugin before asking. If needed, enable search, get_page and list_pages in its settings.
Official setup guide

3. Ask a question

Use GroupeZ MCP to help me create a zMenu inventory. Search relevant pages, read the examples and cite your sources.
Other clients and troubleshooting

For clients using mcpServers, adapt this example to their format:

{
  "mcpServers": {
    "groupez-docs": {
      "url": ""
    }
  }
}

Available tools are search, get_page and list_pages. Refresh the connector’s tools after updates. If your AI cannot access them, check that the connector is enabled in the conversation and your account allows custom MCP servers. Opening the URL in a browser is not an MCP test.