9 File format✎

Graphs are stored as JSON, one graph file per script. An implementation conforming at level 1 (§1.3) reads and writes these files as this chapter says. Field names are given exactly; a field marked optional MAY be left out, and one left out means what this chapter says it means.

9.1 The graph file

A graph file holds one script: the main graph and the graph of every function declared in it. It is named with the .nodescript extension, and its top level is an object:

scriptClass, runContext, typecheck and services are the Luau profiles' fields, kept at the top level for Draft 0.1; §10.1 says how a profile names its own.

9.2 Nodes and links

A node

graph decides only where a node is drawn. What a function's body is, is decided by its wires (§7.5).

A value typed in

A literal is an object with a tag t, and a value v for every tag but nil:

A link

A link is { "id", "from": { "node", "pin" }, "to": { "node", "pin" } }: from an output to an input, each named by its node's id and its pin's id. Its route is never stored; it is drawn from the two pins' positions (§5.2).

Ids are opaque strings. Roswaal makes them as random UUIDs; another implementation MAY use any scheme that keeps them unique within the file.

9.3 Variables, modules, services

Locals and functions are not listed: each is a node (§3.6, §3.7).

9.4 Comments

A comment is { "id", "x", "y", "w", "h", "text" }, with an optional color, six hexadecimal digits without the #, an optional graph, as on a node, and an optional style: lines (a -- line each), doc (a --- line each) or docBlock (a --[=[ ]=] block), how its header is written when not the default. What a comment holds is never stored: it is whatever lies inside it (§4.3).

9.5 Node maps

A node map, .nodemap, says where each compiled program goes in the place it runs from. Its top level is { "schemaVersion", "kind": "map", "id", "name", "output", "root" }, with an optional target. root is a tree of entries, each with an id, a name and children. A map, and what its entries may say, belongs to the profile: the Roblox profile's describes a place and becomes a Rojo project file (§11.7); the Lune profile's describes folders.

9.6 Project settings

A project is a folder with a roswaal.json at its root. Its fields say which profile the project uses (target), where graph files are (sourceDir), where programs are written (outDir), where node packs are (nodePaths), when to compile (compileMode, "manual" or "hot"), and how programs are laid out (format, indentStyle, indentWidth, comments). A missing field takes its default.

9.7 Versions and migration

• Every file carries schemaVersion. This draft describes version 1.

9.8 Writing a file

{
  "schemaVersion": 1,
  "kind": "script",
  "id": "demo-count-characters",
  "name": "count-characters",
  "scriptClass": "ModuleScript",
  "target": "lune",
  "typecheck": "strict",
  "variables": [],
  "modules": [{ "id": "m_fs", "name": "fs", "specifier": "@lune/fs" }],
  "nodes": [
    { "id": "n0", "def": "script.begin", "x": 0, "y": 0 },
    {
      "id": "n1",
      "def": "lune.value",
      "x": 4,
      "y": 105,
      "literals": { "a0": { "t": "string", "v": "README.md" } },
      "config": { "call": "readFile", "module": "fs" }
    }
  ],
  "links": [],
  "comments": []
}

The start of examples/lune-demo/.roswaal/scripts/count-characters.nodescript, shortened to its first two nodes and without its wires, with short objects drawn on one line.

Not reviewed yet