Commands

gozen reads a game directory (game.yaml, data/, assets/) and checks, simulates, documents and packages it. Results go to stdout and diagnostics to stderr.

gozen <command> [<sub-command>] [OPTIONS] [ARGUMENTS]
gozen help <command> [<sub-command>]   # the same as the command with --help
gozen help GZN1101                     # explain a diagnostic code

A group alone (gozen sim) exits 2 and lists its commands. gozen sim --help shows the group’s page.

Conventions #

• Exit status: 0 for success and help, 1 when a check, I/O, simulation or capture fails, 2 for invalid arguments. A name the command line gives that the game does not have (a troop, a location, a persona, a shot) is an invalid argument.
• A diagnostic may end with a code such as [GZN1101]; its first digit is the exit status. gozen help GZN1101 explains it, and Error codes lists them all.
• Options follow the GNU style. --seed 7 and --seed=7 both work, a few common options have a one-letter form (-n 100, -o DIR, -v, -h), options may come before or after the arguments, and -- ends the options. A single-dash long option such as -seed is rejected with exit status 2.
• Commands that write a directory (sim design, play notes, pack release, pack trial, play shots) refuse one that already exists, even if empty, and an output inside an input. They never overwrite.
• Every command except play shots, art faces and art mosaic detection needs nothing beyond the gozen binary: no cgo, display or sound device.

The examples below use game as the game directory, lesson as a troop and grotto as a dungeon location.

check #

Loads every definition, resolves references and expressions, checks that the assets exist, and lays out dialogue with the game’s font. Warnings go to stderr and do not fail the check.

gozen check game
gozen check --only structure game  # structure only, before the game has fonts
gozen check -- -draft              # a directory whose name starts with a dash
gozen check --format json game     # every error and warning as JSON, for a tool or an agent

ok: 2 locations, 1 events, 1 actors, 2 skills, 0 items, 1 enemies, 1 troops, 0 ai sets
data/world.yaml:26:5: locations.grotto.encounters: unknown troop "lessn" [GZN1101]

[
  {
    "file": "data/world.yaml",
    "line": 8,
    "col": 15,
    "path": "events.bad.do[0].battle",
    "message": "unknown troop \"wolves\"",
    "severity": "error",
    "code": "GZN1101"
  }
]

--only layout lays out every line of dialogue and every choice with the game’s font and display rules, and reports the ones that overflow. Warnings alone exit 0.

gozen check --only layout game

sim #

Plays the game by its rules alone, with no window or sound. --seed, --turns and --format mean the same in every sim command: the same --seed gives the same result.

sim battle #

Fights the troop with the starting party (or --party, or a saved state) under AUTO and prints the win, loss, flight and draw rates and the average turns. The numbers are the same as the F7 balance panel. The same --seed gives the same result.

gozen sim battle game lesson -n 100
gozen sim battle game lesson -n 100 --party scout --level 5 --seed 7
gozen sim battle game lesson --state memo.save --hp                 # from a note, HP left after a win
gozen sim battle game lesson --state memo.save --as-is --streak 10  # keep the saved HP, count wins in a row
gozen sim battle game lesson -n 1 -v                                # the messages of the first battle

lesson: 100 battles  win 100%  lose 0%  fled 0%  draw 0%  avg turns 1.0  avg standing after a win 1.0

sim dive #

Takes the starting party down a dungeon location, fighting --battles battles on each floor, buying better equipment from --shops, resting, and fighting the bosses. Prints the level, HP, gold and win rates of each floor.

gozen sim dive game grotto --floors 3 --battles 5
gozen sim dive game grotto --floors 3 --boss 3:lesson --grind 0.8
gozen sim dive game grotto --floors 4 --rest 2 --boss 2:lesson --tries 50

floor Lv   battles lost   turns  hp_left mp     gold   scenes boss    troops
B1    1    5       0      1.0    1.00    1.00   15     0      -       lesson
B2    1    5       0      1.0    1.00    1.00   30     0      -       lesson
B3    1    5       0      1.0    1.00    1.00   45     0      -       lesson

sim floors #

Generates the floors of a dungeon location and prints each map with the steps to the stairs and the expected encounters. With --try, compares seeds on one floor.

gozen sim floors game grotto --from 1 --to 3
gozen sim floors game grotto --floor 1 --try 3
gozen sim floors game grotto --no-map

sim design #

Plays the game headless with the personas of designeval.yaml (players, rewards and time weights) and writes summary.json, the timelines, band.png and report.md to a new directory. A simulation error keeps the report and exits 1. A small configuration is in the CLI test fixture.

gozen sim design game -o report
gozen sim design game -o report --only walker -v

sim campaign #

Plays the game’s campaign (Campaigns) many times, headless, with a strategy for the player, and prints the win rate, the turns the campaigns ended in, the mean of the regions each faction held at the start of each turn, the factions that fell and when, the orders given, and how the marches went. Campaign i uses the seed --seed + i, so the same --seed gives the same result.

gozen sim campaign game
gozen sim campaign game --as random -n 500 --format json
gozen sim campaign game --tactic guard

play #

Reads and takes pictures of real plays. The game binary itself is run by its own --dev.

play trace #

Prints a trace written by the game’s --trace in time order. With --check, lists faults of the standing pictures and the music instead and exits 1 if there are any.

gozen play trace run.jsonl
gozen play trace run.jsonl --only say,battle --from 10 --to 60
gozen play trace run.jsonl --check

play notes #

Reads the notes the game writes with F9 and builds an HTML page with thumbnails in a new directory. The notes are not changed.

gozen play notes notes                 # writes notes-html/
gozen play notes notes -o review-html

play shots #

Launches the game binary once per entry of a list and writes PNG, JPEG, an HTML index and shots.json to a new directory. Each shot runs with its own save directory.

gozen play shots game shots.yaml --bin ./mygame --raw -o shots
gozen play shots game shots.yaml --bin ./mygame --raw --only camp --timeout 1m
xvfb-run -a gozen play shots game shots.yaml --bin ./mygame --raw     # unattended on Linux

A list:

shots:
  - id: camp
    title: Camp overview
    start: camp
    wait: 30

id becomes the file name. An entry can also start a scene or an event, stop at a picture, line or answers, or run a script.

play shots needs what the game window needs: a display and the graphics libraries (on Linux, Xvfb for unattended runs). A failed launch is recorded in the work tree and exits 1.

book #

Writes the locations, events, scenes, troops and items of the game to stdout as one Markdown document. A quick way to review a whole game, or what an agent wrote. The headings follow the game’s language.

gozen book game > book.md

pack #

Copies the game to a new directory. --overlay takes replaced assets from a directory, and --inspect reads the approval records every asset of the overlay must have.

pack release #

Checks the approval records and the assets the game refers to, then copies the game to a new directory, taking replaced assets from an overlay. Any unapproved reference fails the build.

gozen pack release game release --inspect inspect.jsonl
gozen pack release game release --overlay overlay --inspect inspect.jsonl

pack trial #

Keeps only the definitions and assets reachable within the range of trial.yaml and writes them to a new directory: a demo version of the game.

gozen pack trial game -n                            # count what would be kept, write nothing
gozen pack trial game trial --list trial.txt        # build, and list what was kept and dropped
gozen pack trial game trial --overlay overlay --inspect inspect.jsonl

art #

Tools for the pictures of a game. art prompt assembles image-generation text from a catalog, and art mosaic pixelates regions of images; both are described on Production tools.

art fetch #

Downloads fixed revisions of the detection models (censor, face, head) into the user cache and checks each file against a SHA-256 written in gozen. art mosaic and art faces use a model in the cache when --model is omitted.

gozen art fetch --list     # the models and whether each is in the cache
gozen art fetch face       # the face detector of art faces

art faces #

Finds the face in each standing picture a painted scene (stage:) cuts a balloon face from (the people placed in a stage and the actors’ face pictures) with the anime face detector that gozen art fetch face downloads, and writes the boxes with each picture’s size and SHA-256 to assets/faces.json. The game only reads that file and runs no model, so a web build shows the same faces. A doll’s icon (a face drawn for the balloons) comes first and is not searched, then its face_at, then the box; a picture without a box gets a guessed face, and gozen check warns of it and of a picture changed since.

gozen art fetch face                          # download the model once
gozen art faces game                                 # find the faces
gozen art faces game --preview faces-check           # and look at the boxes and the cut faces

It needs a gozen built with cgo, an ONNX Runtime shared library and the model, as gozen art mosaic does; a build without cgo says so and fails.

art puppet #

Loads a moving portrait (a puppet YAML for the puppet package) with the same checks as puppet.Load and prints where each face, closed-eyes and mouth picture lies on the base picture. A difference picture as large as the base is cut down to the part that differs.

gozen art puppet streamer/puppet.yaml                        # check it and show the positions
gozen art puppet streamer/puppet.yaml --out streamer-packed  # write it with small difference pictures

It needs nothing beyond the gozen binary: no cgo, display or sound device.

theme #

A dungeon theme is a wall, a floor, a ceiling and a door picture with colors that go together. The gozen binary carries five themes (cave, ice, ruins, castle, crystal); gozen theme add copies one into a game, and theme: cave in a dungeon or one of its looks then fills the walls, floor, ceiling, door and colors that the YAML does not write. The pictures are not part of the game runtime, so a game that uses no theme does not carry them.

theme list #

Prints the name of each theme with a line on how it looks.

gozen theme list

theme add #

Copies wall.jpg, floor.jpg, ceiling.jpg, door.jpg (1024x1024) and theme.yaml (the far fog and map colors), with LICENSE.txt for the pictures, to assets/dungeon/themes/<name>/ of the game. No network is used. A file the game already has is kept, so your own edits stay.

gozen theme add cave game          # the files of the cave theme go to game/assets/dungeon/themes/cave/
gozen theme add cave game --force  # replace the files that are already there

An unknown theme name exits 2 (GZN2402), and a directory without game.yaml exits 1 (GZN1110). A game that says theme: cave without the folder fails gozen check with GZN1111 and the line run gozen theme add cave <game-dir>. The pictures are CC BY 4.0, see ASSETS.md.

version and help #

gozen version
gozen -v

Prints the version recorded by go install, or devel for a build from source.

gozen help takes the words of a command (gozen help sim battle is gozen sim battle --help), or a diagnostic code:

gozen help sim battle
gozen help GZN2101