Physics and collision geometry

GDCraft uses block-space geometry for voxel queries. AABB is an immutable double-precision axis-aligned bounding box; VoxelShape represents block collision/selection geometry. The code has both Godot-integrated body movement and a source-style entity movement path, so first identify which actor and caller a change affects.

Collision resolution path

1. Build or read the mover’s bounding box in block coordinates.
2. Expand it toward the requested movement to find candidate block shapes.
3. Resolve movement one axis at a time, clipping each component against intersecting shapes.
4. Compare requested and resolved movement to derive horizontal/vertical collision and grounded state.
5. Apply movement-specific follow-up such as step-up, fall distance, or block restitution in the owning entity path.

EntityCollision keeps collision resolution separate from entity lifecycle. Shapes and boxes are data/algorithms; WorldManager or its collision interface supplies candidate block collisions. That boundary makes the resolver reusable and keeps hot movement loops away from scene lookup policy.

Geometry conventions

Positions and dimensions are measured in blocks. Entity boxes are centered horizontally around the feet position and extend upward by entity height. AABB methods return new boxes instead of mutating shared bounds. Coordinate conversion must use the established floor-based voxel math, especially for negative values; integer truncation toward zero gives the wrong occupied block below the origin.

Collision shape, selection outline, and rendered mesh represent different questions. A slab can have a partial collision volume while its mesh has textured faces; a raycast target can use a selection shape. Keep these data separate when changing shape behavior.

Godot boundary and verification

Many live mobs still move through CharacterBody3D and Godot physics, while the newer Entity path resolves against ICollisionGetter and VoxelShape. Check docs/PORTING_PLAN.md before extending source-style movement to another actor. Compare collision outcomes at edges, corners, steps, ceilings, and negative coordinates in the owning path.

Start with src/Phys/AABB.cs, VoxelShape.cs, Shapes.cs, EntityCollision.cs, and the actor’s Move/physics callback. Avoid changing geometry and movement response in the same broad patch unless the behavior requires both.