yoshida yoshida DEV
Open the editor

Docs Format

Limits and Versioning

On this page

Limits

WhatLimitCan be raised withError
Visible layers drawn per card, after repeat expansion (checked per card)500YOSHIDA_MAX_LAYERS5001
Iterations of one repeat1000YOSHIDA_MAX_REPEAT5001
Canvas10000 x 10000 pixelsYOSHIDA_MAX_CANVAS5001
Rendered image at an export resolution (canvas x resolution)10000 pixels per sideYOSHIDA_MAX_CANVAS5001
Image size50 megapixelsYOSHIDA_MAX_IMAGE_MP4002
Cards per set10000YOSHIDA_MAX_SET_CARDS5001
Group nesting16 levelsfixed5001
Nesting inside one expression200 levelsfixed3001
Text made by a function10000 bytesfixed3106
Sheet (yoshida render --sheet)20000 pixels per side, 400 megapixelsfixedCLI error
Server: cards per render request1000 by default (--max-cards)YOSHIDA_MAX_CARDSHTTP 413
Server: request body200 MB by default (--max-body-mb)YOSHIDA_MAX_BODY_MBHTTP 413

Only visible layers count toward the layer limit: every visible repeat iteration is one layer, hidden layers and hidden iterations are free, and a visible group counts as one plus its visible layers. The limit depends on card data, so it is evaluated per card: yoshida check (and Check all in the editor) evaluates every card and reports the cards over it, naming the layers that use most of the budget. When rendering such a card, the layers up to the limit are drawn, the PNG is written and marked as written with errors, and the run exits with status 1. See Repeat.

Exports at a higher resolution (the editor's export dialog, yoshida render --scale, the server's "scale") render the canvas that many times larger, and the rendered image must stay within the canvas limit too: with the default, a 4961 x 3508 canvas can be exported at 2x (9922 x 7016) but not at 3x. A card over it is not drawn and gets error 5001; the export dialog disables those resolutions. SVG files and vector PDFs are not bound by it: they use the resolution only for the parts that stay pixels, which are drawn at a lower resolution when the area is very large.

Raising a limit

The defaults suit cards and keep a mistake (a repeat over the wrong list, a canvas in the wrong unit) from using all memory. A project that needs more can raise them with environment variables. Each takes a whole number of 1 or more, or the word unlimited; leaving it unset or empty keeps the default. Anything else is refused when the program starts, with a message that names the variable.

VariableDefaultCountsunlimited means
YOSHIDA_MAX_LAYERS500Visible layers drawn per cardNo limit
YOSHIDA_MAX_REPEAT1000Iterations of one repeatNo limit
YOSHIDA_MAX_CANVAS10000Pixels per side of the canvas and of an exported image65535 pixels per side
YOSHIDA_MAX_IMAGE_MP50Megapixels of one image fileNo limit
YOSHIDA_MAX_SET_CARDS10000Cards in one setNo limit
YOSHIDA_MAX_LAYERS=2000 yoshida check my-game
YOSHIDA_MAX_LAYERS=unlimited YOSHIDA_MAX_REPEAT=5000 yoshida render my-game

Who reads them:

  • The command line (yoshida check and yoshida render), from the environment it is started in.
  • The server, from its environment or, with Docker Compose, from .env (Server and Docker). It prints the limits that differ from the defaults when it starts and lists them all in /api/capabilities.
  • The editor has no environment. Served by a yoshida server, it takes that server's limits when it starts, so the editor and Render on server accept the same designs. Opened from plain files or from the project's website, it keeps the defaults.

A variable can also lower a limit, for a shared server.

What a higher limit costs. Every layer is drawn, so render time grows with the number of layers; a card with 5000 layers takes about ten times as long as one with 500. A bitmap needs 8 bytes per pixel while it is drawn: 800 MB for 10000 x 10000, 3.2 GB for 20000 x 20000. An image file needs 4 bytes per pixel once decoded. With unlimited nothing stops a design from asking for more memory than the machine has; the render then fails with an out-of-memory error. The editor runs in the browser, which gives one page at most 4 GB: a bitmap of more than about 268 megapixels (16384 x 16384) is refused there with error 5001 whatever the limit says. Projects that rely on raised limits only work where the limits are raised, so note them in the project's README.

What stays fixed. Group nesting (16) and nesting inside an expression (200) guard the program's own stack, so removing them could crash it. The length of text made by a function and the sheet size are not configurable yet.

The server's --max-cards and --max-body-mb are limits of one request, separate from the limits of a design.

Versioning

format is an integer in every JSON file. These docs describe format 1, implemented by yoshida 0.8.0.

  • Adding optional fields with defaults does not bump the version. Fields added within format 1 so far: canvas.dpi, canvas.bleed, consts, functions, group repeat and translate, text stroke and shrink_group, stroke dash and arrow, ellipse arc, polygon shape, enum list item fields and item field defaults, list changes by position in card data, @layer[n] references. Older yoshida versions report the new fields as unknown (error 1101).
  • A new major format version comes with a migration in the core. A file with a format the tool does not know is error 1105.
  • The format version is printed by yoshida version.
  • A planned yoshida migrate command (rewrite files in place and keep everything else byte-identical) is not implemented yet: version 1 is the only version, so there is nothing to migrate.

Ideas that are not in format 1 (rich text, shared design parts via include, per-card layer overrides) are listed in Known Gaps.

↑↓ to moveEnter to openEsc to close