Web Games
←back to documentation

Web Games

Ship your own HTML, ThreeJS and JavaScript game on Portals with player identity, multiplayer, coins, avatars, and server logic.

Guardian Avatars Changelog

Every release of the Guardian avatar SDK is archived immutably and can be pinned from portals.json with { "guardiansSdk": "x.y.z" }. This page lists what each version changed. Versions that are not listed were never released: the number was skipped, so pinning it fails the publish.

Names in backticks are exports or options of @portals/avatars; see the Guardian Avatars guide for how to use them. A version listed with two entries was cut on two parallel branches on the same day; the first version that contains both is called out below it.

0.46.13 — 2026-09-18

  • First-person camera faced the wrong way: the eye was placed half a turn from the heading the movement code uses, so W walked backwards and A/D were swapped. The view now matches getFlatForward in both camera modes. Games that flipped the camera themselves after the SDK placed it should drop that workaround when pinning this version.

0.46.12 — 2026-09-04

  • Finishing a ledge climb no longer snaps the body back to where the jump started when the final stand-point check fails. The character lands at the target, is pushed out of anything it grazes, and the normal collision loop takes over. Fixes the "teleported back to the jump" reports.

0.46.11 — 2026-09-03

  • Ledge probing runs every Nth airborne frame instead of every frame, with the first airborne frame always probing, so a jump at a ledge still catches it. New controller option; 1 restores per-frame probing.
  • Falling grabs only take ledges within 80° of the heading (was 150°), so the body no longer spins around after a grab. Rising grabs keep 55°.
  • The stand point on top of the ledge is found before the climb plays, not after. Irregular tops aim the climb at a nearby spot that fits and refuse the grab when none does.
  • The camera eases in behind the body over the climb instead of snapping, and only for moderate turns.

0.46.0 — 2026-08-29

  • Ledge climbs are gated on a capsule sweep of the path the root will travel: up the wall and over the lip. New optional collision hook sweepCapsule(from, to, radius, height); SceneCollider supplies one, and without it the controller steps depenetrate along the path. A blocked path refuses the grab.
  • After landing, the stand point is verified again. A body that is not free there moves to the nearest standable spot on the ledge, or falls back from where it grabbed.

0.45.0 — 2026-08-29

  • Touch controls gain a fullscreen toggle next to the camera toggle wherever the browser offers the Fullscreen API. iPhone Safari has no element fullscreen, so the button is absent there.

0.44.0 — 2026-08-28

  • Ledge climb safety: the climb drives the root without collision, so the landing is now checked when the body is handed back. Depenetration fixes a landing that clips the ledge's back wall; a landing still inside the level is undone immediately by the stuck rescue instead of a second later.
  • For one second after a climb the buried watchdog treats a walkable face overhead as proof of burial on its own.
  • The buried check no longer misreads a swimmer, or a body under a single-sided slope with its head above the surface, as buried.

0.43.0 — 2026-08-26

  • Rigid wearable attachments fixed. A mesh-bearing node authored under a bone such as mixamorig:Head is followed as one logical part, even when the loader expands it into a multi-primitive group, and its authored local transform is preserved without attaching the wearable's duplicate armature. attachBone and offset still override it.
  • A flat GLB with no authored bone uses the natural bone for its declared slot. Body-sized or slotless items keep avatar-root coordinates instead of defaulting to the head.

0.42.0 — 2026-08-26

  • avatars.onAfterUpdate(cb) runs a callback after the animation mixer tick, so procedural posing, ragdoll blending and tooling can write bones without being overwritten. Returns an unsubscribe function.
  • The Pose Tuner dev tool ships alongside this release and depends on it.

0.41.0 — 2026-08-25

  • No SDK code change. The hosted three/addons/ mapping gains the postprocessing set: EffectComposer, RenderPass, ShaderPass, MaskPass, Pass, UnrealBloomPass, plus the CopyShader and LuminosityHighPassShader shaders. Games reaching for a bloom effect no longer 404 on publish.

0.40.0 — 2026-08-24

  • Collision fixes for the character controller and NPCs.
  • NPCs gain a stepDown option and a buried-floor recovery: an NPC dropped through a floor is put back on the floor it was standing on. The recovery uses the isUnderSurface probe that collider.controllerOptions() already hands over.
  • GroundProbe type exported from SceneCollider.

0.39.0 — 2026-08-21

  • Merge release. The first version that contains both branches of 0.36.0 and 0.37.0 below, together with 0.38.0. No other changes.

0.38.0 — 2026-08-18

  • HealthController: hit points, flinch reactions, a death take and respawn for one Guardian. Reactions play on the base animation layer so they travel with animations.getCurrent() in multiplayer, and the body is locked for exactly as long as a reaction plays. Call warm() when combat becomes likely.
  • MeleeSweep: continuous melee hit detection. The weapon is a capsule measured off the equipped GLB, the target is capsules over the posed skeleton, and the blade path is swept every frame of the strike so fast swings cannot tunnel.
  • readRootYaw() and writeRootYaw() on the character controller.
  • Animation sync fix.

0.37.0 — 2026-08-17 and 2026-08-19

Two parallel branches. The first version with both is 0.39.0.

  • Stuck rescue (2026-08-17). New collision hook isUnderSurface(position, maxDistance?) and controller option stuckRescue (default true): a character falling for over about 0.7 s with a walkable surface overhead is put back at its last grounded position. Landing also uses a per-frame continuous ray along the feet's true displacement, so a fast or diagonal fall cannot cross a floor without landing on it. depenetrate pushes a body whose capsule centre crossed a floor straight back up.
  • Shouldered scope and shooting from the barrel (2026-08-19). ScopeTuning for the shouldered aim stance, and MuzzleWorldOptions plus ShotOriginParams to read the shot origin from the weapon's barrel.

0.36.0 — 2026-08-17

Two parallel branches. The first version with both is 0.39.0.

  • Ragdoll, weapon posing and shooter strafing. RagdollOptions and RagdollTuning; aimWeapon with three stances (GunPoseName, LoadGunPosesOptions, AimBendTuning, CarryTuning, RecoilTuning, ShotKick); arm IK; shooter-grade strafing through strafeTuning (StrafeTuning, StrafeCollapse); WearableOffset.
  • Swimming collision fix and collision optimisation. New optional collision hook depenetrateSegment.

0.35.0 — 2026-08-13

  • Swimming collision fix. New optional collision hook resolveMovement({ current, proposed, radius, airborne }).

0.34.0 — 2026-08-12

  • Ground probing is capsule-shaped: getGroundHeight(x, z, y?, radius?) receives the capsule radius and SceneCollider probes the centre plus four rim rays, so a landing half on a ledge stands on it instead of falling through.
  • Avatar-vs-avatar collision. Controllers and NPCs created through PortalsAvatars push out of every other avatar's capsule automatically (XZ only, hidden avatars skipped). Opt out per character with collideWithAvatars: false; hand-built setups wire the obstacle set with setAvatarObstacles(). NPCs are solid by default.
  • Camera rig adjustments.
  • The README describes these features as 0.32.0. That number was never released; the bump went from 0.30.0 straight to 0.34.0.

0.30.0 — 2026-08-11

  • Camera rig fix. ControllerOptions.cameraCollision and controller.cameraRig.collision.enabled control obstacle avoidance, on by default wherever a raycast hook is wired. The boom shortens on contact and drops to first person when squeezed.

0.29.0 — 2026-08-11

  • The depenetrate(position, radius, height) hook is documented and run after the vertical step each frame: walls push horizontally, ceilings push down, floors stay the job of getGroundHeight.
  • Animation controller fix for camera avoidance.

0.28.0 — 2026-08-10

  • Capsule collider. New optional collision hook depenetrate for capsule overlap recovery, which the swept probes cannot do on their own; GuardianAvatar exposes its capsule dimensions.

0.27.0 — 2026-08-10

  • Merge release. The first version that contains both 0.23.0 and 0.26.0. No other changes.

0.26.0 — 2026-08-10

  • Camera obstacle avoidance (CameraCollisionOptions) and camera rotation limits (CameraLimitOptions).
  • Swimming.
  • Falling, stairs and step-downs.
  • Touch control and catalog adjustments.

0.23.0 — 2026-08-09

  • Current Portals player. avatars.createAvatarFromPlayer(player) builds the avatar a signed-in player saved on /avatar; null means guest. Types PortalsPlayerProfile, PortalsPlayerAvatar, PortalsPlayerFullAvatar, PortalsPlayerAvatarWearable and PlayerAvatarLoadOptions.

0.22.0 — 2026-08-07

  • Touch controls for mobile: TouchControls with a virtual joystick and action buttons, wired into the character controller.

0.21.0 — 2026-08-07

  • NPCs: NPCController for code-driven avatars.
  • Loading performance: asset fetching moves to a worker.
  • Eye material and wearable loading adjustments.

0.20.0 — 2026-08-05

  • Run styles. RunStyle and HiddenRunStyle swap the jog band of the locomotion set.
  • Catalog expansion.

0.13.1 — 2026-08-04

  • Melee: a single click strikes with alternating side slashes; holding the press for controller.meleeHoldTime seconds (0.3) launches the authored combo. useItemCombo() triggers the combo directly.
  • Remaining references to the Invector controller the port was based on were removed.

0.10.0 — 2026-08-04

  • New animation clip set and the ANIMATION_SETS opt-in behaviour groups.
  • Throwing an item away and picking it up again (ReleasedWearable).
  • Strafing (StrafeMode).
  • Movement speed and stride controls.

0.9.0 — 2026-08-03

  • Overlay clips accept sync: true to take their phase from the base locomotion clip, so a carry clip with an arm swing stays in step with the run.
  • Throwing tested and fixed.

0.8.0 — 2026-08-01

  • Avatar switching fix: adoptFrom carries controller state over when the avatar is swapped.
  • boneAdjust: corrective Euler rotations applied to named bones' keyframes when a clip is registered.
  • Hand-item overlays are declared up front through DEFAULT_HAND_ANIMATIONS, so the carry pose is found the moment something lands in the right hand.

0.5.0 — 2026-08-01

  • portalsItemId on wearable definitions: equip a catalog item by its inventory id. Hand grab.

0.4.1 — 2026-08-01

  • Ledge grab: probeLedge, LedgeGrab, LedgeProbeParams.
  • SceneCollider replaces the earlier box collider world. getGroundHeight collision hook.

0.2.0 — 2026-08-01

  • Avatar setup pipeline, preloadAnimations, face animation controller, and THREE re-exported from the SDK so a game has one Three.js instance.

0.1.0 — 2026-07-31

  • Initial release: body types, skin, hair and eye colours, hair styles, the wearables system with the never-naked basic set, retargeted locomotion clips, hand items, facial animation, and the first and third-person character controller with camera rig.