Limits
A PokeLoom game runs on a Nintendo DS: 4 MB of RAM, a 67 MHz processor without floating point, 656 KB of video memory, a 3D engine that draws at most 2,048 polygons a frame. Every limit on this page comes from that machine. The desktop could do more, but a game must play the same on both (decision 310: graphical detail may differ, never logic, rules or content), so the DS’s limits are every game’s.
The engine’s rule is to optimise, never drop content: a limit is met by making things cheaper, not by cutting a map or a creature, and a creator never needs a special toolchain to save memory. So each limit is checked on your machine, with the file and the fix, before the game ever reaches a DS.
Checks
Section titled “Checks”| Check | Catches |
|---|---|
ploom check |
every map’s views, video memory, textures and pieces; the one height of people; text too wide; script errors; data errors |
ploom check --art |
every picture against the art contract (Art) |
ploom build |
the same errors; it writes no part it cannot convert and keeps the last good one |
| The script compiler | the language’s limits (below) |
cargo xtask size, profile-nds |
the engine’s own code size and heaps (contributors; Budgets) |
Screen
Section titled “Screen”What the DS limits is what it draws in one frame, not what a map holds. So ploom check takes every cell a character can stand on, lists what the game would draw there
with the map’s camera (pieces, ground, a card and a shadow for every character the map
starts with), and counts what is sent, what the DS keeps after dropping polygons that
face away or are off screen, and the meshes listed. The map’s line ends like this:
town.pfa: ... busiest chunk 305 polygons, busiest view sends 421 polygons and keeps 220 (camera on (28, 23)), most meshes in a view 53| Limit | Value | It is | Why |
|---|---|---|---|
| Polygons kept in a view | 2,048 | an error | the 3D engine draws no more in a frame |
| Vertices in a frame | 6,144 | (counted by the hardware) | the same |
| Meshes listed in a view | 256 | an error | the engine’s list of what to draw; the rest would be dropped without a word |
| Polygons sent in a view | over 1,800 | a note | sending takes time even for what is not kept |
| Polygons in one piece | over 310 | a note | far above what the style’s pieces cost |
Not counted: emotes, footprints and splashes, a door on its way open. The busiest chunk is information only, since a chunk is never drawn whole.
Video memory
Section titled “Video memory”A map’s textures share the field’s video memory with the sprites loaded with every map: the shadow, the character sheets, the emotes and the walking effects.
maps/town with the sprites in video memory: 66048 of 262144 bytes of texels, 784 of 4096 palette colours, 61 of 256 textures| Limit | Value | Why |
|---|---|---|
| Texels | 256 KB | the share of the DS’s texture banks the field takes |
| Palette colours | 4,096 | the share of texture palette memory the field takes |
| Textures at once | 256 | the engine’s books of video memory |
| Texels in a battle | 320 KB | the battle scene and creatures |
Palette colours are counted as video memory holds them: each texture keeps one copy of its palette for every light its materials take (the sun, the lamp, the constant light), and each copy takes at least 8 colours. A 4-colour texture costs 8; a 16-colour window under the sun and the lamp costs 32. Fewer lights on one texture, or 16-colour textures in place of 256-colour ones, are the usual fixes.
Models and pictures
Section titled “Models and pictures”| Limit | Value | Why |
|---|---|---|
| A model’s reach from its origin | under 8 cells; 16 or more across is an error | a DS vertex is a 16-bit number with 12 bits of fraction |
| Faces | triangles and quads | the DS draws no others |
| Texture sides | 8, 16, 32, 64, 128, 256, 512 or 1,024 | the DS’s texture sizes |
| Colours of a texture | 4, 16 or 256 from a palette; 32 or 8 with opacity levels | the DS’s texture formats |
| Steps of a moving texture | 18 | the animation table |
| Moving textures a map | 16 | each is rewritten in video memory as it moves |
Characters
Section titled “Characters”| Limit | Value | Why |
|---|---|---|
| A sheet | 128 × 128, sixteen 32 × 32 frames | one layout for every character |
| A standing figure | 24 rows, feet on row 29 | one height for every person (decisions 123, 133) |
| Character sheets a map loads | 24, the player’s included | video memory, shared with the map |
| Character sheets a game | 255 | a sheet’s number is 8 bits |
| People on a map | 63, the player not counted | the world’s table of characters |
| Trainer picture | what is drawn at most 64 × 80 | the sprites the battle reserves |
| Creature picture | 96 × 96 after trimming | the same |
| Limit | Value | Why |
|---|---|---|
| Maps a game | 4,096 | map numbers in warps and saves |
| Chunk | 32 × 32 cells, at most 4 loaded | the world heap |
| Heights | half levels to 31½ | the cell’s height field |
Scripts
Section titled “Scripts”The script compiler refuses a script over these.
| What | Limit |
|---|---|
| Code in one file | 32,767 bytes |
| Text in one file | 65,535 bytes |
| Values at once in one expression | 16 |
call depth (procedures too) |
16 |
| Temporaries of one script | 16, and 64 words with its procedures’ frames |
| Entries of an array | 255 |
| Text registers | 8, of 64 bytes each |
| Saved flags | 4,096 |
| Saved variables | 512 |
| Map-local flags and variables | 64 and 32 |
| Scripts running at once | 4 |
| Actors moving by lists at once | 8 |
on sight events in a map |
32 |
| Entries in one movement list | 255 |
| A game’s currencies besides money | 8 |
Not in the language: decimals, data structures beyond arrays. A game that needs more adds commands in Rust (Rust extensions). The full list is in the scripting guide.
| Limit | Value | Why |
|---|---|---|
| A line of talk | 216 pixels | the talk box’s text area, 27 tiles |
A name in a line ({player}, {var:N}) |
counted as 72 pixels | twelve letters of 6 pixels, so any name fits |
| A glyph | 16 pixels wide at most | the font format |
The build checks every line against the box and refuses one that is too wide, naming
the line and its key. wide_text = "cut" in [text] turns that into a note and lets
the box cut the line, for text written for other windows, as an import’s is. The build
also refuses a font missing a character the text uses (Text).
Tile-map style
Section titled “Tile-map style”| Limit | Value | Why |
|---|---|---|
| Different tiles a map | 1,024, 512 a tileset | the tile memory the top screen’s layers read |
| Palettes a map | 16, of 255 colours and clear | the DS’s extended palettes |
| Metatiles | 512 a set, a primary and a secondary | the cell’s metatile number |
| Sprites a screen | 128 | the DS’s sprite table |
Planned (plan 37): a tile cache, so a map may hold any number of different tiles and only what one view shows must fit. Details are on The tile-map (GBA) style.
Sound and memory
Section titled “Sound and memory”The DS’s 4 MB are split into budgets that the engine is held to (Budgets):
| Budget | Size |
|---|---|
| Code and static data | 1.5 MB |
| World heap (map chunks, objects, scripts) | 512 KB |
| Battle heap | 256 KB |
| Interface, text and save buffer | 256 KB |
| Asset staging (data on its way to video memory) | 512 KB |
| Sound bank | 512 KB, of which music 320 KB |
For a creator, the sound bank is the one you fill directly: music and effects go into it, and long effects are stored compressed on DS. A game’s data never lives in RAM all at once; maps, text banks and pictures are read from the cartridge as needed.
Planned (plan 46): a game’s own Rust may use 128 KB of the code budget and 64 KB of
heap; ploom build nds reports each part’s bytes and refuses a game past the whole
program’s budget.