Character format version 1

A guide to the character file format read by mascot_read_character() and mascot_check_character(). Descriptions are JSON objects with format_version = 1, id, name, description, a family, colours, ground, parts and five shared moods (idle, thinking, happy, worried, celebrating). Optional anchors, palettes, face kits and gestures describe their own supported names. Palette ids cannot be original or the reserved style aliases minimal, pastel, vivid, corporate, earthy and night. Small sizes may hide details the character marks for small sizes. Text is displayed as text, never HTML.

Details

Start from system.file("examples", "characters", "study_bot.json", package = "mascot"). To change a character, edit the plain list or JSON source and check it again; a checked object cannot be edited. A source file names its family and gives that family's definition in family_definition (id, name, description and optional defaults, such as shared gestures and palettes); a custom character cannot take a definition from the installed package. A resolved file has its family defaults merged in and embeds its face kits, so it does not depend on the installed package. A source file that names a shipped face kit (classic or screen) draws with that kit as installed; a change to a shipped kit's drawing is listed in NEWS.

Drawing coordinates are design units in a 300 by 300 frame. The point where the character stands on the ground is (0, 0): 150 units from the left edge and 270 from the top. y grows downwards, so a part above the ground has a negative y. Every part, movement and effect must stay inside the frame at every detail size.

Capabilities and `requires`

Every version-1 mascot can draw the eight version-1 capabilities: parts, paints, clip, outline, glow, face_kit, tracks and lod. A file does not need to ask for them, so it needs no requires field. requires lists only capabilities added after version 1. A file that lists the version-1 names still loads. A name this version of mascot does not know, or a reserved one, stops the check with an error that names it and says to update mascot. Unsupported and reserved capabilities used as keys (such as connector or morph) are refused too.

Keys for other tools

A top-level $schema string is accepted and kept, so an editor can link the file to a schema. mascot never reads it.
A key that starts with x_, in any object whose fields the format fixes (the character itself, a part, an item, a mood, a gesture, a face and so on), is an extension key. Its value can be any JSON value (from R, a list or an unnamed vector; a data frame or a named vector is refused). It is kept as written when the character is checked, resolved and saved, and it is never read; it counts towards the file's size, depth and node limits. Resolution keeps the character's own extension keys; those of a family's defaults object stay in the resolved family snapshot. In an object whose keys are ids or names (colours, moods, gestures, palettes and the other maps), a key that starts with x_ is an ordinary id.
A note string, accepted in every fixed-field object, is a comment.

Diagnostics

Checks stop at the first problem, giving a diagnostic code, the JSON path and a repair instruction, and the value where one is at fault. A value outside its range or choices is named with the range or the choices. A drawing budget gives the band, the count and the limit; a character too big for its frame names the part, face, effect or shadow that reaches furthest outside, the side and by how much. The limits on input bytes, depth and node count, and the drawing budgets, apply to every input form. The format version, the capability set and the version of the input and drawing limits can each change on their own. The installed files are in system.file("format", package = "mascot"): character-v1.json describes the allowed fields, types and values; policy-v1.json holds the input limits, the capability names and the drawing budget of each detail band.

Compatibility

The format is experimental and its future direction is open; these points hold either way. Additions (new optional keys, wider ranges, new categories) stay in format version 1, so existing files keep working. A file that uses an addition lists it in requires, and an older version of mascot then stops with an error naming it instead of drawing it wrongly. Only a change that would break existing files introduces format version 2; retiring an older format version is announced in NEWS at least one release ahead. The checker may only get stricter in a new format version, except for a documented security or resource-safety fix, which comes with a diagnostic and migration guidance. Files are never modified or upgraded silently. A resolved file is self-contained.

Experimental

Experimental What the format accepts may grow in a later release; version-1 files keep loading (see Compatibility).

Examples

# Start from the bundled source, give the copy its own id, then check it again.
path <- system.file("examples", "characters", "study_bot.json", package = "mascot")
source <- jsonlite::read_json(path)
source$id <- "my_bot"
source$name <- "My Bot"
source$colours$body <- "#2a9d8f"
bot <- mascot_check_character(source)
bot
#> my_bot: My Bot (visorfolk)
#> Moods: idle, thinking, happy, worried, celebrating
#> Gestures: rock, nod, wave, greet
#> Detail overrides: micro
#> From: object
ui <- mascot("helper", character = bot)