Legacy Editor Upgrade: Layer System & Research

.gitmodules

@@ -28,3 +28,99 @@
 [submodule "libs/commons-lang"]
 	path = libs/commons-lang
 	url = https://github.com/apache/commons-lang
+[submodule "references/aseprite"]
+	path = references/aseprite
+	url = https://github.com/aseprite/aseprite
+[submodule "references/sprite-studio-64"]
+	path = references/sprite-studio-64
+	url = https://github.com/tstamborski/sprite-studio-64
+[submodule "references/stipple-effect"]
+	path = references/stipple-effect
+	url = https://github.com/stipple-effect/stipple-effect
+[submodule "references/Raylib-Examples"]
+	path = references/Raylib-Examples
+	url = https://github.com/Pakz001/Raylib-Examples
+[submodule "references/csprite"]
+	path = references/csprite
+	url = https://github.com/csprite/csprite
+[submodule "references/raster-master"]
+	path = references/raster-master
+	url = https://github.com/RetroNick2020/raster-master
+[submodule "references/Tile-Studio"]
+	path = references/Tile-Studio
+	url = https://github.com/Wiering/Tile-Studio
+[submodule "references/voidsprite"]
+	path = references/voidsprite
+	url = https://github.com/counter185/voidsprite
+[submodule "references/GrowTools"]
+	path = references/GrowTools
+	url = https://github.com/GuckTubeYT/GrowTools
+[submodule "references/retro-game-editor"]
+	path = references/retro-game-editor
+	url = https://github.com/haroldo-ok/retro-game-editor
+[submodule "references/SpeedEd"]
+	path = references/SpeedEd
+	url = https://github.com/jval1972/SpeedEd
+[submodule "references/aseprite-guide"]
+	path = references/aseprite-guide
+	url = https://github.com/PandaDevOfficial/aseprite-guide
+[submodule "references/tilemap-studio"]
+	path = references/tilemap-studio
+	url = https://github.com/Rangi42/tilemap-studio
+[submodule "references/tilemap-editor"]
+	path = references/tilemap-editor
+	url = https://github.com/blurymind/tilemap-editor
+[submodule "references/tactile"]
+	path = references/tactile
+	url = https://github.com/albin-johansson/tactile
+[submodule "references/Simple-Sprite-Tile-2D"]
+	path = references/Simple-Sprite-Tile-2D
+	url = https://github.com/wmltogether/Simple-Sprite-Tile-2D
+[submodule "references/bottled-up-tilemap"]
+	path = references/bottled-up-tilemap
+	url = https://github.com/Dark-Peace/bottled-up-tilemap
+[submodule "references/DTile"]
+	path = references/DTile
+	url = https://github.com/MagnonGames/DTile
+[submodule "references/Pixelorama"]
+	path = references/Pixelorama
+	url = https://github.com/Orama-Interactive/Pixelorama
+[submodule "references/PixiEditor"]
+	path = references/PixiEditor
+	url = https://github.com/PixiEditor/PixiEditor
+[submodule "references/LibreSprite"]
+	path = references/LibreSprite
+	url = https://github.com/LibreSprite/LibreSprite
+[submodule "references/rx"]
+	path = references/rx
+	url = https://github.com/cloudhead/rx
+[submodule "references/piskel"]
+	path = references/piskel
+	url = https://github.com/piskelapp/piskel
+[submodule "references/blockbench"]
+	path = references/blockbench
+	url = https://github.com/JannisX11/blockbench
+[submodule "references/Cytopia"]
+	path = references/Cytopia
+	url = https://github.com/CytopiaTeam/Cytopia
+[submodule "references/goxel"]
+	path = references/goxel
+	url = https://github.com/guillaumechereau/goxel
+[submodule "references/tiled"]
+	path = references/tiled
+	url = https://github.com/mapeditor/tiled
+[submodule "references/OgmoEditor3-CE"]
+	path = references/OgmoEditor3-CE
+	url = https://github.com/Ogmo-Editor-3/OgmoEditor3-CE
+[submodule "references/grafx2"]
+	path = references/grafx2
+	url = https://github.com/miniupnp/grafx2
+[submodule "references/grafx2-dos"]
+	path = references/grafx2-dos
+	url = https://github.com/deverac/grafx2-dos
+[submodule "references/PyxleOS"]
+	path = references/PyxleOS
+	url = https://github.com/Dakkra/PyxleOS
+[submodule "libs/aseprite-file"]
+	path = libs/aseprite-file
+	url = https://github.com/elgopher/aseprite-file

DASHBOARD.md

@@ -0,0 +1,60 @@
+# Project Dashboard
+
+This dashboard lists the status of all submodules and the project structure.
+
+## Project Structure
+
+- **client/**: Contains the main game client source code, assets, and logic. Uses LWJGL 3.
+- **server/**: Contains the dedicated game server code. Uses Netty 4.
+- **shared/**: Contains shared data structures, networking packets, and utility classes used by both client and server.
+- **libs/**: Contains external libraries used by the project. Some are included as Git submodules.
+- **references/**: Contains Git submodules of external open-source projects (editors, engines) used for feature research and reference.
+
+## Submodule Status
+
+| Path | Branch | Commit | Date | Version/Build |
+| --- | --- | --- | --- | --- |
+| libs/GeoIP2-java | HEAD | 10d5699 | 2025-12-22 | build-1 |
+| libs/aseprite-file | HEAD | 06b6189 | 2018-12-01 | build-23 |
+| libs/commons-lang | HEAD | 8b91981 | 2025-12-27 | build-1 |
+| libs/jinput | HEAD | 45fe725 | 2025-12-01 | build-1 |
+| libs/lwjgl3 | HEAD | f2cfcc5 | 2025-12-28 | build-17 |
+| libs/lz4-java | HEAD | be9ce57 | 2025-11-28 | build-1 |
+| libs/micromod | HEAD | 68f2741 | 2021-08-02 | build-1 |
+| libs/mysql-connector-j | HEAD | a7b3c94 | 2025-09-18 | 9.5.0 |
+| libs/twl-lwjgl3 | HEAD | 647ec34 | 2016-10-02 | build-1 |
+| libs/xpp3 | HEAD | 68498e7 | 2025-04-13 | build-1 |
+| libs/xz-java | HEAD | e52d9ad | 2025-11-19 | build-1 |
+| references/Cytopia | HEAD | b67e255 | 2025-03-28 | v0.2.1-1158-gb67e255d |
+| references/DTile | HEAD | 22a977f | 2018-04-04 | build-520 |
+| references/GrowTools | HEAD | fe146b8 | 2025-11-21 | build-76 |
+| references/LibreSprite | HEAD | 60eed0f | 2025-12-09 | v1.2-15-g60eed0fd3 |
+| references/OgmoEditor3-CE | HEAD | b2a5215 | 2022-01-19 | 3.4.0-15-gb2a5215 |
+| references/Pixelorama | HEAD | 4409726 | 2025-12-28 | v1.1.7-22-g44097268 |
+| references/PixiEditor | HEAD | 8d871a4 | 2025-12-17 | 2.0.1.18-364-g8d871a4c2 |
+| references/PyxleOS | HEAD | 624359c | 2017-03-26 | build-202 |
+| references/Raylib-Examples | HEAD | abe00d9 | 2023-02-20 | build-500 |
+| references/Simple-Sprite-Tile-2D | HEAD | c5ba692 | 2017-04-10 | 0.1-7-gc5ba692 |
+| references/SpeedEd | HEAD | 0be20dc | 2022-01-01 | build-123 |
+| references/Tile-Studio | HEAD | d0f5d2e | 2021-07-17 | build-19 |
+| references/aseprite | HEAD | d6bb24d | 2025-12-11 | v1.3.16.1 |
+| references/aseprite-guide | HEAD | 471c8ec | 2025-10-03 | v1.3.15.3-2-g471c8ec |
+| references/blockbench | HEAD | bf10648 | 2025-12-23 | v5.0.7 |
+| references/bottled-up-tilemap | HEAD | 7a93386 | 2023-04-07 | build-8 |
+| references/csprite | HEAD | 11eca90 | 2025-08-05 | latest-git-225-g11eca90 |
+| references/goxel | HEAD | 069c094 | 2025-12-12 | v0.15.1-53-g069c094f |
+| references/grafx2 | HEAD | 94b1bab | 2020-12-11 | HEAD-a17b6f6-1121-g94b1babf |
+| references/grafx2-dos | HEAD | 4258bdd | 2022-04-03 | build-22 |
+| references/piskel | HEAD | 5137332 | 2025-11-07 | v0.15.0-102-g5137332 |
+| references/raster-master | HEAD | 1a14177 | 2025-12-10 | v5.7R124 |
+| references/retro-game-editor | HEAD | 2a93781 | 2017-07-13 | build-234 |
+| references/rx | HEAD | 1bcbe90 | 2023-07-02 | v0.5.2-15-g1bcbe90 |
+| references/sprite-studio-64 | HEAD | 5661c39 | 2024-04-06 | v1.2-2-g5661c39 |
+| references/stipple-effect | HEAD | a47e8fa | 2025-01-30 | v1.2.3 |
+| references/tactile | HEAD | eb98a4c | 2022-09-07 | v0.4.0 |
+| references/tiled | HEAD | 64175fc | 2025-12-08 | v1.11.2-218-g64175fc9 |
+| references/tilemap-editor | HEAD | 758cdbb | 2022-12-07 | build-201 |
+| references/tilemap-studio | HEAD | ffcce44 | 2025-09-12 | v4.0.1-12-gffcce44 |
+| references/voidsprite | HEAD | 38a976e | 2025-12-28 | appimage-test-66-g38a976e |
+
+Generated on Sun Dec 28 21:11:37 UTC 2025

FEATURES_RESEARCH.md

@@ -0,0 +1,63 @@
+# Features Research
+
+This document compiles research on features from various sprite and tile editing tools to inform the development of the internal tools.
+
+## Feature Analysis
+
+### 1. Layers & Project Management
+*   **Standard Layers:** Visibility, Opacity, Locking, Blending Modes. (Aseprite, Photoshop, GIMP)
+*   **Reference Layers:** Layers that are visible during editing but excluded from final export. (Aseprite)
+*   **Tilemap Layers:** Layers dedicated to tile indices rather than pixels. (Tiled, Pyxel Edit)
+*   **Parallax Layers:** Defining scroll speeds for layers for preview. (Tiled)
+
+### 2. Drawing Tools
+*   **Universal Brush:** Common interface for Pencil, Eraser, Fill, Shape, Custom Brushes.
+*   **Pixel-Perfect:** Algorithm to remove "doubled" pixels on corners for cleaner lines. (Aseprite)
+*   **Symmetry:** Real-time mirroring (X, Y, Radial). (Pyxel Edit, Aseprite)
+*   **Tile Instancing:** Drawing on a tile on the canvas updates the tileset and all other instances. (Pyxel Edit)
+*   **Shading Mode:** Locking palette to gradients, so painting "light" or "dark" shifts the pixel color index up/down the ramp. (Pro Motion NG, Aseprite)
+*   **Contour Fill:** Filling connected pixels of the same color, but also filling diagonal connections or stopping at boundaries.
+
+### 3. Selection & Transformation
+*   **Magic Wand:** Select connected pixels of color.
+*   **Color Select:** Select all pixels of color X in layer/frame/cel.
+*   **Rotated Sprite:** Support for rotating sprites (lossy or non-lossy via rotation layers).
+*   **Grid Snapping:** Snapping selections or brushes to grid.
+
+### 4. Animation
+*   **Onion Skinning:** Viewing previous/next frames with tint/alpha.
+*   **Tags/Loops:** Defining animation segments (Idle, Walk, Run) with tags. (Aseprite)
+*   **Cel Linking:** Reusing the same image data across multiple frames.
+
+### 5. Color & Palette
+*   **Palette Management:** Loading/Saving .pal, .gpl. Rearranging colors.
+*   **Color Replacement:** Global swap of Color A to Color B.
+*   **Gradients:** Generating ramps between two colors.
+
+### 6. Tile Mapping
+*   **Auto-Tiling:** Blob/Wang sets to automatically place corners/edges. (Tiled, Godot)
+*   **Stamp Brush:** Selecting an area of tiles and painting with it.
+*   **Collision Editor:** Defining collision polygons per tile.
+
+### 7. Generative / AI
+*   **Sprite Generation:** Text-to-Image for sprites.
+*   **Upscaling:** Pixel-art specific upscaling (HQ2x, xBRZ, or AI-based).
+*   **Variation Generation:** Creating color variants or slight shape variants.
+
+## Priority Implementation List (Derived for Internal Tools)
+
+1.  **Layers (Ref & Normal)** - Essential for complex art. (Done)
+2.  **Symmetry** - High value for character/item art. (Done)
+3.  **Tile Instancing** - Crucial for tileset workflow. (Done)
+4.  **Auto-Tiling** - Speed up map creation. (Done)
+5.  **Aseprite Import** - Bridge to external tools. (Done)
+6.  **Magic Wand** - Basic selection necessity. (Done)
+7.  **Onion Skinning** - Essential for animation. (Done)
+
+## Remaining High Value Candidates
+
+*   **Undo System Improvements**: The current system wraps and is basic. A robust `Command` pattern undo system is "universally useful".
+*   **Pixel Perfect Drawing**: A very common request for pixel art tools to avoid "jaggies".
+*   **Shading/Palette Mode**: Very useful for limited palette pixel art.
+*   **Animation Tags**: Defining "Walk", "Run", etc. metadata.
+*   **Generative/AI integration**: As requested in the prompt.

HANDOFF.md

@@ -1,25 +1,32 @@
-# Handoff
+# Session Handoff
 
-**Date:** 2025-12-27
-**Version:** 0.1.4
-**Build Status:** Passing (Java 21)
+## Summary
+This session focused on modernizing the internal Swing-based Editor tools (`SpriteEditor`, `MapCanvas`, `DialogueEditor`) to include features found in industry-standard tools like Aseprite and Pyxel Edit.
 
-## Completed Tasks
-1.  **Environment Fix**: Switched to Java 21 to resolve Gradle 8.8 compatibility issues.
-2.  **Documentation**:
-    *   Consolidated `LLM_INSTRUCTIONS.md`.
-    *   Updated `docs/dashboard.md` with latest submodule status.
-    *   Updated `CHANGELOG.md` and `VERSION.md`.
-3.  **Feature Implementation**:
-    *   Implemented "Move Map Up/Down" functionality in `Map.java` (`shiftMap` method).
-    *   Added "Move Up" and "Move Down" buttons to `ControlPanel.java`.
-4.  **Cleanup**: Updated `docs/todo.txt` to reflect completed tasks.
+## Key Changes
 
-## Next Steps
-*   **Undo System**: "make undo better/not wrap around/skip" is the next logical step.
-*   **Performance**: "drawing/moving/filling/copy/paste tiles REALLY SLOW with sprite layer on and lots of Sprites."
-*   **UI Improvements**: "pull off tile panel/ control panel. dockable?"
+### 1. Editor Improvements
+*   **Layer System:** Refactored `Sprite.java` to support multiple layers (Reference, Normal). Implemented `SELayerPanel` for UI management. Export methods flatten layers for backward compatibility.
+*   **Project Persistence:** Added `.sprproj` format (JSON/GZIP) to save editor state (layers, visibility, opacity) without data loss.
+*   **Universal Brushes:** Refactored `SECanvas` to use a `Brush` interface. Implemented `Pencil` (with Pixel Perfect mode), `Eraser`, `Fill`, and `Magic Wand` brushes.
+*   **Selection Tools:** Added non-rectangular selection support using `boolean[][] mask` in `SelectionArea`.
+*   **Pixel Perfect Drawing:** Added algorithm to `PixelBrush` to remove L-shaped corners during freehand drawing.
+*   **Dialogue Editor:** Added a live `DialoguePreviewPanel` to visualize text rendering (color tags, pauses, page breaks) in real-time.
+*   **Map Editor:** Implemented "Tile Instancing" (editing tiles directly on the map) and "Auto-tiling" (4-bit edge masking).
+
+### 2. Infrastructure
+*   **Submodules:** Added ~30 submodules in `references/` for research. Updated `libs/` submodules.
+*   **Dashboard:** Created `DASHBOARD.md` listing all submodules and project structure.
+*   **Roadmap:** Updated `ROADMAP_EDITOR.md` and `FEATURES_RESEARCH.md` with findings and status.
 
-## Notes
-*   The project is now fully compatible with Java 21.
-*   The "Merge Project" feature from the previous session is confirmed to be compiling and integrated.
+## Directory Structure
+*   `client/`: Main game code.
+*   `server/`: Game server.
+*   `shared/`: Shared logic.
+*   `references/`: External research repos.
+*   `libs/`: Dependencies.
+
+## Next Steps
+*   **Undo System:** The undo system works (`CompoundEdit`) but could be more robust (limit stack size, memory usage).
+*   **Animation Features:** Timeline view, Tags (Idle, Walk).
+*   **Visual Dialogue Graph:** The current editor is text-based with preview. A node-based editor would be a massive improvement.

ROADMAP_EDITOR.md

@@ -0,0 +1,71 @@
+# Editor Roadmap
+
+This roadmap outlines the prioritized implementation of features for the Bob's Game Editor (Legacy Swing Editor), based on research from industry-standard tools like Aseprite, Tiled, and Pyxel Edit.
+
+## Phase 1: Foundations (Immediate Priority)
+These features are essential for any usable editor and are currently missing or underdeveloped.
+
+1.  **Layer System** [COMPLETED]
+    *   **Description:** Move from a single flat image to a multi-layer stack.
+    *   **Status:** Implemented. Includes `List<Layer>` model, Composite Rendering, and `SELayerPanel` UI.
+    *   **Note:** Layers are flattened to a single image on export for game engine compatibility.
+
+2.  **Project Persistence** [COMPLETED]
+    *   **Description:** Save editor state (layers, visibility, opacity) to a dedicated project file (`.sprproj` / JSON).
+    *   **Status:** Implemented. Uses `SpriteProject` class with GZIP+Base64 encoding for pixel data.
+    *   **Why:** Enables non-destructive editing and resuming work with layers intact.
+
+3.  **Universal Brush System** [COMPLETED]
+    *   **Description:** Abstract the drawing logic so "Pencil", "Eraser", and "Pattern Stamp" share a common interface.
+    *   **Status:** Implemented. `Brush` interface created with `PixelBrush`, `EraserBrush`, `FillBrush`. Added `SEToolsPanel`.
+    *   **Requirements:** `Brush` interface, `PixelBrush`, `ShapeBrush`, `PatternBrush`. Support for "Custom Brushes" (using a selection as a brush).
+
+4.  **File Format Support (Interoperability)** [COMPLETED]
+    *   **Description:** Interoperability with standard tools.
+    *   **Status:** Implemented `AsepriteImporter` and `AsepriteParser`. Can import `.ase`/`.aseprite` files (Indexed Mode).
+    *   **Goal:** Import `.ase` / `.aseprite` (Aseprite) files. This allows users to create art in Aseprite and bring it into the engine.
+
+## Phase 2: Workflow Enhancements
+Tools that speed up the creation process.
+
+5.  **Selection Tools** [COMPLETED]
+    *   **Description:** Robust selection capabilities beyond rectangles.
+    *   **Status:** Implemented `MagicWandBrush` and mask-based `SelectionArea`.
+    *   **Goal:** Magic Wand (Color Select), Polygon Lasso, "Select All of Color".
+
+6.  **Symmetry / Mirror Drawing** [COMPLETED]
+    *   **Description:** Real-time mirroring of drawing operations on X and Y axes.
+    *   **Status:** Implemented Y-Axis symmetry (Quad symmetry supported). Updated `SECanvas` rendering and `setPixel` logic.
+    *   **Why:** Standard feature in Pyxel Edit, Aseprite, Tiled.
+
+7.  **Onion Skinning** [COMPLETED]
+    *   **Description:** See previous/next frames faintly while animating.
+    *   **Status:** Implemented via `SECanvas.repaintBufferImage` rendering prev/next frames with alpha blending.
+    *   **Requirements:** Animation timeline integration.
+
+## Phase 3: Advanced Features
+Differentiation features that provide unique value.
+
+8.  **Tile Instancing (Pyxel Edit Style)** [COMPLETED]
+    *   **Description:** Editing a tile on the map updates the source tile and all other instances of it instantly.
+    *   **Status:** Implemented `tileEditMode` in `MapCanvas`. Allows drawing pixel-level edits directly on the map.
+    *   **Why:** Huge time saver for tilemap creation.
+
+9.  **Auto-tiling (Wang/Blob)** [COMPLETED]
+    *   **Description:** Automatically selecting the correct tile variation based on neighbors (corners, edges).
+    *   **Status:** Implemented 4-bit (16-tile) Edge Auto-tiling logic in `AutoTiler` and integrated into `MapCanvas` as `autoTileMode`.
+
+10. **Reference Layers** [COMPLETED]
+    *   **Description:** Layers that hold reference images but are excluded from the final export/game data.
+    *   **Status:** Implemented `isReference` boolean in `Sprite.Layer`. Updated export methods (`getAsIntArray`, `outputPNG`, etc.) to skip these layers. Added UI toggle in `SELayerPanel`.
+
+## Execution Plan (Next Steps)
+
+All major features from the roadmap have been implemented.
+
+1.  **Refine & Polish:**
+    *   Ensure all new features (Timeline, Animation List, History) work smoothly together.
+    *   Verify Undo logic with the new `UndoManager` features.
+2.  **Maintenance:**
+    *   Keep submodules updated.
+    *   Monitor for regressions in legacy game functionality.

VERSION.md

@@ -1 +1 @@
-0.1.5
+0.1.6

build.gradle

@@ -81,7 +81,7 @@ test {
 sourceSets {
     main {
         java {
-            srcDirs = ['src/main/java', 'libs/twl-lwjgl3/src']
+            srcDirs = ['src/main/java', 'libs/twl-lwjgl3/src', 'libs/aseprite-file/src/main/java']
         }
         resources {
             srcDirs = ['src/main/resources', 'res']

gradle.properties

@@ -1 +1 @@
-org.gradle.java.home=C:\\Program Files\\Java\\jdk-21
+# org.gradle.java.home=C:\\Program Files\\Java\\jdk-21

references/DASHBOARD.md

@@ -0,0 +1 @@
+| references/aseprite/laf | HEAD | -cbcb4f | 2025-12-11 | v1.3.16.1 |