Docs: Deep project analysis, documentation updates, and submodule tracking

.gitignore

@@ -1,25 +1,10 @@
-.gradle
-build
-out
-bin
+.gradle/
+build/
 *.class
+*.log
+*.tmp
+
+references/grafx2/doc/quickstart.rtf
+out/
+bin/
 *.bak
-build/
-.gradle/8.8/executionHistory/executionHistory.bin
-.gradle/8.8/executionHistory/executionHistory.lock
-.gradle/8.8/fileHashes/fileHashes.bin
-.gradle/8.8/fileHashes/fileHashes.lock
-.gradle/8.8/fileHashes/resourceHashesCache.bin
-.gradle/buildOutputCleanup/buildOutputCleanup.lock
-.gradle/8.8/checksums/checksums.lock
-.gradle/8.8/checksums/md5-checksums.bin
-.gradle/8.8/checksums/sha1-checksums.bin
-.gradle/8.8/executionHistory/executionHistory.bin
-.gradle/8.8/executionHistory/executionHistory.lock
-.gradle/8.8/fileHashes/fileHashes.bin
-.gradle/8.8/fileHashes/fileHashes.lock
-.gradle/8.8/fileHashes/resourceHashesCache.bin
-.gradle/buildOutputCleanup/buildOutputCleanup.lock
-.gradle
-.gradle
-.gradle

.gitmodules

@@ -124,3 +124,18 @@
 [submodule "bobcoin"]
 	path = bobcoin
 	url = https://github.com/robertpelloni/bobcoin
+[submodule "references/defold"]
+	path = references/defold
+	url = https://github.com/defold/defold
+[submodule "references/love2d"]
+	path = references/love2d
+	url = https://github.com/love2d/love
+[submodule "references/phaser"]
+	path = references/phaser
+	url = https://github.com/phaserjs/phaser
+[submodule "libs/bobui"]
+	path = libs/bobui
+	url = https://github.com/robertpelloni/bobui
+[submodule "references/voidsprite"]
+	path = references/voidsprite
+	url = https://github.com/counter185/voidsprite

AGENTS.md

@@ -1,2 +1,3 @@
 # Agents Instructions
-Please refer to [LLM_INSTRUCTIONS.md](LLM_INSTRUCTIONS.md) for core instructions.
+Please refer to [docs/UNIVERSAL_LLM_INSTRUCTIONS.md](docs/UNIVERSAL_LLM_INSTRUCTIONS.md) for core instructions.
+Always remember to bump the version in `VERSION.md`, update `CHANGELOG.md`, and include the version number in the git commit message.

CHANGELOG.md

@@ -2,6 +2,21 @@
 
 All notable changes to this project will be documented in this file.
 
+## [2.0.31] - 2026-04-27
+
+### Fixed
+- Stabilized documentation and submodule sync loop.
+
+## [2.0.31] - 2026-04-26
+
+### Added
+- Created `VISION.md`, `MEMORY.md`, `DEPLOY.md`, and `TODO.md` to comprehensively document project goals, observations, deployment steps, and upcoming tasks.
+- Added new references for Defold, Love2D, Phaser, and `bobui` to the git submodules for feature analysis and integration.
+- Updated `AGENTS.md`, `CLAUDE.md`, `GEMINI.md`, `GPT.md`, `copilot-instructions.md`, and `LLM_INSTRUCTIONS.md` to point to the universal LLM instructions.
+
+### Changed
+- Bumped `VERSION.md` to `2.0.31`.
+
 ## [2.0.30] - 2026-04-06
 
 ### Added

CLAUDE.md

@@ -1,2 +1,3 @@
-# Claude Instructions
-Please refer to [LLM_INSTRUCTIONS.md](LLM_INSTRUCTIONS.md) for core instructions.
+# Agents Instructions
+Please refer to [docs/UNIVERSAL_LLM_INSTRUCTIONS.md](docs/UNIVERSAL_LLM_INSTRUCTIONS.md) for core instructions.
+Always remember to bump the version in `VERSION.md`, update `CHANGELOG.md`, and include the version number in the git commit message.

DEPLOY.md

@@ -0,0 +1,17 @@
+# DEPLOY: Deployment Instructions
+
+The project consists of multiple deployable artifacts:
+
+## Server Deployment (Docker)
+1. Ensure Docker and docker-compose are installed.
+2. Configure `server.properties` or environment variables for database credentials.
+3. Run `docker-compose up --build -d` to launch the Game Server, STUN Server, and MySQL database.
+
+## Client Deployment
+1. Build the client using Gradle: `./gradlew :client:build`
+2. Run the client: `./gradlew :client:run`
+
+## Web Deployment (Hetzner / bobsgameweb)
+*(To be expanded as the web port is finalized)*
+- Target: 30-player cross-platform multiplayer, leaderboards, and live editing.
+- Ensure all WebSocket proxy layers are configured to bridge web traffic to the Netty TCP backend.

GEMINI.md

@@ -1,2 +1,3 @@
-# Gemini Instructions
-Please refer to [LLM_INSTRUCTIONS.md](LLM_INSTRUCTIONS.md) for core instructions.
+# Agents Instructions
+Please refer to [docs/UNIVERSAL_LLM_INSTRUCTIONS.md](docs/UNIVERSAL_LLM_INSTRUCTIONS.md) for core instructions.
+Always remember to bump the version in `VERSION.md`, update `CHANGELOG.md`, and include the version number in the git commit message.

GPT.md

@@ -1,2 +1,3 @@
-# GPT Instructions
-Please refer to [LLM_INSTRUCTIONS.md](LLM_INSTRUCTIONS.md) for core instructions.
+# Agents Instructions
+Please refer to [docs/UNIVERSAL_LLM_INSTRUCTIONS.md](docs/UNIVERSAL_LLM_INSTRUCTIONS.md) for core instructions.
+Always remember to bump the version in `VERSION.md`, update `CHANGELOG.md`, and include the version number in the git commit message.

HANDOFF.md

@@ -181,3 +181,20 @@ This session focused on modernizing the internal Swing-based Editor tools (`Spri
 *   **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.
+
+---
+
+## Handoff - Google Jules (Version 2.0.31)
+
+### Action Taken
+1.  **Documentation Updates:** Created `VISION.md`, `MEMORY.md`, `DEPLOY.md`, `TODO.md` in the root.
+2.  **LLM Instructions:** Appended universal instructions link to agent files.
+3.  **Submodules:** Added git submodules for `defold`, `love2d`, `phaser`, and `bobui`.
+4.  **Version Bump:** Bumped the version to `2.0.31` in `VERSION.md` and updated `CHANGELOG.md`.
+
+### Next Steps
+- Port the legacy Swing `bgeditor` to JavaFX and/or C++ (Qt6) using `bobui`.
+- Port bgeditor to Web.
+- Implement advanced selection tools (Polygon Lasso) in the Sprite Editor.
+- Build the UI for Generative AI tools (Text-to-Sprite, Image-to-Sprite).
+- Integrate submodules related to generative AI.

LLM_INSTRUCTIONS.md

@@ -14,3 +14,6 @@ This is the Java (LibGDX) implementation of the unified puzzle engine.
 - Refer to [AGENTS.md](AGENTS.md) for agent roles.
 - Refer to [VERSION.md](VERSION.md) for the current version.
 - Refer to [CHANGELOG.md](CHANGELOG.md) for historical changes.
+
+## 4. Universal Omni-Workspace Instructions
+For workspace-wide context, rules on merging, and cross-repo interactions, refer to the root [docs/UNIVERSAL_LLM_INSTRUCTIONS.md](docs/UNIVERSAL_LLM_INSTRUCTIONS.md).

MEMORY.md

@@ -0,0 +1,9 @@
+# MEMORY: Observations & Design Preferences
+
+- **Architecture:** The project is deeply modular, with distinct `client`, `server`, and `shared` modules.
+- **Language:** Migrating towards modern Java 21 features. Strong preference for clean, well-structured, straightforward code.
+- **UI/UX:** Every feature must be comprehensively represented in the UI. No hidden functionality. Must have exhaustive tooltips, labels, and documentation.
+- **Submodules:** The project aggressively incorporates external open-source projects as git submodules in `libs/` and `references/` to study their features, algorithms, and workflows.
+- **Versioning:** A single `VERSION.md` file serves as the universal source of truth for the project version. Every build/session requires a version increment and a corresponding `CHANGELOG.md` entry.
+- **AI Collaboration:** Continuous, iterative development through agent handoffs (Gemini -> Claude -> GPT), with strict requirements for updating `HANDOFF.md` and following `UNIVERSAL_LLM_INSTRUCTIONS.md`.
+- **Refactoring:** Legacy code (e.g., Swing-based editors) is being actively modernized, ported to JavaFX/Web/C++ (Qt6), and refined for extreme robustness.

TODO.md

@@ -0,0 +1,18 @@
+# TODO: Short-Term Tasks & Fixes
+
+## Documentation & Organization
+- [ ] Complete the exhaustive feature analysis of all referenced submodules (Construct, Phaser, GameMaker, etc.).
+- [ ] Finalize the comprehensive submodule dashboard with URLs, descriptions, versions, and build numbers.
+- [ ] Submodule all generative AI tools.
+
+## Editor Enhancements
+- [ ] Implement advanced selection tools (Polygon Lasso) in the Sprite Editor.
+- [ ] Build the UI for Generative AI tools (Text-to-Sprite, Image-to-Sprite).
+- [ ] Finalize the Undo/Redo robust Command pattern across all editor tabs.
+- [ ] Port the legacy Swing `bgeditor` to JavaFX and/or C++ (Qt6).
+- [ ] Port bgeditor to Web.
+
+## Engine & Multiplayer
+- [ ] Ensure `bobsgameweb` has 100% stable deployment to Hetzner.
+- [ ] Optimize the Netty 4 pipeline for massive concurrency (30+ players).
+- [ ] Clean up and refactor the C++ project using Ultimate++.

VERSION.md

@@ -1 +1 @@
-2.0.30
+2.0.31

VISION.md

@@ -0,0 +1,11 @@
+# VISION: The Ultimate Omni-Engine
+
+The ultimate goal of this project is to create the absolute most complete, robust, useful, and functional game engine and editor in existence—an "omni-engine" capable of matching and exceeding the 1:1 functionality of every other major 2D game engine (Defold, LÖVE, Phaser, Construct, GameMaker, RPG Maker).
+
+The project aims to synthesize the best features from dozens of specialized sprite editors, tilemap editors, and voxel tools, integrating them into a cohesive, cross-platform, multi-language suite. It encompasses:
+1.  **A high-performance C++ core** (integrated with Ultimate++).
+2.  **A modernized Java backend and client** (Java 21, LWJGL 3, Netty 4).
+3.  **A versatile Web port** capable of 30-player cross-platform multiplayer.
+4.  **Advanced Generative AI tools** for sprite generation, animation interpolation, and 3D voxel creation.
+
+This omni-engine will support seamless game editing, live multiplayer server deployments (e.g., to Hetzner), and global leaderboards.

copilot-instructions.md

@@ -1 +1,3 @@
-See `AGENTS.md`.
+# Agents Instructions
+Please refer to [docs/UNIVERSAL_LLM_INSTRUCTIONS.md](docs/UNIVERSAL_LLM_INSTRUCTIONS.md) for core instructions.
+Always remember to bump the version in `VERSION.md`, update `CHANGELOG.md`, and include the version number in the git commit message.