AIZone

A soft circular boundary that eases a wandering agent back toward a zone center instead of slamming it into a wall.

What it does

AIZoneSystem keeps a ground agent inside a circular region — a defender's half-pitch, a sentry's patrol area, a boss arena — without the bang-bang jitter a hard wall produces. Each frame it reads the agent's live world position from the renderer adapter (getMeshWorldPosition), feeds the XZ position to a pure deterministic core, and only when the agent is outside the radius nudges the mesh back toward center with setMeshPosition. The core measures horizontal distance from center and ramps a [0,1] steering weight linearly across a softness band: zero inside the zone, small just past the edge, saturating at 1 far outside — so the agent eases back rather than snapping to the rim. The System learns each agent's mesh handle from meshprimitive.created (plus a sweep at initialize time for siblings whose handle already exists), mirrors live panel edits into the core before each frame, and emits aiZone.steered on every frame it applies a correction so HUDs and viz panels can draw the nudge. The boundary math holds no engine references; downstream consumers subscribe to the steer event rather than reading the component.

Use it in a scene

bjs download scene AIZone

{
  "Sentry": {
    "tags": ["enemy"],
    "components": {
      "MeshPrimitive": {
        "primitive": "capsule", "radius": 0.5, "height": 1.6, "position": [9, 0.8, 0]
      },
      "AIZone": {
        "center": [0, 0, 0], "radius": 6, "softness": 0.5, "strength": 1, "returnSpeed": 4
      }
    }
  }
}

Props

• center ([x, y, z], default [0, 0, 0]) — world-space zone center on the XZ plane; the Y coord is ignored by the math.
• radius (number, default 6) — zone radius in world units. Inside this distance the pull is zero.
• softness (number, default 0.5) — width of the ramp as a fraction of radius. 0.2 is a steep cliff at the edge; 0.8 is a gentle gradient that builds across a wide strip.
• strength (number, default 1) — scalar applied to the normalized ramp before it becomes weight.
• returnSpeed (number, default 4) — world units per second the mesh moves inward when outside, multiplied by weight and dt.

Events

• Emits aiZone.steered (AIZoneEvents.STEERED) on every frame the core returns a non-zero weight, with { entityId, directionX, directionZ, weight, distance } — directionX/directionZ is the horizontal unit vector pointing back toward center.
• Listens for aiZone.recenter (AIZoneInputEvents.RECENTER) — { entityId?, position? }. It teleports the matching agent to an absolute XZ via setMeshPosition; with no position it drops the agent on the floor at the zone center. Omit entityId to recenter every zone-bound agent.

Dependencies

MeshPrimitive — supplies the mesh the System steers. The System caches each agent's mesh handle from the meshprimitive.created event and reads/writes its world position through the adapter; an agent without a mesh handle is skipped.

Notes

• An agent with no cached mesh handle is skipped silently — the meshprimitive.created listener and the initialize-time sweep are the only ways a handle enters the map, so an AIZone on an entity without MeshPrimitive does nothing.
• The correction only moves the agent inward; it never adds outward push, so an agent already inside the zone is left entirely free.
• softness scales with radius, not absolute units: the band width is radius * softness, so widening the zone widens the easing strip proportionally.
• Live panel edits land because the System calls setParams(comp.params) before every frame's update, so retuning radius or softness in the tuning panel takes effect immediately.