From 2718983cd139bf33b6ea36f7195e6a1d9b46371a Mon Sep 17 00:00:00 2001
From: RobertoMaurizzi <roberto.maurizzi@gmail.com>
Date: Thu, 17 Jul 2025 22:35:42 +0800
Subject: [PATCH] Add minimal docs on coordinate translations for Gridvania
 levels

---
 docs/level-layout-doc.txt | 67 +++++++++++++++++++++++++++++++++++++++
 1 file changed, 67 insertions(+)
 create mode 100644 docs/level-layout-doc.txt

diff --git a/docs/level-layout-doc.txt b/docs/level-layout-doc.txt
new file mode 100644
index 0000000..75cfeb0
--- /dev/null
+++ b/docs/level-layout-doc.txt
@@ -0,0 +1,67 @@
+
+Y ↑
+  │  Bevy world ↑                                        LDtk-World ↓ 
+  │  (Y increases upward)                           (increases downward)
+  │
+  │     -32          -16            0            16            32
+  │      ┌────────────┬─────────────┬─────────────┬─────────────┐   │
+  │  32  │            │             │      L2     │             │-32│
+  │      │            │             │  (top-lvl)  │             │   │
+  │      │            │             │             │             │   │
+  │      ├────────────┼─────────────┼─────────────┼─────────────┤   │
+  │  16  │            │     L1      │   L0        │     L3      │-16│
+  │      │            │             │             │             │   │
+  │      │            │             │   (0,0)     │             │   │
+  │      ├────────────┼─────────────O─────────────┼─────────────┤   │
+  │   0  │            │             │   L4        │             │ 0 │
+  │      │            │             │             │             │   │
+  │      │            │             │             │             │   │
+  │      ├────────────┴─────────────┴─────────────┴─────────────┤   │
+  │ -16  │                        L5                            │ 16│
+  │      │                 (bottom-lvl)                         │   │
+  │      │                                                      │   │
+  │      └──────────────────────────────────────────────────────┘   ↓
+  │
+  └───────────────────────────────────────────────────────────────► X →
+        -32         -16            0            16            32
+```
+
+Legend
+──────
+• Each square = 16×16 tiles.
+• **Bevy Y** increases **upward** (↑).
+• **LDtk Y** (both world & inside level) increases **downward** (↓).
+
+Coordinate examples
+───────────────────
+Level L0  (at origin)
+  LDtk world anchor (top-left) = (0, -16)
+  Top-left corner in Bevy world   = (0, 16)
+
+Level L1  (left of origin)
+  LDtk world anchor               = (-16, -16)
+  Top-left corner in Bevy world   = (-16, 16)
+
+Level L2  (above origin)
+  LDtk world anchor               = (0, -32 )
+  Top-left corner in Bevy world   = (0, 32)
+
+Level L3  (right origin)
+  LDtk world anchor               = (16, -16)
+  Top-left corner in Bevy world   = (16, -16)
+
+Level L4  (below L3)
+  LDtk world anchor               = (0, 16)
+  Top-left corner in Bevy world   = (0, -16)
+
+Level L5 (below L4, spanning 4 x levels)
+  LDtk world anchor               = (-32, 32)
+  Top-left corner in Bevy world   = (-32, -32)
+
+
+Player's world-based gridcoords need to be converted to the internal coordinates for a level (so we can match it with
+the cached walls HashMap).
+To convert between world and in-level coords:
+
+lX = wX - level_world_x
+lY = wY - (-level_world_y - level_height)