Budgets
Overview
Section titled “Overview”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.
Measurements
Section titled “Measurements”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.
Code size
Section titled “Code size”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.
What keeps code small
Section titled “What keeps code small”- No
core::fmtin 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.
Heap, time and stack
Section titled “Heap, time and stack”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::BUDGETSholds 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.
Changes
Section titled “Changes”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.