feat: Enhance UI and control features for Phase 4, including status bar, mode switcher, and cursor feedback

plans/PHASE_4b_POLISH.md.bugs.md

@@ -0,0 +1,119 @@
+# Phase 4: Triggers & Event System — Implementation Plan
+
+## 1. Overview
+
+We have a good start with feature implementation, we want to polish some of the features and fix bugs before the next phase. We don't want too much tech debt
+
+## 2. UI
+
+1. There should be a status bar across the bottom of the screen that can hold information. As of now, that status bar should hold the current coordinates of the mouse at the right side of the bar. Similar to what is in the stickman editor.
+2. We need a better way to distinguish between EDIT and DIRECT modes. Let's change to the following
+
+- **Unified Mode Switcher (Segmented Control):** Move mode toggles into a single visual group [ ✏️ Edit | 🎬 Direct | ▶️ Play ] at the far left of the toolbar. Currently, "Direct" sits between object spawners (Area and Grid), making it look like a spawnable object rather than a mode toggle.
+- **Contextual Toolbars:** Swap toolbar options based on active mode to eliminate clutter:
+  - **Edit:** Show spawner buttons (Ground, Ramp, Crate, Stickman), transform tools, and Grid/Snap settings.
+  - **Direct:** Hide spawner buttons; show director controls like action queue triggers, sequence prompts, target selectors, and event rules (when planning and implementation is complete).
+  - **Play:** Collapse layout tools entirely, keeping only playback controls (Pause, Restart). This is already complete!
+
+3. **Viewport Color Frame / Canvas Background:** Use distinct visual cues directly on the canvas so you don't need to look at text:
+
+- **Edit Mode:** Keep the active construction grid visible.
+- **Direct Mode:** Add a subtle amber/gold viewport border frame (like a camera viewfinder overlay) or change gizmo colors to gold.
+- **Play Mode:** Fade out the grid background for a clean preview, accompanied by a subtle green glow around the Play control.
+
+4. **Status Badge (High-Contrast Pill):** Replace the plain text Mode: EDIT with a prominent badge in the top-left or top-right of the viewport:
+
+- ✏️ EDIT (Cyan / Blue Accent)
+- 🎬 DIRECTING (Amber / Gold Accent)
+- ▶️ SIMULATING (Green Accent)
+
+5. **Cursor Feedback:** Change the mouse cursor per mode (e.g., standard pointer/crosshair in Edit, a target ring or director wand in Direct, and a default game pointer in Play).
+
+## Control and Response
+
+Creating a stage should be a little like 'drawing'. The user should have a very easy time building.
+
+### Terrain Placement (Edit Mode)
+
+1. **Input Handling & Drag Trajectory**
+
+- **Anchor & Drag Trajectory:** Pressing the left mouse button sets a fixed grid anchor coordinate. Moving the mouse updates a dynamic target grid coordinate.
+- **Cardinal Angle Lock (Shift Key):**
+  - When Shift is active, calculate the dominant delta component ($\vert{}dx\vert{}$ vs $\vert{}dy\vert{}$) from anchor to target.
+  - Force the target coordinate to lock to the dominant axis, restricting the placement trajectory strictly to 0°, 90°, 180°, or 270°.
+  - Non-dominant delta is overridden to 0 relative to the anchor point, suppressing diagonal step generation completely.
+- **High-Contrast Guide Line:**
+  - Render a primary vector guide line from the center of the anchor cell to the center of the locked target cell.
+  - Line style uses a high-contrast accent (e.g., bright cyan or gold) with dashed styling to ensure visibility over any terrain color.
+
+2. **Pathing & Ghost Preview System**
+
+- **Staircase Pathing Engine:**
+  - When unrestrained by Shift, run Bresenham's line algorithm between anchor and target to yield an ordered array of target grid cell coordinates.
+  - This array forms a continuous, non-overlapping sequence of horizontal, vertical, and diagonal staircase steps.
+- **Ghost Rendering Pipeline:**
+  - For each cell coordinate in the path array, project a semi-transparent preview block (matching the active terrain block's dimensions and sprite).
+  - Preview blocks update dynamically every frame as the mouse moves.
+
+3. **Overlap & Connection Handling (Existing Blocks)**
+   To support connecting new lines to existing structures (such as extending a 3-block row with 4 additional blocks), use a three-state grid query for every cell along the drag path:
+
+- **Cell State 1: Empty Cell (Valid Placement)**
+  - **Visual:** Standard semi-transparent green ghost.
+  - **Action on Release:** Instantiate and place a new block node at this coordinate.
+- **Cell State 2: Occupied by Same Block Type (Overlap Skip)**
+  - **Scenario:** Dragging across or starting from an existing ground block.
+  - **Visual:** Neutral outline ghost or fully transparent preview (signifying no double-creation).
+  - **Action on Release:** Skip instantiation for this cell. The tool treats existing identical blocks as valid structural connections without duplicating physics nodes or causing rendering z-fighting.
+- **Cell State 3: Occupied by Different/Conflicting Object (Blocked)**
+  - **Scenario:** Dragging across an obstacle (e.g., crate, hazard, stickman spawn).
+  - **Visual:** Muted red ghost.
+  - **Action on Release:** Skip instantiation for this specific cell while preserving valid placements along the rest of the line.
+- **Connecting Workflow Example:**
+  - **Scenario:** Existing blocks at positions (1,0), (2,0), (3,0).
+  - **Case A (Seamless Extension):** User clicks empty cell (4,0) and drags to (7,0). Ghost blocks display at 4, 5, 6, 7. On release, 4 new blocks are created cleanly adjacent to block 3.
+  - **Case B (Overlapping Extension):** User clicks existing block (3,0) and drags through to (7,0). Position 3 is flagged as Occupied (Skip), while 4, 5, 6, 7 flag as Empty. On release, block 3 remains untouched and blocks 4, 5, 6, 7 are instantiated.
+
+4. **Atomic Transaction & State Management**
+
+- **Batch Commit:** On mouse release, process the path array in a single frame. Collect all newly instantiated block nodes into a single batch array.
+- **Grid Spatial Dictionary:** Update the stage’s centralized grid data structure with references to the newly spawned blocks, marking those cell coordinates as occupied for subsequent editing tasks.
+
+5. **Controls**
+
+- **Build Cancelling:**
+  When in edit mode and an object is selected to be created (terrain, prop, stickman, etc) - if the use clicks the LMB we end draw/placement mode (the object button gets toggled) and the cursor returns to normal.
+
+- **Moving Trigger Objects**
+  When a trigger object (such as an 'Area') gets moved, and it has a current action binded with it, the action display with the dashed line connecting to it does not follow the shape. The action line should redraw once the shape is moved so the use can see it updated.
+
+## Bugs
+
+### Director Issues
+
+1. Area trigger not working
+
+- **Scenario:** Area triggers do not see to do anything.
+- **Reproduce:**
+  1. Place a stickman
+  2. Place an area
+  3. Go into direct mode
+  4. Create a walking waypoint for the stickman that moves through the Area
+  5. Assign a 'When' action to the stickman - When Enters Trigger Area - Ragdoll
+  6. Enter Play mode
+- **Results:** The stickman walks to the waypoint, but nothing happens when it passes through the area.
+- **Expected:** The stickman triggers the area and activates ragdoll.
+
+2. Collisions are not working
+
+- **Scenario:** When assigning a collision trigger, nothing happens
+- **Reproduce:**
+  1. Place a stickman
+  2. Place a ground where the crate will be on top.
+  3. Place a crate on top of the ground
+  4. Go into direct mode
+  5. Create a walking waypoint for the stickman that moves through the crate
+  6. Assign a 'When' action to the stickman - When Enters Collides (with crate) - Ragdoll
+  7. Enter Play mode
+- **Results:** The stickman walks to the waypoint, but nothing happens when it collides with the prop.
+- **Expected:** The stickman collides with the prop, and the prop moves, etc....