Compiling for Lune✎

A graph becomes a file, and the file is where it is. No DataModel, no project file.

Pending review

This page is about graphs whose Target is Lune. The Inspector says which with nothing selected, and a new graph takes the project's. For Roblox, the answer is a different one and it is on Compiling for Roblox.

A graph is a .nodescript under .roswaal/scripts. Compiling it writes a .luau file to the same place under the output directory, in the same shape: .roswaal/scripts/lib/json.nodescript writes src/lib/json.luau. Both directories are project settings.

Info

There is no DataModel, so there is nothing to sync. Lune runs the file where it is — lune run main — so the layout on disk is the whole answer.

What a graph compiles to

Always a .luau file named after the graph. A Roblox graph picks between Script, LocalScript and ModuleScript, and the choice decides the file's ending because Rojo reads it — Greeter.server.luau. Lune has no such distinction: a file is a file, and whether it is a program or a module is decided by whether something requires it.

Warning

Lune support is experimental. It has not yet been tested by an experienced Lune developer, so treat what it writes as a starting point.

Compiling

What it compiles
Compile script, or Ctrl + SThe open graph
Compile projectEvery graph, then every node map
Compile: DynamicEach graph as you edit it, and each graph whose file changes on disk, such as after a git pull
roswaal compileEverything, or the one graph or map you give it
roswaal watchThe same, without the editor

A graph with errors writes nothing; warnings do not stop it. With format on and StyLua on your PATH, the file is formatted as it is written. If StyLua refuses it, it is written unformatted and the compile says why. Then lune run main — Roswaal does not run it for you.

A generated file starts with a header naming its graph and a hash of what was written. Roswaal will not overwrite a file whose hash no longer matches — one edited by hand — or a file it did not write. Rename a graph or move it and its next compile removes the file it used to write; roswaal prune lists the ones left behind by a graph that is gone.

Requires, and what the file depends on

Everything a Lune program reaches for arrives through a require you wrote. The standard library is Lune's standard library; a short name for a path is Aliases and .luaurc; and the rule behind both is on Modules — a generated file does not grow imports nobody chose.

Warning

Roblox datatypes need @lune/roblox. Vector3 and CFrame compile once it is required with the datatype as a member; the Inspector has the button. TweenInfo is not offered in Lune.

Node maps

The map editor

Here is the whole of it. A .nodemap is edited in Roswaal rather than by hand, and this is that editor with Describes set to Filesystem: the tree in the middle, Instance and This map beside it, and the layout along the foot. Every part is named beside it; the rest of this section explains them in order.

  • The treeEvery directory and file the project has. Pick one and Instance follows.
  • List or GraphThe tree as rows, or as a graph from left to right with a + on each node to add inside it.
  • Directory, File, UndoBuild the tree. A file takes no children.
  • NameWhat it is called on disk, with no extension: the row adds it.
  • KindA directory, or a file Roswaal writes a .luau for.
  • DescribesA DataModel for Roblox, or a filesystem for Lune. It decides the rest.
  • Project fileThe layout: where each file lands, and the require that reaches it. Nothing is written.
The same editor, describing a filesystem. Select a row to fill Instance. A name carries no extension — main in the map, main.luau on disk, and the require that reaches it beside.

What a map is for here

A map still has a job, and it is the one Rojo was doing incidentally: saying the layout out loud, and checking it holds together. Set a map's Describes to Filesystem and it becomes directories and files rather than services and instances. A new map is already the right kind — it follows the project's target.

What the right-hand column is not is a file Roswaal writes. A filesystem map compiles to nothing: the disk is already the answer, and compiling the map is checking that the answer is one Luau can load.

A DataModel mapA filesystem map
Root isThe DataModelThe project directory
Children areServices, folders, instancesDirectories and files
Compiles todefault.project.json, for RojoNothing — it is a check
A node hasA class and a path on diskA name, and whether it is a file

What it checks

These are require-time errors in Luau, not house style. The language refuses an ambiguous path rather than picking one, so a layout with both of these is one the runtime will not load — and a map catches it while you can still move something, with both things named.

  • A file beside a directory of the same name. require("./foo") cannot mean both foo.luau and foo/init.luau.
  • Two files differing only by extension. foo.luau and foo.lua both answer to ./foo.
  • A name a require cannot reach — letters, digits, ., - and _, and no directory separators.

Info

A file's name has no extension: main in the map, main.luau on disk. Typing one is a warning, so you do not end up with main.luau.luau.

Not reviewed yet