Skip to content

Authoring Locations Capture Badges

Jump to bottom
codemann8 edited this page Apr 24, 2026 · 2 revisions

Authoring Locations — Capture Badges

When a section with a captured item slot also defines capture_badge_offset, EmoTracker will automatically place the captured item's icon as a badge on the parent location's map pin whenever an item is captured into that slot. This is a way to show "what was at this spot" directly on the map — no custom scripting required.

This page covers capture badge authoring. For the base capture slot feature, see Authoring Locations — Captured Items. For the full placement fields reference (badge_alignment, badge_offset, badge_size), see Authoring Locations — Map Placement.

Enabling capture badges

Add capture_badge_offset to a section alongside capture_item: true:

{
  "name": "Bumper Ledge",
  "sections": [
    {
      "name": "Ledge",
      "item_count": 1,
      "capture_item": true,
      "capture_badge_offset": "0, 0"
    }
  ],
  "map_locations": [
    { "map": "overworld", "x": 600, "y": 280 }
  ]
}

The capture_badge_offset value is an "x, y" pixel pair that applies an additional offset on top of whatever the placement's badge_alignment and badge_offset dictate. "0, 0" means no extra nudge.

When the player captures an item into this section, the item's current icon appears as a badge on the location dot for every map placement of that location. When the capture is cleared, the badge disappears.

Positioning the badge

Badge position is controlled by two things working together:

1. capture_badge_offset on the section

The "x, y" offset on the section is a nudge that applies on top of the placement's alignment anchor. It is consistent across every map this location appears on.

2. badge_alignment and badge_offset on map_locations

Each entry in map_locations can independently control where all badges on that placement sit. A badge will be centered on one of nine anchor points of the map location square. The image below shows the nine anchor points and a badge aligned to the bottomright corner. Adding an additional badge_offset will nudge the badge in any direction relative to the standard anchor point:

badge-alignment
Field Type Default Description
badge_alignment enum bottomright Which of nine anchor points on the location square to attach the badge to. Options: topleft, top, topright, left, center, right, bottomleft, bottom, bottomright.
badge_offset string "x, y" "0, 0" Additional pixel offset applied after alignment. Positive x moves right, positive y moves down.
badge_size number 75% of size Size of the badge in map pixels. 
"map_locations": [
  {
    "map": "overworld",
    "x": 600,
    "y": 280,
    "badge_alignment": "topleft",
    "badge_offset": "-4, -4"
  }
]

The section's capture_badge_offset and the placement's badge_offset are additive — both offsets are applied together.

badge_alignment and badge_offset affect all badges on a placement, not just capture badges. If a location has both a hosted-item badge and a capture badge, they share the same placement-level alignment and offset settings.

Badge lifecycle

Event Badge behavior
Item captured into section Badge appears showing the captured item's icon
Section cleared (default) Badge disappears; capture slot is cleared
Capture slot manually reset Badge disappears
Section cleared with capture_persist: true Badge persists — see Persisting captures
clear_on_capture: true fires Section clears; badge remains — see Auto-clearing on capture

Persisting captures (capture_persist)

By default, when the section's chest count reaches zero (whether by user interaction or autotracker), both the capture slot and its badge are cleared, and the captured item advances one step (e.g. a toggle activates, a progressive advances).

Set capture_persist: true to opt out — the capture slot and its map badge will remain set even after the section is cleared:

{
  "name": "Ledge",
  "item_count": 1,
  "capture_item": true,
  "capture_badge_offset": "0, 0",
  "capture_persist": true
}

Use this when the map should continue showing what was at a location even after the player has collected it — for example, open-mode keys where the player wants a permanent record of what they retrieved.

capture_persist only suppresses the automatic clear-on-section-clear. Manually clearing the capture slot from the UI still removes the badge.

Auto-clearing on capture (clear_on_capture)

Set clear_on_capture: true to automatically set the section's chest count to zero the moment an item is captured:

{
  "name": "Ledge",
  "item_count": 1,
  "capture_item": true,
  "capture_badge_offset": "0, 0",
  "clear_on_capture": true
}

When clear_on_capture fires, the section clears but the capture and its badge are preserved. This is intentional — clear_on_capture means "capturing this item is equivalent to clearing the check", so clearing the chest count without wiping the capture record is the correct behavior.

This pairs naturally with capture_badge_offset: the player captures the item, the section auto-clears, and the badge appears on the map immediately.

Examples

Overworld location — show what was there after collection

{
  "name": "Bumper Ledge",
  "sections": [
    {
      "name": "Ledge",
      "item_count": 1,
      "capture_item": true,
      "capture_badge_offset": "0, 0",
      "clear_on_capture": true
    }
  ],
  "map_locations": [
    {
      "map": "overworld",
      "x": 600,
      "y": 280,
      "badge_alignment": "bottomright",
      "badge_size": 24
    }
  ]
}

The player captures the item (section auto-clears), the badge shows permanently on the map dot.

Dungeon boss and prize — multiple badges with explicit persist

{
  "name": "Eastern Palace",
  "sections": [
    { "name": "Dungeon", "item_count": 5, "access_rules": [ "lamp,bow" ] },
    {
      "name": "Boss",
      "item_count": 1,
      "capture_item": true,
      "capture_layout": "tracker_capture_bosses",
      "capture_badge_offset": "-40, 0",
      "capture_persist": true
    },
    {
      "name": "Prize",
      "item_count": 1,
      "capture_item": true,
      "capture_layout": "tracker_capture_prizes",
      "capture_badge_offset": "40, 0",
      "capture_persist": true,
      "hosted_item": "ep_prize"
    }
  ],
  "map_locations": [
    {
      "map": "lightworld",
      "x": 1850,
      "y": 380,
      "badge_alignment": "center"
    }
  ]
}
image

The boss and prize badge stays on the map dot even after the section is cleared, so the player can always see what they were for this dungeon. Notice the differing capture_badge_offset for each of the types of badges.

Tips and pitfalls

  • capture_badge_offset requires capture_item: true. Defining the offset without a capture slot does nothing.
  • The badge icon updates when the captured item's state changes. If the item is a progressive and the player advances it after capturing, the badge reflects the new stage's icon.
  • Multiple sections with capture_badge_offset on the same location each produce a separate badge entry. All share the same placement-level badge_alignment and badge_offset, so they will stack visually unless you use capture_badge_offset to nudge each one apart.
  • Lua AddBadge calls still work. If you were previously using location:AddBadge(...) from a script to implement this pattern manually, those calls continue to work. The native capture_badge_offset field is offered as a no-Lua alternative for the common case.

See also

Home

For Users

For Developers

The Basics
Authoring Items
Authoring Locations
Authoring Layouts
Authoring Lua Scripts
Hosting Packages

Clone this wiki locally