Authoring Items Badged Toggle

Authoring Items — Badged Toggle

A badged toggle is a toggle item that also carries a second, independent toggle drawn as an overlay badge on top of the base item. The base item behaves like its underlying type; the badge is an extra active/inactive flag with its own image.

Use cases: marking an item as "found but already used", flagging a duplicate, or attaching a small status indicator to an existing item without consuming a grid slot.

See Authoring Items for the general items file format and base fields. This page only covers fields specific to the toggle_badged type.

JSON schema

Parsed in EmoTracker.Data/Items/ToggleBadgedItem.cs. Matches the toggle_badged branch in items.json.

Field	Type	Required	Default	Description
type	"toggle_badged"	yes	—	Literal string.
base_item	string	yes	—	A code identifying the underlying item whose icon this badge sits on top of. Must resolve to an item already loaded earlier.
codes	string	yes	—	Comma-separated codes that the badge provides while active. These are independent from the base item's codes.
img	string	yes	—	Path (relative to pack root) to the badge overlay image (active state).
img_mods	string	no	—	Image filter spec applied to img.
disabled_img	string	no	derived	Path to the badge's inactive-state image. If omitted, EmoTracker derives one from img by applying the disabled filter.
disabled_img_mods	string	no	inherited	Image filter spec applied when deriving / loading the inactive badge image.
initial_active_state	boolean	no	false	Whether the badge starts active.

Plus the standard base fields from Authoring Items → Fields every item shares.

Mouse behavior

Button	Action
Left click	Passes through to the base item's left-click behavior
Right click	Toggles the badge on/off

See Item Types And Mouse Controls → Badged Toggle for the user-facing explanation.

The display icon is a composite: the base item's current icon with the badge image layered on top of it when the badge is active. When inactive, the base icon is shown with either the base's "inactive badge" appearance (if supplied) or no overlay.

How the composite icon is built

On load, the item captures the base item's Icon and PotentialIcon, then uses LayeredImageReference to stack the badge on top. Whenever either the base item's icon or the badge's state changes, the layered icon is recomputed, so the visual always reflects both underlying states.

Because the badge is applied after whatever image the base item is currently showing, a badge on a progressive item visually updates as the base item advances — you don't need to declare per-stage badges.

Examples

"Found and used" badge on the Bottle

// Assume a prior progressive bottle item advertising code "bottle".
{
  "name": "Bottle Used",
  "type": "toggle_badged",
  "base_item": "bottle",
  "img":      "images/badges/used_badge.png",
  "codes":    "bottle_used",
  "initial_active_state": false
}

• Left click still advances the underlying bottle progressive.
• Right click flips the "used" badge on or off without touching the bottle count.
• has("bottle_used") is true only when the badge is active.

Marking a duplicate item

{
  "name": "Duplicate Bow",
  "type": "toggle_badged",
  "base_item": "bow",
  "img":      "images/badges/dup_badge.png",
  "codes":    "bow_duplicate"
}

Tips and pitfalls

• base_item must exist first. Same rule as Composite Toggle: look up by code, which means the target must be declared earlier in load order. If it isn't, the badge can still be created but its base interactions become no-ops.
• Badge codes are separate from base codes. The badge's codes field declares codes that are active only when the badge is on and completely independent from whatever the underlying item provides.
• The base item is still clickable through the composite. Because left click passes through, using a badged toggle doesn't "replace" the underlying item — it adds a badge interaction on top.
• Badges work with any base item type, not just toggles. A badge on a progressive item advances the progression on left click; a badge on a consumable increments the counter on left click. Whatever the base does on left click is what the badged toggle does on left click.

See also

• Authoring Items — top-level items file format and base fields
• Authoring — Image Filters — syntax and built-in filters for img_mods / disabled_img_mods
• Authoring Items — Toggle — the plain toggle type that a badge often wraps
• Item Types And Mouse Controls → Badged Toggle — user-facing click behavior
• items.json schema — authoritative JSON schema