Skip to content

A fast 2D and 3D game engine — TypeScript SDK, C++/WebAssembly core, visual editor. Ship one project to web, desktop, WeChat MiniGames, playable ads, and native Android / iOS.

fix(nav): honor final arrival radius while steering bodies

yhh136e964b5ef3
diff --git a/CHANGELOG.md b/CHANGELOG.md
index 9606c65bd..30a2323a1 100644
--- a/CHANGELOG.md
+++ b/CHANGELOG.md
@@ -18,6 +18,8 @@ published separately; it ships inside the editor.
- **Couriers can pass occupied intermediate grid waypoints.** A parked agent no longer traps a follower at an intermediate cell centre. The follower may join the next route segment only when its full body fits the connection through the static grid; final destinations still use the existing arrival rules.
+- **Crowd followers honor the configured final arrival radius.** Intermediate waypoint tolerances no longer complete a route before its final goal is within the agent's stop distance. Kinematic followers and character steering retain their intermediate reach behavior; zero arrival radius continues toward the actual endpoint.
+
- **Finished Web audio handles release their runtime references.** Stopped and naturally completed voices drop decoded buffers, sources, pool nodes and contexts after releasing their pool slot. Retaining a finished handle keeps its ID and duration available without pinning PCM; terminal controls remain harmless, while paused voices retain the state needed to resume and natural completion still notifies once.
## [0.87.0] - 2026-10-15
diff --git a/sdk/src/ai/nav/NavPlugin.ts b/sdk/src/ai/nav/NavPlugin.ts
index c35d822a9..1bbb3c5ff 100644
--- a/sdk/src/ai/nav/NavPlugin.ts
+++ b/sdk/src/ai/nav/NavPlugin.ts
@@ -458,8 +458,12 @@ function walkAmongBodies(
}
while (rt.index < rt.waypoints.length) {
const wp = rt.waypoints[rt.index]!;
- const reach=rt.recoveringStart && rt.index===0 ? 0.1 : Math.max(agent.speed*dt*1.5,WAYPOINT_REACH);
- if (planeDistance(wp, pos, flat) > reach) break;
+ const final = rt.index === rt.waypoints.length - 1;
+ const reach = final
+ ? Math.max(0, agent.arriveRadius)
+ : rt.recoveringStart && rt.index === 0 ? 0.1 : Math.max(agent.speed * dt * 1.5, WAYPOINT_REACH);
+ if (planeDistance(wp, pos, flat) > reach
+ && !(final && agent.arriveRadius <= 0 && sameGroundPoint(wp, pos, flat))) break;
rt.index++;
rt.recoveringStart=false;
}
@@ -501,6 +505,12 @@ function planeDistance(a: Vec3, b: Vec3, flat: boolean): number {
return Math.hypot(a.x - b.x, (flat ? a.y : a.z) - (flat ? b.y : b.z));
}
+/** A native Transform stores Float32 coordinates, including at a zero-radius goal. */
+function sameGroundPoint(a: Vec3, b: Vec3, flat: boolean): boolean {
+ return Math.fround(a.x) === Math.fround(b.x)
+ && Math.fround(flat ? a.y : a.z) === Math.fround(flat ? b.y : b.z);
+}
+
/**
* Point a character controller at the next waypoint and let its own solver move
* it. Only the horizontal axes are written — the vertical one is the world's, and
@@ -520,7 +530,9 @@ function steerCharacter(
const reach = Math.max(agent.speed * dt * 1.5, WAYPOINT_REACH);
while (rt.index < rt.waypoints.length) {
const wp = rt.waypoints[rt.index]!;
- if (Math.hypot(wp.x - pos.x, wp.z - pos.z) > reach) break;
+ const tolerance = rt.index === rt.waypoints.length - 1 ? Math.max(0, agent.arriveRadius) : reach;
+ if (Math.hypot(wp.x - pos.x, wp.z - pos.z) > tolerance
+ && !(rt.index === rt.waypoints.length - 1 && agent.arriveRadius <= 0 && sameGroundPoint(wp, pos, false))) break;
rt.index++;
}
diff --git a/sdk/tests/nav-step.test.ts b/sdk/tests/nav-step.test.ts
index 3673dd994..b97714c6b 100644
--- a/sdk/tests/nav-step.test.ts
+++ b/sdk/tests/nav-step.test.ts
@@ -77,6 +77,38 @@ function openNav(width = 10, height = 3, cellSize = 10): Navigation {
}
describe('stepNavigation', () => {
+ it.each([0, .5, 3, 5])('crowd followers honor a final arrival radius of %s', arriveRadius => {
+ const world = new FakeWorld();
+ const e = world.spawnAgent(20, 150, {speed:78, radius:8, arriveRadius,
+ repathInterval:0, hasTarget:true, targetX:270, targetY:150});
+ world.spawnAgent(245, 190, {speed:0, radius:8});
+ const nav = openNav(32, 32, 10), runtimes = new Map<Entity, AgentRuntime>();
+ for (let frame=0;frame<600 && !world.agent(e).arrived;frame++) {
+ stepNavigation(world, nav, 1/60, runtimes);
+ }
+ expect(world.agent(e).arrived).toBe(true);
+ const p=world.pos(e);
+ expect(Math.hypot(p.x-270,p.y-150)).toBeLessThanOrEqual(arriveRadius+1e-6);
+ });
+ it('zero-radius arrival tolerates only native coordinate rounding', () => {
+ const world=new FakeWorld(), nav=openNav(32,32,10);
+ const target={x:270.123456,y:150.123456,z:0};
+ const e=world.spawnAgent(20,150,{speed:78,radius:8,arriveRadius:0,repathInterval:0,
+ hasTarget:true,targetX:target.x,targetY:target.y});
+ world.spawnAgent(245,190,{speed:0,radius:8});
+ vi.spyOn(nav,'queryWorldPath').mockReturnValue({path:[{x:20,y:150,z:0},target],status:'complete',reason:'none'});
+ const set=world.set.bind(world);
+ world.set=(entity,component,data)=>{
+ if(component===Transform){const tf=data as {position:{x:number;y:number;z:number}};
+ tf.position.x=Math.fround(tf.position.x);tf.position.y=Math.fround(tf.position.y);}
+ set(entity,component,data);
+ };
+ const runtimes=new Map<Entity,AgentRuntime>();
+ for(let frame=0;frame<600&&!world.agent(e).arrived;frame++)stepNavigation(world,nav,1/60,runtimes);
+ expect(world.agent(e).arrived).toBe(true);
+ expect(world.pos(e)).toEqual({x:Math.fround(target.x),y:Math.fround(target.y)});
+ });
+
it('walks an agent to its target on an open grid and marks arrival', () => {
const nav = openNav();
const world = new FakeWorld();
@@ -297,6 +329,15 @@ describe('an agent with a body', () => {
expect(world.character(entity).velocity.y).toBe(-320);
});
+ it.each([0, 2])('keeps steering a character outside its final radius of %s', arriveRadius => {
+ const {world, nav, entity} = walker();
+ const agent=world.agent(entity); agent.arriveRadius=arriveRadius;
+ world.place(entity,73,0);
+ stepNavigation(world,nav,1/60,new Map());
+ expect(world.agent(entity).arrived).toBe(false);
+ expect(world.character(entity).velocity.x).toBeGreaterThan(0);
+ });
+
it('stops the body when it arrives', () => {
const { world, nav, entity } = walker();
const runtimes = new Map<Entity, AgentRuntime>();
diff --git a/tools/releaseNotes.mjs b/tools/releaseNotes.mjs
index 75ef34f57..893ff2c07 100644
--- a/tools/releaseNotes.mjs
+++ b/tools/releaseNotes.mjs
@@ -30,6 +30,8 @@ export const NOTES_FLOOR = 'v0.65.0';
export const NOTED = {
'fix(nav): pass occupied intermediate grid waypoints safely':
{ note: 'Couriers can pass occupied intermediate grid waypoints.' },
+ 'fix(nav): honor final arrival radius while steering bodies':
+ { note: 'Crowd followers honor the configured final arrival radius.' },
'test(nav): sample trusted keys before paused frame cleanup':
{ internal: 'Workshop acceptance steps trusted keyboard input in its event task so paused animation frames cannot erase it before sampling; movement traces retain final agent positions for failure diagnosis.' },
'test(nav): cover authored workshop obstacle layouts':