mirror of
https://github.com/imjasonh/nescript
synced 2026-07-09 09:18:01 +00:00
48832ccb13
Adds six NES-friendly authoring shortcuts so programs don't have to
hand-pack hex bytes for every kind of art asset. Every new syntax is
strictly additive — existing examples keep their byte-identical ROMs
and goldens.
* palette: ~50 named NES colours (`black`, `sky_blue`, `dk_red`, …)
usable anywhere a colour byte is expected, plus a grouped-form
`bg0..sp3` + `universal:` shape that auto-fills every sub-
palette's first byte (fixing the `$3F10` mirror trap).
* sprite: `pixels:` ASCII-art alternative to 16-byte CHR, supporting
multi-tile sprites split in row-major reading order.
* sfx: scalar `pitch:` matching the v1 driver's latch-once behaviour,
plus `envelope:` as a friendlier alias for `volume:`.
* music: `tempo:` default duration + note-name notes (`C4, Eb4,
rest 10`) alongside the existing `pitch, duration` pair form.
* background: `legend { '.': 0, '#': 1 }` + `map:` string rows,
plus `palette_map:` grids that auto-pack the 64-byte attribute
table from 16×15 sub-palette digits.
A new `examples/friendly_assets.ne` exercises every shortcut at once
with a matching pixel + audio golden; the other 22 golden tests still
match byte-for-byte.
https://claude.ai/code/session_01PzaSFj3VahDzxEYTKCESkz
75 lines
3.1 KiB
Markdown
75 lines
3.1 KiB
Markdown
# NEScript Examples
|
||
|
||
## Quick Start
|
||
|
||
```bash
|
||
# Build the compiler
|
||
cargo build --release
|
||
|
||
# Compile all examples
|
||
for f in examples/*.ne; do cargo run -- build "$f"; done
|
||
|
||
# Or compile one
|
||
cargo run -- build examples/hello_sprite.ne
|
||
```
|
||
|
||
Open any `.nes` file in an NES emulator ([Mesen](https://www.mesen.ca/), [FCEUX](https://fceux.com/), etc.)
|
||
|
||
## Examples
|
||
|
||
| File | Features | Description |
|
||
|------|----------|-------------|
|
||
| `hello_sprite.ne` | input, draw | Move a sprite with the d-pad |
|
||
| `bouncing_ball.ne` | if/else, variables | Auto-bouncing sprite with edge detection |
|
||
| `coin_cavern.ne` | states, functions, constants | 3-state game with gravity and coin collection |
|
||
| `arrays_and_functions.ne` | arrays, functions, while | Enemy array with collision detection |
|
||
| `state_machine.ne` | on enter/exit, transitions | Multi-state flow with timers |
|
||
| `sprites_and_palettes.ne` | sprites, scroll, cast | Inline CHR data, PPU scroll writes, type casting |
|
||
| `mmc1_banked.ne` | MMC1, banks, multiply | Banked mapper with software multiply |
|
||
| `palette_and_background.ne` | palette, background, set_palette, load_background | Reset-time initial load plus vblank-safe runtime swaps |
|
||
| `friendly_assets.ne` | named colours, grouped palette, pixel art, tilemap+legend, palette_map, scalar sfx pitch, note-name music | Exercises every "friendlier" asset syntax at once — the `palette` uses `bg0..sp3` + a shared `universal:`, the sprite is authored as ASCII pixel art, the background uses a `legend { ... } + map:` tilemap with a `palette_map:` for attributes, the sfx uses a scalar `pitch:` + `envelope:` alias, and the music uses note names (`C4, E4 40, rest 10`) with a `tempo:` default. |
|
||
| `platformer.ne` | **every subsystem** | End-to-end side-scrolling demo: custom CHR tileset, full 32×30 nametable with per-region attribute palettes, 2×2 metasprite hero with gravity/jump physics, wrap-around horizontal scrolling, enemies, coin pickups, user-declared SFX + music, and a Title → Playing state machine with an autopilot so the headless harness still hits interesting gameplay at frame 180. Regenerate the tile art with `cargo run --bin gen_platformer_tiles`. |
|
||
|
||
## Emulator Controls
|
||
|
||
| NES Button | Typical Key |
|
||
|------------|-------------|
|
||
| D-pad | Arrow keys |
|
||
| A | Z |
|
||
| B | X |
|
||
| Start | Enter |
|
||
| Select | Right Shift |
|
||
|
||
## About Sprites
|
||
|
||
Sprite names in `draw Player at: (x, y)` are parsed and recorded in the AST.
|
||
You can define sprites with inline CHR tile data:
|
||
|
||
```
|
||
sprite Player {
|
||
chr: [0x3C, 0x42, 0x81, 0x81, 0x81, 0x81, 0x42, 0x3C,
|
||
0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00]
|
||
}
|
||
```
|
||
|
||
If no matching sprite declaration exists, the draw uses the built-in default
|
||
tile (a smiley face). See `sprites_and_palettes.ne` for a full example.
|
||
|
||
## Compiler Commands
|
||
|
||
```bash
|
||
# Compile to ROM
|
||
cargo run -- build game.ne
|
||
|
||
# Custom output path
|
||
cargo run -- build game.ne --output my_game.nes
|
||
|
||
# Type-check only
|
||
cargo run -- check game.ne
|
||
|
||
# View generated 6502 assembly
|
||
cargo run -- build game.ne --asm-dump
|
||
|
||
# Debug mode
|
||
cargo run -- build game.ne --debug
|
||
```
|