[jonit-dev]

Implementation

Commit a899a82ea304b6eacdd074ff2318233fc09feaa0 adds actual Yuka Vision integration, caller-owned occlusion queries, immutable last-seen memory, simulation-time expiry and executable regression tests.

Code: examples/integrations/perception/. This is editable, opt-in game source. Yuka answers the view cone, the existing world answers occlusion, and existing navigation/physics remain the only movement owner. No EntityManager, second loop or mandatory core AI dependency is introduced.

Verified repair — 2026-09-26

Commit 38dde724ddd74e7737efb78de5c0dc3cd4cde883 fixes a real validation bug: sparse position arrays bypassed Array.some and could corrupt last-seen memory or advance its clock. All three coordinate slots are now validated before state mutation. Two added regressions failed on the old validator and pass after the fix. They cover missing coordinates, sparse arrays, null and undefined. Package lint repairs preserve existing rules; the concurrent develop merge is retained.

Executed: complete npm test passes the pinned TypeScript 5.9.3 strict build, 12 policy contracts and 3 real Yuka/Three integration tests: 15 passed, 0 failed. Biome 1.9.4 and git diff --check pass. Dedicated Integration perception rerun is green: https://github.com/ThreeNativeHQ/threenative/actions/runs/36214585234 . This supersedes the earlier local dependency limitation.

Remaining: playable navigation/replay integration, direct-baseline comparison, browser/native/Android traces, complete repository checks and independent review. Keep draft/experimental; no unexecuted platform requirement is marked complete.

Run npm install --ignore-scripts && npm test in the example directory. PRD: docs/PRDs/threejs-integrations/PRD-threejs-yuka-perception.md.

Checklist — mirrors PRD

Phase 1 — baseline and dependency admission

• Search existing navigation, ray-query, scheduling and replay capabilities.
• Implement the direct state-machine baseline and pin its expected event trace.
• Pin and audit only the Yuka modules needed for the comparison.
• Execute ten dependency-free policy tests after observing the stub fail: 10 passed, 0 failed on Node 22.16.0.

Phase 2 — optional perception example

• Add failing occlusion, memory-expiry and single-movement-owner tests.
• Implement the Yuka candidate without adopting its world or navigation architecture.
  Three real Yuka/Three integration tests now pass, including occlusion, authored-axis transforms and unchanged movement ownership.
• Pass replay, pause/resume, target-deletion and cleanup tests.
• Strict-check search.ts with locally available TypeScript 5.8.3: exit 0.

Phase 3 — playable platform proof

• Pass the patrol/search browser WebGPU playtest.
• Pass the same input/event trace on desktop native, naming the actual OS and adapter.
• Pass the same input/event trace on Android, naming the executed lane.
• Compare behavior, code and cost against the direct state-machine baseline.

Phase 4 — ship as game source

• Prove a normal core-only game loads no Yuka code.
• Document editable policy and the existing physics/navigation integration.
• Run repository checks and keep the smaller solution if the donor adds no value.
• Complete a separate code review and synchronize PRD, PR and progress label.

Acceptance criteria

• The example demonstrates occlusion-aware acquire, last-seen search and expiry.
• Search does not consult an occluded target's live position.
• Replay uses simulation time and reproduces the expected decision events.
• Exactly one existing movement/physics path controls the NPC body.
• Gameplay policy stays in editable source and core does not depend on Yuka.
• Browser WebGPU evidence is recorded.
• Desktop-native evidence is recorded.
• Android evidence is recorded.

[jonit-dev]

Executed dependency-backed verification

The focused Integration perception workflow passed on implementation commit a899a82ea304b6eacdd074ff2318233fc09feaa0: https://github.com/ThreeNativeHQ/threenative/actions/runs/36202145809

The actual npm test command passed: strict TypeScript build, the 10 policy contracts, and integration tests importing real Yuka Vision and Three.js raycasting. These cover wall occlusion, copied last-seen memory, the authored forward axis/range and keeping body movement outside the adapter.

The full repository CI remains queued. This does not prove a complete navigation encounter, GPU/native/Android behavior or an improvement over direct gameplay code. Those acceptance gates remain open and this PR stays draft.