skillZs
★ LIVE SKILL TAGS ★
>>> LIVE SKILLS INDEX <<<
* OPEN SOURCE *
NO LOGIN, NO TRACKING
※ REAL INSTALL DATA ※
← back to all skills
decentraland/sdk-skills349 installs

npcs

Create NPCs in Decentraland: GLB or primitive bodies, NPC Toolkit dialogue and paths, or AvatarShape wearables and emotes. Use for shopkeepers, guards, quest givers and other non-player characters; choose SDK/FSM, HTN or hybrid behavior. For the live player see player-avatar.

How do I install this agent skill?

npx skills add https://github.com/decentraland/sdk-skills --skill npcs
view source ↗

Is this agent skill safe to install?

  • Gen Agent Trust Hubpass

    The skill provides instructions and examples for creating Non-Player Characters (NPCs) in Decentraland using the NPC Toolkit and AvatarShape components. It covers dialogue systems, movement, animations, and AI behavior via HTN planners. The security analysis found the skill to be safe, with external dependencies and code generation patterns following standard developer practices for the Decentraland platform.

  • Socketpass

    No alerts

  • Snykwarn

    Risk: MEDIUM · 2 issues

What does this agent skill do?

NPCs in Decentraland

Choose the character's representation and decision logic separately.

RepresentationUse when
GLB + NPC Toolkit (dcl-npc-toolkit)Custom model with built-in dialogue, paths, animations and interaction
AvatarShapeDecentraland avatar appearance: wearables, expressions or a copy of the player
GLB or primitives with SDK componentsCustom movement/animation, or a prototype body; the game owns interactions

For behavior selection, extensions or integration, read behavior-selection.md. Choose SDK systems, FSM/HFSM, HTN or a hybrid from the actual tasks, reuse, recovery and available cost evidence. For chosen HTN behavior, load htn-npcs for domain authoring, module setup and host contracts.

Animation, sound and movement adapters can serve either controller. Give movement and rotation one owner at a time. Stop or coordinate Toolkit path-following, tweens and faceUser before another executor drives the same Transform. Check completion and cancellation against the body's actual motion; AvatarShape uses engine-managed movement and has the playback limits below. Toolkit and AvatarShape need game-owned adapters/executors for HTN.

Either body can take planned behaviour (patrol, notice, chase, search, give up) from the HTN planner module: see Behaviour: the HTN planner module below.


Approach 1 — NPC Toolkit (GLB-based)

The toolkit handles dialogue UI, movement along paths, animations, and interaction out of the box.

Install:

pnpm add dcl-npc-toolkit

Basic usage:

import * as npc from 'dcl-npc-toolkit'
import { Vector3, Quaternion } from '@dcl/sdk/math'

const dialogs: npc.Dialog[] = [{ text: 'Hello there!', isEndOfDialog: true }]

const npcEntity = npc.create(
  { position: Vector3.create(8, 0, 8), rotation: Quaternion.fromEulerDegrees(0, 180, 0) },
  {
    type: npc.NPCType.CUSTOM,
    model: { src: 'assets/Models/guard.glb' },
    idleAnim: 'Idle',
    walkingAnim: 'Walk',
    hoverText: 'Talk',
    onlyExternalTrigger: false,
    onActivate: () => {
      // called when player activates the NPC
      npc.talk(npcEntity, dialogs)
    },
  }
)

For full dialogue scripting, movement paths, state machines, and all config options, see {baseDir}/references/npc-library.md — it covers:

  • Dialogue types (talk, button choices, NPC responses)
  • Walking to positions and following paths
  • State management (quest giver, guard, shop patterns)
  • Multiplayer considerations
  • Performance optimization

Gotchas (NPC Toolkit)

  • Button labels are clipped at about 15 characters with no ellipsis. Use short labels ("Yes", "No thanks", "Tell me more"); for longer text drop fontSize or set size on the button. Details: {baseDir}/references/npc-library.md → ButtonData fields.

  • Opening dialogs on an entity not created via npc.create needs addDialog(entity) plus a minimal npcDataComponent.set(entity, ...); a standalone createDialogWindow() needs the same or its UI crashes on reading 'theme'. Setup code: {baseDir}/references/npc-library.md → Toolkit Dialog UI vs Bubble UI.

  • Speech bubbles need createDialogBubble(entity) before talkBubble. Bubbles do not render question buttons; questions are HUD-only.

  • faceUser: true — place fixed-world objects unparented, beside the NPC. faceUser rewrites the NPC entity's Transform.rotation every frame (via TrackUserFlag + faceUserSystem) to look at the player. Any child placed at a local offset inherits that rotation and orbits the NPC as the player moves, landing in unintended places (behind a door, occluded, unclickable). Fix: spawn such objects unparented at a computed world position (derive a stable world spot from a non-rotating reference like a door, plus the NPC's position). The same caveat applies to any entity whose Transform you rotate every frame.

  • An NPC that approaches or confronts the player moves in world space. Pick its spot once (a ground point in front of the player at approach time) and let the player turn away from it. Parenting it to engine.PlayerEntity / engine.CameraEntity, or re-targeting it to a point in front of the camera every frame, makes it follow the camera when the player turns, which reads as broken (owner report and in-world camera-turn check, 2026-11-06).

  • dcl-npc-toolkit must be statically imported from the entry point. The toolkit calls engine.defineComponent(...) at module-load time. engine.defineComponent throws "Engine is already sealed. No components can be added at this stage" if it runs after the engine seals. A dynamic await import('./client-setup') defers that registration past the seal point. So any module that imports the toolkit must be reached via a static import from index.ts. In an authoritative-server scene, keep the client setup (which imports the toolkit) static and dynamically import only the server-only branch. See authoritative-server.


Approach 2 — AvatarShape (Decentraland avatar look)

Create an NPC that looks like a Decentraland player avatar, dressed in any wearables.

import { engine, Transform, AvatarShape } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const npc = engine.addEntity()
Transform.create(npc, { position: Vector3.create(8, 0, 8) })

AvatarShape.create(npc, {
  id: 'guard-0001',          // unique; its last 4 characters show beside the name
  name: 'Guard',             // display name shown above head
  bodyShape: 'urn:decentraland:off-chain:base-avatars:BaseMale', // or BaseFemale
  wearables: [
    'urn:decentraland:off-chain:base-avatars:eyebrows_00',
    'urn:decentraland:off-chain:base-avatars:mouth_00',
    'urn:decentraland:off-chain:base-avatars:eyes_00',
    'urn:decentraland:off-chain:base-avatars:blue_tshirt',
    'urn:decentraland:off-chain:base-avatars:brown_pants',
    'urn:decentraland:off-chain:base-avatars:classic_shoes',
    'urn:decentraland:off-chain:base-avatars:short_hair',
  ],
  hairColor: { r: 0.92, g: 0.76, b: 0.62 }, // RGB 0–1
  skinColor: { r: 0.94, g: 0.85, b: 0.6 },
})

Notes:

  • Always include eyebrows, mouth, and eyes wearables — the avatar won't render face features without them.
  • id is required and must be unique per AvatarShape entity. The Explorer prints the last 4 characters of id after the name, in faded text, the way an unclaimed player name shows its address. An NPC has no profile, so it always gets the suffix and no field turns it off: id: 'guard-1' with name: 'Guard' renders as "Guard" with a faded "rd-1" appended. Choose ids whose last four characters look intentional, such as guard-0001 (an id shorter than 4 characters shows 0000). The only way to lose the suffix is to drop the whole tag.
  • Set name: '' (empty string) to suppress the name tag above the NPC's head, suffix included.
  • Moving the Transform position causes the NPC to walk/run to the destination (it does not teleport). This mutation DOES take effect — unlike the read-only player Transform. You can also drive movement with Tween (Tween.Mode.Move) + TweenSequence for scripted paths; the avatar plays its walk animation along the tween. For an NPC that continuously chases the player (or another moving target), use Tween.setMoveContinuous; re-creating setMove tweens every frame jitters. See the animations-tweens skill ("PITFALL — a CONSTANTLY changing target") and the 79,-4-tween-following-cube test scene.
  • Use expressionTriggerTimestamp as a Lamport timestamp to replay the same emote: first play = 0, second play = 1, etc.
  • Clone the current player's look: read getPlayer() and pass userData.wearables and userData.emotes straight into AvatarShape.create. getPlayer() may return null / empty emotes on the first frames — poll in a system until userData.emotes.length > 0 before spawning (test scene 4,21).

Label plate above the NPC's name (AvatarNametag)

AvatarNametag works on any entity with an AvatarShape, not just on players. Attach it to the same entity:

import { AvatarNametag } from '@dcl/sdk/ecs'

AvatarNametag.create(npcEntity, { label: 'Shopkeeper' })
  • name: '' on the AvatarShape shows only the plate, with no empty native name box under it — label an NPC with a title alone.

Field table, edge cases, and gotchas: player-avatar skill ("Custom Nametag Plates") and {baseDir}/../player-avatar/references/avatar-nametag.md.

Playing expressions on an AvatarShape NPC

AvatarShape.getMutable(npc).expressionTriggerId = 'wave'
AvatarShape.getMutable(npc).expressionTriggerTimestamp = 1

expressionTriggerId accepts either a built-in emote name ('robot', 'wave', ...) OR a scene-emote .glb path (e.g. 'animations/Snowball_Throw_emote.glb') — the same _emote.glb-suffixed files used with triggerSceneEmote. This is how you play a custom emote on an NPC (there is no triggerSceneEmote equivalent for AvatarShape entities). To cycle through the player's own emotes, set expressionTriggerId = userData.emotes[i].

Before authoring a custom clip for an NPC pose (sit, idle variant), check the embedded emotes first. The Explorer ships 21 emotes that expressionTriggerId accepts by name; the sitting ones loop and hold the pose with no re-trigger. Full list with ids and loop flags (single source of truth): {baseDir}/../avatar-animations/references/embedded-emotes.md. A built-in sit often reads more naturally than a hand-authored one. Next, the Creator Hub's Avatar Animations pack has 45 downloadable _emote.glb clips (stools, puffs, bean bags, ledges, chess, fishing, drinking, crafting…) that expressionTriggerId plays by file path — catalogued with previews in {baseDir}/../avatar-animations/references/animation-catalog.md. Only author a custom clip (avatar-animations) when neither fits.

Note: replaying the same expressionTriggerId value back-to-back requires bumping expressionTriggerTimestamp; setting a different id each time replays without touching the timestamp.

AvatarShape playback limits (mechanisms and workarounds: {baseDir}/references/avatar-shape-npcs.md):

  • Custom clips do not loop on an AvatarShape; only built-in emotes whose loop flag is yes in the avatar-animations catalog (sitting poses, several social dances) hold a pose. For a sustained custom pose, retrigger a long clip before it ends.
  • Moving the NPC cancels its emote (Transform write or Tween). Bake travel during an emote into the _emote.glb as root motion.
  • Hide it by scaling to 0.001, not by moving it away: a moved AvatarShape visibly walks there.
  • No masked (upper-body) emotes: expressionTriggerId is always full-body.

Copies of the player

A lookalike of the player — a line-up of "you", a clone posing in a shop, a twin that waves back — is an AvatarShape fed from live getPlayer() data (field mapping in player-avatar, clone bullet above), so it wears whatever the player wears.

  • An AvatarShape cannot be puppeted frame by frame: the engine walks it toward the authored position and turns it to face its travel. For a mirror double, shadow or replay ghost, use a rigged humanoid GLB with an Animator and write its Transform each frame.
  • What a copy can visibly differ in is decided by wearable categories (readable from the catalyst); scaling the copy (1.07, 0.93, 1.10) always shows.

Details for both: {baseDir}/references/avatar-shape-npcs.md.

Mannequin mode (show wearables without a body)

Useful for storefronts and wearable displays:

AvatarShape.create(mannequin, {
  id: 'mannequin-0001',
  name: 'Display',
  wearables: ['urn:decentraland:matic:collections-v2:0x...:0'],
  showOnlyWearables: true,
})

For the full AvatarShape field reference, body shape URNs, and common base wearable URNs, see {baseDir}/../player-avatar/references/avatar-apis.md.


Adding interactivity to AvatarShape NPCs

AvatarShape entities are not clickable — they have no collider, so pointer events won't register on them directly. To let players interact with an AvatarShape NPC, use one of these approaches:

Option A — Add a MeshCollider for click interaction

Attach an invisible collider to the same entity so pointerEventsSystem can detect clicks (see add-interactivity skill):

import { MeshCollider, pointerEventsSystem, InputAction } from '@dcl/sdk/ecs'

// invisible cylinder collider roughly matching avatar size.
// Pointer clicks require the CL_POINTER collider layer; MeshCollider defaults to
// all layers (which includes CL_POINTER), so an explicit layer is optional here.
// If you set a layer, include ColliderLayer.CL_POINTER or clicks won't register.
MeshCollider.setCylinder(npc)

pointerEventsSystem.onPointerDown(
  { entity: npc, opts: { button: InputAction.IA_POINTER, hoverText: 'Talk' } },
  () => {
    console.log('Player clicked NPC')
  }
)

Option B — Proximity-based interaction

Trigger the interaction when the player walks near the NPC, with a native TriggerArea on a child entity (the area's size is its Transform.scale, so scaling the NPC entity itself would scale the avatar):

import { engine, Transform, TriggerArea, triggerAreaEventsSystem } from '@dcl/sdk/ecs'
import { Vector3 } from '@dcl/sdk/math'

const zone = engine.addEntity()
Transform.create(zone, { parent: npc, scale: Vector3.create(8, 8, 8) }) // ~4 m radius
TriggerArea.setSphere(zone)

triggerAreaEventsSystem.onTriggerEnter(zone, (result) => {
  if (result.trigger?.entity !== engine.PlayerEntity) return // local player only
  // start dialogue or other interaction (fires once per entry)
})

Full TriggerArea reference: add-interactivity → Trigger Areas.


Behaviour: the HTN planner module

When the controller selection above favours HTN, load htn-npcs for the matching module revision, setup and domain authoring. The sdk7-test-scenes HTN module is a TypeScript port of urosidoki/htn_planner, maintained as a test-scene module, not an SDK built-in or package. Use its installed or recorded revision for integration; main is a browsing entry point.

  • Behaviour lives in .domain files, compiled to .htn.ts modules with pnpm run htn:generate (rerun after every .domain or include change; commit sources, htn.config.json and generated output together; never edit the generated file). TypeScript supplies perception (facts), executes primitive actions (!move_to, !chase, !look_around, …) and decides when to replan.
  • Host: GuardSquad (new GuardSquad({ planner: plannerFor(guardDomain), reasoning: 'reasoning' }), then guards.spawn([{ id, route, body }])) registers one system for many NPCs; createCapsuleBody gives a model-free first guard, possessEntityBody drives an existing figure (GLB or AvatarShape). Positions and routes are scene coordinates. Call guards.despawn() when the encounter ends.
  • Kit: sight (range, FOV cone, raycast line of sight), hearing (player footsteps and landings, noise bus), a seeded RNG and a pausable scene clock; example domains for a guard and a stalker.
  • NPCs run on each client. The module gives no multiplayer authority or sync: the game owns it (multiplayer-sync, authoritative-server). [UNVERIFIED: no obstacle-aware pathfinding appears in the module; read npc/actions.ts before routing an NPC around walls.]
  • Install: follow the module guide (src/htn-planner/README.md → Install by copying): copy the library, the domain compiler, the notice command and the game-owned guard files, add the package scripts/hooks and .dclignore exclusions, keep the licence notices. The scene README holds a ready prompt for an agent-driven install; recipes in src/htn-planner/HOW-TO.md, domain design in docs/htn-guidance.md, examples in docs/htn-examples-catalog.md.
  • A clean build proves nothing about the encounter: walk up to the NPC in the Explorer and check it patrols, notices and gives up as designed.

Example scenes

Engine-team test scenes for the AvatarShape approach (exercised against the real engine):

  • 4,20-avatar-shape — spawn AvatarShape NPCs with base-avatar wearables and with on-chain collection wearable URNs; name: '' to hide the name tag.
  • 4,19-avatar-shape-movement — moving an AvatarShape by mutating its Transform (walks to target) and by Tween/TweenSequence; an AvatarAttach box on the NPC's hand via its id.
  • 4,21-avatar-shape-emotes — clone the local player onto an NPC using getPlayer().wearables / .emotes, then cycle emotes via expressionTriggerId.
  • 4,22-avatar-shape-scene-emotes — play custom scene emotes on an NPC by setting expressionTriggerId to an _emote.glb path.

These are AvatarShape-only scenes; they do not use dcl-npc-toolkit.

For dialogue flow, the docs example catalog ({baseDir}/../sdk-scenes/references/example-scenes.md) lists the NPC Toolkit and The Fortune Teller, a published game that models a conversation as an explicit state machine (tryTransition with allowed steps) and frames it with a pivot-mounted VirtualCamera.

Add the canonical catalog link to the repository README so users can inspect current installs and available audits. The publishing guide covers the complete discovery path.

<a href="https://skillzs.dev/skills/decentraland/sdk-skills/npcs">View npcs on skillZs</a>