NPC Avatars
Display an avatar as an entity in a scene.
Create an avatar #
The following snippet creates an avatar with random wearables and body shape, and name “NPC”.
const myAvatar = engine.addEntity()
AvatarShape.create(myAvatar)
Transform.create(myAvatar, {
position: Vector3.create(4, 0.25, 5),
})
When passing data to generate an AvatarShape
, the following fields are required:
id
: (required) Internal identifier for the Avatar
The following optional fields are also available:
name
: Name to display over the Avatar’s head. Default: “NPC”.bodyShape
: String to define which body shape to use.wearables
: Array with list of URNs for wearables that the avatar currently has on. If wearables conflict (like two of them are hats), the last one in the list replaces the other.emotes
: Array with list of URNs for NFT emotes that the avatar is capable of playingeyeColor
: Color3 for the eye color (any color is valid)skinColor
: Color3 for the skin color (any color is valid)hairColor
: Color3 for the hair color (any color is valid)talking
: If true, it displays a green set of bars next to the name, like when players use voice chat in-world.💡 Tip: See color types for more details on how to set colors.
📔 Note: The
AvatarShape
component must be imported via
import { AvatarShape } from "@dcl/sdk/ecs"
See Imports for how to handle these easily.
📔 Note: The URN fields must follow the same format used for
NFTShapes
: urn:decentraland:<CHAIN>:<CONTRACT_STANDARD>:<CONTRACT_ADDRESS>:<TOKEN_ID>
Animations #
Avatars play default idle animations while still.
To play animations on the avatar, set the expressionTriggerId
string to the name of the animation you want to play.
const myAvatar = engine.addEntity()
AvatarShape.create(myAvatar, {
id: '',
emotes: [],
wearables: [],
expressionTriggerId: 'robot',
})
Transform.create(myAvatar, {
position: Vector3.create(4, 0.25, 5),
})
The expressionTriggerId
field supports all
default animations
, as well as custom animations
from a scene file
, and even URNs from emotes that are published to the marketplace.
Looping Animations #
Animations on an AvatarShape
play once, if you want the avatar to keep looping an animation, you should create a system that tells it to play the animation again every couple of seconds.
Use the expressionTriggerTimestamp
to replay a same emote. The value of this field is a
lamport timestamp
, meaning that it’s not a time value, but rather an index that is raised by 1 for each repetition of the emote.
So the first time you play an emote, you set expressionTriggerTimestamp
to 0. To play the emote again, you must update this value to 1. That’s how the engine knows that this is a new instruction, and not an instruction it already acted upon.
The following snippet creates a system that runs a same emote every 2 seconds:
const myAvatar = engine.addEntity()
AvatarShape.create(myAvatar, {
id: '',
emotes: [],
wearables: [],
expressionTriggerId: 'clap',
expressionTriggerTimestamp: 0
})
Transform.create(myAvatar, {
position: Vector3.create(4, 0.25, 5),
})
let clapTimer = 0
let emoteDuration = 2 // 2 seconds
// system
engine.addSystem((dt: number) => {
clapTimer += dt
if (clapTimer >= emoteDuration) {
// Trigger the clap emote
AvatarShape.getMutable(wearable).expressionTriggerTimestamp =+ 1
clapTimer = 0 // Reset timer
}
})
💡 Tip: You must know the duration of the emote, and make that the duration of the system. If you create an emote that fixes the avatar still in a same pose, it’s recommendable to make the duration of the emote longer than the system. That way, you can make sure that there are no artifacts when finishing and resetting the animation.
Copy wearables from player #
The following snippet changes the wearables and other characteristics of an NPC avatar to match those that the player currently has on. This could be used in a scene as a manequin, to show off a particular wearable or emote combined with the player’s current outfit.
import { getPlayer } from '@dcl/sdk/src/players'
export function swapAvatar(avatar: Entity) {
let userData = getPlayer()
console.log(userData)
if (!userData || !userData.wearables) return
const mutableAvatar = AvatarShape.getMutable(avatar)
mutableAvatar.wearables = userData.wearables
mutableAvatar.bodyShape = userData.avatar?.bodyShapeUrn
mutableAvatar.eyeColor = userData.avatar?.eyesColor
mutableAvatar.skinColor = userData.avatar?.skinColor
mutableAvatar.hairColor = userData.avatar?.hairColor
}
Display only wearables #
Use the show_only_wearables
field to display only the listed wearables of an avatar. The rest of the avatar’s body will be invisible.
const myAvatar = engine.addEntity()
AvatarShape.create(myAvatar, {
id: '',
emotes: [],
wearables: [
'urn:decentraland:matic:collections-v2:0x90e5cb2d673699be8f28d339c818a0b60144c494:0'
],
show_only_wearables: true,
})
Transform.create(myAvatar, {
position: Vector3.create(4, 0.25, 5),
})
This is useful for displaying wearables, for example in a store.
💡 Tip: If a wearable is rather small, try setting thescale
of theTransform
to a larger value.