Glyphweft file formats

All files are UTF-8 text that can be edited in any text editor. JSON files allow // comments and trailing commas, property names are not case-sensitive, and unknown properties are errors (so a misspelt field is reported, not ignored). The engine writes every format in one canonical form: two-space indents, short arrays on one line, properties in the order the tables below list them, and every value that equals its default left out. Writing a file twice gives the same bytes; comments are not kept (see the Engine manual's Writing files).

Each Glyphweft format has its own extension (.gwanim, .gwworld, .gwcolors and the rest), not a double one like .gwanim.json: Windows only looks at the last extension, and a name of its own lets Glyphweft Studio be the program that opens these files. Most of them are JSON inside. The repository and the game template include .vscode/settings.json, which tells VS Code to show them as JSON (with comments); in another editor, set the same association. glyphweft.json, the game's settings, keeps .json.

Glyph art: name.gwart + name.gwcolors#

A piece of art is two files side by side: the glyphs, and a JSON sidecar with size, pivot and colours. The glyphs and the colours are kept apart, so the glyph file stays readable as ASCII art.

name.gwart — the glyphs#

A rectangle of printable ASCII (0x20–0x7E): exactly size[1] lines of exactly size[0] characters. Whitespace is significant and never trimmed. A newline after the last line is optional. Tabs and non-ASCII characters are errors. Each error names the file, line and column, for example:

art/nature/bush.gwart:4: line is 28 characters wide, "size" says 26.
art/nature/bush.gwart:6:5: tab character; use spaces.

name.gwcolors — the sidecar#

{
  "schemaVersion": 1,
  "id": "characters.hero.down",
  "size": [30, 34],
  "transparent": " ",
  "origin": [15, 33],
  "defaultForeground": "#BAC6D1",
  "defaultBackground": "#101418",
  "colorsByGlyph": { "o": { "foreground": "#1C2C48", "background": "#F2F6FA" } },
  "palette": { "a": "#E2B090", "b": "#6A3A1E", "c": "transparent" },
  "foregroundMap": ["  ab  ", "..."],
  "backgroundMap": ["   c  ", "..."],
  "sockets": [ { "id": "head", "x": 15, "y": 3 } ]
}

Colours are #RRGGBB, #RRGGBBAA or "transparent".

Colour precedence, highest first: foregroundMap/backgroundMap > colorsByGlyph > defaults.

Transparent cells draw nothing, not even the default background. The exception is a cell that a backgroundMap key gives a background: it becomes a background-only cell. A background of "transparent" on a glyph cell removes the default background for that cell.

Colour maps let dense art give every cell its own colour without one JSON object per cell. With one-character keys a map can use 94 colours; with "mapKeyWidth": 2 it can use 8,836.

Canonical form#

The engine writes art in one canonical form (ArtFormat.Write, used by Glyphweft Studio later):

• the defaults are the most common colours of the glyph cells;
• the maps hold only cells that differ from the defaults;
• palette keys are assigned in order of first use (a–z, A–Z, 0–9, then punctuation);
• the key width is 2 only when more than 94 colours are needed.

Reading the canonical form back gives exactly the same cells, and writing it again gives the same text.

Animation sets: name.gwanim#

The clips of one character or effect: sequences of .gwart frames with timing, events and directions.

{
  "schemaVersion": 1,
  "id": "hero",
  "fps": 8,
  "clips": {
    "idle.down": { "fps": 4, "frames": ["hero/idle_down_0.gwart", "hero/idle_down_1.gwart"] },
    "walk.down": { "frames": [
      { "art": "hero/walk_down_0.gwart", "ms": 105, "events": ["step"] },
      { "art": "hero/walk_down_1.gwart", "ms": 105 }
    ] },
    "walk.right": { "frames": ["hero/walk_right_0.gwart", "hero/walk_right_1.gwart"] },
    "attack.down": { "mode": "once", "next": "idle", "frames": [
      { "art": "hero/attack_down_0.gwart", "ms": 110 },
      { "art": "hero/attack_down_1.gwart", "ms": 70, "events": ["swing"] },
      { "art": "hero/attack_down_2.gwart", "ms": 120, "events": ["hit"], "offset": [1, 0] }
    ] }
  }
}

Paths are relative to the .gwanim file; a path starting with / is relative to the asset folder.

Directions are down (the front), downright, right, upright, up (the back), upleft, left and downleft. To find the clip for a facing, the engine tries in order:

1. that direction;
2. the mirror image of the opposite side (left plays right mirrored, so most sets author five directions and get eight);
3. for a diagonal, its left/right side (or that side's mirror), then its up/down side;
4. the plain {name};
5. the front, {name}.down.

Headings, for things seen straight down (the overhead view) that turn to any angle, are h0 (facing up the screen) to h31, turning clockwise 11.25 degrees each: h8 faces right, h16 down, h24 left. Any of them may be left out; a game turned to a heading in degrees shows the nearest one the clip has, else the plain {name}.

Validation reports, with the file, clip and frame: missing frame files, durations of 0 ms or less, unknown directions, headings and modes, next clips that do not exist, and unknown fields (in a frame object too).

Canonical form: a frame that sets nothing but its art is written as just its path.

Models: name.gwmodel#

A model asset: one of the art kit's models and the values of its parameters. Studio's model editor writes it; building it writes ordinary art next to it, named after it: a character's animation sets (name.gwanim, frames in name/, and name_sword.gwanim for a sword layer), or one piece of art (name.gwart). Games use the built files and never read the model file.

{
  "schemaVersion": 1,
  "model": "runefox",
  "parameters": {
    "fur": "#9FB6D8",
    "ears": 1.4,
    "sword": false
  }
}

Validation reports, with the file: an unknown model, unknown parameters, and values of the wrong kind or out of range. Canonical form: every parameter, in the model's order.

Worlds: name.gwworld and name.gwmap#

A world is tile ground of unlimited size with objects standing on it. Hand-made maps (.gwmap) are placed in it, and an optional generator makes everything around them, as far as anyone walks.

{
  "schemaVersion": 1,
  "tile": [8, 6],
  "tiles": {
    "grass": { "texture": "art/ground/grass.gwart" },
    "water": { "texture": "art/ground/water.gwart", "solid": true, "surface": "water", "edge": "#B8A47A", "edgeWidth": 3 }
  },
  "default": "grass",
  "objects": {
    "oak": { "art": "art/nature/oak.gwart", "sway": 1, "collider": [-12, -10, 24, 12] },
    "cottage": { "art": "art/buildings/cottage.gwart", "snowTop": 0.5 },
    "flowers": { "art": "art/nature/flowers.gwart" }
  },
  "maps": [
    { "file": "village.gwmap", "at": [-32, -20], "legend": {
      ".": "grass",
      "~": "water",
      "O": { "tile": "grass", "object": "oak" },
      "h": { "tile": "grass", "object": "cottage", "flipX": true, "offset": [4, 0] },
      "@": { "tile": "grass", "spawn": "hero" }
    } }
  ],
  "generator": {
    "seed": 7,
    "layers": [ { "tile": "water", "scale": 34, "below": 0.27 } ],
    "scatter": [ { "object": "oak", "on": "grass", "density": 0.01 } ]
  }
}

A tile's join makes it join up with neighbours of its own type, like a road, a wall or a stream:

"road": { "texture": "art/ground/dirt.gwart", "join": { "under": "grass", "style": "path", "shapes": ["art/ground/road_join/road_0.gwart", "...16 in all"] } }

A tile's animate (every field optional):

"water": { "texture": "art/ground/water.gwart", "solid": true, "surface": "water", "edge": "#B8A47A", "edgeWidth": 3,
  "animate": { "frames": ["art/ground/water_1.gwart", "art/ground/water_2.gwart"], "fps": 2.5, "shimmer": 0.5, "glints": 0.05,
               "shore": "#D6E8F0", "waves": 3.2, "shoreWidth": 3, "reflect": true } }

.gwmap is plain text with one character per tile. Spaces count, every row must be the same width, and every character must be in the legend. Errors give the line and column:

village.gwmap:12:30: 'x' is not in the legend.
village.gwmap:7: row is 63 characters wide, the first row is 64.

Objects from a map stand at the bottom centre of their tile (plus offset). A map replaces whatever the generator made inside its area. The same seed always makes the same world, whichever part is visited first.

Particle effects: name.gweffects#

{
  "schemaVersion": 1,
  "effects": {
    "fire": {
      "blend": "add", "glow": true, "glyphs": "*^'.", "colors": ["#FFD070F0", "#FF9028D0", "#E04810A0", "#40080000"],
      "life": [0.4, 0.75], "speed": [30, 60], "direction": -90, "spread": 30, "gravity": -70, "drag": 1.4,
      "size": [9, 2], "rate": 46, "jitter": 7,
      "light": { "color": "#FF8030", "radius": 40, "intensity": 0.22 }
    }
  }
}

Comments and trailing commas are allowed. Unknown fields are errors. Every field of an effect is optional:

Weather: name.gwweather#

{
  "schemaVersion": 1,
  "start": "clear",
  "blend": 10,
  "look": { "rain": "#C4D4ECD8", "snow": "#F2F6FFE8", "fog": "#B8C0CC", "snowGround": "#F2F6FC", "puddle": "#36435A", "lightning": "#E0E8FF" },
  "states": {
    "clear": { "cloud": 0.1, "wind": 10, "gust": 0.3, "seconds": [60, 120], "next": ["cloudy", "fog"] },
    "storm": { "cloud": 1, "rain": 1, "fog": 0.15, "wind": 95, "gust": 0.8, "lightning": 7, "seconds": [25, 50], "next": ["rain"] }
  }
}

Comments and trailing commas are allowed. Unknown fields are errors.

Every field of a state is optional:

Sounds: name.gwsounds#

{
  "schemaVersion": 1,
  "sounds": {
    "hit": { "pitch": [0.85, 1.15], "max": 6, "voices": [
      { "wave": "square", "freq": [380, 70], "duty": 0.35, "attack": 0.001, "decay": 0.14, "lowpass": [5000, 900], "volume": 0.45 },
      { "wave": "noise", "freq": [9000], "attack": 0.001, "decay": 0.07, "volume": 0.55 } ] },
    "rain": { "bus": "ambient", "loop": true, "length": 3, "voices": [
      { "wave": "noise", "freq": [30000], "lowpass": [2600], "highpass": 500, "volume": 0.3 } ] },
    "door": { "file": "sounds/door.wav" },
    "town": { "file": "music/town.ogg", "bus": "music", "loop": true, "loopStart": 6.4, "max": 1 }
  }
}

Comments and trailing commas are allowed. Unknown fields are errors. A game can load several sounds files; a sound named like one read before replaces it (a game's own file, loaded after the shared one, can change a shared sound). A sound has either voices or file:

A voice (every field optional):

Music: name.gwmusic#

{
  "schemaVersion": 1,
  "bpm": 84,
  "steps": 2,
  "beats": 4,
  "volume": 0.9,
  "instruments": {
    "lead": { "volume": 0.22, "pan": -0.15, "voices": [ { "wave": "triangle", "attack": 0.012, "decay": 0.15, "sustain": 0.45, "release": 0.3 } ] },
    "kick": { "volume": 0.4, "voices": [ { "wave": "sine", "freq": [150, 45], "decay": 0.18 } ] }
  },
  "patterns": {
    "a": { "lead": "E5 - - - D5 C5 - - | A4 - - - C5 - - -",
           "kick": "x . . . x . . . | x . . . x . . ." }
  },
  "song": ["a", "a"]
}

A track is tokens separated by spaces, one per step: a note (C4, F#3, Bb5) starts on its step, - holds the note before for another step, . is a rest, x is a hit at the instrument's own pitch (drums), and | marks a bar (it is skipped). A track plays one note at a time. The piece is rendered once into a stereo loop; notes still ringing at the end carry on into the start, so the loop has no seam.

Data tables: name.gwtable + name.gwschema#

A game's own data (items, monsters, recipes, buildings, moves, its settings) is kept in tables, one file each, in a folder of the assets (normally data/). Each table has a schema beside it, named the same, that says what its rows hold. GameTables.Load(assets) reads every table in the folder, checks every row against its schema, then every reference to another table's rows and every asset path, and reports every problem at once with its file, row and field.

A schema:

{
  "schemaVersion": 1,
  "title": "Monsters",
  "about": "What the hero fights.",
  "fields": {
    "title": { "type": "text", "about": "The name players see." },
    "life": { "type": "int", "min": 1 },
    "damage": { "type": "range", "min": 0, "whole": true },
    "anim": { "type": "asset", "kind": "anim" },
    "tint": { "type": "colour", "optional": true },
    "drops": { "type": "map", "key": { "type": "ref", "table": "items" }, "of": { "type": "number", "min": 0, "max": 1 }, "default": {} }
  }
}

Every field has a type, and may have optional (a row may leave it out), default (the value a row that leaves it out gets; the field is then optional) and about (one line on what it means, for Studio's forms). The types:

A table:

{
  "schemaVersion": 1,
  "rows": {
    "skeleton": { "title": "Skeleton", "life": 16, "damage": [1, 4], "anim": "anim/skeleton.gwanim", "drops": { "potion": 0.14 } },
    "bone_lord": { "title": "The Bone Lord", "life": 260, "damage": [7, 13], "anim": "anim/bone_lord.gwanim", "tint": "#C0A0FF" }
  }
}

• rows: each row by name, in the order the game sees them. Row, field and table names are letters, digits, _ and -, starting with a letter or digit.
• A field the schema does not name is an error; so is a missing field that is neither optional nor has a default.
• A table of settings ("single": true) holds one row; its name is up to you.
• Problems read like data/monsters.gwtable: row "skeleton" "life": 0 must be at least 1. or data/units.gwtable: row "archer" "tech": "archeryy" is not a row of techs (it has pottery, archery, ...).
• A game reads rows into its own C# classes with table.Read<T>() (fields map to properties by name, catchRate to CatchRate), or value by value with table["skeleton"]["life"].Int. What only the code knows (a building kind the game must have, levels that must rise) the game checks itself, reporting it the same way.

Dialogue: name.gwdialogue#

A conversation, or every conversation of one character, as nodes. A conversation starts at start and stops at each node with a line for the game to show; nodes without a line only change the story and go on.

{
  "schemaVersion": 1,
  "speaker": "Professor Elm",
  "start": "hello",
  "nodes": {
    "hello": { "branch": ["later", "first"] },
    "later": { "text": "How is {starter} doing?", "if": ["starter"] },
    "first": { "text": "Which wildling will you take?",
               "choices": [ { "text": "Emberkit", "to": "emberkit" }, { "text": "Let me think" } ] },
    "emberkit": { "set": ["starter"], "do": "give_starter emberkit", "next": "thanks" },
    "thanks": { "text": "Look after each other.", "add": { "visits": 1 } }
  }
}

A node's fields, all optional:

A node goes on by next, branch or choices, only one of them. Conditions are flag (set), !flag (not set), or a number compared with a whole number: coins >= 20, visits == 3 (==, !=, <, <=, >, >=). Flags and numbers belong to the story (StoryState); a game can lend it numbers of its own, such as coins.

Quests: name.gwquests#

{
  "schemaVersion": 1,
  "quests": {
    "partner": {
      "title": "A first partner",
      "about": "Every trainer starts with a wildling.",
      "stages": [
        { "text": "See Professor Elm in the town square.", "done": ["starter"] },
        { "text": "Beat your rival on Route 1.", "done": ["rival"] }
      ]
    }
  }
}

A quest's stage is the first one not done yet; it is done when every stage is. The same conditions as dialogue.

Texts: name.gwtext#

The words a game shows, in every language it has, named by "texts" in glyphweft.json:

{
  "schemaVersion": 1,
  "languages": [ { "code": "en", "name": "English" }, { "code": "af", "name": "Afrikaans" } ],
  "texts": {
    "title.play": { "en": "New game", "af": "Nuwe speletjie" },
    "hud.gold": { "en": "{gold} gold", "af": "{gold} goud" },
    "elder.hello": { "en": "Hello, Runefox." }
  }
}

A text a language lacks shows in the first language. A text can hold values ({gold}), filled in where it is shown, and may use the accented letters the fonts draw (see the Engine manual's Fonts); other characters are errors. Screens (.gwui), dialogue and quests name a text as {@title.play}; the asset check reports a name the table does not have, with its file and line. Problems name the text: runeglyph.gwtext: "only.af" has no English text (the first language's text is the one every row needs).

Input actions: name.gwinput#

A game's input actions, named by "actions" in glyphweft.json:

{
  "schemaVersion": 1,
  "actions": {
    "up": { "keys": ["W", "Up"], "about": "Walk up" },
    "act": { "keys": ["Z", "Space", "Enter"], "about": "Talk, read on, choose" }
  }
}

An action the game's code also defines (Actions.Define) keeps the file's keys. Problems name the action: game.gwinput: action "jump": 'Spcae': 'Spcae' is not a key or mouse button (...).

Screens: name.gwui#

A menu or HUD of the engine's glyph widgets. C# binds the actions its buttons name and sets the values its text and bars show; nothing in a layout runs code.

{
  "schemaVersion": 1,
  "overlay": true,
  "back": "resume",
  "values": { "gold": 0 },
  "widgets": [
    { "type": "label", "anchor": "topRight", "at": [1, 1], "text": "{gold} gold" },
    {
      "type": "panel",
      "anchor": "center",
      "size": [30, 0],
      "padding": [2, 1, 2, 1],
      "title": "Paused",
      "children": [
        {
          "type": "stack",
          "size": [26, 0],
          "children": [
            { "type": "button", "text": "Back to the game", "action": "resume", "primary": true },
            { "type": "button", "text": "Quit the game", "action": "quit" }
          ]
        }
      ]
    }
  ]
}

Every widget has a type and may have:

and the fields of its kind:

In text, tooltip, art, icon, count and hint, {name} shows a value and {name:format} formats a number (.NET formats: {life:0%}, {gold:N0}). A field a kind does not take is an error, said with where it is: hud.gwui: widgets[2].children[0] "play": a button has no "value" (it takes name, anchor, ...).

Saves: name.gwsave and name.gwinfo#

A save slot is two files in the player's folder for the game (saves/): the save, and its information for lists of saves. Both are written in the game's saves format: plain JSON, gzip-compressed JSON, or encrypted. A plain save:

{
  "schemaVersion": 1,
  "game": "glyphweft-walkabout",
  "info": { "title": "Day 1, 17:52", "saved": "2026-10-20T10:38:02Z", "playSeconds": 62.4, "detail": "clear, walking",
            "thumbnail": { "width": 48, "height": 20, "glyphs": [ "..." ], "colors": [ "..." ] } },
  "sections": {
    "world": { "tiles": [ { "x": 5, "y": 8, "type": "dirt" } ], "removed": [ { "kind": "oak", "x": 132, "y": 191 } ],
               "added": [ { "kind": "crate", "x": 140, "y": 215, "flipX": false } ] },
    "time": { "hours": 17.86, "day": 0 },
    "walkabout": { "actors": [ { "name": "hero", "pos": [140.5, 190], "facing": 4 } ], "torch": true, "zoom": 1, "played": 62.4 }
  }
}

• info.thumbnail: rows of glyphs, and rows of colours with 12 hex digits a cell (foreground, then background).
• A section is any JSON value the game wrote. The engine writes world (WorldChanges), time, weather, inventory, and for a simulation simulation (clock, random state, timers, entity ids) plus one section per component type (simulation.machine: entity ids as index, generation pairs, and the values in packed order).
• Values: [x, y] for vectors and points, [index, generation] for entity ids, "#RRGGBB" for colours.
• Compressed files are gzip. Encrypted files start with GWSE and a version byte, then a 12-byte nonce and a 16-byte AES-GCM tag, then the compressed JSON, encrypted with a key made from the game's passphrase and id (PBKDF2, SHA-256, 100,000 rounds).
• The previous save of a slot is kept as name.gwsave.bak.

Asset packs: assets.gwpack#

An exported game's assets in one file beside it, written by the export (you do not edit it). The game reads it in place of its assets folder, and a folder given after it with --assets overrides its files (a patch). It is binary, little-endian:

• GWPACK, a version byte (1) and a flags byte (1 = encrypted).
• The number of files (32-bit), then for each: its asset path (a UTF-8 string after its length, 7 bits a byte), where its data starts in the file (64-bit), how many bytes of data it has (32-bit) and how long the file is (32-bit).
• Then the data, file after file. Each file is deflated; encrypted, it is a 12-byte nonce, a 16-byte AES-GCM tag and the cipher text, with the asset path as associated data. The key is the SHA-256 of glyphweft pack, a zero byte and the game's id, so encryption stops casual copying, not a determined person.

Asset paths are not case-sensitive. A pack that is not one, an unsupported version, an encrypted pack opened without a key and a file the key does not open are reported with the pack's name.

The player's settings: settings.json#

In the player's folder for the game. Every field is optional; the ones present replace the game's settings.

{ "schemaVersion": 1, "window": [1600, 900], "fullscreen": false, "vSync": true, "pixelScale": 1,
  "audio": { "master": 0.8, "music": 0.5, "sfx": 1, "ambient": 0.8, "ui": 0.8, "mute": false },
  "input": { "attack": ["Space", "MouseRight"] }, "language": "af" }

language is the language the player chose, a code of the game's texts; without it (or when the texts no longer have it) the game shows their first language.

Project settings: glyphweft.json#

See the Engine manual.

Studio projects: Name.gwproject#

How Glyphweft Studio opens a game. It is named after the game (RuneCrawler.gwproject) and sits next to the game's .csproj and its glyphweft.json; a project folder has exactly one.

{
  "schemaVersion": 1,
  "name": "RuneCrawler",
  "game": "RuneCrawler.csproj",
  "assets": ["../../samples/assets", "assets"],
  "startupScene": "TitleScene",
  "platforms": ["win-x64", "linux-x64"]
}

Checking a project reports, naming the file: an empty name or startup scene, a game that is not an existing .csproj, missing asset folders, unknown platforms, and a missing glyphweft.json.

Input scripts: .gws#

See the Engine manual.