Skip to content

Budgets

The DS has 4 MB of main RAM, shared by code, static data, heap and stack (see DS memory). That is hard rule 3: a change that breaks a budget is not done. Two things make it bite harder than on most consoles:

  • Code sits in RAM. Every move, ability and item effect is compiled into the ARM9 binary, which is loaded whole. Code size is the largest single risk of the project (plan 00).
  • Content is never dropped to fit, and creators are never asked to use a toolchain to save memory. The answer to a budget problem is to optimise: smaller code, data read on demand, memory shared between modes (plan 09).

So the RAM is divided in advance, each subsystem has its share, and each share is measured.

Main RAM (plan 00, “RAM budget”):

Use Budget Last measured Where measured
Code and static data (ARM9 binary) 1.5 MB (1,572,864 bytes) 1,030,304 bytes, 65.5 % cargo xtask size for task 46b, 2026-11-15
Heap: world (map chunks, objects, scripts) 512 KB 123,101 bytes peak (the demo); 339,478 (an imported game’s outdoor world, walking across a zone border) profile-nds over demo part 1 (task 17g, 2026-11-13); task 28f
Heap: battle 256 KB 116,892 bytes peak profile-nds, task 17g
Heap: UI, text, save buffer 256 KB not reported separately
Heap: asset staging (data on its way to video memory) 512 KB 169,276 bytes peak profile-nds, task 17g
Audio (the sound bank in RAM): music 320 KB, the rest effects, cries and tables 512 KB 85,488 bytes for the sample; imported games 77 to 88 % tasks 13d, 25p, 32b
Stack and slack about 450 KB deepest stack mark 11,016 of 15,808 bytes profile-nds, task 17g

All heap tags together peaked at 411,394 bytes, at the demo’s first battle (task 17g).

Other limits that act as budgets:

Limit Value Why
Frame time one 60 Hz frame a tick Logic runs at 60 ticks a second. Worst steady tick in the demo: 40 % of a frame; frames are lost only on ticks that read files (an area arriving, a battle starting)
Zone crossing under one frame Measured at 14 ms on DS after the crossing stopped reading files (decision 276)
Polygons 2,048 a frame (MAX_POLYS), warning at 1,800 The DS 3D hardware’s limit. The demo keeps at most 214
Video memory 656 KB in fixed regions The DS’s banks; see rendering
pl-battle share of code 900 KB of the 1.5 MB Plan 09’s planning figure for every modern effect
Battle data in RAM at most 12 species and 48 moves, about 1.5 KB Only the creatures in the battle are loaded
Script instructions 2,000 a script a tick A loop cannot freeze the game
Script module 32 KB of code The module’s offsets
Save 256 KB a copy, two copies in a 4-megabit flash The size of a DS save chip
Engine limits 4,096 maps, 63 people a map, 24 character sheets a map and 255 a game, 256 meshes a view The engine’s own call, held to the budgets above (decisions 179, 194)
Sound 16 channels, divided between music and effects The DS’s mixer

The limits a creator meets are explained for them in limits.

cargo xtask size (xtask/src/budget.rs) builds the DS program and reports the ARM9 binary’s code and static data against 1,572,864 bytes, and fails above it. It runs before every merge and in CI. --by-crate (xtask/src/sizes.rs) reads the linker’s map and nm to say which crate and which functions the bytes come from.

The DS build is set for size: Thumb code, opt-level = "z", fat LTO, one codegen unit, panic = "abort" ([profile.nds] in Cargo.toml). The build remaps paths so the size is the same on every machine.

Each change reports its size against the code it is merged onto. That is how growth is caught early: a task that comes in well over its plan’s estimate says so and names where the bytes went.

  • No core::fmt in size-sensitive paths; messages are string IDs.
  • No generics instantiated per effect; static tables of plain functions.
  • Cargo features leave out what a game does not use: online play, menu styles, test programs, the profiler (see architecture).
  • Battle effects share helpers and prefer data fields to handlers.

If that is not enough, plan 09 has two relief valves, neither needed so far:

  • Planned (plan 09): code overlays, as commercial DS games do: battle code and field code are never needed at once, so they could share an address range.
  • Planned (plan 09): effects loaded per battle: the parameter table and bespoke effects as data or bytecode in the pack, loaded for the battle’s participants only.

cargo xtask profile-nds (xtask/src/profile_nds.rs) builds the profiling ROM, plays recorded input in melonDS with no window, and turns its output into tables (xtask/src/profile.rs).

  • Heap by tag. Engine code names what it is allocating for: let _t = pl_prof::tag(Tag::World);. In the profiling ROM the allocator (crates/pl-nds/src/heap.rs) keeps the current tag in an 8-byte header in front of each allocation and counts per tag. Tags: other, world, battle, ui, staging, audio; Tag::BUDGETS holds plan 00’s limits, and the report puts each peak beside its budget.
  • Time by section. let _s = pl_prof::scope(Section::World); charges the rest of the block to a section: waiting, input, update, world, streaming, file reads, loading into video memory, building the frame, emitting geometry and so on. Time is exclusive: a tick’s sections add up to the tick. The clock is two chained hardware timers; the display’s line counter is read beside it, so a missed vertical blank shows.
  • Stack. The deepest timing mark, against the stack’s size.

Without the on feature, scope and tag are empty types with no Drop, so the calls compile to nothing and the shipping ROM pays nothing for them.

Sound memory is measured from the sound bank the build makes (task 25p’s measure): tables, the sample cache and the largest pair of music modules that may play together.

A plan states the cost of what it adds (code, RAM, frame time, video memory), as an estimate first, then measured by its tasks. Examples:

Plan Estimated cost
28 the world grid 6 to 10 KB of code; the matrix (8 bytes a slot) and at most two staged zones in the world heap
29 scenes 3 to 6 KB of code; under 64 bytes for the stack
30 script language 2 4 to 8 KB of code; about 2 KB a machine
42 presentation nothing on the DS from the GPU renderer: pl-gpu never builds for it

When a measurement passes the estimate by more than half, the task says so and where the bytes went, so the next change can decide whether to cut.