Reference
Limits and caps
Every size and count cap a mod author is likely to hit — table state, setup and manifest arrays, file trees, assets, and the mod draft text fields.
On this page9 sections
- Table state (TableSnapshot)
- The legacy mod-setup format
- Manifest and file-tree
- Setup options (manifest.setupOptions)
- Variants (manifest.variants)
- Game bots (manifest.aiModels, manifest.bots)
- The mod-project draft's raw text fields
- Table Scripting scene scripts — a different surface, included for completeness
- See also
Every hard numeric limit relevant to authoring a mod, gathered into one table. Each row names the field it bounds and the file:line it was verified against on 2026-07-27 — source wins if this page and the code ever disagree; treat a mismatch as a documentation bug, not a schema change to make.
Table state (TableSnapshot)#
The replicated, persisted state of a live table — what any mod, script or save file's objects collection
is bounded by, regardless of how the objects got there.
| Collection | Cap | Source |
|---|---|---|
objects |
5000 | tableObjects.ts, tableSnapshotSchema.objects |
zones |
500 | tableObjects.ts, tableSnapshotSchema.zones |
snapPoints |
1000 | tableObjects.ts, tableSnapshotSchema.snapPoints |
vectorLines |
10000 | tableObjects.ts, tableSnapshotSchema.vectorLines |
decals |
5000 | tableObjects.ts, tableSnapshotSchema.decals |
textLabels |
1000 | tableObjects.ts, tableSnapshotSchema.textLabels |
joints |
3000 | tableObjects.ts, tableSnapshotSchema.joints |
ui.elements |
2000 | tableObjects.ts, tableUiStateSchema.elements |
eventLog |
5000 | tableObjects.ts, tableSnapshotSchema.eventLog |
All nine are enforced by tableSnapshotSchema/tableUiStateSchema — a snapshot exceeding any of them fails
Zod parsing outright, on every peer, the same way. See Object state for
what each collection is.
Per-entity#
| Field | Cap | Source |
|---|---|---|
secretMetadata |
2 KB (2,048 bytes of JSON.stringify output, UTF-8) |
tableObjects/secretMetadata.ts, MAX_SECRET_METADATA_BYTES |
secretMetadata is the only per-entity field with a hard size cap; metadata has none, and both are bounded
in practice by the 5,000-entity ceiling above. The cap is deliberately an order of magnitude tighter than the
16 KB mod saved-data value cap, because saved data is one blob per mod while this rides on every entity of
every snapshot. Over the cap, the object fails schema validation — except on load, where
migrateTableSnapshot() prunes the field instead, so a hand-edited save cannot wedge a room. See
Object state.
The legacy mod-setup format#
| Field | Cap | Source |
|---|---|---|
templates |
500 | tableObjects.ts, modSetupSchema.templates |
objects (template references / inline definitions) |
500 | tableObjects.ts, modSetupSchema.objects |
These two belong to the legacy mod-setup setup-file format (templatesVersion/templates/objects),
not the modern edit-scene format every mod authored through Edit Mode produces today. See
Setup JSON for the distinction. The modern format's objects[] has no
separate array-level cap of its own beyond the overall setup-file byte limit below — it is bounded by size,
not count.
Manifest and file-tree#
| Field | Cap | Source |
|---|---|---|
assets[] (declared asset paths) |
2000 | modManifest.ts, MOD_MAX_DECLARED_ASSETS |
assetManifest[] |
2000 | modManifest.ts, modManifestSchema.assetManifest |
soundSets[] |
64 | modManifest.ts, modManifestSchema.soundSets |
Published file-tree files[] (modFileTreeSchema) |
2000 | modFileTree.ts |
Local draft files[] (modProjectDraftSchema, a separate schema — same number, coincidentally) |
2000 | modManifest.ts |
| Per-asset size | 50 MB (50 * 1024 * 1024 bytes) |
modManifest.ts; enforced twice more server-side — see Assets |
See Required and conventional files § the file-tree envelope
for the full ModFileEntry shape these counts bound, and Assets for the
allowlist the 50 MB cap applies alongside.
Setup options (manifest.setupOptions)#
The typed controls a mod declares for a host to answer before the table starts. Verified against
packages/shared/src/modManifest.ts and packages/shared/src/settingControls.ts on 2026-09-04.
| Field | Cap | Source |
|---|---|---|
setupOptions[] |
12 options | modManifest.ts, MOD_MAX_SETUP_OPTIONS |
setupOptions[].key |
1-64 chars, and must match /^[a-z][a-z0-9_]*$/ |
modManifest.ts, MOD_SETUP_OPTION_KEY_PATTERN |
setupOptions[].label |
1-80 chars | modManifest.ts, modSetupOptionSchema.label |
setupOptions[].help |
240 chars | modManifest.ts, modSetupOptionSchema.help |
setupOptions[].default (string form) |
2000 chars | modManifest.ts, modSetupOptionSchema.default |
setupOptions[].maxLength (text only) |
an integer from 1 to 2000 | modManifest.ts, modSetupOptionSchema.maxLength |
setupOptions[].options[] (select choices) |
32 choices | modManifest.ts, MOD_MAX_SETUP_OPTION_CHOICES (= settingControls.ts, PLUGIN_MAX_SETTING_OPTIONS) |
setupOptions[].options[].value / .label |
1-120 chars each | settingControls.ts, pluginSettingOptionSchema |
The option count and choice-count caps are the plugin-settings numbers reused rather than re-chosen, so a
control that moves between the two surfaces does not meet a different ceiling. Every one of these is enforced
by modManifestSchema, so a manifest over any of them fails registration outright.
The room's owner answers them in the lobby, under Game options, and the answers reach the mod as the
third argument of setup. See setupOptions.
Variants (manifest.variants)#
The set-ups one game pack can be offered in — see Game variants. Verified
against packages/shared/src/modVariants.ts and packages/shared/src/sceneEditor.ts on 2026-10-02.
| Field | Cap | Source |
|---|---|---|
variants[] |
12 variants | modVariants.ts, MOD_MAX_VARIANTS |
variants[].id |
1-40 chars, and must match /^[a-z0-9]+(?:-[a-z0-9]+)*$/; constructor and prototype are refused |
modVariants.ts, MOD_VARIANT_ID_MAX, MOD_VARIANT_ID_PATTERN, MOD_VARIANT_RESERVED_IDS |
variants[].name |
1-60 chars | modVariants.ts, modVariantSchema.name |
variants[].description |
240 chars | modVariants.ts, modVariantSchema.description |
variants[].players.min / .max |
an integer from 1 to 64 each, max >= min |
modVariants.ts, modVariantSchema.players |
Variants with differences recorded in setup.json (variants.deltas) |
12 | sceneEditor.ts, sceneVariantsSchema |
Entities one variant removes (deltas[id].removed) |
2000 ids | sceneEditor.ts, SCENE_VARIANT_MAX_OBJECTS |
Entities one variant adds or customises (deltas[id].objects) |
2000 | sceneEditor.ts, SCENE_VARIANT_MAX_OBJECTS |
A variant's own entity order (deltas[id].order) |
4000 ids | sceneEditor.ts, sceneVariantDeltaSchema.order |
A variant's own copies of scene keys (deltas[id].scene) carry the same caps as the top-level keys they
replace. The seat cap a variant's players.max allows is additionally bounded by the platform's ten seats.
Game bots (manifest.aiModels, manifest.bots)#
See Game bots. Verified against packages/shared/src/ai/aiModels.ts, bots.ts and
apps/web/src/mods/sandboxAiEvaluate.ts on 2026-10-02.
| What | Cap | Source |
|---|---|---|
aiModels[] |
4 models | aiModels.ts, MOD_MAX_AI_MODELS |
| One model file | 64 MiB | aiModels.ts, AI_MODEL_MAX_BYTES |
| All of a mod's models together | 128 MiB | aiModels.ts, AI_MODELS_MAX_TOTAL_BYTES |
| One file through the in-app Publish | 45 MiB — push a larger model with git | MOD_ASSET_MAX_PUBLISH_BYTES |
| Model graph nodes | 8,192 | AI_MODEL_MAX_NODES |
| Model parameters | 32,000,000 | AI_MODEL_MAX_PARAMS |
| Elements in one tensor — a stored weight, a declared shape, or any value the model computes when run | 16,777,216 (2^24) | AI_MODEL_MAX_TENSOR_ELEMENTS |
All the values a model computes in one run, added together (an int64 element counts twice; weights excluded) |
536,870,912 elements (2^29) | AI_MODEL_MAX_ACTIVATION_ELEMENTS |
| A model's batch limit — the most positions one call may carry | the largest batch up to 256 at which both caps above hold; worked out when the model is checked | onnxValidate.ts, runtime.maxBatch |
| One position's declared outputs | 8 MiB (float32) | AI_EVALUATE_MAX_OUTPUT_BYTES |
| Model descriptions and metadata | 8 KiB | AI_MODEL_MAX_METADATA_BYTES |
| ONNX opset / IR version | 11–21 / 6–12 | AI_MODEL_OPSET_RANGE, AI_MODEL_IR_VERSION_RANGE |
| Inputs, outputs per model | 8 each, 1–6 dimensions | modAiTensorSchema |
| Difficulties per model or per bot | 8 | modAiModelDifficultySchema, modBotDifficultySchema |
bots[] |
8 bots | bots.ts, MOD_MAX_BOTS |
| Bots seated at one table | 9, and never more than the free seats | bots.ts, ROOM_MAX_BOTS |
Positions per ai.evaluate call |
256, and never more than the model's batch limit | AI_EVALUATE_MAX_BATCH, runtime.maxBatch |
Input per ai.evaluate call |
4 MiB | AI_EVALUATE_MAX_INPUT_BYTES |
Output per ai.evaluate call (every declared output, float32, for the call's batch) |
8 MiB | AI_EVALUATE_MAX_OUTPUT_BYTES |
Time per ai.evaluate call |
2 s | AI_EVALUATE_BUDGET_MS |
ai.evaluate calls in flight per script |
4 | sandboxAiEvaluate.ts, AI_EVALUATE_MAX_CONCURRENT |
| How long a cancelled or timed-out call keeps its in-flight slot | until the host's work for it stops; at most the call's budget plus 1 s after it was cancelled | sandboxAiEvaluate.ts, AI_EVALUATE_SLOT_GRACE_MS |
| Time-budget overruns in a row before a model's batch is limited | 3 — then calls with more than half the overrunning batch are refused ai-budget-exceeded |
AiInferencePool.ts, AI_POOL_BUDGET_DEMOTE_AFTER |
| One bot turn | 30 s by default; a model difficulty's params.turnBudgetMs, kept between 250 ms and 5 min |
BOT_TURN_BUDGET_MS, botTurnCoordinator.ts |
| Failed bot turns in a row before the bot is paused | 3 | tableBots.ts, BOT_MAX_CONSECUTIVE_TURN_FAILURES |
bots.skipTurn reason |
200 characters | botTurnCoordinator.ts, BOT_SKIP_REASON_MAX_LENGTH |
The batch limit is per model. Most board-game networks keep the full 256: 15×15 and 19×19 boards with the
trainer's tiny, small and medium presets all do. A large tower gets less — 88 for a 19×19 board with 12 blocks
× 192 filters, 61 for 13 × 256 — because at a bigger batch its values would pass the caps above. A model over
those caps for a single position is refused at publish as
ai-model-shape-unbounded. A script is not told
its model's limit; a call above it fails ai-shape-mismatch, and the fix is a smaller batch.
The output cap works the same way: a model whose outputs for one position are over 8 MiB fails the manifest,
and a call whose batch would take its outputs over 8 MiB fails ai-shape-mismatch. AlphaZero chess's 4,673
outputs a position fit a full batch of 256; a shogi-sized policy of 11,259 moves runs at up to 186 positions a call.
The mod-project draft's raw text fields#
Separate from the file-tree caps above: modProjectDraftSchema (modManifest.ts) is the
server-persisted editor draft record for a mod-in-progress, and its three big text fields each have
their own independent byte cap (measured in JavaScript string length, effectively UTF-16 code units):
| Field | Cap | Source |
|---|---|---|
Manifest text (manifestText) |
1 MB (1,000,000 chars) | modManifest.ts |
Setup text (setupText) |
5 MB (5,000,000 chars) | modManifest.ts |
Script text (scriptText) |
2 MB (2,000,000 chars) | modManifest.ts |
These bound the draft's raw JSON/JS text while you are authoring — they are independent of, and looser than, the per-file 50 MB cap and the 2000-file tree cap above, which apply once content is committed to the file-tree representation for publish.
Table Scripting scene scripts — a different surface, included for completeness#
⚠ These three numbers belong to Table Scripting (the
TypeScript scripts authored in Edit Mode, attached to a scene or an entity) — not to a mod's own
entry.script, which has no dedicated source/compiled-length cap beyond the draft-level scriptText cap
above. Listed here because a scene's scripts travel inside the same edit-scene setup document a mod
publishes, so they are still a real limit a mod author can hit.
| Field | Cap | Source |
|---|---|---|
| Scene script source (author TypeScript) | 2 MiB (2,097,152 chars) | scripting.ts, SCENE_SCRIPT_MAX_SOURCE_LENGTH |
| Scene script compiled output (transpiled JS) | 4 MiB (4,194,304 chars) | scripting.ts, SCENE_SCRIPT_MAX_COMPILED_LENGTH |
| Scripts per scene | 64 | scripting.ts, SCENE_SCRIPT_MAX_COUNT |
See Sandbox limits for what else constrains a script beyond sheer size.
Data files a scene script reads (world.readData / world.readText)#
A scene script can read its own game's declared .json, .txt and .csv files at run time, which is how a game
keeps large reference data out of the script itself. See
world.readData for the declaration rule.
| Limit | Cap | Source |
|---|---|---|
| One file | 2 MiB (2,097,152 bytes) | scriptDataFiles.ts, SCRIPT_DATA_FILE_MAX_BYTES |
| Distinct files read per game's scripts per run | 16 MiB (16,777,216 bytes) | scriptDataFiles.ts, SCRIPT_DATA_SESSION_BUDGET_BYTES |
| Downloads in flight at once | 6 (further reads queue) | scriptDataFiles.ts, SCRIPT_DATA_MAX_CONCURRENT_FETCHES |
| One download | 30 s, then unavailable |
scriptDataFiles.ts, SCRIPT_DATA_FETCH_TIMEOUT_MS |
| Readable files | Those declared in assets or excludedAssets (each list at most 2000 paths) |
modManifest.ts |
Getting them into a project: the explorer's Import data files dialog (Upload, Upload folder…, or a drop) and
the agent tool asset_import (one file, or a whole local folder) share these import caps. See
Data files.
| Import limit | Cap | Source |
|---|---|---|
| One imported data file | 50 MB stored (written with a warning over 2 MiB, which scripts cannot read) | modDataFiles.ts, checkModDataFileContent |
| Files per import | 2,000 (an agent's folder import defaults to 500, maxFiles) |
modDataFiles.ts, MOD_DATA_IMPORT_MAX_FILES |
| Bytes per import | 128 MiB (an agent's folder import defaults to 64 MiB, maxBytes) |
modDataFiles.ts, MOD_DATA_IMPORT_MAX_TOTAL_BYTES |
| Folders never written by an import | top-level rules/, originals/, thumbnails/, screenshots/, media/, materials/, links/, attribution/ |
modDataFiles.ts, MOD_DATA_RESERVED_FOLDERS |
See also#
- Object state — what the nine
TableSnapshotcollections are. - Setup JSON — the modern vs. legacy setup-file formats these caps span.
- Required and conventional files — the file-tree envelope in full.
- Assets — the extension allowlist alongside the 50 MB per-asset cap.
- Manifest reference — every manifest field, including the capped arrays above.
- Mod scripting API —
TableSnapshot, the shape every collection cap on this page applies to. - Mod hooks and capabilities —
ModTurnStartPayload.actionLimit, a per-turn cap that is not on this page.
