neslua

PICO-8-flavored Lua, ahead-of-time compiled to a real NES .nes ROM. No interpreter, no VM: your Lua becomes native 6502 machine code. Zero native tools, either - the cc65 toolchain runs as bundled WebAssembly. neslua is the NES member of the luacretro console SDK family (GameTank, GBA, Genesis, NES, C64), sharing one statically-typed Lua-to-C front-end.

Your first game

The whole hello, one main.lua: a greeting plus a hardware sprite you move with the d-pad. _update60 runs the movement 60 times a second; _draw redraws the sprite every frame (examples/hello/main.lua):

local x = 120
local y = 120

function _update60()             -- 60fps: read the d-pad, move the ship
  if (btn(1)) then x += 2 end    -- right
  if (btn(0)) then x -= 2 end    -- left
  if (btn(3)) then y += 2 end    -- down
  if (btn(2)) then y -= 2 end    -- up
end

function _draw()                 -- runs every frame
  cls(0)                         -- black backdrop (space)
  print("hello neslua", 72, 88, 7)
  nes.spal(1)                    -- cyan sprite sub-palette
  spr(0, x, y, 2, 2)             -- the ship (16x16), redrawn every frame
end

Build it with the sprite sheet (a PNG imported to CHR):

npx neslua run examples/hello/main.lua --sheet examples/hello/ship.chr

Featured example: a full shmup

examples/starfall is a complete shmup in ~200 lines of Lua: a staggered invader formation (all 12 on-screen within the NES's 8-sprites-per-scanline limit), a ship you fly and fire, collisions, score/lives, and a background-tile starfield. Sprite art is imported from a PNG. Build and play it:

npx neslua run examples/starfall/main.lua --sheet examples/starfall/shmup_sheet.chr

Or build the cartridge - a byte-for-byte .nes that runs on any emulator or real hardware:

npx neslua build examples/hello/main.lua --sheet examples/hello/ship.chr -o hello.nes

That's the whole loop: write main.lua, run it, ship the .nes. (npx neslua c main.lua prints the generated C, for debugging.)

Why neslua

• Real cartridges. The output is a byte-for-byte .nes that runs on real hardware and every NES emulator - not a fantasy console.
• The same Lua as the rest of the family. PICO-8's 16.16 fixed-point number model, the _init/_update/_draw callback contract, the dialect (+= -= *= /= \= %=, \ floor-division, // comments). Where the hardware has a wall, the compiler fails loudly at compile time with a fix-it.
• Honest about the hardware. The NES has no framebuffer, so neslua exposes three real surfaces (background tiles, sprites, a small pixel canvas) plus a blank-mode escape hatch - see docs/DIFFERENCES.md. It does not pretend a 60fps full-screen pset canvas exists, because that is physically impossible on this machine.
• 8 KB of RAM for your game. The standard cart is MMC1 with battery-backed PRG-RAM at $6000, so array()/pool() allocations have room (bare NROM leaves 512 bytes).

The three-surface graphics model

surface	verbs	what it is
background	cls print map nes.tset nes.tpal nes.camera	nametable tiles (32x28 text cells), written through the VRAM queue
sprites	spr	8x8 hardware sprites (64 max, 8/scanline), staged in the shadow OAM
pixel canvas	pset line rect rectfill circ circfill	a small CHR-RAM window nes.canvas(cw,ch) the P8 drawing verbs paint
blank mode	the full verb set	nes.blank(true) - unlimited VRAM writes, screen dark (title cards)

Resolution: the PPU renders 256 x 240; NTSC output crops to 256 x 224 visible. Coordinate space is 256 x 240. Full details in docs/DIFFERENCES.md.

Examples

Each builds to a .nes and runs on the emulator (real captured frames below):

• starfall - a complete shmup: staggered invaders, a ship that flies and fires, collisions, score/lives, a starfield (the hero image above). Shows the sprite-budget discipline the NES demands.
• hello - a greeting + a hardware sprite you move (the simplest idiomatic NES program).
• pad-square - move a sprite with the d-pad.
• mathcheck - the 16.16 fixed-point conformance cart.
• canvas - the pixel-canvas surface: a vector logo.

Docs

• CHEATSHEET.md - the whole API on one page.
• DIFFERENCES.md - how the NES differs from PICO-8.
• ASSETS.md - PNG -> CHR, tilemaps, color rules.

Requirements

Node.js 24+, and nothing else. npm install pulls in luacretro (the shared front-end), romdev-toolchain-cc65 (the cc65 toolchain as WebAssembly), romdev-core-fceumm (the emulator core), and romdev-core-runner (the shared SDL host that neslua run opens a window through - the same one the whole SDK family and the romdev playtest tool use). The window needs @kmamal/sdl, an optional dependency of the runner. No native compiler or emulator to install.

License

MIT. No commercial game names in the shipped docs; the API is generic.