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/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