Add Box3D upstream research notes; note godot-box3d is single-threaded

Engine notes from the eval session (Apple Silicon 24-P-core worker cap, the
benchmark harness, binding gaps, provenance), linked from the README.
Annotated with a verified fact: the binding hardcodes workerCount=1, so the
E-core trap cannot trigger through Godot until it grows a task system.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
This commit is contained in:
m3ultra 2026-08-06 09:03:34 +10:00
parent 804e4c0fb8
commit 5fa6bbf67b

View File

@ -33,6 +33,12 @@ sysctl -n hw.ncpu # 32 — do NOT use this
Within the performance cores the threading scales well: upstream's M2 Air `joint_grid` figures
are 1,089 ms single-threaded → 309 ms on 4 threads (**3.52×**).
> **Status in godot-box3d (verified 2026-08-06 against the commit vendored in `bin/`):** the
> binding hardcodes `def.workerCount = 1` in `src/spaces/box3d_space_3d.cpp` and wires no task
> system, so Godot runs Box3D **single-threaded** — there is no worker setting to cap, and the
> E-core trap can't trigger through Godot today. This section applies to the raw benchmark
> harness below, and becomes load-bearing the day the binding grows threading.
Caveat on the table above: it is one scene (8,002 bodies / 40,444 contacts), best-of-4 runs, and
the low-thread-count rows of that particular sweep were lost to a truncated capture. The
*direction* is unambiguous and reproduces; treat the exact millisecond figures as indicative.