Dungeon Editor Guide

1. Scope and Core Rules

This guide is for using and maintaining the Dungeon Editor. It focuses on the authoring side: selecting active save slots, editing maps, choosing tiles, configuring actors, assigning abilities, managing inventory slots, and publishing a private save into the public project.

• Use actor everywhere. Do not introduce new NPC wording, UI labels, comments, or npc.json references.
• Use conditions.json for tunable game behavior rather than hiding rules inside one-off Editor or runtime branches.
• Keep public assets, private save slots, and publish behavior explicit.
• Use shared GE behavior when a fix applies to every GE-supported game.
• Preserve data fidelity: floats stay floats, ability sprite frames stay assigned, and active save slots must be overwriteable.

2. Editor Mental Model

The Editor is the authoring authority for Dungeon. It is not only a map painter. It coordinates active storage, data normalization, asset galleries, actor metadata, inventory slots, and public promotion.

Before editing, decide whether you are changing a profile, a placed instance, a tile asset, a map cell, or a runtime condition. Many confusing bugs come from changing the wrong layer.

3. Start, Login, and Save Slot

The Editor should always make the active save slot visible. Save-slot selection is part of the editing context, just like the active map and selected tool.

Save slot rules

• The Editor must include a save-slot selection drop-down.
• The selected slot determines which private save tree is loaded and saved.
• New save slots must be saveable and overwriteable.
• Saving should not accidentally write to public assets.
• Publishing is separate from saving.

/public/alpha/Dungeon/assets/
/<flavor>-private/users/<username>/Dungeon/saves/<save-slot>/assets/

4. Screen Anatomy

The exact layout may evolve, but the Editor should make these working areas obvious and persistent enough that an editor never loses the current context.

Any pop-up panel that captures mouse, keyboard, or gamepad focus should clearly release that focus when it closes.

5. Map Editing Workflow

Map editing should be treated as a small transaction: choose the active slot, load current state, make a targeted edit, validate the resulting actor/tile behavior, then save the selected slot.

1. Select the correct save slot.
2. Load the active map and confirm the status area shows the expected source.
3. Choose the intended tool: paint, select, place, inspect, or edit properties.
4. Make the change in the map canvas or in a property panel.
5. Check validation warnings before saving.
6. Save to the selected private slot.
7. Test in runtime using the same active save source before publishing.

Map-cell data versus actor data

A map cell describes where something is and what the tile/cell contributes. An actor profile describes reusable actor behavior. A placed actor instance describes one actual actor on the map. Keep those concepts separate in the UI and in saved data.

6. Tiles and Image Operations

Tile authoring combines literal CSV-backed data with visual preview behavior. CSV tiles from /assets/tiles/*.csv should display in a gallery grid as processed image previews. Each preview should show the filename prefix below it, and selecting the preview should load that tile into the editor.

Required tile operations

• Flip horizontally.
• Flip vertically.
• Roll horizontally with edge wrap.
• Roll vertically with edge wrap.
• Reassign the selected tile/image where supported.

CSV and PNG behavior

.csv files are comma-separated value files. GE-Ink should directly convert CSV to JSON unless plain or raw flags are present. CSV should convert to PNG only when the png flag is present.

CSV as data:
assets/tiles/STONE_01.csv

CSV as preview image:
assets/tiles/STONE_01.csv?png=1&frame=0&w=24&h=24

7. Actors, Groups, and Instances

The Editor must use actor terminology everywhere. Treat any remaining npc.json wording or labels as obsolete. New UI should say actor, actor group, actor profile, or actor instance.

Authoring concepts

Suggested command wording

• Create Actor Profile defines a reusable actor type/profile.
• Drop Selected Actor Profile places a copy on the map.
• Add Actor Instance adds one placed actor instance.
• Remove Actor Profile deletes the reusable profile and should make copy/deletion consequences clear.

8. Actor Properties

The Actor property UI should list and edit all available actor properties. Boolean values should use checkboxes where appropriate. Blocking should be a single checkbox, not both a numeric field and a checkbox.

Property validation

• Warn when required actor identity fields are blank.
• Warn when a Receiver references a missing Granter.
• Warn when a visible actor has no sprite and no intentional placeholder behavior.
• Warn when conflicting or duplicate boolean representations exist.
• Warn when ZIndex creates an obvious hitbox/rendering mismatch.

9. Granters and Receivers

Granters are Actor definitions that provide reusable traits. Receivers merge those traits into another Actor or Tile. This allows repeated behavior, sound, BGM, interaction flags, or tuning to live in one reusable definition.

Editor workflow

1. Create or select an actor profile intended to act as a Granter.
2. Set the Granter flag or equivalent profile role.
3. Add the inheritable traits: BGM, Trade, Purge, sound, interaction flags, or other supported properties.
4. Select the receiving Actor or Tile.
5. Set Receiver to reference the Granter.
6. Validate that runtime preview/evaluation shows merged traits before behavior checks.

Granter Actor:
Unique Name: BGM - Catacombs
Granter: 1
BGM: catacombs
Loop: 1
Crossfade: 1

Receiving Actor:
Unique Name: Hexdot - West Hall
Receiver: BGM - Catacombs

10. Abilities and Inventory Slots

Actors need a per-Actor inventory slot manager with up to 15 item/ability slots. Inventory slot assignment should use an abilities.csv-driven pop-up Abilities Gallery picker rather than free-typed item names.

Slot rules

• Maximum: 15 slots per actor.
• Ability/item selection comes from abilities.csv.
• Amounts are floats, not integers.
• Displayed counts should round up.
• Depletion must preserve fractional amounts.
• The same amount/depletion behavior must work for keys and locks.

stored amount: 0.25  → displayed count: 1
stored amount: 1.00  → displayed count: 1
stored amount: 1.10  → displayed count: 2

Starting loadout examples

Double-quoted CSQ/CSV entries may be used for actor loadouts. Preserve commas inside quoted inventory strings.

Poindexter: "Leather Vest:1,Darts:12,Dagger:2"
Dereck:     "Leather Vest:1,Guardian Blade:1"
Phillip:    "Leather Vest:1,Wooden Staff:1"
Guard:      "Emerald Guard Suit:1,Pike:1,Dagger:1"

11. Abilities CSV Editor

The Editor needs an abilities.csv editor because abilities are not only battle actions. They are also inventory items, equipment, keys, lock resources, shop goods, sprites, and depletion definitions.

Ability row responsibilities

Sprite assignment forms

Legacy Battle Stats token:
"sprite:frame1.csv,frame2.csv,frame3.csv,frame4.csv"

Normalized explicit columns:
Frame 1 = frame1.csv
Frame 2 = frame2.csv
Frame 3 = frame3.csv
Frame 4 = frame4.csv

The Editor should read both forms, but save a normalized representation that survives reloads and private save persistence.

12. Sprite and Ability Galleries

Galleries should be pop-up pickers that preserve focus and return a clear selection to the calling panel. They should not require direct text entry when the source is a known data table.

Shared Sprite Gallery

• The first option should be the Empty animation.
• Sprite previews should animate when multiple frames are present.
• Selection should return frame assignments to the calling actor/tile/ability field.
• Missing or unavailable animation in the Editor should display the Empty animation.

Abilities Gallery

• Driven by abilities.csv.
• Used by actor inventory slot assignment.
• Shows animated ability sprite before ability name.
• Shows the Empty animation when the ability has no Editor animation.
• Returns canonical ability name and selected amount/depletion metadata to the inventory slot manager.

13. Conditions-Driven Logic

The Editor should expose or preserve conditions.json as the game-logic source where practical. Runtime and Editor previews should consume the same normalized conditions so the Editor does not lie about gameplay.

Good candidates for conditions

• Door hover-adjacent animation and runtime door behavior.
• Actor auto-walk cadence, stall prevention, and movement gating.
• Battle Mode action timing and action-choice selection rules.
• Party Panel and Battle Mode input capture rules.
• Shop transfer, depletion, purge, Trade, and container behavior.
• Door, key, lock, ZIndex, hitbox, and interaction priorities.

When a behavior needs a magic number, it should usually become a named condition/tuning value rather than an unexplained literal in editor.js or Dungeon.js.

14. Shops, Chests, Trade, and Purge

The Editor should make container/shop behavior visible through actor flags and inventory slots. Chests and Body Bags have Purge behavior by default. Chests also have Trade behavior by default.

Essence/appraisal values should display with a space between the number and unit mnemonic, such as 12 Ess, not 12Ess.

15. Audio and BGM

BGM is actor behavior generally, not simply a Hexdot feature. Any actor can carry BGM properties, including looping and crossfade behavior.

Sound paths

Public sound asset:
/public/alpha/Dungeon/assets/sounds/<track>.mp3

Private save sound asset:
/<flavor>-private/users/<username>/Dungeon/saves/<save-slot>/assets/sounds/<track>.mp3

Tracks should be uniquely identified by the filename stem, such as catacombs for catacombs.mp3. The Editor should avoid storing full absolute paths when a stable track identifier is enough.

BGM editor fields

• Track identifier.
• Loop enabled.
• Crossfade enabled or duration, where supported.
• Actor/Granter source of inherited BGM behavior.

16. Input Capture and GE HUD

Dungeon is a GE-supported game, so editor-facing controls should cooperate with GE input conventions. Do not assume raw axes or raw face-button labels are identical across controller families.

Editor input rules

• Use GE-resolved aliases/config mappings rather than fixed raw gamepad axes.
• Party Panel and Battle Mode should consume mouse, keyboard, and gamepad inputs.
• Party Panel and Battle Mode should still allow inputs that activate GE HUD items.
• Pop-up galleries should capture selection input while open and release it cleanly when closed.
• HUD hitboxes need ZIndex-aware handling.

Face label convention

Raw A, B, X, and Y labels are Xbox-style by default, not Nintendo. Nintendo-style labels should only be selected when configuration or device identity indicates Nintendo/Switch/Joy-Con/8BitDo Nintendo-style layout or labels are in Nintendo order.

17. Save and Publish Checklist

Before saving

• The intended save slot is selected.
• The status area shows the expected active source.
• Actor terminology is clean: no new NPC labels or npc.json references.
• All ability/item amounts still preserve floats.
• Sprite and ability assignments survived a local reload or preview pass.
• No duplicate Blocking numeric/checkbox state was introduced.

Before publishing

• The user is authorized: admin or joy.
• The selected private save slot is the intended source.
• The runtime has been tested against the selected save data.
• Ability sprites, actor inventory, keys/locks, Trade/Purge behavior, doors, and ZIndex were checked.
• The publish action copies from the selected private slot to public assets.

18. Troubleshooting

The Editor shows different data than the files I inspected.

Check the selected private save slot. Dungeon may be loading server-side saved data instead of the original public files.

A new save slot cannot be overwritten.

Treat this as a persistence bug. New slots should become normal overwriteable save targets after creation.

An ability has the wrong or missing sprite.

Inspect abilities.csv normalization. Check both the legacy sprite: token in Battle Stats and explicit Frame 1-4 columns. In the Editor, missing ability animation should show Empty.

Item amounts lose fractional values.

Look for integer parsing in slot assignment, transfer, depletion, key, or lock paths. Amounts must remain floats and displayed counts should round up.

Doors or actors click/render in the wrong order.

Check ZIndex and hitbox priority together. Visual order and hit target order should not fight each other.

Battle Mode or Party Panel leaks input.

Check input capture rules. These panels should consume general mouse, keyboard, and gamepad input while still allowing GE HUD item activation.

Tile CSV previews behave like raw data or vice versa.

Check GE-Ink flags. CSV should become JSON by default unless plain or raw is present. CSV becomes PNG only when png is present.

19. Quick Reference

Actor terminologySave-slot authorityAbilities GalleryEmpty animationFloat amountsconditions.jsonZIndex hitboxesNo stubs