aether-shards/specs/BridgeCreation.spec.md

Crystal Spires: Light Bridge Specification

This document details the generation logic for "Light Bridges" (ID 20) connecting floating islands in the Crystal Spires biome.

1. Visual & Gameplay Goals

• Visuals: Translucent, glowing blue pathways projected between solid structures.
• Gameplay: Must be strictly walkable.
  • Max Step Height: 1 Voxel (Units cannot jump 2 blocks up).
  • Width: 1 voxel (Standard) or 2 voxels (Main thoroughfares).
  • Material: "Hard Light" (ID 20). Unlike stone, it has no "thickness" below it (floating).
  • Trajectory: Organic curves or arcs, not strict straight lines. Can defy gravity slightly (arcing up/down).

2. Generation Logic: Additive Bezier Arcs

Bridges are constructed using Quadratic Bezier Curves that strictly adhere to an Additive-Only rule.

Algorithm:

1. Anchor Selection (Edge-to-Edge):
   • Do not connect centers. Find the voxel on the perimeter of Island A that is closest to Island B.
   • Find the corresponding perimeter voxel on Island B (or the surface of a Spire).
2. Control Point Calculation:
   • Calculate the midpoint between Start and End.
   • Apply a randomized Vertical Offset (Arch) and Lateral Offset (Curve) to the midpoint to create the Bezier Control Point (P_1).
3. Voxelization (Non-Destructive):
   • Interpolate the curve.
   • Collision Scan: Before placing a voxel, verify that the target coordinate is Air (ID 0) AND the two voxels above it (Headroom) are Air (ID 0).
   • Placement: If and ONLY if the scan is clear, set the target coordinate to Bridge (ID 20).
   • Abort: If the scan finds any solid block in the path (Floor or Headroom), the bridge segment stops or the entire connection is recalculated.

3. Conditions of Acceptance (CoA)

CoA 1: Walkability (Gradient)

• Between any two adjacent voxels on the bridge path, the Y-difference must be <= 1.

CoA 2: Strictly Additive (No Destruction)

• The generator must never set a Voxel ID to 0 (Air) if it was previously non-zero.
• The generator must never set a Voxel ID to 20 (Bridge) if it was previously non-zero.
• Bridges must weave around existing geometry or fail; they cannot tunnel.

CoA 3: Headroom Validation

• Instead of carving headroom, the generator must validate headroom.
• A bridge voxel is only valid if Grid[y+1] and Grid[y+2] are already 0.

CoA 4: Connectivity

• The bridge must connect the edge of the start platform to the edge of the end platform without leaving a gap.

CoA 5: Global Reachability (No Orphans)

• After all bridges are generated, a Flood Fill check from the player spawn zone is mandatory.
• Any platform that is not reached by this fill is considered an "Orphan."
• Resolution: Orphans must be explicitly connected via a fallback teleport node. The Orphan will have one teleport node randomly placed on it, and the other will be randomly on a non-Orphan platform