Connections & the dataflow graph

A document is also a graph

A property can store its own value, or connect to another Element's output and take its value from there. The moment one connection exists, the Document reads two ways: a tree, and a directed graph laid over the same Elements.

def group "world" {
    def material "mat" { float3 out = (0.8, 0.1, 0.1) }
    def object "ball" {
        float3 albedo = (1, 1, 1)            # fallback if nothing is connected
        albedo.connect = </world/mat.out>     # …but the value flows from the material
    }
}

A connection is written slot.connect = <path> and is, fundamentally, two paths: a target Property and a source Property. Because both endpoints are paths, the entire web of dataflow is plain, diffable text, and because identity is hierarchical, it stays acyclic through the tree structure itself.

doc.connect(Path("/world/mat.out"), Path("/world/ball.albedo"));  // source output drives target input
for (const Connection& c : doc.connections())          // the graph is just data
    /* c.source, c.target */;

doc.connect("/world/mat.out", "/world/ball.albedo")    # source output drives target input
for c in doc.connections():                            # the graph is just data
    c.source, c.target

The evaluator

Resolving a connected, possibly animated Property is the job of the evaluator. It walks the connection to its source, resolves that source Property at the requested time (interpolating samples, following further connections), and returns the concrete value:

Value albedo = doc.eval(Path("/world/ball.albedo"), /*time*/ 0);
// → (0.8, 0.1, 0.1): pulled through the connection to the material's output

albedo = doc.eval("/world/ball.albedo", time=0)
# → (0.8, 0.1, 0.1): pulled through the connection to the material's output

Connections compose: a chain of them is a small dataflow program, pulled on demand. A generator feeding a transform feeding a material is just three Elements and two connections, evaluated lazily when something asks for the end of the chain.

The dependency graph

To keep an edit from forcing a full recompute, Core tracks a dependency graph: which Elements depend on which, derived from the connections. When an input changes, only the outputs that actually depend on it are invalidated, and an evaluation cache keeps repeated reads of unchanged values cheap.

The dependency graph the evaluator pulls through is the Elements and their connections, the same Document you saved. The document doubles as the scene graph, so it is safe to drive live from a UI or an agent: change a value, and exactly the dependent values recompute against one structure.

Connections link properties within one document. To link across documents, reusing whole subtrees, see composition.