M1.1.12 — Forge 3D: the kinematic character controller

bench/results/forge_3d_character.md

@@ -0,0 +1,27 @@
+# forge_3d kinematic character controller bench
+
+- Build mode: ReleaseFast
+- 2000 calls per mode per rep, 8 INTERLEAVED reps, best rep reported
+- Anti-DCE checksum: 31917.672
+
+| mode | ns/call | calls/s | calls per 16.67 ms frame |
+|---|---|---|---|
+| moveCharacter / plane | 212.0 | 4716981 | 78616 |
+| moveCharacter / stairs | 2235.5 | 447327 | 7455 |
+| moveCharacter / wall | 1764.5 | 566733 | 9446 |
+| moveCharacter / mesh floor | 7979.0 | 125329 | 2089 |
+| resizeCharacter | 203.0 | 4926108 | 82102 |
+
+**Reported, not gated.** No envelope is pre-registered: this is the first measurement of
+this path, and registering a bound before measuring its baseline is the failure mode
+recorded at M1.1.8.
+
+Runs are INTERLEAVED — every rep runs all five modes in sequence and the best rep per mode
+is kept — so a thermal ramp or a scheduling burst lands on all five rather than on
+whichever happened to be measured while it passed. Best-of-N per mode cannot resolve a gap
+under about 5 %, which is the size of the gaps between these rows.
+
+The five rows are five different code paths, not five scales of one: the plane row runs the
+ground sweep alone, the stairs row arms the climb's three sweeps, the wall row arms the
+slide, the mesh row puts the ground sweep and the contact fallback on a `.triangle_soup`
+shape, and `resizeCharacter` is the only row that allocates.

build.zig

@@ -1015,6 +1015,34 @@ pub fn build(b: *std.Build) void {
     );
     forge_mesh_bench_step.dependOn(&forge_mesh_bench_run.step);
 
+    // -------------------------------- M1.1.12 forge character controller bench --
+    //
+    // `moveCharacter` on a plane / stairs / a wall / a triangle mesh, plus
+    // `resizeCharacter`, INTERLEAVED across reps. Writes
+    // `bench/results/forge_3d_character.md`. REPORTED, not gated — no envelope is
+    // pre-registered (bench header).
+    const forge_char_bench_module = b.createModule(.{
+        .root_source_file = b.path("bench/forge_3d_character.zig"),
+        .target = target,
+        .optimize = optimize,
+        .link_libc = true,
+    });
+    forge_char_bench_module.addImport("forge_3d", forge_3d_module);
+    forge_char_bench_module.addImport("weld_forge", forge_api_module);
+    const forge_char_bench_exe = b.addExecutable(.{
+        .name = "forge-character-bench",
+        .root_module = forge_char_bench_module,
+    });
+    b.installArtifact(forge_char_bench_exe);
+    const forge_char_bench_run = b.addRunArtifact(forge_char_bench_exe);
+    forge_char_bench_run.step.dependOn(b.getInstallStep());
+    if (b.args) |args| forge_char_bench_run.addArgs(args);
+    const forge_char_bench_step = b.step(
+        "bench-forge-character",
+        "Run the M1.1.12 forge character controller bench (five paths interleaved, writes bench/results/forge_3d_character.md)",
+    );
+    forge_char_bench_step.dependOn(&forge_char_bench_run.step);
+
     // -------------------------------------- M1.0.5 scene loader bench --------
     //
     // `loadFromBytes` on a ~10k-entity image synthesized in-bench via the

src/foundation/math/math.zig

@@ -33,6 +33,17 @@ pub const CrossOutcome = vec.CrossOutcome;
 /// Whether a triangle is EXACTLY flat, decided in integer arithmetic. THE classifier: callers that
 /// must not admit a flat triangle ask this, never `triangleCross`.
 pub const triangleIsFlat = @import("exact.zig").triangleIsFlat;
+/// A vector PARALLEL to the exact area vector of three points, or `null` when that vector is
+/// EXACTLY zero — the exact tier `triangleIsFlat` is written on, exposed for callers that need the
+/// DIRECTION together with that exact null.
+///
+/// Re-exported at M1.1.12 for its second consumer: the character controller's edge slide, whose
+/// direction is `n₁ × n₂` and whose `null` must mean "the two normals are exactly parallel" and
+/// nothing weaker. The tiered `triangleCross` cannot serve there — its `.direction` comes from the
+/// first float tier that forms a non-zero vector, so on exactly parallel normals it returns a
+/// rounding residue that reads as a valid crease. That is the very confusion §1.11.17 records as
+/// having nearly shipped.
+pub const triangleCrossDirection = @import("exact.zig").triangleCrossDirection;
 /// The power-of-two exponent that reduces three points below unit magnitude.
 pub const pow2ReductionExponent = vec.pow2ReductionExponent;
 

src/foundation/math/vec.zig

@@ -125,10 +125,43 @@ pub fn Vec(comptime N: usize, comptime T: type) type {
         /// `surfaceArea`, `rayInterval`, `inflate` and `overlapsHalfSpace` — pure vector
         /// arithmetic, no threshold, no physical semantics.
         pub fn normalizeScaled(self: Self) ?Self {
+            const both = self.unitAndLength() orelse return null;
+            return both.unit;
+        }
+
+        /// The unit direction AND the length, from ONE reduction by the largest absolute component.
+        ///
+        /// **Three questions, one reduction, and that is the whole point.** A caller that asks
+        /// `lengthSq() == 0` to test emptiness, `@sqrt(lengthSq())` for the length and this for the
+        /// direction has asked three times and gets three different domains: the square UNDERFLOWS for
+        /// a denormal vector, so a real displacement reads as empty and is dropped, and it OVERFLOWS
+        /// for a large one, so the length comes back infinite and poisons whatever consumes it. The
+        /// reduction has neither failure, and returning both quantities from it is what stops a caller
+        /// from reconstructing one of them the unsafe way.
+        ///
+        /// `null` at EXACTLY zero — the largest absolute component is zero exactly when all three are —
+        /// which is the emptiness test the caller needs, exact and without a threshold.
+        ///
+        /// **`length` is itself optional, because a DIRECTION always exists where a LENGTH need not.**
+        /// The reduction protects the intermediate square, but the final product `largest · ‖reduced‖`
+        /// can still leave the range: two components at `0.75 · floatMax` have a norm of about
+        /// `1.06 · floatMax`, which is not representable at either precision. Answering `inf` there
+        /// would be answering a number that is not the length, and it propagated — measured, it became
+        /// an infinite sweep bound and tripped a kernel's finiteness assert one call later.
+        ///
+        /// So the unrepresentable case is an ANSWER this function gives, not an assumption each caller
+        /// re-derives. The direction is unaffected: it is scale-free by construction, which is exactly
+        /// why the two are returned separately rather than as one vector.
+        pub fn unitAndLength(self: Self) ?struct { unit: Self, length: ?T } {
             const largest = @reduce(.Max, @abs(self.data));
             if (largest == 0) return null;
             const reduced: Self = .{ .data = self.data / @as(Simd, @splat(largest)) };
-            return reduced.scale(1 / reduced.length());
+            const reduced_length = reduced.length();
+            const full = largest * reduced_length;
+            return .{
+                .unit = reduced.scale(1 / reduced_length),
+                .length = if (std.math.isFinite(full)) full else null,
+            };
         }
 
         /// Largest absolute component. Zero exactly when every component is zero.

src/modules/forge/api/root.zig

@@ -31,7 +31,11 @@ pub const EntityId = types.EntityId;
 pub const BodyId = types.BodyId;
 /// Opaque collision-shape handle (`u32`, same packing as `BodyId`).
 pub const ShapeId = types.ShapeId;
-/// The `index:24 | generation:8` packing shared by `BodyId`/`ShapeId`.
+/// Opaque character-controller handle (`u32`, same packing as `BodyId`).
+pub const CharacterId = types.CharacterId;
+/// The `index:24 | generation:8` packing shared by `BodyId`, `ShapeId` and
+/// `CharacterId`, and the `PackedId.dead` all-ones reservation those three use for
+/// "no handle".
 pub const PackedId = types.PackedId;
 /// Simulation class of a body (static / kinematic / dynamic).
 pub const BodyType = types.BodyType;
@@ -44,6 +48,18 @@ pub const BodyDescriptor = types.BodyDescriptor;
 /// Physics pose (position + rotation, no scale).
 pub const Transform = types.Transform;
 
+// --- Character controller (`engine-physics-forge.md` §1.12) ---
+
+/// Everything needed to create one character controller. A controller is VIRTUAL —
+/// it takes part in no solver pass, and its pose is written by `moveCharacter` alone.
+pub const CharacterDescriptor = types.CharacterDescriptor;
+/// The TERNARY ground verdict. Zig mirror of the Etch enum owned by
+/// `engine-movement.md` §2 — same order, same values.
+pub const GroundState = types.GroundState;
+/// Result of one `moveCharacter`: the resolved BASE position plus the five ground
+/// quantities, of which `ground_state` is the discriminator.
+pub const CharacterMoveResult = types.CharacterMoveResult;
+
 // --- Queries (the complete frozen family, `engine-tier-interfaces.md` §1) ---
 
 /// Number of object layers a query mask can address; `addBody` rejects a body