295 lines
9.3 KiB
Markdown
295 lines
9.3 KiB
Markdown
# Node Compilation and Runtime Execution
|
|
|
|
## Overview
|
|
|
|
Nodarium nodes are WebAssembly modules written in Rust. Each node is a compiled WASM binary that exposes a standardized C ABI interface. The system uses procedural macros to generate the necessary boilerplate for node definitions, memory management, and execution.
|
|
|
|
## Node Compilation
|
|
|
|
### 1. Node Definition (JSON)
|
|
|
|
Each node has a `src/input.json` file that defines:
|
|
|
|
```json
|
|
{
|
|
"id": "max/plantarium/stem",
|
|
"meta": { "description": "Creates a stem" },
|
|
"outputs": ["path"],
|
|
"inputs": {
|
|
"origin": { "type": "vec3", "value": [0, 0, 0], "external": true },
|
|
"amount": { "type": "integer", "value": 1, "min": 1, "max": 64 },
|
|
"length": { "type": "float", "value": 5 },
|
|
"thickness": { "type": "float", "value": 0.2 }
|
|
}
|
|
}
|
|
```
|
|
|
|
### 2. Procedural Macros
|
|
|
|
The `nodarium_macros` crate provides two procedural macros:
|
|
|
|
#### `#[nodarium_execute]`
|
|
|
|
Transforms a Rust function into a WASM-compatible entry point:
|
|
|
|
```rust
|
|
#[nodarium_execute]
|
|
pub fn execute(input: &[i32]) -> Vec<i32> {
|
|
// Node logic here
|
|
}
|
|
```
|
|
|
|
The macro generates:
|
|
- **C ABI wrapper**: Converts the WASM interface to a standard C FFI
|
|
- **`execute` function**: Takes `(ptr: *const i32, len: usize)` and returns `*mut i32`
|
|
- **Memory allocation**: `__alloc(len: usize) -> *mut i32` for buffer allocation
|
|
- **Memory deallocation**: `__free(ptr: *mut i32, len: usize)` for cleanup
|
|
- **Static output buffer**: `OUTPUT_BUFFER` for returning results
|
|
- **Panic hook**: Routes panics through `host_log_panic` for debugging
|
|
- **Internal logic wrapper**: Wraps the original function
|
|
|
|
#### `nodarium_definition_file!("path")`
|
|
|
|
Embeds the node definition JSON into the WASM binary:
|
|
|
|
```rust
|
|
nodarium_definition_file!("src/input.json");
|
|
```
|
|
|
|
Generates:
|
|
- **`DEFINITION_DATA`**: Static byte array in `nodarium_definition` section
|
|
- **`get_definition_ptr()`**: Returns pointer to definition data
|
|
- **`get_definition_len()`**: Returns length of definition data
|
|
|
|
### 3. Build Process
|
|
|
|
Nodes are compiled with:
|
|
```bash
|
|
cargo build --release --target wasm32-unknown-unknown
|
|
```
|
|
|
|
The resulting `.wasm` files are copied to `app/static/nodes/` for serving.
|
|
|
|
## Node Execution Runtime
|
|
|
|
### Architecture
|
|
|
|
```
|
|
┌─────────────────────────────────────────────────────────────┐
|
|
│ WebWorker Thread │
|
|
│ ┌─────────────────────────────────────────────────────────┐│
|
|
│ │ WorkerRuntimeExecutor ││
|
|
│ │ ┌───────────────────────────────────────────────────┐ ││
|
|
│ │ │ MemoryRuntimeExecutor ││
|
|
│ │ │ ┌─────────────────────────────────────────────┐ ││
|
|
│ │ │ │ Node Registry (WASM + Definitions) ││
|
|
│ │ │ └─────────────────────────────────────────────┘ ││
|
|
│ │ │ ┌─────────────────────────────────────────────┐ ││
|
|
│ │ │ │ Execution Engine (Bottom-Up Evaluation) ││
|
|
│ │ │ └─────────────────────────────────────────────┘ ││
|
|
│ │ └───────────────────────────────────────────────────┘ ││
|
|
│ └─────────────────────────────────────────────────────────┘│
|
|
└─────────────────────────────────────────────────────────────┘
|
|
```
|
|
|
|
### 1. MemoryRuntimeExecutor
|
|
|
|
The core execution engine in `runtime-executor.ts`:
|
|
|
|
#### Metadata Collection (`addMetaData`)
|
|
|
|
1. Load node definitions from registry
|
|
2. Build parent/child relationships from graph edges
|
|
3. Calculate execution depth via reverse BFS from output node
|
|
|
|
#### Node Sorting
|
|
|
|
Nodes are sorted by depth (highest depth first) for bottom-up execution:
|
|
|
|
```
|
|
Depth 3: n3 n6
|
|
Depth 2: n2 n4 n5
|
|
Depth 1: n1
|
|
Depth 0: Output
|
|
Execution order: n3, n6, n2, n4, n5, n1, Output
|
|
```
|
|
|
|
#### Input Collection
|
|
|
|
For each node, inputs are gathered from:
|
|
1. **Connected nodes**: Results from parent nodes in the graph
|
|
2. **Node props**: Values stored directly on the node instance
|
|
3. **Settings**: Global settings mapped via `setting` property
|
|
4. **Defaults**: Values from node definition
|
|
|
|
#### Input Encoding
|
|
|
|
Values are encoded as `Int32Array`:
|
|
- **Floats**: IEEE 754 bits cast to i32
|
|
- **Vectors**: `[0, count, v1, v2, v3, 1, 1]` (nested bracket format)
|
|
- **Booleans**: `0` or `1`
|
|
- **Integers**: Direct i32 value
|
|
|
|
#### Caching
|
|
|
|
Results are cached using:
|
|
```typescript
|
|
inputHash = `node-${node.id}-${fastHashArrayBuffer(encoded_inputs)}`
|
|
```
|
|
|
|
The cache uses LRU eviction (default size: 50 entries).
|
|
|
|
### 2. Execution Flow
|
|
|
|
```typescript
|
|
async execute(graph: Graph, settings) {
|
|
// 1. Load definitions and build node relationships
|
|
const [outputNode, nodes] = await this.addMetaData(graph);
|
|
|
|
// 2. Sort nodes by depth (bottom-up)
|
|
const sortedNodes = nodes.sort((a, b) => b.depth - a.depth);
|
|
|
|
// 3. Execute each node
|
|
for (const node of sortedNodes) {
|
|
const inputs = this.collectInputs(node, settings);
|
|
const encoded = concatEncodedArrays(inputs);
|
|
const result = nodeType.execute(encoded);
|
|
this.results[node.id] = result;
|
|
}
|
|
|
|
// 4. Return output node result
|
|
return this.results[outputNode.id];
|
|
}
|
|
```
|
|
|
|
### 3. Worker Isolation
|
|
|
|
`WorkerRuntimeExecutor` runs execution in a WebWorker via Comlink:
|
|
|
|
```typescript
|
|
class WorkerRuntimeExecutor implements RuntimeExecutor {
|
|
private worker = new ComlinkWorker(...);
|
|
|
|
async execute(graph, settings) {
|
|
return this.worker.executeGraph(graph, settings);
|
|
}
|
|
}
|
|
```
|
|
|
|
The worker backend (`worker-runtime-executor-backend.ts`):
|
|
- Creates a single `MemoryRuntimeExecutor` instance
|
|
- Manages caching state
|
|
- Collects performance metrics
|
|
|
|
### 4. Remote Execution (Optional)
|
|
|
|
`RemoteRuntimeExecutor` can execute graphs on a remote server:
|
|
|
|
```typescript
|
|
class RemoteRuntimeExecutor implements RuntimeExecutor {
|
|
async execute(graph, settings) {
|
|
const res = await fetch(this.url, {
|
|
method: "POST",
|
|
body: JSON.stringify({ graph, settings })
|
|
});
|
|
return new Int32Array(await res.arrayBuffer());
|
|
}
|
|
}
|
|
```
|
|
|
|
## Data Encoding Format
|
|
|
|
### Bracket Notation
|
|
|
|
Inputs and outputs use a nested bracket encoding:
|
|
|
|
```
|
|
[0, count, item1, item2, ..., 1, 1]
|
|
^ ^ items ^ ^
|
|
| | | |
|
|
| | | +-- closing bracket
|
|
| +-- number of items + 1 |
|
|
+-- opening bracket (0) +-- closing bracket (1)
|
|
```
|
|
|
|
### Example Encodings
|
|
|
|
**Float (5.0)**:
|
|
```typescript
|
|
encodeFloat(5.0) // → 1084227584 (IEEE 754 bits as i32)
|
|
```
|
|
|
|
**Vec3 ([1, 2, 3])**:
|
|
```typescript
|
|
[0, 4, encodeFloat(1), encodeFloat(2), encodeFloat(3), 1, 1]
|
|
```
|
|
|
|
**Nested Math Expression**:
|
|
```
|
|
[0, 3, 0, 2, 0, 3, 0, 0, 0, 3, 7549747, 127, 1, 1, ...]
|
|
```
|
|
|
|
### Decoding Utilities
|
|
|
|
From `packages/utils/src/tree.rs`:
|
|
- `split_args()`: Parses nested bracket arrays into segments
|
|
- `evaluate_float()`: Recursively evaluates and decodes float expressions
|
|
- `evaluate_int()`: Evaluates integer/math node expressions
|
|
- `evaluate_vec3()`: Decodes vec3 arrays
|
|
|
|
## Geometry Data Format
|
|
|
|
### Path Data
|
|
|
|
Paths represent procedural plant structures:
|
|
|
|
```
|
|
[0, count, [0, header_size, node_type, depth, x, y, z, w, ...], 1, 1]
|
|
```
|
|
|
|
Each point has 4 values: x, y, z position + thickness (w).
|
|
|
|
### Geometry Data
|
|
|
|
Meshes use a similar format with vertices and face indices.
|
|
|
|
## Performance Tracking
|
|
|
|
The runtime collects detailed performance metrics:
|
|
- `collect-metadata`: Time to build node graph
|
|
- `collected-inputs`: Time to gather inputs
|
|
- `encoded-inputs`: Time to encode inputs
|
|
- `hash-inputs`: Time to compute cache hash
|
|
- `cache-hit`: 1 if cache hit, 0 if miss
|
|
- `node/{node_type}`: Time per node execution
|
|
|
|
## Caching Strategy
|
|
|
|
### MemoryRuntimeCache
|
|
|
|
LRU cache implementation:
|
|
```typescript
|
|
class MemoryRuntimeCache {
|
|
private map = new Map<string, unknown>();
|
|
size: number = 50;
|
|
|
|
get(key) { /* move to front */ }
|
|
set(key, value) { /* evict oldest if at capacity */ }
|
|
}
|
|
```
|
|
|
|
### IndexDBCache
|
|
|
|
For persistence across sessions, the registry uses IndexedDB caching.
|
|
|
|
## Summary
|
|
|
|
The Nodarium node system works as follows:
|
|
|
|
1. **Compilation**: Rust functions are decorated with macros that generate C ABI WASM exports
|
|
2. **Registration**: Node definitions are embedded in WASM and loaded at runtime
|
|
3. **Graph Analysis**: Runtime builds node relationships and execution order
|
|
4. **Bottom-Up Execution**: Nodes execute from leaves to output
|
|
5. **Caching**: Results are cached per-node-inputs hash for performance
|
|
6. **Isolation**: Execution runs in a WebWorker to prevent main thread blocking
|