Getting started

FractalEngine is a desktop application for building and sharing live 3D models of real places. This page takes you from download to a first scene. FractalEngine is a preview: expect rough edges, and see Preview status for what is and is not ready.

Download the preview build

The preview is the rolling latest build on GitHub. It is rebuilt from the main branch whenever the Linux and Windows build jobs pass. There is no tagged release yet.

Get them from the releases page or straight from the latest build. The status page lists the files in the current build. There is no macOS build.

The downloads are unsigned preview builds. Windows SmartScreen may warn the first time you run one.

First launch

1. Extract the whole archive into a folder you can write to. It holds the program, an assets/ folder of sample models, a QUICKSTART.txt and the licence files.
2. Run fractalengine (fractalengine.exe on Windows) from that folder.

Keep assets/ next to the program. Its presence tells the app it is running from an unpacked download, so it keeps its database in a data/ folder beside the program wherever you launch it from. To back up or move an install, copy the whole folder.

On the first start the app creates a cryptographic identity for this machine (stored in the operating system’s keychain, or in a file under your per-user data folder if there is no keychain), creates the database, and seeds a starter hierarchy: a Genesis Verse, a Genesis Fractal and a Genesis Petal. Then the editor opens on an empty grid.

The app also serves a local API on 127.0.0.1:8765. It listens on this computer only. See API overview.

The hierarchy

FractalEngine organises a site in four levels.

Verse     the top level: one shared space, the unit you share with peers
  Fractal   a grouping inside a verse
    Petal     one 3D scene: its terrain, its map scale, its objects
      Node      an object placed in a petal: a model, a path, a sensor

Only one petal is open at a time. Roles (Owner, Manager, Editor, Viewer) are granted at verse, fractal or petal scope, and a role at a wider scope applies to everything below it unless a narrower grant overrides it.

Create a verse, a fractal and a petal

The Genesis hierarchy is enough to start. To make your own, use the Hierarchy sidebar on the left: it creates a verse, adds a fractal inside a verse, and adds a petal inside a fractal. Selecting a petal opens its scene in the viewport.

Import a model

FractalEngine loads glTF and GLB models; convert other formats, such as FBX or OBJ, first (Blender can do it). Use the app’s model import dialog to bring a file in, then place it in the open petal as a node. Imported models are content-addressed by their BLAKE3 hash.

Models whose textures use KTX2 or Basis compression are refused, whether imported locally or received from a peer. Convert those textures to PNG or JPEG first. The refusal is reported in the console window only.

Where to go next

• Put the scene on real terrain: the Maps section of the app installs map packages and binds one to each petal. Packages come from peers or from the package registry.
• Draw paths with the pen tool, or import a GPX file.
• Share a verse with other people: the verse’s settings dialog has an Access tab for roles and invitations.
• Pull the data into analysis tools: the Data window’s Export tab has a Copy for BI card.
• Script it with the API or write an extension.

Build from source

You need Rust 1.96 or newer; the repository pins the toolchain it expects in rust-toolchain.toml. Platform packages and a known compiler workaround are in BUILDING.md.

git clone https://github.com/Escherbridge/fractalengine
cd fractalengine
cargo build --release -p fractalengine   # the desktop app
cargo run -p fractalengine