Hexagonal grid with sub-grid positioning, velocity management, and mass-based interactions.

Objects move freely on a hexagonal grid using sub-grid offsets and persistent velocities. Movement is driven by forces (collision, cohesion, spells) that modify velocity each frame, with mass determining acceleration response.

Hex Cell Size: Corner-to-corner distance d chosen to equal the minimum object merging distance.

One-Per-Cell Guarantee: Cell size ensures no two objects can occupy the same cell.

Polar Coordinates: Grid uses polar/cube coordinate system for neighbor lookup and point-to-hex conversion.

GPU Storage: Grid stored as skewed parallelogram with wrapped boundaries, enabling rectangular indexing.

World Wrapping: Objects at world edges wrap to opposite side for continuous circular world.

Offset Storage: Each object stores precise x,y offsets from its hex cell center using fixed-point arithmetic.

Unconstrained Movement: Objects can move freely in any direction based on applied forces.

Precision: Fixed-point representation ensures deterministic positioning across platforms.

Cell Assignment: Objects remain assigned to their current hex cell until the final "set grid position" pass.

See cross-referenceDeterminism for fixed-point arithmetic implementation.

Vector Representation: Two-component velocity (x,y) stored with fixed-point precision.

Texture Storage: Velocities stored in GPU textures alongside position data.

Deterministic Updates: All velocity changes use fixed-point arithmetic for cross-platform consistency.

Frame Persistence: Velocity persists frame-to-frame unless modified by forces.

Applied Forces: Collision, cohesion, and spell forces modify velocity each frame.

Mass Response: Velocity change determined by F=ma (acceleration inversely proportional to mass).

Object Merging: Merged objects receive mass-weighted average velocity.

Damping: ⚠️ TBD - Optional velocity damping to prevent perpetual motion (needs playtesting).

Maximum Velocity: ~9.69 hex cells/second at 60fps based on two-layer force range guarantee.

Gameplay Range: Typical gameplay velocities 2-6 cells/second, providing margin for force application.

Range Guarantee: Two hex layers sufficient for all force interactions within speed limits.

Type-Based: Each object type has an associated mass value.

Layer Variation: Different layers may have different mass ranges (e.g., ground heavier than air).

Gameplay Impact: Mass affects force response and merging outcomes.

⚠️ NEEDS SPECIFICATION: Specific mass values for object types TBD through gameplay balancing.

Force Response: Heavier objects accelerate less from the same applied force (a = F/m).

Collision Interaction: Mass ratio between colliding objects affects their relative acceleration responses.

Momentum Conservation: When objects merge, velocities are mass-averaged to conserve total momentum:

See Object Merging for combination mechanics.

Position:

Velocity:

Properties:

Texture Layout: Data packed efficiently for GPU texture storage and access patterns.

Force Application Pass: Velocity updated by accumulated forces in "Apply Forces + Move" pass.

Position Update: Sub-grid offset updated by velocity in same pass.

Cell Assignment: Final hex cell determined in "Set Grid Position" pass.

See Pipeline Passes for multi-pass execution coordination.

Arithmetic: All position and velocity calculations use 16.16 fixed-point format.

Overflow Prevention: Calculations designed to prevent overflow in extreme cases.

Determinism: Integer-only operations ensure identical results across platforms.

Forces modify velocity each frame:

Object Merging - Mass-weighted velocity averaging when objects combine

Reactions - Type transformations affect mass assignment

Each layer maintains independent position and velocity data but shares the same movement mechanics.