006 - Motion System

The Motion System provides reusable movement patterns based on deltaTime.

Why Motion AND Animation?

At first glance, animation and motion seem to be the same thing – both move things. But they solve different problems:

Animation: "In 3 seconds, the size should go from 80% to 120%."

• Has defined duration
• Interpolates between start and end
• Needs a clock

Motion: "The object moves at 50 pixels per second to the right."

• Runs endlessly (or until boundary)
• Based on velocity, not time
• Only needs deltaTime

Practical Example: A ball animates its pulsing (Breathe Animation). At the same time, it moves across the screen (VelocityMotion). Both together: Animation for values, Motion for position.

Animation vs. Motion

Components

Motion Base Class

Interface:

interface MotionContext {
  deltaTime: number;    // Time since last frame
  time: number;         // Total time since start
  canvasSize?: Size;    // For boundary calculations
}

abstract class Motion<T extends MotionOptions> {
  apply(position: Vector, context: MotionContext): Vector;
  getOffset(context: MotionContext): Vector;
}

LinearMotion

Linear movement between two points.

Options:

Modes:

VelocityMotion

Constant velocity in one direction.

Options:

NoiseMotion

Organic, random movement (Perlin Noise).

Options:

WaveMotion

Sine-based oscillation.

Options:

Waveforms:

PathMotion

Movement along a defined path.

Path Types:

Options:

OrbitMotion

Orbit around a center point.

Options:

Boundary Behaviors

Behavior at canvas boundaries.

                                         ┌─────────────────────┐
                                    ┌───▶│   BounceStrategy    │
                                    │    └─────────────────────┘
                                    │    ┌─────────────────────┐
                                    ├───▶│   WrapStrategy      │
                                    │    └─────────────────────┘
                                    │    ┌─────────────────────┐
┌──────────┐    ┌─────────┐   Yes   │    │   ClampStrategy     │
│ Position │───▶│ Boundary│────────▶├───▶└─────────────────────┘
└──────────┘    └─────────┘         │    ┌─────────────────────┐
                    │               ├───▶│   FadeStrategy      │
                    │ No            │    └─────────────────────┘
                    ▼               │    ┌─────────────────────┐
              ┌──────────┐         ├───▶│   ShrinkFadeStrategy│
              │ Continue │         │    └─────────────────────┘
              └──────────┘         │    ┌─────────────────────┐
                                   ├───▶│   DissolveStrategy  │
                                   │    └─────────────────────┘
                                   │    ┌─────────────────────┐
                                   ├───▶│   SendStrategy      │
                                   │    └─────────────────────┘
                                   │    ┌─────────────────────┐
                                   └───▶│   CompositeStrategy │
                                        └─────────────────────┘

Basic Strategies

Advanced Strategies (NEW)

BoundaryResult

ShrinkFade Example

const boundary = new ShrinkFadeStrategy({ 
  fadeDistance: 100, 
  minScale: 0.1,
  easing: 'easeOut'
});

const result = boundary.apply(position, canvasSize);

// Apply scale and alpha
ctx.globalAlpha = result.distanceToEdge ?? 1;
ctx.scale(result.scale ?? 1, result.scale ?? 1);

// Remove object when too small
if (result.remove) {
  entities.delete(entity.id);
}

Dissolve Example

const boundary = new DissolveStrategy({ particleCount: 30 });

const result = boundary.apply(position, canvasSize);

// Process particle burst
if (result.particleBurst) {
  particleSystem.emit({
    position: result.particleBurst.position,
    count: result.particleBurst.count,
    velocity: result.particleBurst.velocity,
  });
}

if (result.remove) {
  entities.delete(entity.id);
}

Send/Receive (Multi-Screen)

The SendStrategy integrates with the MultiScreenClient for real multi-screen installations:

import { 
  SendStrategy, 
  MultiScreenClient, 
  MultiScreenDebugPanel,
  calculateEntryPosition,
  calculateEntryVelocity,
  getOppositeEdge
} from '@carstennichte/cc-toolbox';

// 1. Set up MultiScreenClient
const client = new MultiScreenClient(socket, 
  { artworkId: 'item-001', instanceId: '0' },
  { room: 'exhibition:demo', autoJoin: true }
);

client.configureTopology({
  arrangement: '1x3',  // 3 Screens side by side
  position: 0,         // Left Screen
  totalScreens: 3,
  wrapAround: true
});

// 2. SendStrategy for boundary handling
const boundary = new SendStrategy({
  onExit: (pos, edge, data) => {
    // Send via MultiScreenClient to neighbor screen
    client.sendEntity(
      {
        type: 'Entity',
        exitPosition: { x: pos.x / canvasWidth, y: pos.y / canvasHeight },
        velocity: data.velocity,
        appearance: { color: data.color, size: data.size },
      },
      edge,
      'neighbor'  // Automatically to correct neighbor
    );
  },
  exitData: () => entity.toData(),
});

// 3. Receive entities
client.onEntityReceive((data) => {
  const entryPos = calculateEntryPosition(data.exitEdge, data.entity.exitPosition, { bounds: canvasSize });
  const entryVel = calculateEntryVelocity(data.exitEdge, data.entity.velocity);
  
  const newEntity = createEntity({
    position: entryPos,
    velocity: entryVel,
    color: data.entity.appearance.color,
  });
  entities.add(newEntity);
});

// 4. Debug panel (optional)
const debugPanel = new MultiScreenDebugPanel(client);
debugPanel.show();

Send Modes:

See also: Multi-Screen Communication

Composite (Combined Effects)

// Shrink + Send
const boundary = new CompositeStrategy({
  strategies: [
    new ShrinkFadeStrategy({ fadeDistance: 50 }),
    new SendStrategy({ onExit: sendToOtherScreen }),
  ],
  combineMode: 'merge',
});

Combining Motion

Motions can be combined:

// Orbit + Noise
const basePos = orbitMotion.apply(center, ctx);
const finalPos = noiseMotion.apply(basePos, ctx);

Tweakpane Integration

All motions have Tweakpane support.

Registration:

Typical Blades: