002 - Core System

The core system forms the foundation of the cc-toolbox. It solves a central problem: How do I manage the state of a generative artwork so that it's persistable, synchronizable, and controllable via UI?

The answer: A central ParameterObject that serves as the single source of truth. All components read from and write to it. The IOManager coordinates communication, and the TweakpaneManager binds the UI.

Components

Artwork

The central container for each artwork.

Lifecycle:

    User           Sketch          Artwork         SceneGraph
      │               │               │               │
      │ SketchRunner  │               │               │
      │   .run()      │               │               │
      │──────────────>│               │               │
      │               │ new Artwork() │               │
      │               │──────────────>│               │
      │               │               │ initCanvas()  │
      │               │               │ initTweakpane()
      │               │ configure()   │               │
      │               │──────────────>│               │
      │               │               │ addAgent()    │
      │               │               │──────────────>│
      │               │               │               │
      │               │    ┌──────────────────────────┤
      │               │    │     Render Loop          │
      │               │    │                          │
      │               │ draw()        │               │
      │               │<──────────────│               │
      │               │    draw()     │               │
      │               │──────────────────────────────>│
      │               │    │                          │
      │               │    └──────────────────────────┤
      │               │               │               │

Props:

SceneGraph

Manages all drawable objects (Agents/Drawables).

Features:

• Hierarchical Structure
• Z-Order Management
• Batch Updates
• Visibility Control

API:

ParameterObject

The ParameterObject is the heart of the architecture. It's a simple JavaScript object that contains the complete state of an artwork – from canvas size to colors to agent-specific settings.

Why so central?

The problem with generative art: You find the perfect setting after hours of tweaking – and lose it on the next reload. The ParameterObject solves this:

1. Serializable: Saveable as JSON (Snapshots!)
2. Synchronizable: Via Sockets to Studio/other Artworks
3. UI-bindable: Tweakpane reads and writes directly to it
4. Versionable: Git-friendly, diffable

Structure:

parameter
├── artwork                    # Artwork Settings
│   ├── canvas
│   └── animation
├── format                     # Format Settings
├── colorset                   # Active Colors
├── tweakpane                  # UI State (prefixed)
│   └── {component}
│       └── {subcomponent}
│           └── {key}: value
└── {agent}                    # Agent-specific
    └── {property}: value

Properties:

• Serializable (JSON)
• Import/Export capable
• Event-capable via IOManager

IOManager

The IOManager is the event hub of the application. It decouples components from each other – no one needs to access other components directly.

The problem without IOManager:

ColorSet changes color → must know all Brushes → tight coupling

With IOManager:

ColorSet → emits "colorset:changed" → IOManager → all Subscribers receive it

Two communication patterns:

1. Channel-based (Pull)

   • For Tweakpane updates
   • State-based
   • onUpdate() Callbacks

2. Event-based (Pub/Sub)

   • For events like colorset:changed
   • Payload-based
   • subscribe() / emit()

Example Events:

TweakpaneManager

Tweakpane is a fantastic UI library for parameter manipulation. But with complex artworks with many agents, management becomes chaotic: Who writes where? Whose state is that?

The TweakpaneManager solves this through modules with isolated state areas. Each module:

• Has its own namespace in the ParameterObject
• Knows only its own state
• Communicates via IOManager channels

The Brush Pattern is the reference implementation: A Brush module manages parameter.tweakpane.{component}.brush.* and transforms UI values (with prefix brush_) into business logic values (without prefix).

Concept:

TweakpaneManager
├── createModule(options)     → TweakpaneModule
│   ├── id: "brush:shape"
│   ├── statePath: ["brush", "shape"]
│   ├── stateDefaults: {...}
│   └── channelId: "ui:brush:shape"
└── modules: Map<id, Module>

TweakpaneModule API:

Format

Predefined canvas formats.

Categories:

Responsive Behavior:

• FitMode: 'contain' - Fit in container
• FitMode: 'cover' - Fill container
• FitMode: 'none' - Original size

Vector

2D/3D vector operations.

Methods:

Coordinate & Size

Helper classes for positions and sizes.

// Coordinate - Row/Col
const coord = new Coordinate(row, col);

// Size - Width/Height
const size = new Size(width, height);
size.area;     // → width * height
size.aspect;   // → width / height

Debug

Logging and debugging utilities.

Modes:

• silent - No output
• minimal - Errors only
• normal - Errors + Warnings
• verbose - Everything

Methods: