Install and Run

This page shows you how to download the Isometry engine, get it running, and load an example campaign. It ends with the exact commands you use to confirm a campaign loads.

Introduction

Isometry is a single program that loads game campaigns defined entirely in YAML. There is no separate server to install and nothing else to set up; the program is the whole product. To build campaigns you first need it on your machine, and you need a reliable way to check that a campaign you wrote actually loads.

This page covers downloading the engine, running it, and the headless verification boot you return to throughout the manual.

Prerequisites

You have read What is Isometry and understand that a campaign is YAML data the engine loads.

Download Isometry

Isometry ships as a ready-to-run binary from itch.io:

https://dark-mode-games.itch.io/isometry

Download the build for your platform and unzip it. The download contains the engine executable and nothing else to install: no separate installer, no runtime, and no extra dependencies. The binary is the whole product.

Note: Isometry is in open beta, version 0.387. itch.io is the only official download source.

Run the engine

Launch the engine executable to open the launcher, where you pick a campaign, log in, and host or join a session. The engine reads campaign .zip files from a folder beside the binary, so a campaign you want to play is placed next to the executable before you launch.

Throughout this manual, command examples call the engine as isometry; use the actual file name of the executable you downloaded for your platform.

Load an example campaign

A campaign's Main entity is the single required entry point that names the player actor and the starting map. A minimal Main.yaml defines one Main entity:

Main:
  demoMain:
    actor: heroActor
    map: demoMap

Here actor is a KeyRef to the heroActor entity and map is a KeyRef to demoMap. The hero actor it points to uses real values you will reuse later:

Actor:
  heroActor:
    name: Hero
    speed: 1.0
    base: 8

speed is the actor's movement rate and base is the footprint size in pixels.

To play a campaign, package its folder into a .zip (see Your first campaign for packaging), place the zip beside the engine binary, and launch.

Verify a campaign loads (headless)

When you write your own campaign, you need a fast way to confirm it loads and validates without opening a window. The engine offers two headless checks.

Quick validate

The fastest check runs the campaign validator and exits with status 0 on success or 1 on failure, without building the world. Point it at a campaign directory or a .zip:

isometry --validate=mycampaign.zip

Use this in scripts and quick iteration: a zero exit code means every entity, KeyRef, and dice expression passed validation.

Full host boot

To exercise the full load-and-validate pipeline, boot in host mode. The --network flag selects the multiplayer mode: none, host, server, or client. Host mode runs the pipeline you want to exercise.

Warning: --network=none currently loads no campaign. The engine boots but does nothing, so single-player from the command line does not work yet. Single-player today works only through the launcher. To boot a campaign from the CLI, use --network=host.

Place the campaign zip next to the engine binary, then run the boot:

isometry --campaign=demo --network=host --port=5000 --username=p --secret=p --log-level=INFO

The campaign zip must sit beside the binary because the engine resolves campaign files relative to the executable's directory. The --campaign flag names the zip without its extension.

Note: The log level defaults to NONE, which produces an essentially empty log. You must pass --log-level=INFO (or higher) to see the verification lines. Valid levels, from quietest to loudest, are NONE, FATAL, ERROR, WARN, INFO, DEBUG, and TRACE.

The engine writes to a file named log.txt in the same directory as the binary. Open that file and look for two lines that confirm success:

Campaign validation passed
Successfully created Entity

If both appear, the campaign loaded and every entity was created. If validation fails instead, the log names the entity and field at fault.