Skip to content

Memory

Memory is the DS’s tightest limit. A game made with PokeLoom has to fit its code, the part of the world around the player, a battle, menus, music and a save in 4 MB, and every picture on both screens in 656 KB of video memory. This page explains what those memories are and how the engine shares them out.

Memory Size Holds
Main memory 4 MB Code, data, everything loaded from the cartridge; shared by both processors
Video memory 656 KB in nine banks Textures, tiles, tile maps, sprite pictures, extended palettes
Palette memory 2 KB Each 2D engine’s 256 layer and 256 sprite colours
Sprite tables 2 KB Each 2D engine’s 128 sprite entries
Shared work memory 32 KB Fast memory either processor can be given
ARM7 memory 64 KB The sound and input processor’s own
Fast on-chip memory 32 KB + 16 KB The main processor’s tightly coupled memory, for hot code and the stack
Cartridge up to hundreds of MB Read-only game data, read in pieces as needed

The cartridge is large; main memory is small. So a DS game never loads everything. It reads what the current place, battle or menu needs, and frees it when it leaves.

The whole program sits in main memory: unlike a PC, there is no disk to page from. Every move, ability and item effect compiled into the game takes room there for the whole session. So does every buffer. That is why PokeLoom keeps budgets:

Use Budget
Code and static data 1.5 MB
The world: map pieces, people, scripts 512 KB
A battle 256 KB
Menus, text, the save buffer 256 KB
Pictures on their way to video memory 512 KB
Sound: the music playing, effects and cries 512 KB
Stack and slack about 450 KB

Each is checked: the code by cargo xtask size, the heaps by a profiling build that tags every allocation with the part of the engine that made it and reports the peaks. A change that breaks a budget is not finished. Last measured numbers are on Budgets.

A few rules follow from this, and hold everywhere in the engine:

  • Nothing is loaded “just in case”. Map chunks stream in as the player walks; a battle loads only the effects of the creatures in it; a cry is read from the cartridge when it is played.
  • No allocation every frame. Lists of things to draw are reused from frame to frame.
  • The stack is small (16 KB on the main processor), so large tables live on the heap, not on the stack.

Planned (plan 09): if the code grows past its budget, code overlays, as commercial DS games use: battle code and field code are never needed at once, so they can take turns in one region of memory, loaded from the cartridge when the game changes mode.

The DS’s 656 KB of video memory is not one block. It is nine banks of fixed sizes, and each bank can be connected to a few uses and not others. A game decides at run time which bank serves what, by writing a register per bank.

Bank Size May serve as
A 128 KB main screen layers or sprites, 3D textures
B 128 KB main screen layers or sprites, 3D textures
C 128 KB main or sub screen layers, 3D textures, ARM7 memory
D 128 KB main screen layers, sub screen sprites, 3D textures, ARM7 memory
E 64 KB main screen layers or sprites, texture palettes, layer extended palettes
F 16 KB main screen layers or sprites, texture palettes, extended palettes
G 16 KB main screen layers or sprites, texture palettes, extended palettes
H 32 KB sub screen layers, sub screen layer extended palettes
I 16 KB sub screen layers or sprites, sub screen sprite extended palettes

Any bank can also be mapped as plain memory for the processor to write into, which is how pictures get loaded: map the bank for writing, copy, map it back.

Two things follow:

  • The main screen can have far more than the sub screen. Banks A to G can all serve the main engine; only C, D, H and I can serve the sub engine. The 3D screen gets the big banks.
  • Textures compete with 2D. The 3D engine reads textures only from A to D and texture palettes only from E to G. Every bank given to textures is a bank the main screen’s layers and sprites cannot use.

In the 3D style every bank has one fixed job:

Use Banks Size
3D textures A, B, C 384 KB
Texture palettes F 16 KB (8,192 colours)
Top screen tiles and maps E 64 KB (1,024 tiles, 4 maps)
Top screen sprite pictures G 16 KB (512 tiles)
Lower screen tiles and maps H, I 48 KB (1,024 tiles, 4 maps)
Lower screen sprite pictures D 128 KB (1,024 tiles used)

That is all 656 KB. The desktop keeps arrays of the same sizes, so a picture that does not fit on the DS does not fit on desktop either.

Inside those banks an allocator hands out room as a scene loads, and a budget per kind of scene keeps a scene from taking more than its share:

Scene Textures Texture colours Top / lower tiles Top / lower sprite tiles
Field 256 KB 4,096 512 / 1,024 256 / 512
Battle 320 KB 2,048 1,024 / 1,024 512 / 1,024

Going over is a bug in the game’s content: ploom check reports a map whose textures and sprites pass 256 KB of texels, 4,096 palette colours (every light’s copy of a palette counts) or 256 textures, before the game runs.

The tile-map style draws no 3D, so on entering a 256-colour tile map the top screen takes the 3D engine’s banks: bank A becomes the top screen’s layer memory (1,024 tiles of 256 colours and 1,024 of 16), and bank E holds the layers’ extended palettes. Banks B, C and F are free. Leaving switches back. See GBA tile worlds.

Planned (plan 37): bank B as sprite memory for large set pieces, and a tile cache that streams a tile map’s tiles into bank A as the view moves, so a map’s art is limited per view rather than per map.

A desktop could hold all of it a thousand times over. Budgets exist so that a game that runs on desktop also runs on the DS, and so that a problem is found by a check at build time, with the name of the map and the number, not by a crash in the emulator an hour into play. Every limit a creator meets is listed on Limits.