HW

Getting Started

Installation

Install the library using npm:

npm install hw-ts-parametric-sequencer

Or via yarn:

yarn add hw-ts-parametric-sequencer

Or via pnpm:

pnpm add hw-ts-parametric-sequencer

Requirements

  • Node.js >= 18.0.0
  • TypeScript >= 5.0.0 (for TypeScript projects)

Importing

The library provides separate entry points for 2D and 3D functionality:

3D Animations

import { reconcileScene, reconcile_animationState, NodeMain, NodeCamera, Vector3, Euler, SceneObject } from 'hw-ts-parametric-sequencer/3d';

2D Animations

import { reconcileScene2D, reconcile_animationState2D, NodeMain2D, NodeCamera2D, Vector2, SceneObject2D } from 'hw-ts-parametric-sequencer/2d';

Important: There is no default/root export. You must explicitly import from `/2d` or `/3d`.

TypeScript Support

The library is written in TypeScript and includes full type definitions. No additional `@types` package is needed.

Tree-Shaking

The library is designed for optimal tree-shaking:

  • Importing only from `/2d` will exclude all 3D code from your bundle
  • Importing only from `/3d` will exclude all 2D code from your bundle
  • No shared code between 2D and 3D implementations ensures complete separation

Basic Usage

3D Example

import { reconcileScene, reconcile_animationState, NodeMain, Vector3, Euler, SceneObject } from 'hw-ts-parametric-sequencer/3d';

// Create a scene object
const object1 = new SceneObject(
  'object1',
  {} // markers
);

// Define animation scene
const scene = [
  new NodeMain({
    name: 'object1-position',
    chapter: 'intro',
    sceneObject: object1,
    time: { type: 'absolute', value: 0 },
    duration: 2,
    position: { type: 'absolute', value: new Vector3(1, 0, 0) },
    rotation: { type: 'relative', value: new Euler(0, 90, 0) },
    opacity: 1.0
  })
];

// Reconcile the scene (processes nodes, resolves timing dependencies)
const reconciled = reconcileScene(scene);

// Your own animation loop
let startTime = Date.now();
function animate() {
  requestAnimationFrame(animate);
  
  const currentTime = (Date.now() - startTime) / 1000;
  const state = reconcile_animationState(reconciled, currentTime);
  
  // Update your 3D scene with state.models and state.camera
  state.models.forEach((modelState, modelID) => {
    updateModelPosition(modelID, modelState.position);
    updateModelRotation(modelID, modelState.rotation);
    updateModelOpacity(modelID, modelState.opacity);
  });
  updateCamera(state.camera);
}

animate();

2D Example

import { reconcileScene2D, reconcile_animationState2D, NodeMain2D, Vector2, SceneObject2D } from 'hw-ts-parametric-sequencer/2d';

// Create a scene object
const object1 = new SceneObject2D(
  'object1',
  {} // markers
);

// Define animation scene
const scene = [
  new NodeMain2D({
    name: 'object1-move',
    chapter: 'intro',
    sceneObject: object1,
    time: { type: 'absolute', value: 0 },
    duration: 2,
    position: { type: 'absolute', value: new Vector2(100, 50) },
    rotation: { type: 'relative', value: 90 },
    opacity: 1.0,
    scale: 1.5
  })
];

// Reconcile the scene (processes nodes, resolves timing dependencies)
const reconciled = reconcileScene2D(scene);

// Your own animation loop
let startTime = Date.now();
function animate() {
  requestAnimationFrame(animate);
  
  const currentTime = (Date.now() - startTime) / 1000;
  const state = reconcile_animationState2D(reconciled, currentTime);
  
  // Update your 2D scene
  state.models.forEach((modelState, modelID) => {
    updateModelPosition(modelID, modelState.position);
    updateModelAngle(modelID, modelState.rotation);
    updateModelOpacity(modelID, modelState.opacity);
    updateModelScale(modelID, modelState.scale);
  });
  updateCamera(state.camera);
}

animate();

Framework Integration

This library is framework-agnostic. It only provides animation state data. You need to integrate it with your chosen rendering framework:

  • Three.js: Update Object3D positions, rotations, and materials
  • React Three Fiber: Use state in your component render functions
  • Canvas 2D: Draw sprites based on animation state
  • SVG: Update SVG element transforms
  • Any other framework: Use the animation state to update your scene