Imported from mochi-cut/coalesce (src/components/hexes/AGENTS.md). Install upstream with npx skills add mochi-cut/coalesce --skill hexes. Copyright stays with the author.

Hex System Architecture

The Hex system is the core modular entity framework of the game. It allows players (and potentially enemies) to be constructed from interconnected hexagonal nodes that form a physical tree structure while maintaining a graph-like neighbor awareness.

Core Component: HexBase

HexBase (src/components/hexes/hex_base.gd) is the base class for all hex modules. It handles the state machine, physical attachment, and spatial relationships.

State Machine

• PICKUP: The hex is floating in the world. It attracts to the player when close.
  • Collision: Detects player (for pickup) and other hexes.
• ATTACHED: The hex is part of a larger structure (like the player). It moves relative to its parent.
  • Collision: Functions as a physical part of the entity (taking damage, blocking).
• DETACHED: A branch of hexes that has been severed. It floats away and will eventually despawn or reattach if it collides with a valid root structure.
  • Collision: Bounces off obstacles until it settles or reattaches.

Connectivity

• Tree Structure: Hexes are organized in a parent-child hierarchy (parent_hex, child_hexes). This handles the transformation hierarchy (Godot node structure).
• Neighbor Graph: Each hex maintains references to its 6 adjacent neighbors (neighbors[0..5]). This allows for grid-based logic (like infection or resource transfer) to flow across the structure regardless of the parent-child hierarchy.
• Slots: There are 6 attachment slots (directions) defined in HexUtils.

Life Cycle

1. Attachment: When a PICKUP hex touches a valid socket on the player, it calls attach_to(). It becomes a child node, sets its position offset, and calculates its local neighbors.
2. Damage/Severing: If a hex takes damage, it may be destroyed or detached.
   • Branch Detachment: If a hex is detached, it and all its children become DETACHED. They physically separate from the main body but maintain their relative structure.
3. Reattachment: A detached branch can reattach to the main body if the root of the branch collides with a compatible hex.

Hex Variants

HexNode

• Purpose: Basic structural unit.
• Behavior: Extends the player's physical body/hitbox. No special abilities.

HexSpikey

• Purpose: Offensive melee module.
• Behavior:
  • Deals damage to EnemyBase on contact.
  • Has limited durability (MAX_USES).
  • Immune to enemy damage while attached (acts as a shield/weapon).

HexCamera

• Purpose: Vision utility.
• Behavior:
  • Increases the camera zoom level when attached.
  • Restores zoom when detached/destroyed.

HexGrowth

• Purpose: Regeneration/Expansion.
• Behavior:
  • Periodically attempts to spawn new HexNode instances in its empty neighbor slots.

HexVirus

• Purpose: Conversion/Spread.
• Behavior:
  • Infects adjacent neighbors (excluding Core), replacing them with new HexVirus instances.
  • Maintains the structure of the converted branch.

HexDix

• Purpose: Loot/Consumable.
• Behavior:
  • Immediate Use: Does not attach. On pickup, it instantly spawns a cluster of random hexes around the player and disappears.

Utilities: HexUtils

src/util/hex_utils.gd defines the shared geometry constants.

• Geometry: Pointy-top hexagons.
• Directions: 6-direction enum (TOP_RIGHT, RIGHT, BOTTOM_RIGHT, BOTTOM_LEFT, LEFT, TOP_LEFT).
• Layout: Calculates pixel offsets for slots to ensure perfect tiling.