feat: BasisAuthoredMotion — batched authored-motion driver for cosmetic/secondary motion

[towneh]

Summary

Replaces per-avatar cosmetic/secondary Animators with a batched, Burst-compiled authored-motion system. A single cosmetic Unity Animator on the reference avatar measured at roughly 1/5 of scene frame time at 1000 CCU — almost entirely fixed per-instance Animator overhead, paid on every replicated copy. This moves that motion into one job over all avatars.

• BasisAuthoredMotion (SDK, data-only): a Content-Police-allowed component holding a list of reusable Movements — no per-instance Update.
• BasisAuthoredMotionSystem (framework): a static orchestrator + one Burst IJobParallelForTransform over every registered avatar's driven transforms, a sibling to RemoteBoneJobSystem. Registered at local/remote calibration; pumped from BasisEventDriver.LateUpdate immediately before the jiggle pass, so authored motion is the animated base and jiggle layers on top.
• Six movement kinds: Oscillate (sine/triangle/square/pulse, incl. chain travelling waves), Rotate, Orbit, Noise, RandomSelect (weighted random poses, multi-target + idle), Sequence (baked-clip playback).
• Authoring: a per-Kind custom inspector (shows only the relevant fields, localized tooltips) and BasisMotionClipBaker, an editor window that bakes an AnimationClip into a shared BasisMotionClip for Sequence.

It drives only non-humanoid transforms (tails, ears, accessories) that the networked skeleton and IK don't touch, so there's no write contention with the bone pipeline.

Required checks

All boxes below must be ticked before this PR can merge. If a check is genuinely N/A, tick it anyway and explain under Notes.

• Tested — I built and ran this locally. The change works in the editor and (where relevant) in a built player.
• Transform access is combined and limited — In hot paths, transform reads/writes go through TransformAccessArray or are otherwise batched. I have not added per-frame transform.position / transform.rotation / transform.localPosition calls inside loops. Whenever I need both position and rotation, I use the combined APIs — SetPositionAndRotation / SetLocalPositionAndRotation for writes, GetPositionAndRotation / GetLocalPositionAndRotation for reads — instead of two separate property accesses; the combined call does one local-to-world matrix traversal instead of two.
• Addressables used for asset/memory loading — Any new asset loads go through Addressables. No new Resources.Load, no direct asset references that pull large content into memory on scene load.
• No new GetComponent / AddComponent where avoidable — Where unavoidable, the result is cached on a field, and any GetComponent<T> is replaced with TryGetComponent<T>(out var x) — bare GetComponent will be denied. TryGetComponent is the modern API (Unity 2019.2+) and skips the Editor-only GC allocation GetComponent causes when a component is missing: Unity wraps the null return in a managed "fake null" object so its overloaded == operator can still detect destroyed C++ objects, and constructing that wrapper allocates; TryGetComponent returns a bool plus out parameter and never builds the wrapper. None of these calls run inside Update, LateUpdate, FixedUpdate, jobs, or other per-frame code paths.
• Per-frame work is scheduled through BasisEventDriver — Any new per-frame work hooks into BasisEventDriver rather than adding standalone Update / LateUpdate / FixedUpdate callbacks on a MonoBehaviour.
• Considered jobification — I asked whether this work can be moved to a Unity Job (Burst-compiled where possible). If it can, it is. If it cannot, the reason is in Notes.
• No needless { get; set; } properties or access lockdowns — Public fields are fine; Basis is meant to be read and modified freely, so don't wall things off private/internal without a real reason. Don't wrap a field in { get; set; } when the accessors do nothing — property accessors have a real performance cost vs direct field access, and the lead maintainer prefers plain fields (or a method / setter-only property when only the setter needs logic) over a noop-getter pair. For .Instance singletons, callers reassigning Type.Instance is allowed; if that would break your code, log a warning or throw — don't block the assignment. Locking down access is not your call.
• Camera access goes through BasisLocalCameraDriver — Code that needs the local camera (transform, projection, rig data, etc.) pulls it from BasisLocalCameraDriver rather than looking one up itself. Don't roll a separate camera discovery path.
• Logging uses BasisDebug — All new logging calls go through BasisDebug.Log / BasisDebug.LogWarning / BasisDebug.LogError (with an appropriate LogTag) instead of UnityEngine.Debug.Log / Debug.LogWarning / Debug.LogError. BasisDebug routes through Basis's tagged, color-coded logger and respects the project-wide LoggingDisabled toggle so logging can be killed at runtime; bare Debug.Log calls bypass that and will be denied.
• No scene-wide discovery for dependencies — New code is architected so it does not need FindObjectOfType / FindObjectsOfType / GameObject.Find / FindGameObjectsWithTag to locate what it depends on. References are wired in — registered through an existing manager/driver, injected at init, or passed in by the caller — rather than discovered by scanning the scene at runtime. If a scene scan is genuinely unavoidable, justify it under Notes.
• No allocations in hot paths — Per-frame code (Update / LateUpdate / FixedUpdate, simulation loops, jobs, anything called once per frame or more) does not allocate. No new on reference types, no LINQ, no string concatenation/interpolation, no boxing, no foreach over interface-typed collections. Allocate once at init and reuse the buffer.
• No debugging in hot paths — No log calls of any kind on per-frame paths, including BasisDebug. Hot-path logging floods the console and incurs cost on every frame regardless of whether the message is filtered out downstream. If a hot-path log is needed while iterating, gate it behind #if UNITY_EDITOR and remove (or leave gated) before merge.
• Hot-path collection access is optimized — Cache .Count (lists) / .Length (arrays) into a local int before the loop instead of re-reading the property each iteration. Prefer T[] (with a separate length int when the array is over-sized) over List<T> where the data is hot — Unity's mono BCL doesn't expose CollectionsMarshal.AsSpan(List<T>), so a list can't be fed into Span<T> / unsafe paths cleanly. Where the perf justifies it, drop into Span<T> / ref locals / Unsafe.As / unsafe pointer code to skip bounds checks and copies, and call out the invariants you're relying on under Notes so reviewers can sanity-check them.

Testing details

Tick the platforms you actually tested on. Leave the rest unticked — these are informational and do not block merge.

• Windows
• Linux
• Android
• iOS
• macOS

Input / control mode coverage:

• Tested in VR (note headset under Notes)
• Tested in desktop / non-VR mode
• Tested with phone controls (mobile touch input)
• N/A — change does not touch player/XR/input code

Where applicable, confirm these flows still work after your changes:

• Hot-switching (desktop ↔ VR mode swap at runtime)
• Avatar swapping
• Server swapping (joining / leaving / changing servers)
• N/A — change does not touch any of the above

Notes

• Draft because the perf acceptance bar isn't met yet. Validated functionally in-editor (SDK Test In Editor) on the reference avatar — tail wag (baked Sequence) with jiggle layering on top, ear twitch (multi-target RandomSelect), Oscillate and Rotate. The 1000-CCU load test (the whole point — beating the ~1/5-frame-time Animator baseline) and built-player runs are still outstanding.
• Addressables / Camera boxes are N/A — the feature loads no assets at runtime and uses no camera.
• Component lookup is a single GetComponentsInChildren<BasisAuthoredMotion> at calibration (gathering all components on the avatar), never per-frame; no bare GetComponent.
• Allocations — Build/Rebuild allocate (managed lists, flattening config into the SoA) but run only on a structural change at calibration; the per-frame Schedule and the Burst job are allocation-free.
• transform.Find — Sequence binds a baked clip's transform paths to bones via root.Find(path) once at registration, cached into the TransformAccessArray (never per-frame), mirroring how an AnimationClip binds its curves by path. It isn't in checkbox 10's denial list, but flagging it since STYLE.md mentions transform.Find: this is a scoped, one-shot bind, not scene-wide discovery.
• Determinism / follow-up — RandomSelect picks and Sequence playheads currently derive from Time.timeAsDouble. A shared/networked clock is needed for bit-identical playback across clients before multiplayer; tracked as a follow-up. RandomSelect.preventRepeats is serialized but not yet honored by the deterministic picker.
• Critical-flow boxes left unticked: avatar-swap re-registration is wired through the calibration hooks but not yet stress-tested.

Usage

On an avatar: add a BasisAuthoredMotion component (Content-Police-allowed) and one or more Movements, each with a Kind:

• Oscillate — periodic sway on a bone chain (axis, amplitude, frequencyHz, waveform; one chain entry = a simple sway, multiple = a travelling wave down the chain).
• Rotate — constant spin in place (target, axis, speedDeg in deg/sec).
• Orbit — revolve a target around a pivot at a radius.
• Noise — organic simplex drift on a channel.
• RandomSelect — on a fixed interval (intervalRange.x), pick one weighted pose Option; each option can drive its own bone (or fall back to selectTarget), with an idleWeight for the "do nothing" outcome. Good for ear flicks / blinks.
• Sequence — play a baked clip (below).

Baking a Sequence clip: Basis ▸ Authored Motion ▸ Bake Clip → choose the source AnimationClip and the avatar root → it writes a shared BasisMotionClip. Assign that to the Sequence movement's Baked Clip and set Sequence Root to the same root the paths were baked against.

Toggling: a movement group rides the component's own enabled — any toggle system that flips Behaviour.enabled (e.g. an HVR.Vixxy activation) turns it on/off, with no per-frame polling.

Jiggle: authored motion writes before the jiggle pass each frame, so JiggleRig physics layers on top of it automatically.

[towneh]

@dooly123 this will probably be fairly involved to perform a high ccu frame time impact comparison test. I’ll need to build Leona using this new system as well.