Builtin Library
README.md
avatarAppearance
How a person wears an avatar, as one data document, and how the engine composes it onto a live avatar on every peer.
local avatarAppearance = require("@builtin::modules.avatarAppearance")
local doc = avatarAppearance.new("@builtin::avatars.humanoid")
doc.body_shape = { height = 1.9, width = 1.1 }
doc.colours = { body = "#3366cc", hair = "#201008" }
doc.worn = {
{ slot = "hat", item = "@builtin::meshes.cone", adjust = { y = 0.06, scale = 0.25 } },
{ slot = "held", item = "@builtin::meshes.cylinder", adjust = { z = 0.1, scale = 0.1 } },
}
doc.animation_pack = "@builtin::systems.characterController.presets.synty" -- a Locomotion preset
doc.emotes = { "<emote guid>", "<emote guid>" }
doc.parameters = { moveSpeed = 3 }
assert(avatarAppearance.validate(doc).ok)
local root = asset.resolve("@builtin::avatars.humanoid", "avatar"):instantiate()
local r = avatarAppearance.apply(root, doc) -- { changed, pending, unapplied }
-- a player's body: layers.active.players.localPlayer.avatar (the avatar root)
print(#avatarAppearance.encode(doc), avatarAppearance.address(doc))
The document
The fields are ZeroMind's appearance document, field for field, so an outfit an account saved reads as it is:
| field | what |
|---|---|
v | 1 |
avatar | the avatar asset reference |
body_shape | named numbers; height (metres) and width (a factor) are composed |
colours | #rrggbb / #rrggbbaa per region; body is every mesh of the body the avatar's regions (in avatar.json) gives no other region; the items seated on its points (the avatar's own parts, the worn items) keep their own colours |
worn | the worn items in order: { slot, item, adjust? } |
animation_pack | a Locomotion preset reference |
emotes | emote asset guids (uuids, stored lowercase and hyphenated), in menu order |
parameters | named bools, numbers or strings; moveSpeed, sprintMultiplier and tintBlend are composed |
A worn slot is one of the 19 standard attachment points (hat, rightGrip,
bodyBack, ...; see avatarStandard) or a slot alias: held (rightGrip),
offhand (leftGrip), back (bodyBack), face (faceFront), neck
(neckBase), waist (waistCenter). adjust takes x, y, z (metres in
the point's frame), pitch, yaw, roll (degrees), scale, and sx, sy, sz
(a factor along one axis, times scale: { scale = 0.05, sy = 9 } stretches a
cylinder into a stick).
encode writes the canonical bytes (compact JSON, fields in schema order, map
keys sorted), address their sha256, decode(bytes, address?) reads them back
and checks them against an address, and validate names every rule a document
breaks (ZeroMind's bounds, at most 4096 bytes, and the standard's slots and
adjustments).
Composing
apply(root, doc) composes onto a live avatar root and, applied again with
another document, recomposes only what differs: an item both documents wear
stays as it is. read(root) is the document composed there, worn(root) the
items with the entities spawned for them, settle(root) seats items whose
point waits for the body's skeleton, and clear(root) takes it all back off,
returning the avatar to how it stood before the first document. diff(a, b) states what differs between
two documents.
Games
override(doc, rules) is a game's view of a player's document; the player's
document is unchanged. A worn rule reaches every item worn on the point its
slot names, by whichever name the document gives it (held reaches an item
worn as rightGrip):
local seen = avatarAppearance.override(doc, {
worn = { hat = "my_helmet", held = false }, -- replace the hat, take the held item away
body_shape = { height = { min = 1.6, max = 1.8 } }, -- clamp the height for the match
animation_pack = "my_pack", -- force a pack
})
The Appearance component carries the document and the rules on an avatar
root as synced data, so every peer composes the same character.
Outfits and the profile
outfits(answer?) is a set of named outfits with one current, in the shape
ZeroMind answers GET /v1/me/appearance in ({ current, outfits }):
:save(name, doc, { makeCurrent }), :get, :list, :wear, :current,
:remove, :toJson. fromDescriptor(descriptor) reads a ZeroMind profile's
avatar_descriptor (a builtin body, a tint, a height, motion) as the document
ZeroMind's own mapping gives, value for value (the descriptor's numbers are
32-bit floats), so both have one address.
The account
The signed-in person's account keeps their outfits and the one they wear. A
player wears their account's look on the body that binds when they join a world
(or switch modes): the current outfit's document, read by its address, else the
document their profile avatar_descriptor maps to. It is written into the
body's Appearance component, so every peer composes it. A body without
Humanoid wears nothing, and a game's Appearance rules still apply over it.
local me = avatarAppearance.accountAppearance() -- { ok, outfits, current?, look?, from?, address? }
avatarAppearance.saveOutfit("Pirate", doc, { makeCurrent = true })
avatarAppearance.wearOutfit("Pirate") -- by name or id; nil wears none
avatarAppearance.deleteOutfit("Pirate")
avatarAppearance.wearAccountLook() -- the local player wears the account's look again
saveOutfit, wearOutfit and deleteOutfit change how the person appears to
everyone, so the engine asks them in its own dialog first, whoever calls, and
the local player then wears the account's new look. ZeroMind refuses them to an
agent's own account (code = "AGENT_APPROVAL_REQUIRED"); the person makes
those changes on the app menu's Outfits tab (appMenu.open("outfits"),
modules.api.engine.outfits). An engine that booted
offline is signed in to no account and answers { ok = false, offline = true }.