portals-guardian-avatars

Guardian avatars

The Guardian avatar SDK renders the same avatars players wear across Portals. It is a Three.js library, not a renderer: the game owns the scene, camera, and render loop, and the SDK adds avatars to it. Reach for it instead of hand-rolling a character whenever a 3D game wants a player avatar.

Read references/guardian-avatars.md for the full API, code examples, versioning, and local-development setup. For targeting reticles, cast telegraphs and world markers built within the sandbox rules, read references/ability-vfx.md. Types for autocomplete: https://portals.to/portals-sdk/guardians.d.ts — the source of truth for the API.

Wiring

Portals stamps the SDK into every processed preview and published bundle. Load it beside the Portals SDK; never edit, bundle, or ship a copy:

<script src="./_portals/sdk.js"></script>
<script src="./_portals/guardians-sdk.js"></script>
<script src="./game.js"></script>

const { THREE, PortalsAvatars } = await PortalsGuardians.ready();

Module-based games can skip the loader and import { PortalsAvatars } from '@portals/avatars' instead — Portals writes the import map that resolves @portals/avatars, three, and three/addons/. Map the bare specifier at guardians-sdk.module.js, never at the guardians-sdk.js loader. Both routes load the same module and can be mixed. Only three addons are hosted: controls/OrbitControls.js, loaders/GLTFLoader.js, utils/BufferGeometryUtils.js.

Rules that are easy to get wrong

• Call avatars.update(dt) once per frame or nothing animates.
• Anything that writes bones runs AFTER avatars.update(dt). That call is the mixer tick, and it rewrites every bone local from the clips. Ragdoll.update(), aimWeapon() and applyPose() stepped before it are silently overwritten — nothing errors; it just does not work.
• Take THREE from the SDK, not from a CDN. There is exactly one shared instance; the game CSP keeps script-src at 'self', so a second copy will not load and would break instance checks anyway.
• Assets resolve through Portals. Published games run under connect-src 'self'; the SDK rewrites asset URLs onto managed same-origin paths automatically. Two exceptions need action: run a wearable's thumbnail through resolveAssetUrl before using it in an <img> (img-src is 'self' too), and equip an externally hosted wearable as a catalog item with its id rather than a bare URL, since the item proxy addresses it by inventory item id.
• Pin the version. Only editor and AI-builder games are frozen on the avatar SDK version they were first stamped with. A push from this plugin, a zip import or a GitHub build replaces the whole bundle and re-stamps the SDK at the current platform release, so an unpinned pushed game can change version on any push. Pin { "guardiansSdk": "0.36.0" } in portals.json at the project root; the pin wins on every path. Pinning an unreleased version fails the publish. Features below are marked with the release they shipped in — a game pinned lower does not have them.
• Ground and collision are yours to supply. The defaults are a flat floor at y = 0 and free movement. SceneCollider is the quickest real level — register level geometry only, never avatars, and call collider.refresh() after adding or removing meshes. With existing physics, pass getGroundHeight, resolveMovement, raycast, and checkClearance directly.
• Ledge grabbing needs raycast. Without it nothing is climbable. Both shoulders must find the ledge, so a ledge narrower than the character cannot be grabbed, and the probe only runs while airborne — the player always jumps or falls into a climb. Since 0.36.0 a wall standing in front of the ledge rejects the grab, so a wall is never climbed through.
• Swimming is the game's toggle. The SDK has no idea where a level's water is: call controller.setSwimming(true, { surfaceY }) at the water's edge and setSwimming(false) exactly at the boundary on the way out.
• Clips load on demand. createAvatar resolves as soon as the body is on screen; the locomotion GLB downloads on first movement. animations.play() returns false until the clip's bytes arrive — that is not an error; await ensure() for certainty. Call avatars.preloadAnimations() to pay the cost behind a loading screen.
• Clean up with avatars.dispose() when leaving a scene, or avatars.removeAvatar(avatar) / avatars.removeNPC(npc) for one.