avatar.assetType
- README.md10.1 KB
- about.yaml561 B
- behavior.luau45.8 KB
- inspector.luau9.8 KB
- type.yaml4.7 KB
This package holds more than this page lists. See all of its files in its world.
README.md
avatar
A playable character, composed from three independent parts:
- body (optional): a
.bundle(a skinned.mesh+ bone entities, a character imported from a GLB/FBX) or a plain.mesh. The look. An avatar with no body is a controller or first-person camera with no visible mesh. - controller — the movement system. Default: the standard humanoid kit
(
CharacterController+MovementState+Humanoid). - animation — the system that animates the body. Default: the shared
Locomotionblend space (reads the controller's velocity, plays retargeted clips). OrClipPlayer. Or your own component.
Movement and animation are not tied together — attaching the controller never
pulls in Locomotion, and choosing your own animation keeps the standard
controller. Authoring your own locomotion is a one-field swap (animation = ...).
Because the standard clip set retargets onto any humanoid rig, the default
locomotion drives any humanoid body with no per-body setup and no editing of any
built-in content.
Make an imported character playable
-- After importing a rigged humanoid GLB, the importer leaves a `.bundle`
-- (skinned mesh + bones). Survey for it, then wrap it in an avatar:
local body = asset.resolve("my_character", "bundle")
local hero = asset.create("avatar", "my_hero", { body = body })
To make hero the body every connecting player spawns with, point the scene's
PlayerPrototype.body at a body entity whose Asset source is hero (authored
in the scene tree — see man scene). To drive the local player with it right
now, instantiate it and bind the entity:
local root = hero:instantiate() -- spawns the body + movement kit
layers.active.players.localPlayer.avatar = root -- bind the live body
Only the avatar bound as the local player's body answers the player's
controls. Every other avatar you instantiate (an NPC, a mannequin, a preview)
stands where it is until something drives it: with the standard controller,
write its CharacterController input bus (inputX / inputZ / inputJump)
from a component of your own, the way an AI brain does (man CharacterController).
local npc = hero:instantiate() -- stands still
npc.component.get("CharacterController").inputZ = -2 -- walks while this is written each frame
An avatar is not humanoid-only. The body can be anything — a humanoid, a
vehicle, an unrigged plane with a custom controller and shader. The defaults
adapt to the body: a humanoid body defaults to the shared humanoid Locomotion
(the synty clip preset); a non-humanoid / unrigged body gets no
auto-animation (you supply your own controller and animation). This is the
non-humanoid detection — an arbitrary animated model is never auto-driven by
humanoid locomotion — and it never blocks creating the avatar.
-- Non-humanoid avatar (e.g. a custom-controlled body), fully generic:
asset.create("avatar", "ship", { body = shipBundle, controller = { system = "ShipController" }, animation = false })
Options
asset.create("avatar", name, opts):
| opt | meaning |
|---|---|
body (optional) | the body .bundle or .mesh ref; omit for a body-less avatar |
controller | movement: true/nil = standard kit, false = none, or a component name / { system, data } |
animation | a component name or { system, ... } — author your own locomotion here; defaults to Locomotion |
locomotion | clip preset for the default Locomotion (default "synty") |
clip | a single .animation ref — selects a one-clip ClipPlayer |
looping / speed / sourceRig | ClipPlayer tuning (with clip) |
expressions | the blend shape each standard expression preset plays, where the body's shapes are not named after the presets: { aa = "Mouth_A", blink = { shape = "Eyes_Closed", overrideMouth = "block" } } |
parameters / animator / menu / parts | the avatar's parameters, its animator, its expression menu and its own parts seated on its body (below) |
type | the avatar type its body is mapped onto (an avatarType ref or identity); the builtin humanoid when omitted |
Author your own locomotion (keeps the standard movement):
asset.create("avatar", "my_hero", { body = body, animation = { system = "MyLocomotion" } })
avatar.json:
{
"body": { "__ref": "<bundle guid>" },
"controller": true,
"animation": { "system": "Locomotion", "preset": "synty" }
}
A composed body faces the avatar's -Z, the forward every entity states, whatever
way its file authored it. The composition measures the way the body faces from
its skeleton (the hip line crossed with up, carried through the nodes that stand
it upright, so a Z-up Blender or Khronos skeleton is measured as it is drawn) and
stands the bundle under the body entity's child front, turned so that front is
the body entity's -Z. So transform.forward, entity:lookAt, a PlayerSpawn's
heading and capture's local front all name the way the character visibly
faces, and Locomotion turns the body entity to lead its walk with that front. No
per-avatar facing knob.
avatar root (placed, turned by lookAt / a spawn)
body (Locomotion turns this one about up)
front (turns the bundle so its front is -Z)
<bundle nodes>
Use
local root = avatarRef:instantiate() -- spawn body + movement kit
avatarRef:setCharacter(root, asset.resolve("knight", "bundle")) -- swap the body, keep the behaviour
:instantiate() spawns the body and attaches the movement system bound to it.
:setCharacter(root, body) despawns the current body and spawns a new one in its
place; the Locomotion kit on the avatar root re-resolves the new body's rig, so
the look swaps while the behaviour is kept. Items seated with
Humanoid:attach are kept: each moves to the new body's socket for the same
point, with the transform it was seated with. An item whose point the new body
lacks stays on the avatar root and is seated by the next swap to a body that
has it. The new body takes the old body's id and is composed with the options
the avatar was instantiated with, and the avatar's Asset id map names it.
The avatar standard
A humanoid avatar is built around one standard (the avatarStandard module):
the VRM 1.0 bones, 19 attachment points, the viewpoint, the face expressions and
a height band. A game relies on it to seat its own items on any visitor's body
(Humanoid:attach("rightGrip", sword.id)) and to read where the eyes are.
local d = avatarRef:descriptor() -- bones, points, viewpoint, expressions, height
print(d.height, d.points.hat.position.y, d.viewpoint.source)
local v = avatarRef:validate() -- { ok, problems }
for _, p in v.problems do print(p.rule, p.name, p.message) end
:validate() names every rule the body breaks, one problem per missing item: a
required bone (rightHand), an attachment point the body cannot carry
(rightGrip), a face expression no blend shape answers (aa), a height outside
the band, or a body that is not a humanoid at all. A game holds bodies to the
rules it relies on: avatarRef:validate({ rules = { "type", "bone", "point", "height" } })
leaves out the face expressions. A live avatar answers the same through its
Humanoid (:descriptor(), :validate(opts)).
Parameters, an animator and an expression menu
An avatar declares its own state as data: parameters (named bools, ints and floats,
synced or local, saved or not, the synced ones 256 bits in all), an animator (layers of
state machines over the parameters, whose states pose blend shapes and bones, show and
hide parts, set shader data and play .animation clips on the body under the layer's
mask, a wave on the right arm or a dance over the locomotion), a menu (buttons, toggles, sub-menus, radial and
two-axis puppets) the person uses from the app menu's Expressions tab, and parts
(meshes seated on its body's attachment points on every peer). No script is
involved, and every peer draws the same avatar from the parameters it receives.
local hero = asset.create("avatar", "my_hero", {
body = body,
parts = { { name = "Hat", mesh = "@builtin::meshes.cone", point = "hat", scale = 0.25 } },
parameters = { { name = "Hat", type = "bool", default = true, saved = true } },
animator = { layers = { {
name = "Hat",
states = { { name = "On" }, { name = "Off", motion = { hide = { "Hat" } } } },
transitions = { { from = "On", to = "Off", when = "!Hat", duration = 0 },
{ from = "Off", to = "On", when = "Hat", duration = 0 } },
} } },
menu = { { type = "toggle", label = "Hat", parameter = "Hat" } },
})
local check = hero:animator() -- { ok, problems, summary, syncedBits, cost }
hide = { "Hat" } names the part the avatar declares; any entity under the avatar is named
the same way, and an attachment point's name (hat) names every item seated there. An avatar whose synced parameters pass 256 bits is refused when it
is created, with the overrun stated. The avatarAnimator module's README has the whole data
form, and the AvatarAnimator component runs it.
In the Inspector
Selecting an avatar opens its Avatar section, read from avatar.json: its label when it has one, how it moves (controller: the standard mover, none, or the system it names), what animates it, and whether it is humanoid. It links the body the avatar wears, or says the avatar spawns no visible body, and offers to open avatar.json in the Code panel.
The body's skeleton
avatarRef:rig() is the .rig of the body's skinned mesh (nil for a body-less avatar or a
plain mesh), and avatarRef:avatarType() the avatar type its body is mapped onto. The
avatar toolbox reads and corrects that mapping (avatar.inspect, avatar.map), and makes,
dresses and saves avatars; guides { path: "core/avatars" } walks through it.