Skip to content

perf(physics): batch native query and contact results - #24

Merged
GuoLei1990 merged 2 commits into
mainfrom
codex/engine3102-native-queries
Oct 18, 2026
Merged

GuoLei1990 merged 2 commits into
mainfrom
codex/engine3102-native-queries

Conversation

@GuoLei1990

@GuoLei1990 GuoLei1990 commented Oct 18, 2026 •

Copy link
Copy Markdown
Member

Scene queries currently cross the WASM/JS boundary for every filter candidate and every hit property, exposing temporary Embind handles to the engine. Contact extraction has the same ownership problem.

This change gives each scene one native query owner with reusable touch and result buffers. Queries filter collision layers and public query participation natively and return packed borrowed value views; contact callbacks deliver shape IDs and packed contact values that the engine copies before the next callback. All touch chunks remain observable, including more than 256 results, and 32-bit shape identifiers retain full precision.

Public query participation lives in PxShape query filter data (word0 == 0 means enabled, including default shapes). It must not clear eSCENE_QUERY_SHAPE: character-controller movement uses native scene queries for collision detection. The ordinary-shape and controller setters share one metadata helper; controller creation replays the setting from the source shape. Simulation and controller collision behavior remain independent of public query exclusion.

The internal binding contract changes: PxSceneQueries replaces the old query/filter/hit-wrapper APIs, and contact callbacks now receive (shape0ID, shape1ID, contacts). The paired consumer is galacean/engine#3102, engine commit 35b799fc9298cb2cd23eb5a84c26d740c3f4096c. Existing published assets must remain immutable; publish a new standard/SIMD JS+WASM set and update engine defaults together before merging/releasing the consumer.

Validation:

  • ./build.sh: standard WASM and SIMD builds passed.
  • Paired engine module and all package declaration builds passed.
  • Chromium suites: 278/278 passed with explicit standard mode and 278/278 with explicit SIMD mode. Coverage includes 257+ hits/overlaps, full 32-bit IDs, dynamic layers, nested output callbacks, query settings, cloning, controllers, collision events, pooled output identity across scenes, and query-disabled walls still blocking controller movement.
  • Original-PR runtime comparison verified the same controller-wall collision behavior for both public query settings.
  • Engine ESLint, Prettier, and both repository diff checks passed.

The paired public raycastAll API returns a boolean and optionally fills a caller-owned array. That array and its hit/vector objects are reused, including across scenes and caller edits; another query using the same output array overwrites those objects. Resource GC and scene destruction release hidden output caches without mutating caller-held results. Calls without output perform only a hit test. Native callback snapshots still allocate, so the complete path does not promise zero allocations.

Local build runtime SHA-256 values:

695b12588ffb22dd416c70ab34fdb44c9f83bffb136e82cb7c56132245b5b2e2  physx.release.js
e3a44989c050908ddd614d4cef45faab6dc5dd0a3a0a3dbe36df3a2183116a13  physx.release.wasm
3ad8df3e3deec73bcb5c955504d5f63c950d4e51aa6d871b0e17116370738077  physx.release.simd.js
b377805766452cb7a1456db276670d4b13b4e1a8735aa1f4cbea0c129988a4a3  physx.release.simd.wasm

Own query filters and reusable result buffers per scene. Expose packed value views instead of per-hit Embind handles, and filter collision layers inside native queries.

Copy contact values from callback-owned buffers and apply scene-query flags to controller shapes. Preserve all touch chunks and full 32-bit shape identifiers.

Validation: standard and SIMD native builds; paired engine browser suites, 270 tests per runtime.
Store public query exclusion in per-shape filter data. Keep native scene-query flags enabled because controller movement uses native queries for collision detection.

Expose the same query setting for ordinary and controller shapes without affecting simulation or movement collisions. Standard and SIMD builds and paired 272-test engine suites passed.
@GuoLei1990
GuoLei1990 merged commit 98fb302 into main Oct 18, 2026
@GuoLei1990
GuoLei1990 deleted the codex/engine3102-native-queries branch October 18, 2026 15:09
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant