nodarium/docs/LLM.md

Nodarium - LLM Documentation

Overview

Nodarium is a WebAssembly-based visual programming language for creating procedural 3D plants. The app features a node-based interface where users connect WASM modules to generate plant models in real-time. Currently used to develop https://nodes.max-richter.dev, a procedural modelling tool for 3D plants.

Architecture

Core Components

1. Node System (app/static/nodes/)

WASM-based nodes that perform computations. All nodes must implement the NodeDefinition interface.

• Node Storage: app/static/nodes/max/plantarium/

  • box.wasm - Box geometry node
  • branch.wasm - Branch generation
  • float.wasm - Float value node
  • gravity.wasm - Gravity/physics node
  • instance.wasm - Instance rendering
  • leaf.wasm - Leaf geometry
  • math.wasm - Math operations
  • noise.wasm - Noise generation
  • output.wasm - Output node
  • random.wasm - Random value generation
  • rotate.wasm - Rotation node
  • shape.wasm - Shape geometry
  • stem.wasm - Stem generation
  • triangle.wasm - Triangle geometry
  • vec3.wasm - Vector3 node

• Node Registry: app/src/lib/node-registry.ts

  • Loads and manages WASM nodes
  • getNodeWasm() - Creates WASM wrapper from bytes
  • getNode() - Retrieves node definition

• Debug Node: app/src/lib/node-registry/debugNode.js

  • Special debug node with wildcard inputs
  • Variable-height nodes and parameters
  • Quick-connect shortcut

2. Graph Interface

Visual node editor built with Svelte 5.

• Main Wrapper: app/src/lib/graph-interface/graph/Wrapper.svelte

  • Entry point for graph interface
  • Manages GraphManager and GraphState

• GraphManager: app/src/lib/graph-interface/graph-manager.svelte.ts

  • Core entity managing the node graph
  • Handles node connections and execution flow

• GraphState: app/src/lib/graph-interface/graph-state.svelte.ts

  • Tracks UI state (selection, snapping, help, active nodes)

• Graph Components:

  • app/src/lib/graph-interface/graph/ - Graph rendering
  • app/src/lib/graph-interface/node/ - Node rendering
  • app/src/lib/graph-interface/edges/ - Edge rendering
  • app/src/lib/graph-interface/components/ - UI components (AddMenu, Socket, etc.)
  • app/src/lib/graph-interface/debug/ - Debug overlays
  • app/src/lib/graph-interface/background/ - Grid/dots backgrounds

• Helpers:

  • app/src/lib/helpers/ - Utility functions
  • app/src/lib/helpers/createKeyMap.ts - Keyboard shortcuts

3. Runtime Execution

Performs graph execution via WASM nodes.

• Runtime Executors (app/src/lib/runtime/):

  • MemoryRuntime: Direct WASM execution in main thread
  • WorkerRuntime: WebWorker-based execution for performance
  • Both implement the RuntimeExecutor interface

• Runtime Cache: app/src/lib/runtime/cache.ts

  • Memory-based caching for graph execution

• Execution Flow:

  1. Graph serialized from graph interface
  2. Runtime executes nodes in topological order
  3. Results passed through connected edges
  4. Final mesh output rendered

4. 3D Viewer (app/src/lib/result-viewer/)

Three.js-based rendering for 3D output.

• Viewer: app/src/lib/result-viewer/Viewer.svelte
  • Renders generated 3D meshes
  • Uses @threlte/core (Svelte-Three.js wrapper)

5. Application Structure (app/src/routes/)

SvelteKit application routing.

• Main Page: app/src/routes/+page.svelte

  • Combines GraphInterface + 3D Viewer
  • Manages runtime selection (memory vs worker)
  • Handles settings and performance tracking

• Layout: app/src/routes/+layout.svelte

  • Application shell

• Server: app/src/routes/+layout.server.ts

  • Loads git metadata and changelog

6. Settings System (app/src/lib/settings/)

Application and graph settings.

• App Settings: app/src/lib/settings/app-settings.svelte.ts

  • Debug mode, themes, node interface options

• NestedSettings: app/src/lib/settings/NestedSettings.svelte

  • Recursive settings UI component

7. Sidebar Panels (app/src/lib/sidebar/)

• app/src/lib/sidebar/Sidebar.svelte - Main sidebar
• app/src/lib/sidebar/panels/ - Individual panels:
  • ActiveNodeSettings.svelte - Selected node properties
  • BenchmarkPanel.svelte - Performance benchmarking
  • Changelog.svelte - Version history
  • ExportSettings.svelte - Export options
  • GraphSource.svelte - Graph JSON view
  • Keymap.svelte - Keyboard shortcuts

8. Project Management (app/src/lib/project-manager/)

• app/src/lib/project-manager/project-manager.svelte - Project save/load
• Uses IndexedDB for persistence

9. Node Store (app/src/lib/node-store/)

• app/src/lib/node-store/NodeStore.svelte
• Remote node registry management
• IndexDBCache for offline storage

10. Graph Templates (app/src/lib/graph-templates/)

Pre-built graph templates for testing:

• Grid, Tree, LottaFaces, LottaNodes, LottaNodesAndFaces

Key Types (app/src/lib/types.ts)

interface NodeDefinition {
  id: string;
  name: string;
  inputs: Socket[];
  outputs: Socket[];
  parameters: Parameter[];
  execute: (inputs: any[], parameters: any[]) => any[];
}

interface Socket {
  id: string;
  name: string;
  type: string; // datatype (e.g., "number", "vec3", "*")
  defaultValue?: any;
  optional?: boolean;
}

interface Parameter {
  id: string;
  name: string;
  type: string;
  defaultValue: any;
  min?: number;
  max?: number;
  options?: string[];
}

interface Graph {
  nodes: NodeInstance[];
  edges: Edge[];
}

interface NodeInstance {
  id: number;
  nodeId: string;
  position: { x: number; y: number };
  parameters: Record<string, any>;
}

interface Edge {
  id: number;
  fromNode: number;
  fromSocket: string;
  toNode: number;
  toSocket: string;
}

Development Workflow

Prerequisites

• Node.js
• pnpm
• Rust
• wasm-pack

Build Commands

# Install dependencies
pnpm i

# Build WASM nodes
pnpm build:nodes

# Start development server
cd app && pnpm dev

# Run tests
cd app && pnpm test

# Lint and typecheck
cd app && pnpm lint
cd app && pnpm check

# Format code
cd app && pnpm format

Creating New Nodes

See docs/DEVELOPING_NODES.md for detailed instructions on creating custom WASM nodes.

Features

Current Features

• Visual node-based programming with real-time 3D preview
• WebAssembly nodes for high-performance computation
• Debug node with wildcard inputs and runtime integration
• Color-coded node sockets and edges (indicating data types)
• Variable-height nodes and parameters
• Edge dragging with valid socket highlighting
• InputNumber snapping to predefined values (Alt+click)
• Project save/load with IndexedDB
• Performance monitoring and benchmarking
• Changelog viewer
• Advanced mode settings

UI Components

• InputNumber: Numeric input with arrow controls
• InputColor: Color picker
• InputShape: Shape selector with preview
• InputSelect: Dropdown with options

File Structure

nodarium/
├── app/
│   ├── src/
│   │   ├── lib/
│   │   │   ├── config.ts
│   │   │   ├── graph-interface/    # Node editor
│   │   │   ├── graph-manager.svelte.ts
│   │   │   ├── graph-state.svelte.ts
│   │   │   ├── graph-templates/   # Test templates
│   │   │   ├── grid/
│   │   │   ├── helpers/
│   │   │   ├── node-registry.ts
│   │   │   ├── node-registry/     # Node loading
│   │   │   ├── node-store/
│   │   │   ├── performance/
│   │   │   ├── project-manager/
│   │   │   ├── result-viewer/       # 3D viewer
│   │   │   ├── runtime/           # Execution
│   │   │   ├── settings/         # App settings
│   │   │   ├── sidebar/
│   │   │   └── types.ts
│   │   └── routes/
│   │       ├── +page.svelte
│   │       └── +layout.svelte
│   ├── static/
│   │   └── nodes/
│   │       └── max/
│   │           └── plantarium/    # WASM nodes
│   └── package.json
├── docs/
│   ├── ARCHITECTURE.md
│   ├── DEVELOPING_NODES.md
│   ├── NODE_DEFINITION.md
│   └── PLANTARIUM.md
├── nodes/                        # WASM node source (Rust)
└── package.json

Release Process

1. Create annotated tag:

   git tag -a v1.0.0 -m "Release notes"
   git push origin v1.0.0
   

2. CI workflow:

   • Runs lint, format check, type check
   • Builds project
   • Updates package.json versions
   • Generates CHANGELOG.md
   • Creates Gitea release