Discoveries

Discoveries

Discoveries are a zone-based exploration tracker. Any zone can carry an optional discovery block — the first time a player crosses into that zone, they earn discovery points, optional vanilla XP, and a notification toast.

New in Beta 2   Embedded inline inside Zone JSON. No standalone discoveries/ directory.

First-entry only

Each zone can be discovered exactly once per player. Once a player has it, re-entering is a no-op.

Shared points pool

Discovery points feed the same lifetime counter that achievements use. Both progression systems share one currency.

Three display tiers

WORLD, SECRET, TERRITORIAL — purely cosmetic display colors in the Content Book.

---

Quick Start

Add a discovery field to any zone JSON:

File: config/journey/zones/battle_arena.json

{
  "name": "Battle Arena",
  "uuid": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "areas": [
    {
      "type": "sphere",
      "data": {
        "center": { "x": 0, "y": 65, "z": 0 },
        "radius": 10.0,
        "dimension": "minecraft:overworld"
      }
    }
  ],
  "discovery": {
    "name": "Battle Arena",
    "description": "A legendary battleground where trainers test their mettle against one another.",
    "tier": "WORLD",
    "points": 25,
    "xp_reward": 50
  }
}

That’s it. The first time any player crosses into the sphere, they get 25 discovery points, 50 vanilla XP, and a spyglass toast. Every subsequent player earns the same reward on their first entry.

---

Discovery Fields

Field	Type	Default	Description
name	String	""	Display name shown on toasts and the Content Book entry.
description	String or String[]	[]	Accepts a single string, an array of lines, or null.
tier	Enum	WORLD	One of WORLD, SECRET, TERRITORIAL. Drives display color only.
points	Int	10	Awarded to the player’s lifetime achievement points.
xp_reward	Int	0	Vanilla XP granted when greater than zero.

Tier Colors

Tier	Content Book color	Use for
WORLD	White (default)	Named public locations, landmarks, towns.
SECRET	Light purple	Hidden rooms, easter eggs, ruin interiors.
TERRITORIAL	Aqua	Faction-controlled zones, gym territories.

Tiers are cosmetic — they don’t gate visibility, apply point multipliers, or change sound. Pick the one that fits the lore.

---

Rewards

The reward surface is intentionally narrow:

• Discovery points — added to the player’s lifetime achievement points. Same pool as achievements.
• Vanilla XP — granted only when xp_reward > 0.
• Notification toast — a 5-second “Discovery Found” notification with the spyglass icon.

There’s no integration with the broader reward system — discoveries cannot grant items, commands, or scripts directly. If you need richer rewards, pair the discovery with a linked achievement or a zone-enter script.

---

Molang Queries

Query	Returns
query.has_discovery(zoneUuid)	1.0 if the zone has been discovered, else 0.0
query.discovery_count()	Number of zones the player has discovered

has_discovery takes the zone’s canonical UUID string, not its name.

---

Content Book Integration

• List page — the Content Book “Discoveries” tab. Header shows <gray>Discovered: <white>{journey:discovery_count}/{journey:total_discoveries}.
• Detail page — click an entry to open a 3-slot detail header. Undiscovered zones render <gray>??? and hide the description until the player earns the discovery.

Placeholders

Placeholder	Returns
{journey:discovery_count}	Zones the player has discovered
{journey:total_discoveries}	Count of zones with a discovery field

---

Commands

There is no dedicated /journey discovery subcommand. Discoveries are earned by walking into a zone. To reset state, use player data commands.

---

Default Shipped Discoveries

Only one shipped zone carries a discovery block:

• Battle Arena — WORLD tier, 25 points, 50 XP. Serves as the canonical example.

Any other zone you create can opt in by adding a discovery field.

---

Edge Cases

• Re-discovery is impossible. Once a zone is in a player’s discovered set, further entries are no-ops.
• Zone deletion orphans data. Deleting a zone leaves its record in player data forever. The UI filters orphans out, but the {journey:discovery_count} placeholder still counts them.
• Zone UUID changes reset credit. If you regenerate a zone’s UUID, the player loses credit for the old one and can re-earn the points by walking in. There is no name-based aliasing.
• Tier edits don’t refund. Changing points or xp_reward on a zone only affects players who haven’t yet discovered it.
• xp_reward: 0 is skipped entirely — no zero-XP call.
• Malformed tier values ("hidden", "rare", etc.) quietly downgrade to WORLD.

---

Tips

• Stack with progressive achievements. Pair a “zones discovered” progressive achievement with progress_source: "journey:zones_discovered" so players earn a tier and a discovery in one action.
• Keep descriptions short. The Content Book wraps text at around 35 characters. Two or three short lines read cleaner than one long string.
• Use SECRET for hidden map areas. The purple tier color signals “you found something hidden” even though it’s cosmetic.
• Don’t orphan old zones. When you rename or delete a zone, plan to migrate the UUID — otherwise players silently lose the credit.

---

Related

• Zones
• Achievements
• Content Book