# 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.

- Source: https://diceytable.com/docs/mods/reference/limits-and-caps
- Last verified: 2026-10-02

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](https://diceytable.com/docs/mods/reference/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](https://diceytable.com/docs/mods/reference/object-state#secretmetadata-the-place-for-a-secret).

## 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](https://diceytable.com/docs/mods/files/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](https://diceytable.com/docs/mods/files/assets#size-cap) |

See [Required and conventional files § the file-tree envelope](https://diceytable.com/docs/mods/files/required-and-conventional#the-file-tree-envelope)
for the full `ModFileEntry` shape these counts bound, and [Assets](https://diceytable.com/docs/mods/files/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`](https://diceytable.com/docs/mods/manifest/reference#setupoptions).

## Variants (`manifest.variants`)

The set-ups one game pack can be offered in — see [Game variants](https://diceytable.com/docs/mods/manifest/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](https://diceytable.com/docs/mods/concepts/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`](https://diceytable.com/docs/mods/scanner/what-gets-rejected#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](https://diceytable.com/docs/scripting/concepts/choosing-a-surface)** (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](https://diceytable.com/docs/scripting/concepts/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`](https://diceytable.com/docs/scripting-api/world#worldreaddata) 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](https://diceytable.com/docs/editor/interface/asset-explorer#data-files-json-txt-csv).

| 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](https://diceytable.com/docs/mods/reference/object-state) — what the nine `TableSnapshot` collections are.
- [Setup JSON](https://diceytable.com/docs/mods/files/setup-json) — the modern vs. legacy setup-file formats these caps span.
- [Required and conventional files](https://diceytable.com/docs/mods/files/required-and-conventional) — the file-tree envelope in full.
- [Assets](https://diceytable.com/docs/mods/files/assets) — the extension allowlist alongside the 50 MB per-asset cap.
- [Manifest reference](https://diceytable.com/docs/mods/manifest/reference) — every manifest field, including the capped arrays above.
- [Mod scripting API](https://diceytable.com/docs/scripting-api/api) — `TableSnapshot`, the shape every collection cap on this page applies to.
- [Mod hooks and capabilities](https://diceytable.com/docs/scripting-api/hooks-and-capabilities) — `ModTurnStartPayload.actionLimit`, a per-turn cap that is not on this page.
