Zone System

The Zone System allows you to define spatial areas in your world that react to player presence. Zones can trigger scripts, display messages, and control gameplay mechanics through tags and functions.

🛠️ Visual Zone Builder Create zone configurations with an easy-to-use visual interface

Overview

Zones in Journey provide:

Spatial Definitions: Define areas using spheres, cylinders, and boxes
Entry/Exit Detection: Trigger scripts and messages when players enter or leave
Inside Tracking: Execute scripts while players remain in zones
Tag-Based Functions: Control gameplay mechanics with zone tags
Cobblemon Integration: Control Pokémon spawning within zones
Priority System: Handle overlapping zones with priority ordering

Real Zone Structure

{
  "name": "<gold>Zone Display Name",
  "uuid": "88707aeb-3758-4bb1-8bfc-82750577d4ea",
  "color": {
    "red": 23,
    "green": 188,
    "blue": 71
  },
  "entryMessage": {
    "title": "Welcome",
    "subtitle": "To the zone",
    "fade_in": 10,
    "stay": 70,
    "fade_out": 20,
    "type": "title"
  },
  "exitMessage": {
    "title": "Goodbye",
    "subtitle": "",
    "fade_in": 10,
    "stay": 70,
    "fade_out": 20,
    "type": "title"
  },
  "entry_script": "cobblemon:zone_enter_script",
  "exit_script": "cobblemon:zone_exit_script",
  "inside_script": "cobblemon:zone_inside_script",
  "priority": 0,
  "areas": []
}

Required Fields:

name - Display name (supports MiniMessage formatting)
uuid - Unique identifier (generated automatically)
areas - Array of area definitions (sphere, cylinder, box)
color - RGB color for debug visualization
entryMessage - ConfigTitle for entry
exitMessage - ConfigTitle for exit
entry_script - Resource location of Cobblemon script
exit_script - Resource location of Cobblemon script
inside_script - Resource location of Cobblemon script

Optional Fields:

priority - Higher priority zones trigger first (default: 0)

Zone Areas

Each zone can contain multiple areas. Three area types are supported:

Sphere Area

Circular 3D area centered on a point:

{
  "type": "sphere",
  "data": {
    "center": {
      "x": 100,
      "y": 70,
      "z": 200
    },
    "radius": 50.0,
    "dimension": "minecraft:overworld",
    "entry_message": {
      "title": "Area Entry",
      "subtitle": "",
      "fade_in": 10,
      "stay": 70,
      "fade_out": 20,
      "type": "title"
    },
    "exit_message": {
      "title": "",
      "subtitle": "",
      "fade_in": 0,
      "stay": 0,
      "fade_out": 0,
      "type": "title"
    },
    "tags": ["safe_zone", "no_pvp"],
    "functions": ["DENY_FALL_DAMAGE", "DENY_ALL_DAMAGE"]
  }
}

Cylinder Area

Vertical cylindrical area:

{
  "type": "cylinder",
  "data": {
    "center": {
      "x": 500,
      "y": 60,
      "z": 300
    },
    "radius": 30.0,
    "height": 40.0,
    "dimension": "minecraft:overworld",
    "entry_message": {
      "title": "",
      "subtitle": "",
      "fade_in": 0,
      "stay": 0,
      "fade_out": 0,
      "type": "title"
    },
    "exit_message": {
      "title": "",
      "subtitle": "",
      "fade_in": 0,
      "stay": 0,
      "fade_out": 0,
      "type": "title"
    },
    "tags": [],
    "functions": []
  }
}

Box Area

Rectangular box defined by two corners:

{
  "type": "box",
  "data": {
    "corner1": {
      "x": 0,
      "y": 50,
      "z": 0
    },
    "corner2": {
      "x": 200,
      "y": 100,
      "z": 500
    },
    "dimension": "minecraft:overworld",
    "entry_message": {
      "title": "",
      "subtitle": "",
      "fade_in": 0,
      "stay": 0,
      "fade_out": 0,
      "type": "title"
    },
    "exit_message": {
      "title": "",
      "subtitle": "",
      "fade_in": 0,
      "stay": 0,
      "fade_out": 0,
      "type": "title"
    },
    "tags": [],
    "functions": []
  }
}

Zone Functions

Zone areas support built-in functions that modify gameplay mechanics:

Available Functions

DENY_FALL_DAMAGE - Players take no fall damage in this area

{
  "functions": ["DENY_FALL_DAMAGE"]
}

DENY_ALL_DAMAGE - Players are completely invulnerable

{
  "functions": ["DENY_ALL_DAMAGE"]
}

DENY_HUNGER - Hunger does not deplete

{
  "functions": ["DENY_HUNGER"]
}

DENY_ATTACK - Players cannot attack entities

{
  "functions": ["DENY_ATTACK"]
}

NONE - No special function (default)

{
  "functions": []
}

How Functions Work

Functions are registered with the Stimuli event system when zones load. They intercept specific player events and modify behavior within the zone area.

Example - Safe Zone:

{
  "tags": ["safe_zone"],
  "functions": ["DENY_ALL_DAMAGE", "DENY_ATTACK", "DENY_HUNGER"]
}

Zone Tags

Tags are string identifiers attached to zone areas. They serve two purposes:

Automatic Function Mapping: Tags matching function names trigger those functions
Spawn Filtering: Control Cobblemon spawning with zone tags

Tag-to-Function Mapping

Tags are normalized and matched to zone function names (uppercase, underscores only):

{
  "tags": ["deny_fall_damage", "no_pvp"]
}

Normalized tags (uppercase, underscores only):

"deny_fall_damage" → DENY_FALL_DAMAGE function
"no_pvp" → No matching function (used for spawn filtering)

Tags for Spawning

Use custom tags to control Cobblemon spawning via ZoneSpawningAppendageCondition:

{
  "tags": ["city", "water_types", "rare_spawns"]
}

These tags can be referenced in Cobblemon spawn configurations.

Scripts

Zones execute Cobblemon scripts at three lifecycle points:

Entry Scripts

Triggered when a player enters the zone:

{
  "entry_script": "cobblemon:pallet_town_enter"
}

Available Context:

q.zone.name - Zone name
q.zone.uuid - Zone UUID
q.zone.areas - Area data
q.zone.color - Zone color (hex)
q.other_zones.contains(name_or_uuid) - Check other zones
All standard player MoLang functions

Exit Scripts

Triggered when a player leaves the zone:

{
  "exit_script": "cobblemon:pallet_town_exit"
}

Available Context:

q.zone.* - Same as entry
q.other_zones.* - Same as entry

Inside Scripts

Triggered every tick while player is in zone:

{
  "inside_script": "cobblemon:healing_zone_tick"
}

Warning: This runs every tick (20 times per second). Use sparingly.

Available Context:

q.zone.* - Zone data (no q.other_zones available)

Messages

ConfigTitle messages are shown when players enter/exit zones or areas.

Message Types

title - Shows as title and subtitle:

{
  "title": "<gold>Welcome",
  "subtitle": "<gray>To Pallet Town",
  "fade_in": 10,
  "stay": 70,
  "fade_out": 20,
  "type": "title"
}

Empty Message (No Display):

{
  "title": "",
  "subtitle": "",
  "fade_in": 0,
  "stay": 0,
  "fade_out": 0,
  "type": "title"
}

Zone vs Area Messages

Zone messages (entryMessage, exitMessage) - Shown when entering/exiting entire zone
Area messages (entry_message, exit_message) - Shown when entering/exiting specific area within zone

Both can be configured independently.

Priority System

When zones overlap, priority determines which zone’s scripts execute:

{
  "name": "City Zone",
  "priority": 10,
  "areas": []
}

{
  "name": "Gym Building",
  "priority": 20,
  "areas": []
}

Higher priority zones (20 > 10) trigger first. Default priority is 0.

Use Case: Place a high-priority small zone (gym) inside a low-priority large zone (city).

Integration with Task System

Use zones in task event filters:

ENTER_ZONE Event

{
  "event": "ENTER_ZONE",
  "filter": "q.zone.uuid == '88707aeb-3758-4bb1-8bfc-82750577d4ea'",
  "target": 1
}

Verified Query Paths:

q.zone.uuid - Zone UUID (string)

Player Functions in Filters

Check if player is in a zone from any event:

{
  "event": "POKEMON_CAUGHT",
  "filter": "q.player.is_in_zone('88707aeb-3758-4bb1-8bfc-82750577d4ea')",
  "target": 5
}

Integration with Cobblemon Spawning

Journey provides custom spawning conditions for Cobblemon:

ZoneSpawningAppendageCondition

Filter spawns by zone UUID or tags:

{
  "anticondition": {
    "condition": "zone",
    "zoneUUID": "88707aeb-3758-4bb1-8bfc-82750577d4ea",
    "zoneTags": ["city", "safe_zone"]
  }
}

How it Works:

zoneUUID - Must match zone UUID
zoneTags - Spawn position must be in area with at least one matching tag
If zoneTags is empty, only checks if position is in zone

Complete Example

Real zone configuration combining all features:

{
  "name": "<gold><bold>Pallet Town",
  "uuid": "c106b35a-1058-4aca-809c-b9588c14ba11",
  "color": {
    "red": 50,
    "green": 200,
    "blue": 50
  },
  "entryMessage": {
    "title": "<gold>Pallet Town",
    "subtitle": "<gray>Shades of Your Journey Await",
    "fade_in": 10,
    "stay": 70,
    "fade_out": 20,
    "type": "title"
  },
  "exitMessage": {
    "title": "",
    "subtitle": "",
    "fade_in": 0,
    "stay": 0,
    "fade_out": 0,
    "type": "title"
  },
  "entry_script": "journey:pallet_town_enter",
  "exit_script": "",
  "inside_script": "",
  "priority": 5,
  "areas": [
    {
      "type": "sphere",
      "data": {
        "center": {
          "x": 1000,
          "y": 70,
          "z": 1000
        },
        "radius": 150.0,
        "dimension": "minecraft:overworld",
        "entry_message": {
          "title": "",
          "subtitle": "",
          "fade_in": 0,
          "stay": 0,
          "fade_out": 0,
          "type": "title"
        },
        "exit_message": {
          "title": "",
          "subtitle": "",
          "fade_in": 0,
          "stay": 0,
          "fade_out": 0,
          "type": "title"
        },
        "tags": ["town", "safe_zone"],
        "functions": ["DENY_FALL_DAMAGE"]
      }
    },
    {
      "type": "box",
      "data": {
        "corner1": {
          "x": 995,
          "y": 69,
          "z": 995
        },
        "corner2": {
          "x": 1005,
          "y": 75,
          "z": 1005
        },
        "dimension": "minecraft:overworld",
        "entry_message": {
          "title": "<white>Pokémon Center",
          "subtitle": "",
          "fade_in": 5,
          "stay": 40,
          "fade_out": 10,
          "type": "title"
        },
        "exit_message": {
          "title": "",
          "subtitle": "",
          "fade_in": 0,
          "stay": 0,
          "fade_out": 0,
          "type": "title"
        },
        "tags": ["pokemon_center"],
        "functions": ["DENY_ALL_DAMAGE", "DENY_HUNGER"]
      }
    }
  ]
}

Debugging Zones

Players can visualize zone boundaries with a command:

# Enable zone boundary visualization
# Shows colored particle outlines for zones

Zone boundaries are drawn using the configured color RGB values.

Visualization:

Spheres: 3 circular particle rings (XY, XZ, YZ planes)
Cylinders: Top and bottom circles + vertical lines
Boxes: 12 edge lines forming rectangular prism

Limitations

What Zones DO:

✅ Define 3D spatial areas (sphere, cylinder, box)
✅ Detect player entry/exit/inside
✅ Execute Cobblemon scripts on lifecycle events
✅ Display title/subtitle messages
✅ Apply gameplay functions (damage denial, etc.)
✅ Support tags for spawn filtering
✅ Handle overlapping zones with priority
✅ Provide zone context to scripts (q.zone.*)

What Zones DON’T Do:

❌ No dynamic resizing/movement - Zones are static
❌ No teleportation system - Use scripts/commands
❌ No scheduled changes - No time-based activation
❌ No built-in spawn configuration - Use Cobblemon spawn configs with zone conditions
❌ No complex event system - Use entry/exit/inside scripts only. For complex logic, use callbacks.
❌ No action arrays - Single script per lifecycle point

Storage Location

Zone configurations are stored in:

config/journey/zones/<zone_name>.json

Zones are loaded on server start and can be reloaded without restart.

Best Practices

Zone Design

✅ Use appropriate shapes:

Spheres for circular areas (towns, arenas)
Cylinders for vertical structures (towers, caves)
Boxes for buildings and rectangular regions

✅ Keep scripts efficient:

Avoid heavy logic in inside_script (runs every tick)
Use entry/exit scripts for one-time actions

✅ Use priority for nested zones:

Higher priority = more specific area (gym building)
Lower priority = general area (city)

✅ Use tags consistently:

Naming convention: lowercase with underscores
Group related areas with common tags

Performance

✅ Minimize inside_script usage:

Runs 20 times per second per player
Use for lightweight checks only

✅ Use functions instead of scripts when possible:

Functions are more efficient than scripting
Combine multiple functions on one area

✅ Avoid excessive overlapping zones:

Priority system adds overhead
Combine areas into single zone when possible

The Zone System provides the spatial foundation for creating location-aware gameplay. Combined with tasks, scripts, and Cobblemon integration, zones enable dynamic regional content that responds to player presence and actions.