Part I · Principles

2 Principles

The ten principles every rule in the specification follows from, which every profile has to keep.

NormativeDraft 0.11 requirement · Roswaal meets 0

2.1 The ten principles

Every rule in this specification follows from one of these.

A profile MUST keep all ten. Where a language seems to need an exception, the exception is a proposal to change this page (§14.2), not a choice a profile makes quietly.

Roswaal's two Luau profiles do not yet keep principle 9 on the canvas (§8.4), and a graph with more than one script start runs them by position (§7.1), which principle 1 rules out.

Roswaal partly

1. Order is visible

What runs, and in what order, is read from the flow wires: along the headers, one wire per step. No step runs that a flow wire does not reach.

In RoswaalFlow triangles hung outside the node, the flow in and on along the header (§5.5), and flow wires as the only order (§7.1).

A profile must notrun a node because of where it sits, or reorder steps behind the reader.

2. Values have no order

A value node is worked out where it is used and only there. It has no flow pins and no place in time, so it can be read on its own.

In RoswaalValue nodes are rounder and have no header bar (§5.3); a value used twice in a block is worked out once (§7.2).

A profile must notgive a value node an effect a reader cannot see from its name.

3. A pin says what it is without colour

Its name, its family's shape, and its type in words where the name does not already say it. Colour adds to that and never carries it alone.

In RoswaalFive pin shapes, type chips under the rule that a type is never said twice, and the type's card on request (§5.5).

A profile must notintroduce a type that falls outside every family (§6.2).

4. A node at rest shows only what it says

Controls appear when they are reached for: on hover, on selection, from the keyboard. A graph read at a glance is a graph of names and wires.

In RoswaalAdding and removing pins on hover or selection (§4.5); the category as a small corner tab (§5.4).

A profile must notadd chrome to a node that is always shown.

5. A problem is said where it is, and seen first

An error or warning is written in words beside the node it belongs to, and drawn above everything in the graph. Only the panels around the canvas may cover it.

In RoswaalThe note under the node, the pin at fault marked, and a layer of its own (§5.8).

A profile must notreport a problem only in a list, away from the graph.

6. One set of numbers

Where things are is computed from fixed numbers, never measured from text, so a graph is drawn the same by every implementation, in every font and at every zoom.

In RoswaalOne table of geometry, used by the canvas, the wire router and the documentation's pictures alike (§5.2).

A profile must notchange a node's geometry. It may add kinds of node that follow it.

7. Familiar, never surprising

Someone who knows another node graph editor reads a graph without being taught: wires, pins by type, steps in a chain, values feeding them. Where this design differs, it differs on purpose and says why.

In RoswaalFlow triangles hung outside the node and data sockets on its border, as other editors draw them, and a guide that maps one editor's terms onto these (§2.3).

A profile must notrename a core idea after its own language's jargon in Part I's places.

8. What you see is what compiles

A graph file is plain data, and every node compiles from what is on it, its settings and the project's settings file. Nothing else changes the program.

In RoswaalJSON graphs (§9), packs that are data and never run, and a compile that reads only the project's own files.

A profile must notread anything a graph does not show or a project's files do not hold.

9. Every hand, every screen

A mouse, a keyboard, a finger and a screen reader can each do everything; a phone and a projector can each show the graph.

In RoswaalTouch gestures for every action and themes built from tokens (§4.8, §5.7). Not yet: the keyboard and screen readers on the canvas (§8.4).

A profile must notadd a node that only a mouse can use.

10. The output is the language's own

What a graph compiles to reads as code a person in that language would write: named after the graph, laid out by the language's own tools, needing nothing of the implementation's to run.

In RoswaalPlain Luau, formatted by StyLua where the project has it, with no library of Roswaal's to ship beside it.

A profile must notmake its output depend on a runtime library of the implementation's, unless the language offers no other way.

2.2 Where they come from

Info

This section is informative.

Principles 1, 2 and 7 are the node graph editors people already use: the line they all draw between steps and values, and the shapes they draw them in. Principles 3, 4 and 5 were settled in Roswaal 0.161, when the node was redrawn to be read rather than recognised: shapes and words beside colour, controls that wait to be reached for, and problems that cannot be covered. Principle 6 is older: one table of numbers, shared by the canvas and the documentation's pictures, so neither can drift from the other. Principles 8 and 10 are how Roswaal has worked from the start: a node pack is data that is read and never run, and the Luau it writes is meant to be read and kept by people who never open the graph. Principle 9 is the one Roswaal keeps least so far.

2.3 Familiar from other editors

Info

This section is informative.

Coming from Blueprints maps one widely used editor's terms onto these, one by one. In short: flow pins are what node graph editors call execution or flow pins, and are drawn as a flow socket usually is; a value node is what they call pure; a reroute knot is everyone's reroute; and the type colours keep to the usual ones where the types line up, so a boolean is red and a number green.