@drawcall/acta

@drawcall/acta

Acta is a JSON format for 3D character behavior in three.js.

Runtime Shape

Acta separates host intent, Acta-owned animation state, motion output, and gameplay effects:

• The host sends persistent frame input with one flat update(delta, { isGrounded, moveDirection, moveAmount, aimDirection, facingDirection }) object.
• One-shot action inputs are requested with requestAction(...).
• Behavior JSON decides which state currently owns locomotion, jumps, animation, and timed effects.
• Top-level runtime callbacks apply accepted locomotion and jump output.
• Gameplay handles Acta effects with the effects option; acta test logs those as effect lines.

This is the same shape for FPS players, third-person players, enemies, companions, and crowds. A first-person player may use camera-derived aimDirection and headDirection; a third-person player may send camera-relative moveDirection; an NPC may send navigation-derived moveDirection plus target-derived aimDirection or facingDirection.

const interpreter = await CharacterBehaviorInterpreter.create(behavior, model, {
  effects: {
    muzzle: shootWeaponFromActaEffect,
  },
  jump: (jumpVelocity) => physics.applyVelocity(new Vector3(0, jumpVelocity ?? 8, 0)),
  motion: (desiredVelocity, delta) => {
    physics.inputVelocity.copy(desiredVelocity)
    physics.update(model.scene, delta, physicsOptions)
  },
})

interpreter.requestAction('fire')

interpreter.update(delta, {
  aimDirection,
  facingDirection,
  isGrounded: physics.isGrounded,
  moveAmount: moveDirection.lengthSq() > 0 ? 1 : 0,
  moveDirection,
  headDirection: aimDirection,
})

Use effects for animation-timed gameplay moments:

{
  "type": "animation",
  "url": "/humanoid-animation/quaternius-ual1-pistol-shoot.glb",
  "effects": [{ "name": "muzzle", "at": 0.08 }]
}

Use movement.speed to declare the desired locomotion speed for an active animation. In blends, put movement on each animations[] sample so each clip declares its own speed and allowed directions. speed is a positive number in meters per second (root-motion traversal is not supported yet). allowedDirections describes which movement directions the animation supports relative to body facing, not relative to the camera; movement is accepted while it points within 30° of an allowed direction. A blend selects the nearest sample and crossfades to it rather than interpolating two clips, so provide a sample for every direction the character should move. Use "all" only for truly omnidirectional or direction-neutral animation; otherwise list the supported directions such as ["forward"] or ["back"].

Convert Behavior JSON To TypeScript

npx @drawcall/acta convert <behavior.json> > character-behavior.converted.ts

convert validates behavior JSON and turns it into a TypeScript character class template. The generated class extends THREE.Group, loads a provided model or the default Viverse mannequin, creates a ready interpreter with CharacterBehaviorInterpreter.create(...), and includes TODO methods for Motion Output, Jump Output, and Effect Outputs. Use --json only when you want to inspect the validated behavior JSON directly.

Test animations

Animation references point directly at single-animation GLB files. CLI commands look for the nearest public/ directory by default; pass --animation-dir to use a different directory.