FrameTiming
The runtime and API of frameTiming: animation held "on ones, twos, threes" per object while the game underneath keeps running at full rate. Games and other packages call it; the `HeldFrames` and `HeldFramesScene` components call `register` / `applyDefault` for you.
FrameTiming (module)
The runtime and API of frameTiming: animation held "on ones, twos, threes" per object while the game underneath keeps running at full rate. Games and other packages call it; the HeldFrames and HeldFramesScene components call register / applyDefault for you.
FrameTiming.set(entity, timing)/clear(entity): put an object on a timing (a number of frames, a preset name such as"twos","threes","mixedAction", or{ onFrames, baseRate, fastOnFrames, fastSpeed }) by adding or updating its syncedHeldFramescomponent.FrameTiming.setDefault(timing, { allSkeletons }): the scene-wide timing (a syncedHeldFramesSceneon an entity namedFrameTiming).FrameTiming.holdPose(entity, seconds)/isHolding(entity): a held hit pose, the character's drawing frozen on the frame of a hit while its clips, movement and physics run on (impactFrames'holdPosestyle uses it).FrameTiming.now(),drawing(onFrames, baseRate): the shared animation clock every player steps from.FrameTiming.stats(),timingOf(entity),presets(),afterHold(fn),setActiveInEdit(on): what is held, what it costs, and hooks for tests.
How it holds: a skinned skeleton's AnimGraph keeps ticking every frame but hands its pose to the armature only on a step; a drawn subtree (children with no collider, body, camera or listener) is kept in place in its parent's space by math on the parent's current pose; a mesh on the gameplay entity itself is drawn by a local proxy moved only on steps. Colliders, bodies, scripts and cameras are never touched.
Interface
What this asset declares: the schema it conforms to, what it exposes, and the rendered structured payload.
conforms to
zero/source-extract/v2FrameTiming: animation on ones, twos, threes (any N) per object. What you SEE holds its pose for N frames of a fixed animation clock (24 drawings a second by default) while gameplay, scripts and physics keep running at full rate underneath: * Skeleton: every AnimGraph driving a held body (ClipPlayer, Locomotion, LocomotionFull, cutscenes, anything that ticks an AnimGraph) keeps advancing its clips every frame, but its pose is only handed to the armature on a step of the clock. The graph INSTANCE's `tick` is wrapped; no animator source is edited. * Transform, child meshes: the drawn subtrees under a held entity ("visual roots": children with no collider, body, camera or listener anywhere under them) are written back to the world pose they had at the last step, every frame, in one batched native write per timing group. * Transform, a mesh on the gameplay entity itself (a physics ball, a scripted prop): it is drawn by a local, unsynced, unparented proxy that is moved only on steps, and the original mesh is hidden. The gameplay entity, its colliders, body, scripts and camera are never touched, so physics, raycasts and picking read the real transform. Steps come from a shared clock (`FrameTiming.now()`: this peer's frame time plus an offset the host broadcasts), so every player sees the same drawings.
now( ) → number
Seconds on the clock every peer steps drawings from: this frame's time plus the offset to the host's clock (0 when alone or hosting).
examples
local t = FrameTiming.now()
drawing(onFrames: number, baseRate: number?) → number
The drawing index an object on `onFrames` at `baseRate` shows now. Two objects with the same timing show the same index on every peer.
| arg | type | description |
|---|---|---|
| onFrames | number | Frames each drawing is held for (1 = ones). |
| baseRate | number? | Animation clock in frames a second (24 for anime). |
examples
local k = FrameTiming.drawing(3, 24)
resolveSpec(spec: any) → Spec
| arg | type | description |
|---|---|---|
| spec | any |
presets( ) →
The built-in timings, by name. Each is a spec `set` and `setDefault` take, with a `note` saying what it looks like.
examples
for name, p in FrameTiming.presets() do print(name, p.onFrames) end
setOf(comp: any, into: { [string]: boolean }) → void
| arg | type | description |
|---|---|---|
| comp | any | |
| into | { [string]: boolean } |
buildQ( ) → void
idOf(e: any) → string
| arg | type | description |
|---|---|---|
| e | any |
blocksHold(id: string) → boolean
| arg | type | description |
|---|---|---|
| id | string |
pureVisual(e: any, depth: number) → boolean
| arg | type | description |
|---|---|---|
| e | any | |
| depth | number |
makeProxy(e: any, entry: Entry) → void
| arg | type | description |
|---|---|---|
| e | any | |
| entry | Entry |
collect(e: any, isRoot: boolean, entry: Entry, bodies: { string }) → void
| arg | type | description |
|---|---|---|
| e | any | |
| isRoot | boolean | |
| entry | Entry | |
| bodies | { string } |
makeSkel(body: string, n: number, rate: number) → Skel
| arg | type | description |
|---|---|---|
| body | string | |
| n | number | |
| rate | number |
wrapper(self: any, dt: number, sink: any?) → void
| arg | type | description |
|---|---|---|
| self | any | |
| dt | number | |
| sink | any? |
unwrapSkel(rec: Skel) → void
| arg | type | description |
|---|---|---|
| rec | Skel |
wrapSkel(rec: Skel) → void
| arg | type | description |
|---|---|---|
| rec | Skel |
setLocal(vid: string, p: { number }, r: { number }) → void
| arg | type | description |
|---|---|---|
| vid | string | |
| p | { number } | |
| r | { number } |
releaseEntry(entry: Entry) → void
| arg | type | description |
|---|---|---|
| entry | Entry |
scanEntry(entry: Entry) → void
| arg | type | description |
|---|---|---|
| entry | Entry |
applyTiming(entry: Entry) → void
| arg | type | description |
|---|---|---|
| entry | Entry |
qmul(a: { number }, b: { number }) → void
A drawn subtree is held in its parent's space by plain math on the parent's CURRENT pose (read through the entity, which composes the transforms written this frame). A native world-space write converts with the parent's last propagated pose, which lags a parent moved earlier in the same frame by one frame of motion, so it cannot hold a moving body still.
| arg | type | description |
|---|---|---|
| a | { number } | |
| b | { number } |
qconj(q: { number }) → void
| arg | type | description |
|---|---|---|
| q | { number } |
qrot(q: { number }, v: { number }) → void
| arg | type | description |
|---|---|---|
| q | { number } | |
| v | { number } |
parentPose(pid: string?) → void
The parent's world pose now: position, rotation, scale (identity for a root).
| arg | type | description |
|---|---|---|
| pid | string? |
destroyGroup(g: Group) → void
| arg | type | description |
|---|---|---|
| g | Group |
newGroup(key: string, n: number, rate: number) → Group
| arg | type | description |
|---|---|---|
| key | string | |
| n | number | |
| rate | number |
stepVis(v: Vis) → void
Snap a drawn subtree onto its gameplay pose and remember where that is in the world.
| arg | type | description |
|---|---|---|
| v | Vis |
holdVis(v: Vis) → void
Keep a drawn subtree where it was drawn at the last step, whatever its parent did since.
| arg | type | description |
|---|---|---|
| v | Vis |
rebuild( ) → void
restoreAll( ) → void
sampleMixed(t: number) → void
| arg | type | description |
|---|---|---|
| t | number |
scanAutoSkeletons( ) → void
slowWork(t: number) → void
| arg | type | description |
|---|---|---|
| t | number |
frame( ) → void
safeFrame( ) → void
`task.defer` runs at the very end of the frame: after every component update and every task.loop that moved something, so the held pose is the last transform write before the frame is drawn.
register(entityId: string, opts: { [string]: any }) → void
Start holding `entityId` with the given settings. Called by the HeldFrames component; use `set` from your own code.
| arg | type | description |
|---|---|---|
| entityId | string | The gameplay entity whose drawn pose is held. |
| opts | { [string]: any } | `{ onFrames, baseRate, fastOnFrames, fastSpeed, holdTransform, holdSkeleton, children }`. |
examples
FrameTiming.register(e.id, { onFrames = 3 })unregister(entityId: string) → void
Stop holding `entityId`: its meshes and skeleton draw live again.
| arg | type | description |
|---|---|---|
| entityId | string | The entity `register` was called with. |
examples
FrameTiming.unregister(e.id)
canWrite(id: string?) → boolean
| arg | type | description |
|---|---|---|
| id | string? |
holderId( ) → string
applyOp(op: { [string]: any }) → void
| arg | type | description |
|---|---|---|
| op | { [string]: any } |
listen( ) → void
run(op: { [string]: any }, id: string?) → void
| arg | type | description |
|---|---|---|
| op | { [string]: any } | |
| id | string? |
set(target: any, timing: any, opts: { [string]: any }?) → void
Put an entity on a timing: a number of frames (1 ones, 2 twos, 3 threes, ...), a preset name ("twos", "mixedAction", ...) or a spec table. Adds or updates the HeldFrames component, so the timing is synced to every player and saved with the scene. `opts` sets the other HeldFrames fields (holdTransform, holdSkeleton, children).
| arg | type | description |
|---|---|---|
| target | any | The entity (or id) whose drawn pose is held. |
| timing | any | Frames per drawing, a preset name or a spec table. |
| opts | { [string]: any }? | Optional HeldFrames fields to set too. |
examples
FrameTiming.set(entity.find("hero"), 3)FrameTiming.set(entity.find("hero"), "mixedAction")clear(target: any) → void
Take an entity off its timing: removes its HeldFrames component, so it draws smoothly at the display rate again for every player. Any player can call it: the change goes through the entity's owner.
| arg | type | description |
|---|---|---|
| target | any | The entity (or id). |
examples
FrameTiming.clear(entity.find("hero"))setDefault(timing: any, opts: { allSkeletons: boolean? }?) → void
Set the scene-wide default timing: what every HeldFrames with `onFrames = 0` uses, and (with `allSkeletons`) what every animated body in the scene without its own HeldFrames is held on. Writes the HeldFramesScene component on a synced entity named "FrameTiming" (created when absent) so every player sees it and it is saved with the scene. Any player can call it: a player who does not own that entity sends the change to its owner, who applies it for everyone.
| arg | type | description |
|---|---|---|
| timing | any | Frames per drawing, a preset name or a spec table. |
| opts | { allSkeletons: boolean? }? | `{ allSkeletons = boolean }`. |
examples
FrameTiming.setDefault("twos", { allSkeletons = true })clearDefault( ) → void
Take the scene-wide default timing off for every player: the "FrameTiming" entity and its HeldFramesScene go, and the default returns to what it is before any `setDefault` (twos at 24 a second for HeldFrames with `onFrames = 0`, no other body held). Characters with their own HeldFrames keep it; `clear(e)` takes those off. Any player can call it.
examples
FrameTiming.clearDefault()
applyDefault(opts: { [string]: any }) → void
Apply scene-wide default settings to the running driver. Called by the HeldFramesScene component; use `setDefault` from your own code.
| arg | type | description |
|---|---|---|
| opts | { [string]: any } | `{ onFrames, baseRate, fastOnFrames, fastSpeed, allSkeletons }`. |
examples
FrameTiming.applyDefault({ onFrames = 2 })getDefault( ) →
The scene-wide default timing in force.
examples
print(FrameTiming.getDefault().onFrames)
stats( ) →
What the driver holds right now and what it costs per frame.
examples
print(FrameTiming.stats().avgMs)
resetStats( ) → void
Reset the peak/average cost counters `stats` reports.
examples
FrameTiming.resetStats()
afterHold(fn: (number) →
Call `fn(sharedTime)` at the end of every frame the driver runs, straight after the held poses for that frame are written: the moment a read sees exactly what the frame draws. For tests, debug overlays and effects that must line up with the drawings (an impact flash on a step).
| arg | type | description |
|---|---|---|
| fn | (number | Called with the shared clock time of the frame. |
examples
local stop = FrameTiming.afterHold(function(t) print(FrameTiming.drawing(2)) end)
setActiveInEdit(on: boolean) → void
Hold poses in edit mode too while the gameplay clock runs (`engine.paused = false`). Off by default, so an edit-mode save never catches a counter-moved mesh; tests and previews turn it on and off again.
| arg | type | description |
|---|---|---|
| on | boolean | True to hold in edit mode while the clock runs. |
examples
FrameTiming.setActiveInEdit(true)
timingOf(target: any) →
The timing an entity is drawn on right now (after mixed switching and the scene default), or nil when it is not held.
| arg | type | description |
|---|---|---|
| target | any | The entity (or id). |
examples
print(FrameTiming.timingOf(entity.find("hero")).onFrames)measure(target: any, seconds: number?) →
Measure, on this machine, how an entity is drawn against how it moves: for `seconds` (default 3), at the end of every frame, whether its gameplay transform moved and whether its drawn pose (its first held drawn subtree, or its proxy) moved. Yields; call it from a task or a test. Holding runs in play (or edit with `setActiveInEdit`).
| arg | type | description |
|---|---|---|
| target | any | The held entity (or id). |
| seconds | number? | How long to watch. |
examples
print(FrameTiming.measure(entity.find("Apprentice"), 3).drawingsPerSecond)drawnPos( ) → vector
holdPose(target: any, seconds: number?) → number
Hold a character's pose still for `seconds` (a held hit pose: the drawing freezes on the frame of the hit while its clips, its movement, physics and controls keep running at full rate underneath; when the hold ends it snaps to wherever its animation is by then). Works on any entity with a skinned skeleton on or under it, held by HeldFrames or not. Local to this machine (impactFrames sends the hit to every player and each holds its own copy). Holds only while the driver runs (play mode, or edit with `setActiveInEdit`).
| arg | type | description |
|---|---|---|
| target | any | The entity (or id) whose skeletons hold. |
| seconds | number? | How long the pose holds (default 0.2). |
examples
FrameTiming.holdPose(enemy, 0.25)
isHolding(target: any) → boolean
Whether a skeleton body under `target` is in a held hit pose now.
| arg | type | description |
|---|---|---|
| target | any |
examples
print(FrameTiming.isHolding(enemy))
Spec = {Sub-parts
Everything contained inside this part. Assets are composite children (clickable cards). Files are leaf payloads. Expand any row to view its source.
Showing up to 3 levels deep. Open a part to see what it holds further down.
Problems
Everything affecting this asset right now: its own problems, anything wrong inside it, and problems on its direct dependencies.
agent_score is exposed.+ quality × 0.35
+ performance × 0.25
± compat factor
Usability ratings
Did the part work as advertised when consumers tried to drop it in. Separate from upvotes: those are taste; this is "did it function".
Scoped to this part · feeds back into the world's score.