Getting Started

What Eustress Is

Eustress is a source-available simulation and data platform built in Rust. You build a world out of parts, run it with physics and scripts, and read what it produces. The desktop application is Eustress Engine, and the window you work in is Studio, its editor.

Parts and Physics

Unanchored parts fall and collide when you press Run or Play.

Luau and Rune

Two script languages, both runnable from the command bar.

Files You Own

A Space is a folder on your disk; each part you insert starts as a plain TOML file.

Git Snapshots

Saves and autosaves commit the Space's files to git.

Source-available

The source is public under the PolyForm Shield 1.0.0 license: you can read, build and use it, and you may not use it to build a competing product. See License for the full text.

Universes and Spaces

A Space is one world: its parts, lights, scripts and settings, kept together in one folder. A Universe is a folder of related Spaces. Everything you build lives in a Space, and every Space belongs to a Universe.

The Universes page covers how a Space is stored and versioned in depth.

Download

Eustress Engine is in Public Alpha. Sign in on eustress.dev and open Download for the latest build. The page needs a free account; creating one includes an age and identity check.

Keep the assets folder beside the program

The archives hold the program with an assets folder next to it, and Eustress Engine loads its part meshes from there. A copy of the program on its own starts without them: the Linux package's install.sh copies only the binary to ~/.local/bin. Run it from the folder you extracted.

Updates

Each time it starts, Eustress Engine asks downloads.eustress.dev for the latest release. When a newer one exists, an Update to badge with the new version appears at the right end of the menu bar. For now, get the new build from the Download page and install it the same way as the first; the in-app install step is listed under What's Next.

First Launch

The first time Eustress Engine starts, it creates its working folder, Eustress inside your Documents folder, with one Universe and one Space in it, and opens that Space. On Windows the folder is %USERPROFILE%\Documents\Eustress, the local Documents folder, even when OneDrive has redirected Documents, so a sync client never fights the file watcher. To keep your Universes in another folder, set the EUSTRESS_WORKSPACE environment variable to it before you start Eustress Engine.

Eustress/
└── Universe1/
    ├── .eustress/assets/      parts and meshes shared by the Universe
    └── Spaces/
        └── Space1/
            ├── Workspace/     Baseplate, WelcomeCube
            ├── Lighting/      Sun, Moon, Sky, Atmosphere
            ├── SoulService/   scripts
            ├── ...            16 more service folders
            ├── space.toml
            └── simulation.toml

Space1 opens on a 512 m square gray Baseplate with a 4 m blue WelcomeCube at its center. Later launches reopen the last Space you switched to from the Universes panel, or else the first Space in alphabetical order.

The window title names what is open, for example Universe1 > Space1 - Eustress Engine. Once per install, a notice says that anonymous usage stats are on: Eustress counts which tools you click, never your content. Turn it off in Settings, on the Notifications tab under Privacy. If something goes wrong, each run's log is in ~/.eustress_engine/logs, which keeps the last 5 runs.

Signing In

Studio works without an account. You need to sign in to publish a Space and to earn Bliss. Your identity is a file: registering at eustress.dev/login ends by downloading eustress-<username>.toml, which holds your Ed25519 key pair. In Studio, click Sign In at the right end of the menu bar, choose Browse, pick that file, and press Sign In with Identity. Studio remembers the file and signs you in on later launches.

The identity file is your private key

Keep it somewhere safe and never share it: anyone holding it can sign in as you.

Create a Universe

1. Open the File menu and choose New Universe....
2. Type a name for the Universe folder and press Create.
3. A second dialog asks for the name of the first Space in it. Type one and press Create.

Studio creates Documents/Eustress/<Universe>/Spaces/<Space>, fills the Space with its service folders, a Baseplate and a WelcomeCube, and opens it. Characters that cannot appear in a file name become underscores.

Add a Space

To add another Space to the Universe you are in, choose File > New Space or press Ctrl+N. A save dialog opens in the current Universe with the name New Space filled in: type the name you want and confirm. The Space has to stay inside that Universe; Studio creates it in the Universe's Spaces folder and switches to it.

Open and Switch

• Universes tab: the left panel lists every Universe and its Spaces. Click a Space to open it.
• File > Open File... (Ctrl+O): pick a Space folder anywhere on disk.
• File > Recent: the last 8 Spaces you opened.

Insert a Part

Open the Insert menu and choose Part (Block). A 4 by 1 by 2 m part named Block appears 10 m in front of the camera, already selected. It goes into Workspace, or inside whatever you had selected in the Explorer.

To insert any other kind of object, press Ctrl+I for the Insert Object dialog, type part of a class name (PointLight, Folder, TextLabel), and press Enter. Either way the new object ends up selected, and Ctrl+Z takes the insert back.

Look Around

The keys fly at 9.81 m/s; hold Shift to slow down for fine work. The Perspective page covers the 2D view, the orthographic projection and the axis views.

Move It

With the part selected, pick a tool from the Tools group on the Home tab, or press its key:

Moves snap in 1 m steps and rotations in 15 degree steps by default. Press 2 for 0.2 m steps, 1 to go back to 1 m, and 3 to turn move snapping off. Ctrl+Z undoes a move, and Ctrl+Y redoes it. The Studio page covers every tool.

Change Its Properties

The Properties panel on the right edits whatever is selected. Change Color or Material and the part updates at once. One property matters before you press Play: Anchored. An anchored part stays where it is; an unanchored part is a physics body that falls. New parts start unanchored, while the Baseplate and the WelcomeCube are anchored, so a Block you raise above the cube will drop onto it.

To anchor a selection from the keyboard, press Alt+A. Press it again to release it.

Run and Play

The buttons at the left end of the ribbon's tab row start and stop the simulation: the green play button is Run, the gamepad is Play, then Pause and Stop. The same commands are in the Test menu:

Try it: raise your Block a few meters above the WelcomeCube, press F7, and watch it fall onto the cube. Physics runs on Avian. Studio keeps physics paused while you edit, so nothing moves until you press Run or Play.

What Stop Restores

When you press Run or Play, Studio takes a snapshot of the Space. Stop puts it back: every part returns to where it was, with its color, transparency and anchoring; parts deleted during the run come back; anything created during the run is removed; the lighting and the editor camera return to where you left them; and physics pauses again. A run leaves what you built as it was.

Saved as You Work

Studio records your edits as you make them, in the Space's database, world.fjalldb. A simple part (a built-in shape with no children) keeps its edits there only; a part with children or a custom mesh also has its _instance.toml rewritten. Every 5 minutes an autosave commits the Space folder's files to git, so there is a restore point even if you never save by hand.

The database is kept out of git, so edits that live only in the database are not in that history. The Universes page has the full table of what a commit captures.

Terrain waits for Ctrl+S

Terrain sculpting and painting stay in memory until you press Ctrl+S. Close Studio without saving and those strokes are gone.

Snapshots

Press Ctrl+S (or File > Save Space) to take a snapshot now. Studio saves the scene the same database-first way, writes any terrain to disk, then commits the Space folder's files to git with the message manual save and the time. The first snapshot, manual or automatic, creates the git repository in the Space folder.

• Unsaved: a badge at the right end of the menu bar appears when you have edits that no snapshot has recorded yet.
• File menu: shows the last snapshot, for example Snapshot 14:32 or Autosaved 14:37.
• Closing: with unsaved edits, Studio asks before it exits.

Snapshots need git installed

Studio runs the git command to record snapshots. Without git on your machine every edit still reaches disk, but no snapshot is made, and a notification says so each time one fails.

On Disk

Inserting a part writes a folder holding an _instance.toml file that you can read, diff and edit in any text editor. This is the WelcomeCube as a new Space writes it:

[metadata]
class_name = "Part"
archivable = true

[asset]
mesh = "parts/block.glb"
scene = "Scene0"

[transform]
position = [0.0, 2.0, 0.0]
rotation = [0.0, 0.0, 0.0, 1.0]   # quaternion x, y, z, w
scale = [4.0, 4.0, 4.0]           # a part's scale is its size in meters

[properties]
color = [0.388, 0.706, 1.0, 1.0]
transparency = 0.0
reflectance = 0.2
anchored = true
can_collide = true
locked = false

Later edits to a simple part like this one live in the database, so the file keeps the values it was inserted with. The autosave keeps the database (world.fjalldb) and the Space's trash out of git on purpose. Back that folder up with the rest of the Space: it holds edits that exist nowhere else, and it is part of the Space, not a cache.

The Command Bar

The command bar runs a script the moment you press Enter. It is the single line docked along the bottom of the window. The label at its left says which language it runs; click it to switch between Rune and Luau. Shift+Enter adds a line, and a pasted script keeps its line breaks. Whatever the script prints appears in Output.

Make a Part in Luau

Switch the command bar to Luau, paste this, and press Enter:

local part = Instance.new("Part")
part.Name = "HelloPart"
part.Size = Vector3.new(2, 2, 2)          -- meters
part.Position = Vector3.new(0, 8, 0)      -- 4 m above the WelcomeCube
part.Color = Color3.fromRGB(0, 188, 212)
part.Anchored = false
print("Created " .. part.Name)

Output shows Created HelloPart and a line confirming the spawned part, and a cyan cube hangs in the air above the WelcomeCube. The command bar runs in edit mode, so the part is real: it appears in Workspace in the Explorer and is saved with the Space like any other part. Press F7 and it falls.

Meters everywhere

Scripts see every position and size in meters, whatever unit Studio is displaying. Units.to_meters(5, 'ft') returns 1.524 when you think in another unit.

Scripts That Run on Play

A command-bar script runs once, in edit mode. Rune scripts saved in the Space run every time you press Run or Play: each gets on_init() once and on_update(dt) every frame, and Stop ends them. Luau files in a Space show up in the Explorer, but Play does not start them yet, so for now Luau runs from the command bar. The Scripting page covers both languages and the script API.

A SoulScript can also begin as a plain-English summary. Its Build button sends the summary to Anthropic's Claude, using your own API key saved in Settings on the Soul tab, and writes the Rune code it gets back beside the summary.

Keep Learning

Studio

Every panel, tool, shortcut and search operator in the editor.

Building

Parts, materials, lighting and terrain.

Scripting

Luau, Rune and the script API.

Simulation

The clock, recordings and experiments.

Coming Next

• One-click updates: the Update badge will download the new build, check its SHA-256 and restart into it on Windows and Linux. On macOS you will open the new disk image yourself.
• A Windows installer: the Download page will offer the Setup program the release pipeline already builds. It installs to Program Files, adds a Start Menu entry, and opens .eustress files.
• Luau on Play: Luau scripts saved in a Space will start when you press Run or Play, the way Rune scripts do today.