Coordinates, topology, orientation, and layout
Topology decides what positions mean to gameplay; layout decides where those positions appear.
Logical rules and spatial presentation
Coordinates are logical identities. A topology validates them and defines neighbors, directions, distance, footprint transforms, and legal orientations. A layout converts those logical values into poses, polygons, and hit results for one spatial presentation.
A GridCoordinate stores one logical value inside a coordinate system. A GridAddress pairs a topology ID with a compatible coordinate so definitions and states can use it as a stable dictionary key. Neither value identifies a particular board instance.
One logical cell in two layouts
Square coordinate (1, 1) identifies one logical cell. The square topology determines its
neighbors and how a rotated footprint covers nearby cells. A World 3D layout may present it at
(1, 0, 1), while a World 2D layout may present the same cell at (1, 1, 0). Gameplay still refers
to (1, 1).
Rules to preserve
- Never mix coordinates from different coordinate systems.
- Normalize coordinates and orientations through the board topology.
- Footprint offsets are topology-relative, not world-space vectors.
- Gameplay adjacency and range queries belong to topology.
- Cell size, projection plane, spatial pose, and picking belong to layout.
From logical values to gameplay and presentation
flowchart LR
accTitle: Logical topology and spatial layout responsibilities
accDescr: Coordinates and orientations pass through topology for gameplay relationships and through layout for presentation poses, geometry, and hit resolution.
A["GridCoordinate"] --> B["IGridTopology"]
C["GridOrientation"] --> B
B --> D["Neighbors / distance / footprint"]
A --> E["IGridLayout"]
C --> E
E --> F["Pose / geometry / hit"]
What custom implementations must preserve
Square, hex, and triangle are built-in topology families. A custom topology must keep coordinate, orientation, geometry, and snapshot identity stable. A custom layout may change presentation without changing gameplay semantics.