Log inGet started
Package

avatarAppearance.module

Newest version

This package holds more than this page lists. See all of its files in its world.

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:

fieldwhat
v1
avatarthe avatar asset reference
body_shapenamed 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
wornthe worn items in order: { slot, item, adjust? }
animation_packa Locomotion preset reference
emotesemote asset guids (uuids, stored lowercase and hyphenated), in menu order
parametersnamed 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 }.