@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, worldVelocity, aimDirection }) 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 lookDirection; a third-person player may also send camera-relative worldVelocity; an NPC may send navigation-derived worldVelocity 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: (worldVelocity, delta) => {
    physics.inputVelocity.copy(worldVelocity)
    physics.update(model.scene, delta, physicsOptions)
  },
})

interpreter.requestAction('fire')

interpreter.update(delta, {
  aimDirection,
  isGrounded: physics.isGrounded,
  worldVelocity,
  lookDirection: 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.velocityScale to scale the host-provided locomotion velocity while a behavior owns locomotion output. movement.speed, markers, inputStates, motionIntent, applyMove, moveVelocity, and headDirection are invalid API shapes caught by TypeScript; behavior-dependent state/action mistakes are caught at runtime.

Convert Legacy Behavior JSON

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

convert turns behavior JSON 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 converted 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.