008 - Agents

Agents are reusable drawing components for the SceneGraph.

The Concept

An agent is an autonomous "thing that draws." It has its own parameters, its own state, its own Tweakpane UI. You add it to the SceneGraph, and it takes care of the rest.

Why Agents instead of Functions? A function drawParticles(ctx, particles) is stateless – you have to manage the particle list yourself. A ParticleManager agent manages its particles internally, has Tweakpane sliders for Count/Speed/Size, and you only call .draw(props).

Why SceneGraph? Because order matters. What is drawn first is behind. An agent for the background must come before the particles. The SceneGraph makes this explicit and allows reordering at runtime.

The Pattern: Each agent has a static ensureParameterSet() method that writes defaults to the ParameterObject. This must happen BEFORE Tweakpane setup – otherwise the Exhibition Mode crashes (which has no Tweakpane).

Overview

                          ┌─────────────────┐
                          │   SceneGraph    │
                          └─────────────────┘
                                   │
       ┌───────────────────────────┼───────────────────────────┐
       │           │           │   │   │           │           │
       ▼           ▼           ▼   │   ▼           ▼           ▼
┌────────────┐ ┌────────────┐ ┌────┴───┐ ┌────────────┐ ┌────────────┐
│ Background │ │Background- │ │ Brush  │ │ Particle-  │ │ Particle-  │
│            │ │   Shape    │ │        │ │  Manager   │ │   Wind     │
└────────────┘ └────────────┘ └────────┘ └────────────┘ └────────────┘

       ┌───────────────────────────┼───────────────────────────┐
       │           │           │   │   │           │           │
       ▼           ▼           ▼       ▼           ▼           ▼
┌────────────┐ ┌────────────┐ ┌────────┐ ┌────────────┐ ┌────────────┐
│  Entity_   │ │   Grid_    │ │ Image- │ │ ImageLayer │ │ Characters │
│  Manager   │ │  Manager   │ │ Layer  │ │ Dithering  │ │            │
└────────────┘ └────────────┘ └────────┘ └────────────┘ └────────────┘

                          ┌─────────────────────┐
                          │ DitherShapeGenerator│
                          └─────────────────────┘

Agents List

Background

Simple colored background.

Parameters:

BackgroundShape

A shape centered in the background.

Parameters:

Brush

The universal drawing tool.

Parameters:

Physics Options:

ParticleManager

Manages particle systems.

Parameters:

Particle Sources:

ParticleWind

Wind simulation with noise.

Parameters:

Entity_Manager

Bouncing/Wrapping objects.

Parameters:

Entity Features:

• Position, Velocity, Acceleration
• Bouncing at Canvas Boundaries
• Wrapping (Pac-Man Style)
• Collision Detection (optional)

Entity Stats Broadcasting

The Entity_Manager automatically writes statistics to the ParameterObject that can be received by other artworks (e.g., ParameterObserver):

// These values are automatically written to parameter.entity.stats:
{
  centerX: 0.52,      // Normalized center of all entities (0-1)
  centerY: 0.48,
  avgSpeed: 0.023,    // Average speed (normalized)
  spreadX: 0.31,      // Entity spread
  spreadY: 0.28,
  
  // Positions of first 10 entities (normalized 0-1)
  e0_x: 0.12, e0_y: 0.45,
  e1_x: 0.67, e1_y: 0.23,
  // ... up to e9
}

Usage with ParameterObserver:

// In the observer artwork:
const observer = new ParameterObserver({
  serverUrl: 'http://localhost:4000',
  targetArtwork: 'item-cc-entities',
});

observer.onUpdate((params, artworkId) => {
  const stats = params.entity?.stats;
  if (stats) {
    console.log(`Entities center: (${stats.centerX}, ${stats.centerY})`);
    console.log(`Average speed: ${stats.avgSpeed}`);
  }
});

With Smart Filter in ParameterMandala, exactly these dynamic entity stats are visualized while static parameters (canvas size, animation settings) are filtered out.

Grid_Manager

Dual-View Grid System.

Parameters:

Views:

• PointGrid: Focus on intersection points and lines
• CellGrid: Focus on cells as mini canvases

ImageLayer

Image display.

Parameters:

ImageLayerDithering

Image with dithering effect.

Parameters:

Dither Modes:

Dither Shapes:

Characters

Text and single characters.

Parameters:

DitherShapeGenerator

Generates shapes from dither data for plotters.

Methods:

Agent Interface

All agents implement:

interface Agent {
  draw(props: ArtworkProps): void;
  update?(deltaTime: number): void;
  setParameter?(key: string, value: any): void;
}