Error codes

A diagnostic of gozen can carry a code: GZN and four digits at the end of the line, or the code field of the JSON output. The message may be reworded; the code does not change, so you can search for it, link to it, and branch on it.

The first digit is the exit value: GZN0xxx is a warning and the command still exits 0, GZN1xxx exits 1 (processing failed), and GZN2xxx exits 2 (the command line is invalid). The next two digits are the family, what you have to fix. Summary lines such as check: 3 errors carry no code; the diagnostics they count do.

Run gozen help GZN1101 to read an entry in the terminal.

Codes are assigned one family at a time. A diagnostic without a code still exits the same way and still says what is wrong.

GZN01xx #

Warnings of check: the game loads, but something is likely a mistake. Exits 0.

GZN0101 #

A text does not fit the message window.

The layout check lays out every line of dialogue and every choice with the game’s font and display rules. This one needs more lines than the window shows, so the player would see it cut or paged where the author did not plan it.

Fix: Shorten the text, split it into two lines of dialogue, or change the window in game.yaml.

GZN0102 #

A balloon face has no face box, or the box is stale.

A painted scene cuts each person’s balloon face around the face that gozen art faces found and wrote to assets/faces.json. The file is missing, has no box for a picture, has none found, or the picture changed since, so the face is guessed.

Fix: Run gozen art faces again, or give the doll face_at.

GZN0103 #

A place of a map or a painted scene cannot be reached.

A point no road leads to, a point without a way back, an exit or a thing that does not touch the walkable area, or a spot without do (which is no entry) cannot be used by the player.

Fix: Connect it (a road, an exit back, walk that touches it) or remove it; give a spot a do to make it an entry.

GZN0104 #

A picture or a shape will be drawn otherwise than written.

A polygon that crosses itself, a person without an image (its doll takes plain colors), or an icon that is not square (it is cut round from its middle) is drawn, but probably not as meant.

Fix: Fix the polygon’s points, give the person an image, or make the icon square.

GZN0105 #

The game’s language and its words or font do not match.

language is not set while the game is written in Japanese, so the engine’s own words are English; or the regular font lacks letters of the chosen words, which would show as blanks.

Fix: Set language in game.yaml, or choose a font that has the letters.

GZN0106 #

A part of an AI rule’s target is not used.

For some actions the target of a rule only decides whether the rule fires: a random enemy is drawn anew, a self skill always hits its user, and by is read only with pick min or max.

Fix: Remove the part the message names, or use a skill whose target the rule chooses.

GZN0107 #

A set reads another target of the same set.

The targets of one set are assigned one after another in key order, so a right-hand side that reads another target of the same set depends on that order.

Fix: Split it into two set commands in the order you mean.

GZN0108 #

A set changes an actor’s stats or level outside the development mode.

Setting a party member’s stats or level is for the development mode (–dev) and tests. The game skips it when played normally.

Fix: Use a command the game keeps (an item, a class change, experience), or keep it in a development-only event.

GZN0109 #

Lines of a voiced actor have no voice.

An actor with a voices folder has lines without say.voice. They are shown without a voice; the warning counts them so the recording can be finished.

Fix: Record the lines it names and add voice to each, or leave them silent on purpose.

GZN0110 #

A translation is of a text the game does not have.

A key of lang/.yaml is neither a text of the game (a line, a choice, a name) nor a word of the engine. The text was changed or removed after it was translated.

Fix: Change the key to the text as it is written now, or remove the entry.

GZN0111 #

A text of the game is not translated yet.

A language of game.yaml’s languages has no translation of this text in lang/.yaml, so the text is shown as written.

Fix: Add the text as a key of lang/.yaml with its translation; gozen check –format json lists every one with its path.

GZN0112 #

A flag is set but nothing reads it.

A set writes flag., and no condition, expression or line of the game reads it. It may be a typo of another flag, or left over.

Fix: Read the flag where it should matter, fix its name, or remove the set.

GZN0113 #

A flag is read but nothing sets it.

A condition or expression reads flag., and no set, gallery scene or state.names declaration gives it a value, so it stays false (unless a test starts with –flags or the game’s Go code sets it).

Fix: Set the flag where it should become true, fix its name, or declare it in state.names.

GZN0114 #

An expression uses a function’s name as a value.

A built-in function (floor, max, len and the others) or a function of the game (rand, chance, pages) is written alone, not called, as in floor + 1. The expression fails when it is evaluated. floor is the floor’s number only in generate’s size, the count of generate.place and a roamer’s count, appear, wait and every; elsewhere it is the function and the floor’s number is var.floor.

Fix: Call the function (floor(x)), or use the value you meant (var.floor).

GZN11xx #

The definitions of the game: YAML, references, expressions, assets. Exits 1.

GZN1101 #

A definition names something that is not defined.

A troop, item, actor, skill, location, event, song, picture set, state, stat, node or another named thing is referred to but not defined, or the thing has no part of that name (a point of a map, a mood of a song, a face of a puppet).

Fix: Fix the spelling or define the thing. gozen book lists every ID of the game.

GZN1102 #

Something is defined twice.

The same ID or key appears twice, in one file or across the files of data/. The message names the previous definition.

Fix: Rename or remove one of them.

GZN1103 #

An expression cannot be read or uses a name unknown there.

An expression (when, a formula, a condition) has a syntax error, uses a name that does not exist where it is written (turn exists only in battle, a and b only in an effect), or mixes types.

Fix: Fix the expression; the message lists the names known at that place.

GZN1104 #

A definition is missing a part, or has parts that do not go together.

A key that is required is missing or empty, two keys exclude each other, a key is used where it means nothing, or a value has the wrong YAML type (a list where a map belongs, text where a number belongs).

Fix: Write the definition in the shape the Schema page shows for it.

GZN1105 #

An asset file does not exist.

A picture, a sound, a face, a font or another file named by the definitions is not under assets/. Names are relative to assets/ and case-sensitive.

Fix: Add the file, or fix the name.

GZN1106 #

A number is out of its range.

The value is a number, but outside what the key accepts: a rate between 0 and 1, a count of 1 or more, a size above 0, a level within the class’s maximum.

Fix: Use a number in the range the message states.

GZN1107 #

A value is not one of the words the key accepts.

The key takes one word from a fixed list, such as a direction, a mode or a screen name. The message lists the words.

Fix: Use one of the listed words.

GZN1108 #

A word needs a newer schema_version.

The word was added in a later version of the YAML schema, and game.yaml declares an earlier schema_version, so an older engine would not read the game the same way.

Fix: Raise schema_version in game.yaml to the version the message names.

GZN1109 #

A YAML file cannot be parsed.

The file is not valid YAML: an indentation, a quote, a colon or a bracket is wrong. A value of a description containing a colon and a space must be quoted.

Fix: Fix the YAML at the line and column the message names.

GZN1110 #

The game directory or game.yaml cannot be read.

The directory given is not a game directory: it does not exist, cannot be read, or has no game.yaml.

Fix: Pass the directory that holds game.yaml, data/ and assets/.

GZN1111 #

A dungeon theme is named but its pictures are not in the game.

A dungeon or one of its looks says theme: , but assets/dungeon/themes// lacks wall.jpg, floor.jpg, ceiling.jpg, door.jpg or theme.yaml. The theme’s pictures are not part of the game until they are copied in.

Fix: Run gozen theme add (gozen theme list shows the names), or put your own folder of that name there.

GZN12xx #

Fonts and text layout. Exits 1.

GZN1201 #

A font of the game cannot be read.

The layout check reads the game’s fonts to lay out the dialogue, and one of them is missing or is not a TrueType or OpenType font.

Fix: Fix the font files of game.yaml, or check the structure alone with gozen check –only structure.

GZN14xx #

A trace of a play is broken or shows faults. Exits 1.

GZN1401 #

A line of the trace is broken.

play trace reads the JSON Lines the game writes with –trace. A line is not JSON, has no kind t, or has a tick that is not a time.

Fix: Record the trace again with the game’s –trace; do not edit it by hand.

GZN1402 #

A standing picture went wrong in the play.

play trace –check found a standing picture that moved while speaking, was left over after its line, hid an event picture, or was missing for a speaker.

Fix: Look at the event at the time the line names, and fix its show and hide commands or the speaker’s pictures.

GZN1403 #

A song came later than asked for.

play trace –check found a song heard later than –music-late seconds after the game asked for it.

Fix: Make the song shorter to load (a smaller file) or ask for it earlier.

GZN1404 #

Skipping passed a line that was not read.

play trace –check found a line marked not read while skip mode or scene skip was on. Skipping stops before every line not read.

Fix: Record the trace again with this engine; if it happens again, report it with the trace.

GZN1405 #

Rolling back did not go back.

play trace –check found a rollback line whose event stayed and whose line did not go back. Rolling back replays the event from its start to the line before.

Fix: Record the trace again with this engine; if it happens again, report it with the trace.

GZN1406 #

A voice could not be read in the play.

play trace –check found a voice line marked missing: the file of a line’s voice was not there or was not a sound the engine reads.

Fix: Add the file under assets/ (ogg or wav), or fix the say.voice that names it; gozen check lists missing voices too.

GZN15xx #

An output path: it exists, overlaps an input, or cannot be written. Exits 1.

GZN1501 #

The output already exists.

Commands that write a directory or a list never overwrite: the output must not exist yet, even as an empty directory.

Fix: Choose a new path, or remove the old output yourself.

GZN1502 #

The output is inside an input, or holds one.

Writing into the game directory, the overlay or the list would change what is being read.

Fix: Write the output outside the inputs.

GZN17xx #

Building a release or a trial tree. Exits 1.

GZN1701 #

An asset the game refers to is not approved.

pack release copies only approved assets. An asset of the overlay that the game refers to has no approved inspection record, or it changed since the record.

Fix: Inspect the asset and add an approved record, or stop referring to it.

GZN1702 #

The approval settings or records cannot be read.

The game’s asset-policy.yaml, the overlay’s records, or the –inspect file is missing or malformed, or no overlay is given.

Fix: Give –overlay and –inspect, and check the files the message names.

GZN1703 #

An asset the game refers to is not there.

The tree being built refers to an asset that is neither in the game nor in the overlay.

Fix: Add the asset, or remove the reference; gozen check lists missing pictures too.

GZN1704 #

Trial.yaml cannot be read.

The range settings of pack trial are not valid: YAML, an assume that is not var. or flag., a dive_max without blocked, or a bad pattern.

Fix: Fix trial.yaml as the message says.

GZN21xx #

The shape of the command line: commands, operands, options. Exits 2.

GZN2101 #

There is no such command.

The word is not a command of gozen or of the group it follows. The commands are grouped (ADR 0024): check, sim, play, book, pack, art, theme, version, and help. An old name such as curve or memos is answered with its new place, for example gozen sim dive.

Fix: Use the command the message names, or run gozen –help (or the group with –help) for the list.

GZN2102 #

The command takes another number of arguments.

A command takes a fixed list of positional arguments, such as a game directory and a troop for sim battle. Too few or too many were given; an option that needs a value may have taken the next word.

Fix: Give the arguments the usage line of the command’s –help shows, in that order. Put – before an argument that starts with a dash.

GZN2103 #

The command has no such option.

Options belong to a command: an option of sim battle is not an option of sim dive, and a group such as sim has only –help.

Fix: Check the option in the command’s –help.

GZN2104 #

A long option was written with one dash.

Options follow the GNU style (ADR 0018). A long name with one dash, such as -seed, would be read as the short options -s -e -e -d, so it is refused instead.

Fix: Write the long option with two dashes, such as –seed.

GZN2105 #

An option was given before the command.

gozen itself takes only –help and –version. Options of a command come after the command’s name, because the command decides what they mean.

Fix: Write gozen [OPTIONS], for example gozen sim battle –seed 7 game lesson.

GZN2106 #

A command is required.

gozen, and a group such as sim or art, does nothing by itself. The message lists the commands it holds.

Fix: Add one of the listed commands, or run the group with –help to read about them.

GZN22xx #

The value of an option. Exits 2.

GZN2201 #

An option has a value of the wrong type or out of range.

The value cannot be read as the option’s type (a number, a duration), or it is outside the range the option accepts: a count that must be positive, a rate between 0 and 1, a time that cannot be negative, or a pair such as FLOOR:TROOP written another way.

Fix: Give a value of the type and range the option’s description in –help states.

GZN2202 #

An option has a value that is not one of its choices.

The option takes one word from a fixed list, such as –format text or json, or check –only structure or layout. A misspelled choice is refused instead of falling back to a default.

Fix: Use one of the values the message lists.

GZN23xx #

Options that do not go together, or need each other. Exits 2.

GZN2301 #

Two options do not go together.

The options ask for things that exclude each other, such as a saved state and a chosen party for sim battle, or –raw and –overlay for play shots.

Fix: Keep one of the options the message names.

GZN2302 #

An option needs another option.

Some options mean something only in company: –as-is keeps the HP of a –state, –try compares the seeds of one –floor, and –overlay and –inspect go together.

Fix: Add the option the message names, or drop the one that needs it.

GZN2303 #

A required option is missing.

The command cannot run without the option: play shots needs the game binary (–bin), pack release the inspection records (–inspect), and art prompt the catalog (–config).

Fix: Add the option the message names.

GZN24xx #

A path or a name the command line gives. Exits 2.

GZN2401 #

A path must be relative and stay inside its directory.

The option names a file or a directory inside the game, such as pack trial –config or pack release –prefix. It must be a relative path separated by / that does not climb out with .. or start at the root.

Fix: Write the path relative to the game directory, without .., such as trial.yaml.

GZN2402 #

The command line names something the game does not have.

An ID given on the command line, such as the troop of sim battle, the location of sim dive or sim floors, a boss or a shop, a persona of sim design –only, a shot of play shots –only, or a model of art fetch, is not defined. A typo in an argument is an argument error, so it exits 2 in every command.

Fix: Check the spelling against the game’s data (gozen book lists every ID), or the list the message names.

GZN25xx #

Gozen help. Exits 2.

GZN2501 #

There is no such diagnostic code.

gozen help explains a code of the form GZN and four digits, and this one is not registered. The message lists the codes of the same family when there are any.

Fix: Copy the code from the end of the diagnostic, or look it up on the error codes page.