Log inGet started
Package

frameTiming.package

README.md

frameTiming: animation on ones, twos and threes

Hand-drawn animation timing for 3D characters. Put a character on twos and its drawn pose changes 12 times a second, like a drawing in an anime, while its movement, physics, collisions, the camera and the controls keep running at full speed. Ones, twos, threes, fours or any number, per character or for the whole scene, a mixed timing that snaps to full rate for fast moves, and a held hit pose. Every player sees the same drawings.

Get started: install frameTiming, then

require("~frameTiming.FrameTiming").set(character, "twos")

animeBlocks and impactFrames bring it along. Version 1.0.4; the history is at the end.

In five minutes

  1. Install frameTiming from ZeroMind (search "animation on twos"). animeBlocks brings it along.
  2. Put a character on a timing, from any script or once with the execute tool:
local FrameTiming = require("~frameTiming.FrameTiming")
FrameTiming.set(entity.find("Hero"), "twos")

or add the HeldFrames component to the character in the editor (or in your scene's build.luau). For a player, put HeldFrames on the body under your PlayerPrototype: every player who joins is cloned from it.

  1. Press play. The character's poses step; walk it around and the body still moves every frame.

A whole cast at once: FrameTiming.setDefault("twos", { allSkeletons = true }) holds every animated body in the scene that has no HeldFrames of its own.

Timings

PresetWhat it looks like
ones24 drawings a second: full animation on a film clock.
twos12 drawings a second: the classic anime and feature default.
threes8 drawings a second: limited TV animation, snappy and graphic.
fours6 drawings a second: very limited, a deliberate choppy look.
mixedActionTwos while slow, ones once the object moves faster than 4 m/s: smooth fast action.
mixedImpactTwos while slow, threes once it moves fast: hard, punchy action poses.
limitedTVThrees on a 24 clock: the 8-drawings-a-second TV budget look.
stopMotionOne pose per step of a 12 fps clock: puppet and stop-motion cadence.

Or any spec: FrameTiming.set(e, { onFrames = 3, baseRate = 24, fastOnFrames = 1, fastSpeed = 6 }).

The HeldFrames component

FieldDefaultMeaning
onFrames2Frames of the animation clock each drawing is held for: 1 ones, 2 twos, 3 threes, any N. 0 uses the scene default.
baseRate24The animation clock in frames a second (24 for anime and film; 0 uses the scene default). Independent of the display rate.
fastOnFrames0Mixed timing: frames per drawing while the entity moves faster than fastSpeed (1 for smooth fast action, 3 for punchy poses); 0 is off.
fastSpeed4Mixed timing: the speed in m/s above which fastOnFrames applies (it drops back below 80 percent of it).
holdTransformtrueHold the drawn meshes' world pose between steps; the gameplay transform keeps moving.
holdSkeletontrueHold the skinned skeleton's pose between steps; its clips keep playing underneath, so animation events stay on time.
childrentrueHold the drawn meshes and skeletons under the entity too.

HeldFramesScene (one per scene, made by setDefault on a synced entity named "FrameTiming", taken off by clearDefault, which returns the default to twos for HeldFrames with onFrames = 0 and holds no other body) holds the scene default: onFrames, baseRate, fastOnFrames, fastSpeed, allSkeletons. Both are synced and saved with the scene.

The module

set(e, timing, opts?), clear(e), setDefault(timing, { allSkeletons }), clearDefault(), getDefault(), presets(), timingOf(e), now(), drawing(onFrames, baseRate), holdPose(e, seconds), isHolding(e), measure(e, seconds), stats(), resetStats(), afterHold(fn), setActiveInEdit(on). Each is described in FrameTiming.module/README.md and its --!desc.

Held hit pose

FrameTiming.holdPose(enemy, 0.25) freezes a character on the drawing of a hit for a quarter of a second while its clips, movement and physics run on underneath; when it lets go it snaps to wherever its animation is by then, the way an anime holds the frame of a blow. impactFrames' holdPose style uses it on the hit character and the attacker.

How it keeps the game at full speed

Nothing the game reads is held. The gameplay entity, its colliders, physics body, scripts and camera are never touched, so movement, physics, raycasts, picking and controls run every frame as before. What is held is only what is drawn:

  • Skeletons: the AnimGraph driving a held body keeps ticking every frame (clips advance, events fire), but its pose is handed to the armature only on a step of the clock.
  • Drawn subtrees (children with no collider, body, camera or listener under them, such as an avatar's visual): kept in place in their parent's space between steps, from the parent's current pose each frame, and snapped back onto the gameplay pose on each step.
  • A mesh on the gameplay entity itself (a physics ball, a scripted prop): drawn by a local, unsynced proxy moved only on steps; the original mesh is hidden.

Measured

FrameTiming.measure(entity, seconds) watches a held entity at the end of every frame and reports how often its gameplay transform moved against how often its drawn pose changed. Measured in the showcase (the Anime Looks world), and checked by the test suite on every run:

  • A child mesh of a root moved by a component every frame, on threes: the root moved on 45 of 45 frames, the drawn mesh held still to under 1 cm between steps and landed back on the root within 1 mm on every step (child mesh holds its world pose between steps).
  • A falling physics ball on twos: its body moved on over 80 percent of frames, its drawn proxy changed only on frames where the 12-a-second drawing index changed, and never more than once per drawing (physics body moves every frame, drawn pose only on steps).
  • Measured on 12 November 2026 in the showcase, in play, in a client running the game at full speed (a sphere moved by a script every frame, FrameTiming.measure over 4 seconds):
TimingGame frames a secondFrames the gameplay transform movedDrawn pose changes a secondExpected (24 a second base)Changes off a step
twos57.0229 of 22911.7120
threes39.1157 of 1577.9780

So the game (movement, physics, controls, the camera) updates on every frame while the drawing holds each pose for two or three steps of the 24-a-second animation clock. The same probe in the desktop editor, which drew only 9 to 15 frames a second in the heavy forest scene, read 8.3 changes a second on twos: below 24 frames a second every frame already crosses a drawing, so holding on twos only shows once the game runs faster than the drawing rate.

The script cost is reported by FrameTiming.stats() (avgMs, peakMs): a handful of characters costs a few hundredths of a millisecond a frame; it grows with the number of held drawn subtrees (a few property reads and writes each per frame).

Multiplayer

The timing lives in synced component fields, so every player holds the same objects on the same timing. Steps come from a shared clock (FrameTiming.now()): each peer's frame time plus an offset the host broadcasts every two seconds, so two players see the same drawing index at the same moment. The holding itself is done on every machine locally and sends nothing per frame.

Any player can change the timing (since 1.0.3). A synced entity belongs to one player, usually the room's host, and only its owner can write it, so set, clear, setDefault and clearDefault on any other player's machine send the change to the room on the frameTiming.op channel and the owner applies it for everyone. Before 1.0.3 setDefault made the "FrameTiming" holder with a plain spawn, local to the machine that made it, so a timing set there changed on that screen only; 1.0.3 makes the holder synced, and syncs one saved by an older version the next time the scene timing is set.

Known limits

  • Edit mode does not hold unless setActiveInEdit(true) is called with the clock running, so a save in the editor never catches a counter-moved mesh.
  • A world script that steps once per drawn frame stalls while the editor skips frames (engine #22740): in a struggling editor the held clock still follows wall time, so drawings are skipped rather than slowed.
  • Non-uniformly scaled, rotated parents hold their drawn subtrees with per-axis scale, which is exact for uniform scale and close for mild non-uniform scale.
  • Particles, trails and cloth are not held; they keep the display rate.

Contents

  • FrameTiming (module): the runtime and API.
  • HeldFrames (component): one object's timing.
  • HeldFramesScene (component): the scene default.
  • tests/frameTiming.testSuite: the measurements above, the API and the held hit pose.

Version history

Now 1.0.4 (1.0.4: a short description and a lead that says what it gives and how to start, with the history moved here; 1.0.3: any player can set the timing and everyone sees it, the scene timing lives on a synced entity, and clearDefault() takes it off). Built on the engine's own animation graph (@builtin::systems.anim.AnimGraph); no animator or character code is edited. Every player sees the same drawings: steps come from one shared clock.