Doxygen lists the SDK by module, which only helps once you know the module's name. This page goes the other way: what you want → what to use → an example that does it.
It exists because that gap has a cost. While writing the RPG template the author re-implemented collideTile() by hand, wrote a sprite-culling helper without noticing oamHide(), hand-rolled scene switching without noticing <snes/scene.h>, and missed examples/maps/tiled — which already demonstrates the Tiled pipeline. All four were in the tree. If you are about to write a helper, scan this page first.
Modules are opt-in: add the name to LIB_MODULES in your Makefile and nothing you do not list is linked.
Getting something on screen
| I want to… | Use | Module | Example |
| print text | textInit, textPrintAt, textFlush | text | text/print_string |
| show a background from a PNG | bgInitTileSet, bgSetGfxPtr, bgSetMapPtr | background | backgrounds/mode1 |
| bundle a tileset + its palette as one thing | BgAsset, DECLARE_BG_ASSET, bgLoad | asset | backgrounds/mode1 |
| draw a sprite | oamInit, oamSet, oamUpdate | sprite | sprites/simple_sprite |
| hide a sprite that left the screen | oamHide | sprite | games/rpg |
| animate a sprite | AnimClip, animPlay, animTickOam | anim | sprites/animated_sprite |
| draw one character out of many tiles | oamDrawMetasprite, MetaspriteItem, MetaspriteStyle | sprite | sprites/metasprite |
| make a tile while the game runs (procedural art) | tileEncode2bpp, tileEncode4bpp, tileEncode8bpp | tile | sprites/sprite_swarm |
| compose text at the pixel in a 2bpp layer (a proportional font, a label at any x and y) | tileBlitGlyph2bpp | tile | sprites/sprite_swarm |
Moving around a world
Input
Structuring a game
Sound
Effects
Moving data around
| I want to… | Use | Module | Notes |
| upload tiles or a tilemap | dmaCopyVram | dma | VBlank fits ~4 KB; more needs setScreenOff() |
| upload a palette | dmaCopyCGram | dma | the source may live in any bank |
| set one colour | setColor | console | sprite palettes start at CGRAM 128 |
| cycle a palette (waterfall/fire/lights) | setColor, dmaCopyCGram | dma | color/palette_cycle — animate with zero VRAM traffic |
| darken or colour-cast a whole scene (night/underwater/sunset) | colorMathShadow, colorMathTint | colormath | color/shadow_tint |
| draw a HUD / dialog box (9-slice) | panelInit, panelDraw, panelPut, panelFlush | panel | basics/panel_hud |
| structure a whole game (title/play/over) | frame loop + switch(state) | — | basics/game_skeleton |
| scroll each column independently (flag ripple, heat-haze) | offset-per-tile, setMode(BG_MODE2) + BG3 offset table | background | backgrounds/mode2 |
| send several small VRAM uploads in one VBlank (streamed sprite frames, map rows and columns) | vramQueuePush, vramQueuePushSprite, vramQueueFlush | vramqueue | DMA: several small uploads |
| place the sprites of a scrolling game (world coordinates, camera, culling) | oamPlaceWorld, OamWorldBatch | sprite | sprites: a scrolling game's sprites |
| move many sprites at once | oamMemory, oam_update_flag, oamSetFast | sprite | sprites/sprite_swarm — and its 60fps ceiling |
| decompress | lzssDecodeVram | lzss | |
| copy, fill or compare memory and strings | memcpy, memmove, memset, strlen, strcmp, strcpy, strncpy | string | FAR RAM: copying |
3D math on the DSP-1 coprocessor
Going faster
| I want to… | Use | Notes |
| more CPU | SA-1 (USE_SA1=1) | same 65816 ISA at 10.74 MHz — tutorial |
| polygons | Super FX (USE_SUPERFX=1) | GSU assembly only, no C compiler |
| fixed-point maths | fixed32.h | |
The rest, by header
Functions the tables above do not name, each with the page that shows it in use. Anything not listed here or above is in the Doxygen reference of its header.
| Header | Functions | Where it is explained |
| anim.h | animRestart | animation |
| audio.h | audioPlaySampleOn, audioStopVoice, audioStopAll | audio: choosing the voice |
| audio.h | audioSetVolume, audioGetVolume, audioSetVoiceVolume, audioSetVoicePitch | audio: volume and pitch |
| audio.h | audioSetADSR, audioSetGain | audio: ADSR or GAIN |
| audio.h | audioSetEcho, audioSetEchoFilter, audioEnableEcho, audioDisableEcho | audio: echo |
| audio.h | audioIsReady, audioGetFreeMemory, audioGetVoiceState | audio: asking the engine |
| background.h | bgInitTileSetData, bgInit | graphics |
| collision.h | rectSetPos, rectGetCenter | collision |
| colormath.h | colorMathSetChannel, colorMathSetBrightness, colorMathTransparency50, colorMathSetDirectColor | colour math |
| console.h | rngNext, rngSeed | math: random numbers |
| console.h | resetFrameCount | animation |
| console.h | isInVBlank | DMA |
| debug.h | consoleMesenBreakpoint, consoleNocashMessage (behind SNES_BREAK, SNES_NOCASH) | debugging |
| hdma.h | hdmaColorGradient, hdmaColorGradientStop, hdmaBrightnessGradientStop, hdmaIrisWipe, hdmaIrisWipeStop, hdmaWaterRipple, hdmaWaveInit, hdmaWaveStop, hdmaWindowShape, hdmaGetEnabled, hdmaDisableAll | HDMA: ready-made effects |
| input.h | padIsConnected | input: is a pad plugged in? |
| input.h | mouseInit, mouseIsConnected, mouseGetX, mouseGetY, mouseButtonsHeld, mouseButtonsPressed, mouseSetSensitivity, mouseGetSensitivity | input: the mouse |
| input.h | scopeInit, scopeIsConnected, scopeGetX, scopeGetY, scopeGetRawX, scopeGetRawY, scopeButtonsHeld, scopeButtonsPressed, scopeButtonsRepeat, scopeSetHoldDelay, scopeSetRepeatDelay, scopeSinceShot | input: the Super Scope |
| interrupt.h | nmiSet, nmiClear, irqSet, irqClear, irqSetHTimer, irqSetVTimer, irqEnable, irqDisable | interrupts |
| math.h | easeInQuad, easeOutQuad (module math_ease) | math: easing curves |
| profile.h | profileGetScanline | profiling |
| snesmod.h | snesmodGetPosition, snesmodFlush | audio: following the music |
| sprite.h | oamSetX | sprites |
| superfx.h | gsuIsPresent, gsuSetupBitmapTilemap, gsuDmaFullFrame, gsuSetupHdmaBlanking, gsuCacheLoad, gsuStartCached, gsuBusy, gsuWait | Super FX |
When something silently does nothing
The SNES fails quietly. KNOWN_LIMITATIONS.md is the catalogue; the ones that cost the most time:
| Symptom | Likely cause |
| a VRAM upload partly lands | outside VBlank/forced blank, or over the ~4 KB budget |
| the screen stays black after a DMA | setBrightness(0) is not forced blank — use setScreenOff() |
| a sprite renders as background garbage | oamInit's second argument is a page number 0-7, not an address — use OBJ_NAME_BASE(addr) |
| a sprite appears where no entity is | off-camera OAM coordinates wrap — oamHide() it |
| a const array reads as garbage | it spilled past bank $00; the build's bank-blind check should catch it |
| colours shift when you add a tile | gfx4snes re-quantises the whole palette — author a fixed palette |
Keeping this page honest
Example paths here are checked by devtools/check_doc_drift.py, so a renamed or deleted example fails make lint-docs. Function names are not checked — if you rename a public function, grep this file.
1.16.1