nes-pascal

NES Runtime

English

The implemented runtime provides a small initialization sequence and a runtime-owned NMI handler for an NTSC NROM program. Its frame and controller APIs are:

nes.set_background_color sets the universal NES background palette color;
Palette APIs configure four background and four sprite palettes and queue runtime changes for VBlank;
nes.load_background uploads one configured raw nametable and its attribute table during initialization;
Background update APIs optionally maintain a confirmed tile shadow and queue at most four tile or attribute writes for each VBlank;
nes.run completes initialization, enables NMI and rendering at VBlank, and starts the frame-synchronized runtime phase;
nes.set_scroll atomically stages a fixed horizontal and vertical scroll pair for final NMI restoration;
nes.wait_frame waits for the volatile NMI frame counter to change;
nes.on_update statically registers one parameterless procedure for the main-thread frame loop;
nes.on_vblank statically registers one restricted, parameterless procedure for NMI VBlank work.
nes.controller_down, nes.controller_pressed, and nes.controller_released query stable state from standard controllers 1 and 2.
Hardware sprite primitives maintain 64 OAM entries in a page-aligned CPU shadow and upload them through NMI OAM DMA.
Metasprites compile PNG2CHR Studio frame metadata into PRG-resident component lists with one logical position and shared OAM ownership.
Sprite animation advances symbolic metasprite frame sequences on the frame-synchronized main thread.
Collision helpers provide point/rectangle predicates, sprite and metasprite bounds, and immutable background-tile collision lookup.
Random numbers provide deterministic bytes and inclusive, bias-controlled ranges with optional explicit seeding.
Game-state support documents the official enum, transition-helper, dispatcher, pause, game-over, and explicit-restart pattern.
nes.set_sprite_zero is the fixed, example-only OAM staging helper described in the controller documentation; it remains as a compatibility helper.

nes.load_background() and direct initialization palette commands belong before nes.run; palette calls in procedures or after nes.run are queued instead. nes.wait_frame may appear in main-block loops and conditionals after nes.run, but not in procedures. The only user code executed by NMI is the single statically validated VBlank callback, when registered.

See VBlank cycle budget for current worst-case runtime costs, available callback headroom, and scalability limits.

See Target platform for the generated ROM format and hardware initialization behavior. See CPU memory for the physical RAM limit, reserved regions, user capacity, and generated memory-map artifact.

This site is open source. Improve this page.