SCUA

Manual

Getting started

SCUA is a small, dynamic scripting language for structured data that needs to persist. If you know Lua it will feel familiar: untyped by default, quick to pick up. The difference is that program state lives in partitions that can be saved and resumed on another machine without any serialization code. That suits games and multiplayer backends, and just as readily in-app scripting and data validation work. This page gets the compiler onto your machine and walks you through your first two programs.

#Getting the compiler

Using a prebuilt release? If you downloaded a packaged SCUA distribution, the scua binary is already in its bin/ directory — you do not need Zig or to build anything. Skip to putting that directory on your PATH below.

Supported platforms: macOS (Apple Silicon), Linux (x86_64 and arm64), and Windows (x86_64 and arm64), all at feature parity. On Windows the binary is scua.exe, so add its bin\ folder to your PATH (or run bin\scua.exe directly).

On x86-64, scua needs a CPU from 2009 or later — specifically one with SSE4.2 and POPCNT (Intel Nehalem onward, AMD Bulldozer onward). Building for that floor rather than the oldest possible x86-64 makes scripts up to 15% faster, which is worth more than compatibility with hardware that old. If your machine or VM is below it — some virtual machines present a deliberately old CPU model — scua says so and stops rather than crashing, and the same package ships scua-compat: the identical language, built to run on any x86-64. Use that one. arm64 has no such floor.

Building from source uses Zig 0.16. From the repository root:

$ zig build

That produces the compiler at zig-out/bin/scua. The rest of these docs assume you can type scua, so put that directory on your PATH (or copy the binary somewhere that already is):

$ export PATH="$PWD/zig-out/bin:$PATH"
$ scua

Running scua with no arguments prints its usage, which is a quick way to confirm the binary is on your PATH. There is no separate runtime to install: the single scua binary compiles and runs your scripts.

#Your first program

Put this in a file called hello.scua:

print("hello, world")

Run it by passing the file to scua:

$ scua hello.scua
hello, world

That's the whole loop: write a .scua file, run scua file.scua, see the output. There is no build step and no project setup for a single script. When you want more than one file, scua init myproj scaffolds a small runnable project for you — see the command-line reference.

#A slightly bigger program

Here's one that uses a function, a let binding, and string interpolation. Backtick strings can contain {...} holes, and each hole is replaced with the value of the expression inside it.

fn greet(name)
  return `Hello, {name}!`
end

let player = "Ada"
print(greet(player))
print(`2 + 2 = {2 + 2}`)

Run it:

$ scua greet.scua
Hello, Ada!
2 + 2 = 4

A few things to notice. Blocks end with end, not braces. fn declares a function and return hands a value back. let introduces a variable. None of this code has type annotations, and it doesn't need them: SCUA is dynamic unless you ask for a check. One sharp edge worth learning early: + is arithmetic only. To join strings, use ... Reach for + on a string and the compiler tells you so:

scua: file.scua:1: type error: cannot add a string (arithmetic needs numbers) — use `..` to concatenate strings

#Running scripts

scua file.scua compiles and runs a file. A handful of flags change how it runs (fast-forwarding timers, filtering logs, setting build flags) and there is a built-in stepping debugger. All of that is in the command-line reference.

When you're ready to go further:

  • Core concepts covers the ideas that make SCUA different from a plain scripting language: gradual typing, partitions, persistence, and the actor model.
  • Values and types starts the language guide, a feature-by-feature tour you can read in order.