feat: initial group nodes /w some bugs
This commit is contained in:
312
docs/LLM.md
Normal file
312
docs/LLM.md
Normal file
@@ -0,0 +1,312 @@
|
||||
# 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`)
|
||||
|
||||
```typescript
|
||||
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
|
||||
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
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
|
||||
Reference in New Issue
Block a user