Skip to content

Public API not ported: contact data by id, constraint tuning getter, world counts, capacity, host hooks, dumps, debug draw #163

Closed

Description

@nicolas-maman

An audit of e77352c's public header (include/box3d/*.h, 592 B3_API functions) against the port, after #149. #148 covered the API the reference's tests exercise. This covers the rest: public API that no reference test reaches, but a host reaches for.

Getters and queries

  • b3Contact_GetData(contactId): one contact's shapes and manifold by its id. We have contact_is_valid and the per-body and per-shape contact data, but not the per-id getter.
  • b3Joint_GetConstraintTuning: the setter is ported, the getter is not.
  • b3Shape_GetMeshMaterialCount.
  • b3GetWorldCount and b3GetMaxWorldCount.
  • b3GetVersion, and b3IsDoublePrecision, which is true here: world positions are double, as in the reference's large-world build.
  • b3IsAVX2Available: the CPU query, which is half of SIMD width chosen at run time: AVX2 when the CPU has it, one binary for every CPU (b3SetSIMDWidth) #156.
  • b3World_GetMaxCapacity: the most shapes, bodies and contacts the world has held. The reference updates it at every step and carries it in the snapshot, so a host can size the next world's def and avoid run-time growth. Our Capacity lacks the two body counts.
  • b3Hash: the reference's djb2 for determinism tests.

Host hooks

  • b3SetAllocator(alloc, free): every allocation through basics.alloc goes to the host's functions.
  • b3SetLogFcn: the scheduler's task-overflow message and the solver's stage report go through it, instead of println.
  • b3SetAssertFcn: aephysics checks its inputs and returns rather than asserting. Its one hard stop, the scheduler's task overflow, calls the host's function before it aborts.

Debug output

  • b3World_DumpMemoryStats: bytes by part of the world, through the log.
  • b3World_DumpShapeBounds: every shape's box of one body type, to a file.

Debug draw

  • b3DebugDraw and b3DefaultDebugDraw: the callbacks (shape, segment, transform, point, sphere, capsule, bounds, box, string) and the options (shapes, joints and their extras, bounds, mass, sleep, body names, contacts and their anchors, features, normals and forces, graph colours, islands, drawing bounds, force and joint scales).
  • b3World_Draw(world, draw, maskBits), with each joint kind's drawing.
  • The world def's debug-shape callbacks: createDebugShape when a shape is made, destroyDebugShape when it goes, the user shape kept on the shape and passed to DrawShapeFcn.
  • b3RecPlayer_DrawFrameQueries and b3RecPlayer_SetDebugShapeCallbacks, which the recording's query store (Recorded queries and the name cache (#149, third part) #162) was built to feed.

Not ported, with reasons

Each lands with a test that compares against the reference's behaviour where the reference has one (its debug-draw counts, its memory stats categories, its capacity after a step).

Activity

  1. nicolas-maman commented on Oct 9, 2026

    @nicolas-maman
    CollaboratorAuthor

    Two findings from porting:

    • b3World_DumpShapeBounds is declared in e77352c's box3d.h but defined nowhere in its sources, so there is nothing to port. It is left out, and noted as declared-only.
    • b3Counters has more than the audit listed: byteCount, arenaCapacity, taskCount, manifoldCounts and the time-of-impact iteration maxima. They come with this issue too.

    The work lands in two PRs. The first has the getters, capacity, host hooks (every engine allocation routed through the host's allocator: the scheduler, its semaphore and the ragdoll layer as well), the memory dump and the counters. The second has debug draw.

  2. added a commit that references this issue on Oct 9, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Metadata

Metadata

Assignees

No one assigned

    Labels

    No labels
    No labels

    Type

    No type

    Projects

    No projects

      Milestone

      No milestone

      Relationships

      None yet

      Development

      No branches or pull requests

      Issue actions