nes-pascal

Building and running programs

English

Português (Brasil)

Compilation

Compile the minimal example with:

python -m nes_pascal.cli examples/minimal.nsp -o build/minimal.nes

The repository also contains focused examples for each implemented language area:

python -m nes_pascal.cli examples/arithmetic.nsp -o build/arithmetic.nes
python -m nes_pascal.cli examples/boolean_expressions.nsp -o build/boolean_expressions.nes
python -m nes_pascal.cli examples/conditionals.nsp -o build/conditionals.nes
python -m nes_pascal.cli examples/loops.nsp -o build/loops.nes
python -m nes_pascal.cli examples/counting.nsp -o build/counting.nes
python -m nes_pascal.cli examples/arrays.nsp -o build/arrays.nes
python -m nes_pascal.cli examples/enumerations.nsp -o build/enumerations.nes
python -m nes_pascal.cli examples/records.nsp -o build/records.nes
python -m nes_pascal.cli examples/procedures.nsp -o build/procedures.nes
python -m nes_pascal.cli examples/procedure_parameters.nsp -o build/procedure_parameters.nes
python -m nes_pascal.cli examples/functions.nsp -o build/functions.nes
python -m nes_pascal.cli examples/memory_layout.nsp -o build/memory_layout.nes
python -m nes_pascal.cli examples/zero_page.nsp -o build/zero_page.nes
python -m nes_pascal.cli examples/frame_synchronization.nsp -o build/frame_synchronization.nes
python -m nes_pascal.cli examples/frame_callbacks.nsp -o build/frame_callbacks.nes
python -m nes_pascal.cli examples/slow_update_callback.nsp -o build/slow_update_callback.nes
python -m nes_pascal.cli examples/controller_input.nsp -o build/controller_input.nes
python -m nes_pascal.cli examples/sprite_support.nsp -o build/sprite_support.nes --chr assets/chr_asset.chr
python -m nes_pascal.cli examples/metasprite_player.nsp -o build/metasprite_player.nes --chr assets/game.chr --metasprite assets/player_idle.json
python -m nes_pascal.cli examples/metasprite_clipping.nsp -o build/metasprite_clipping.nes --chr assets/game.chr --metasprite assets/player_idle.json
python -m nes_pascal.cli examples/sprite_animation.nsp -o build/sprite_animation.nes --chr assets/game.chr --metasprite assets/player_consolidated.json
python -m nes_pascal.cli examples/chr_asset.nsp -o build/chr_asset.nes --chr assets/chr_asset.chr
python -m nes_pascal.cli examples/palette_support.nsp -o build/palette_support.nes --chr assets/chr_asset.chr
python -m nes_pascal.cli examples/nametable_loading.nsp -o build/nametable_loading.nes --chr assets/chr_asset.chr --nametable assets/nametable_loading.nam
python -m nes_pascal.cli examples/background_updates.nsp -o build/background_updates.nes --chr assets/chr_asset.chr --nametable assets/nametable_loading.nam
python -m nes_pascal.cli examples/scrolling_ppu_state.nsp -o build/scrolling_ppu_state.nes --mirroring horizontal
python -m nes_pascal.cli examples/collision_rectangles.nsp -o build/collision_rectangles.nes --chr assets/game.chr --metasprite assets/player_idle.json
python -m nes_pascal.cli examples/collision_background.nsp -o build/collision_background.nes --collision-map assets/collision_map.cmap
python -m nes_pascal.cli examples/collision_helpers.nsp -o build/collision_helpers.nes --chr assets/game.chr --metasprite assets/player_idle.json --collision-map assets/collision_map.cmap
python -m nes_pascal.cli examples/random_numbers.nsp -o build/random_numbers.nes
python -m nes_pascal.cli examples/game_state.nsp -o build/game_state.nes --chr assets/chr_asset.chr
python -m nes_pascal.cli examples/gameplay_full_stack.nsp -o build/gameplay_full_stack.nes --chr assets/game.chr --nametable assets/nametable_loading.nam --metasprite assets/player_consolidated.json

The examples demonstrate:

• arithmetic.nsp: unary and binary byte arithmetic;
• boolean_expressions.nsp: comparisons and Boolean operators;
• conditionals.nsp: simple, compound, and nested branches;
• loops.nsp: counting, nested control flow, break, and continue;
• counting.nsp: wrapping inc and dec, ascending and descending for loops, exact $00 and $FF endpoints, and nested loops;
• arrays.nsp: fixed byte and Boolean arrays, constant and variable indexes, loop filling, indexed accumulation, and Boolean-element branching;
• enumerations.nsp: nominal game states, member assignments, exact-type comparisons, and a deterministic state transition;
• records.nsp: fixed-layout records, enum and Boolean fields, arrays of records, and constant and variable field indexing;
• procedures.nsp: forward procedure resolution, nested calls, shared global state, JSR/RTS, and a conditional inside a procedure;
• procedure_parameters.nsp: typed value parameters, left-to-right argument copies, mutable local parameter values, and nested parameterized calls;
• functions.nsp: typed byte/Boolean returns, nested calls, result assignment, call-safe temporaries, and the accumulator return ABI;
• scrolling_ppu_state.nsp: one fixed nonzero scroll pair, a palette update, and restoration to the default ($00, $00) pair;
• memory_layout.nsp: globals, procedure parameters, expressions, and a for-loop allocated through the deterministic runtime memory layout;
• zero_page.nsp: mandatory Zero Page temporaries, promoted globals, and a non-promoted regular-RAM fallback variable;
• frame_synchronization.nsp: runtime startup followed by a three-frame main-thread loop synchronized with nes.wait_frame.
• frame_callbacks.nsp: one main-thread update counter and one NMI VBlank counter, including a transitively validated VBlank-safe helper.
• slow_update_callback.nsp: a deliberately long update that crosses NMIs and demonstrates pending-frame coalescing without nested callbacks.
• controller_input.nsp: controller 1 movement, held A speed, B press/release appearance, Start reset, Select mode toggle, safe sprite-0 staging, OAM DMA, and two small embedded CHR tiles.
• sprite_support.nsp: one statically allocated, strongly typed hardware sprite positioned through the OAM-shadow API and uploaded by NMI OAM DMA.
• metasprite_player.nsp: the supplied PNG2CHR Studio player asset, movement in all eight D-pad directions, centered-anchor facing flip, manual frame selection with A, whole-object hide/show with Select, and explicit gameplay bounds that keep every component visible at all four edges.
• metasprite_clipping.nsp: a slow visual loop from center to the left, right, top, and bottom edges and back. Each target is only far enough beyond the screen to clip one component row or column, keeping the demo visible and understandable. Flip state is explicitly cleared in every stage; complete 8-by-8 components disappear and return without wrapping.
• sprite_animation.nsp: one consolidated idle/movement manifest, automatic state switching, explicit A-button restart, Select hide/show without pausing time, persistent left/right facing, and D-pad movement in all eight directions.
• chr_asset.nsp: inclusion of one project-relative raw CHR-ROM asset.
• palette_support.nsp: custom CHR data, initialized background and sprite palettes, then a safely queued full and individual palette update.
• nametable_loading.nsp: one project-relative raw 1 KiB nametable uploaded completely, including its attribute table, before rendering starts.
• background_updates.nsp: bounded and repeated tile writes, confirmed-shadow reads, rejected tile and attribute overflow, pending cancellation, explicit overflow clearing, and one raw attribute update after runtime starts.
• collision_rectangles.nsp: half-open point/rectangle and rectangle/rectangle queries plus bounds generated from one hardware sprite and one metasprite.
• collision_background.nsp: immutable packed collision-map lookups at tile, screen, and logical-index boundaries without the confirmed tile shadow.
• collision_helpers.nsp: every collision API together, including custom bounds, wrap-safe edge behavior, sprite/metasprite integration, and the configured background map.
• random_numbers.nsp: deterministic byte generation, inclusive bounded ranges, explicit seeding, and a small Function-based gameplay roll.
• game_state.nsp: the canonical enum-based Title, Playing, Paused, and GameOver flow with explicit transitions and gameplay reset without ROM reset.
• gameplay_full_stack.nsp: the full-stack example that combines background loading, controller input, palettes, a moving metasprite player with animation, and combined RAM pressure in one program.

The player example’s PlayerMinimumX, PlayerMaximumX, PlayerMinimumY, and PlayerMaximumY constants are specific to the bundled asset rather than renderer clamps. Every imported frame has component top-left offsets from -12 through +4, for a complete visible extent of -12..+11 around the anchor. X therefore uses $0C..$F4. Metasprite component tops use logical Y 1..232, so Y uses $0D..$E4. The clipping example intentionally does not use these gameplay limits.

The loop, counting, and procedure-parameter examples select background color $21 only when their expected final states are reached.

The Makefile shortcut builds the minimal program:

make rom

Generated ROMs use the format described in Target platform.

Each command also writes a generated ld65 configuration beside the ROM using the .cfg suffix and a human-readable CPU RAM report using .map. The map lists reserved, runtime, compiler, user, and free regions plus the address of every source variable and value parameter. See CPU memory.

CHR-ROM assets

Configure one raw CHR-ROM file with --chr:

python -m nes_pascal.cli examples/chr_asset.nsp -o build/chr_asset.nes --chr assets/chr_asset.chr

Relative paths are resolved from the directory containing the .nsp source, not from the compiler process working directory. . and .. components and platform-native separators are supported; absolute paths remain valid. NROM currently requires exactly 8192 bytes (8 KiB). A missing, unreadable, or incorrectly sized configured file stops compilation with a diagnostic. When --chr is omitted, the compiler generates an empty 8 KiB CHR-ROM (except for the existing fixed sprite-0 demonstration, which retains its internal tiles).

Metasprite programs add one or more repeatable --metasprite JSON paths and must also configure the matching 8 KiB CHR bank. Both path types are resolved from the .nsp directory. See Metasprites for the metadata contract, symbolic frame names, and OAM cost, and Sprite animation for sequence symbols, timing, loop policy, and animation RAM/ROM cost.

Nametable assets

Programs using nes.load_background(); configure either one raw 1024-byte file or a 960-byte tile map plus a 64-byte attribute table:

python -m nes_pascal.cli examples/nametable_loading.nsp -o build/nametable_loading.nes --chr assets/chr_asset.chr --nametable assets/nametable_loading.nam
# Illustrative split form: replace the placeholder paths with your own
# 960-byte tile map and 64-byte attribute table.
python -m nes_pascal.cli <your-program>.nsp -o build/<your-program>.nes --nametable-tiles <your-tile-map>.tiles --nametable-attributes <your-attribute-table>.attributes

The options are mutually exclusive forms. Split options must appear together. Paths follow the same source-relative and normalized rules as --chr. See Background loading for the raw layout, initialization behavior, and current single-screen limits.

After nes.run, use nes.set_tile, nes.get_tile, nes.set_attribute, nes.clear_background_updates, nes.background_updates_overflowed, and nes.clear_background_update_overflow as described in Runtime background updates. At most four tile or attribute bytes are uploaded during each VBlank.

Collision-map assets

Programs that call nes.background_collision must configure one text map with --collision-map:

python -m nes_pascal.cli examples/collision_background.nsp -o build/collision_background.nes --collision-map assets/collision_map.cmap

The UTF-8 file contains exactly 30 rows of 32 0/1 characters. The compiler packs the 960 flags into 120 immutable PRG-ROM bytes. It rejects a missing, unreadable, malformed, or unused configured map with a stable diagnostic. Paths follow the same source-relative rules as other assets. See Collision helpers for coordinates, bit order, edge behavior, and interaction with background updates.

Running in Mesen

1. Generate build/minimal.nes.
2. Open Mesen.
3. Select File > Open and choose build/minimal.nes.
4. The display should remain stable with universal background color $21.

Cleaning generated files

Remove build artifacts with:

make clean

This site is open source. Improve this page.