nessemble

nessemble is a 6502 assembler targeting the Nintendo Entertainment System (NES), written in Rust.

Upgrading from a 1.x release? See Upgrading for what changed in 2.0.

Getting Started

To initialize a new project:

nessemble init

Build the project:

nessemble project.asm --output project.nes --format nes

Run project.nes in any NES emulator to see the result.

Documentation

Start here: Installation.

• Usage — the command-line interface.
• Syntax — the assembly language reference.
• Extending — custom pseudo-instructions with Rhai.
• Building — building from source.
• Translating — adding a locale.

Installation

Download and install the latest release for your system:

https://github.com/kevinselwyn/nessemble-rs/releases

Release artifacts are provided for all five supported platforms:

Two more artifacts accompany every release:

• nessemble_<v>.vsix — the VS Code extension.
• nessemble_<v>_wasm.tar.gz — the in-browser assembler bundle (the WebAssembly build plus the <nessemble-assembler> web component).

A linux/amd64 container image is also published to GHCR for CI pipelines and coding agents that only need the executable.

VS Code extension

nessemble_<v>.vsix is the VS Code (and Cursor) extension: a client for the assembler's built-in language server, giving you diagnostics, lint hints, completion, hover, formatting, semantic highlighting, and go-to-definition on .asm/.s files.

It contains no copy of the assembler, so install nessemble itself first — the extension runs the nessemble on your PATH. One universal .vsix works on every platform:

code --install-extension nessemble_<v>.vsix

Or use the Extensions view's Install from VSIX… command. See Editor support for settings and format-on-save.

macOS: "Apple could not verify…"

The macOS .pkg is not signed with an Apple Developer ID or notarized, so after you download it, Gatekeeper blocks it with:

"nessemble_<v>.pkg" Not Opened — Apple could not verify "nessemble_<v>.pkg" is free of malware…

This is expected for an unsigned package; it does not mean the file is harmful. You have two options.

Install the .pkg anyway — clear the download-quarantine flag, then install:

xattr -d com.apple.quarantine nessemble_<v>.pkg
sudo installer -pkg nessemble_<v>.pkg -target /

Or use the plain binary tarball (nessemble_<v>_macos.tar.gz) and skip the installer:

tar -xzf nessemble_<v>_macos.tar.gz
xattr -d com.apple.quarantine nessemble     # clear quarantine
sudo mv nessemble /usr/local/bin/            # put it on your PATH

Both install the same binary to /usr/local/bin/nessemble. (The tarball binary is a 64-bit Intel build, matching the .pkg; it runs on Apple Silicon under Rosetta.)

Container image

A binary-only image is published to the GitHub Container Registry on every release:

ghcr.io/kevinselwyn/nessemble-rs:<version>   # e.g. :2.11.0
ghcr.io/kevinselwyn/nessemble-rs:latest

It exists for CI pipelines and coding agents that need the nessemble executable but not this source tree — pulling the image is faster and simpler than building the workspace. The image is a single statically-linked linux/amd64 binary on scratch: there is no shell, package manager, or libc inside it, only /nessemble. That means you consume it by lifting the binary out, not by opening a shell in it.

Copy it into your own image with a multi-stage COPY --from — the most common pattern for build tools:

COPY --from=ghcr.io/kevinselwyn/nessemble-rs:2.11.0 /nessemble /usr/local/bin/nessemble

Extract it to the host without writing a Dockerfile — create a container from the image (it need not run) and copy the file out:

docker create --name nessemble ghcr.io/kevinselwyn/nessemble-rs:2.11.0
docker cp nessemble:/nessemble ./nessemble
docker rm nessemble

Run it directly — the entrypoint is the binary, so pass nessemble arguments straight through and mount your project as the working directory:

docker run --rm ghcr.io/kevinselwyn/nessemble-rs:2.11.0 --version

docker run --rm -v "$PWD:/work" -w /work \
  ghcr.io/kevinselwyn/nessemble-rs:2.11.0 project.asm --output project.nes --format nes

Pin a version tag (:2.11.0) rather than :latest for reproducible builds. In a Claude Code on the web (or similar) environment, pulling the image in a setup script caches it into the environment snapshot, so the binary is on disk at the start of every later session.

From source

nessemble is a Cargo workspace and builds with a stock Rust toolchain.

git clone https://github.com/kevinselwyn/nessemble-rs
cd nessemble-rs
cargo build --release

The binary is written to target/release/nessemble. See Building for cross-compilation and packaging details.

Upgrading from 1.x to 2.x

nessemble 2.0 is a ground-up rewrite in Rust. Assembly source and ROM output are compatible — the same .asm files assemble to the same bytes — but the tool around them changed. This page covers what a 1.x user needs to know.

Assembly & ROM output

• No changes needed to your source. The assembly language (instructions, addressing modes, expressions, labels, macros, conditionals, includes, data and iNES directives, media importers) is unchanged, and assembled ROMs are byte-for-byte identical to 1.x output. The one behavioral change is how relative filenames are resolved — see Include & asset paths.

Include & asset paths

• In 1.x, every filename-based directive resolved its path against a single global working directory (the top-level file's directory). A relative path in an included file was therefore resolved from the project root, not from the included file.
• In 2.x, relative filenames in .include, .inestrn, and the .inc* media importers (.incbin, .incpng, .incpal, .incrle, .incwav) resolve relative to the directory of the file that contains the directive. This makes subdirectory modules self-contained: a file in sub/ that does .include "helper.asm" or .incbin "data.bin" now finds them in sub/.
• What to check: if a file you .include from a subdirectory referenced a sibling file or asset by a path written relative to the project root, update that path to be relative to the including file instead. Projects that keep each file's includes and assets alongside it need no changes.

Custom pseudo-instructions

• The three embedded scripting engines (JavaScript, Lua, and Scheme) and native shared-object (.so/.dll) plugins are replaced by a single embedded language, Rhai.
• Rewrite custom scripts as .rhai files and update your --pseudo mapping to point at them. A script now defines fn custom(ints, texts) and returns the emitted bytes. See Extending.
• The bundled ease script is provided as .rhai; run nessemble scripts to install it.
• Rhai scripts can still read and write files (as the old Lua/Scheme hosts could), via the rhai-fs open_file API; relative paths resolve against the source file's directory. See Filesystem access.
• Script paths in a --pseudo mapping now resolve relative to the mapping file's own directory, not the source file's directory. In 1.x the paths were resolved against the input file's location (the tool's cwd_path). If your pseudo.txt sits next to the source you assemble, nothing changes; otherwise, keep each script beside the mapping file that names it (or update the paths).

Removed commands and options

The following 1.x features are not part of 2.x — they are not parsed and do not appear in --help:

• The disassembler / reassembler (-d/--disassemble, -R/--reassemble).
• The simulator / debugger (-s/--simulate, -r/--recipe).
• The package registry: registry, install, uninstall, publish, info, ls, search, and the user/auth commands (adduser, login, logout, forgotpassword, resetpassword).

config remains, but is now a general key/value store (the registry key it used to manage is gone).

Internationalization

• Translations moved from gettext (.po/.mo) to Project Fluent. Drop a ~/.nessemble/locales/<lang>.ftl file and select it with NESSEMBLE_LANG. See Translating.

Building & installing

• Building no longer needs a C toolchain, flex/bison, or gettext — just a Rust toolchain. See Building.
• Release artifacts (.deb, .msi, .pkg, and standalone .exe) are provided for the same platforms as before. See Installation.

Usage

nessemble is driven from the command line. This page documents its options and subcommands.

Usage: nessemble [OPTIONS] [infile.asm]
       nessemble <COMMAND>

Commands:
  init       initialize new project
  scripts    install scripts
  reference  get reference info about assembly terms
  lsp        run the language server (stdio)
  format     format assembly source
  lint       lint assembly source
  coverage   report runtime coverage from a CDL capture
  help       Print this message or the help of the given subcommand(s)

Arguments:
  [infile.asm]  assembly source to assemble (stdin if omitted)

Options:
  -o, --output <outfile.rom>  output file
  -f, --format <NES|RAW>      output format
  -e, --empty <hex>           empty byte value
  -u, --undocumented          use undocumented opcodes
  -l, --list <listfile.txt>   generate list of labels and constants
      --mlist                 include labels created by macros in the list file
  -p, --pseudo <pseudo.txt>   use custom pseudo-instruction functions
      --root <dir>            project root for `@/`-relative paths
      --max-operations <n>    cap each pseudo-op script's Rhai operation count
      --time-scripts          report per-directive script call count and wall time
  -c, --check                 check syntax only
  -v, --version               display program version
  -L, --license               display program license
  -h, --help                  Print help

The help text above is generated by clap; run nessemble --help (or nessemble <command> --help) for the current output.

The lsp command starts the built-in Language Server for use with LSP-capable editors. The format command reformats assembly source (§ format) and the lint command reports style problems without rewriting it (§ lint). The coverage command reports coverage from an emulator CDL capture, the -p Rhai scripts, or both (§ coverage).

Options

-o, --output <outfile.rom>

Sets the filename where output is written. An outfile of - (or omitting the flag) writes to stdout.

nessemble infile.asm --output outfile.rom

-f, --format

Specifies the output format:

• NES — an iNES ROM, complete with a 16-byte header.
• RAW — raw assembled 6502 code.

The format is RAW by default, but if iNES header directives (.inesprg, .ineschr, …) are present, it becomes NES unless overridden.

-e, --empty <hex>

Sets the fill value for empty/unwritten ROM bytes. Defaults to FF.

nessemble infile.asm --empty 00

-u, --undocumented

Allows the use of undocumented ("illegal") opcodes.

-l, --list <listfile.txt>

Writes a list of labels and constants to the given file.

Labels defined inside a macro body are omitted by default, so the list is not cluttered with the per-invocation labels a macro emits each time it is called (for example a loop target uniquified with \@). Pass --mlist to include them.

--mlist

Includes labels created by macro expansion in the --list output. Has no effect unless --list is also given.

nessemble infile.asm --list listing.txt --mlist

Constants defined in macros always appear in the list; --mlist affects only the [labels] section. See Macros for more on macro-defined labels.

-p, --pseudo <pseudo.txt>

Points to a mapping file that enables custom pseudo-instructions. See Extending.

--root <dir>

Sets the project root that @/-prefixed filename arguments resolve against, overriding the usual walk-up for the nearest .nessemblerc, .nessemblerc.json, or .nessembleignore.

nessemble src/main.asm --root .

dir must exist; a missing or non-directory path is rejected before assembly starts.

--no-cache

Neither reads nor writes the custom pseudo-instruction cache: every directive's script runs. Reach for this when a build looks stale, or to confirm that a suspected caching problem is one.

--max-operations <n>

Overrides the runaway-script guard on every pseudo-op script, in place of the built-in default of 10,000,000 Rhai operations. 0 means unlimited.

nessemble src/main.asm --pseudo pseudo.txt --max-operations 50000000

--time-scripts

Prints a per-directive report to stderr after assembly: how many times each .foo-style directive was called, how many of those were cache hits versus real script runs, and the total wall time spent in it — busiest directive first. See Runaway-script guard and timing.

-c, --check

Checks the input for syntax errors only; produces no output.

-v, --version / -L, --license / -h, --help

Print the version, license, or usage message respectively.

Commands

init [<arg> ...]

Scaffolds a new project, prompting for any values not supplied as arguments:

nessemble init [filename] [prg] [chr] [mapper] [mirroring]

• filename — file to create.
• prg / chr — number of PRG / CHR banks.
• mapper / mirroring — iNES mapper and mirroring.

scripts

Installs the bundled custom-pseudo-instruction scripts into ~/.nessemble/scripts. See Extending.

cache info | cache clear

Inspects or empties the custom pseudo-instruction cache in ~/.nessemble/cache.

nessemble cache info     # where the cache is, how many entries, how many bytes
nessemble cache clear    # delete every entry

Clearing is always safe: an entry is a saved result, never the only copy of anything, so the next build recomputes what it needs.

reference [<category>] [<term>]

Prints reference information from locally bundled data. With no arguments it lists the categories (instructions, directives, script); with a category it lists its entries; with a term it prints the details (e.g. reference instructions LDA).

The script category is the host API a custom pseudo-op script can call, grouped by domain:

nessemble reference script              # every function, method, and property
nessemble reference script nes_shade    # signature, summary, and a docs link

A name catalogued more than once prints each meaning — read_blob is both a method on an open file handle and a one-call function — and an entry that needs a build feature says so, since the WebAssembly build has neither filesystem access nor random numbers.

format [<opt> ...] <path> ...

Reformats nessemble assembly source in an opinionated, Prettier-style way: consistent indentation and comma spacing, .db/.dw/.color data consolidated a fixed number of values per line, a blank line after each RTS/RTI, collapsed runs of blank lines, and a normalized final newline. Formatting is cosmetic only — the assembled ROM is never changed.

nessemble format path/to/file.asm       # print formatted source to stdout
nessemble format --write path/to/dir    # rewrite files in place
nessemble format --check path/to/dir    # CI gate: exit non-zero if unformatted

• A single file with no flags prints the formatted result to stdout, leaving the file untouched.
• -w, --write rewrites each changed file in place and prints its path.
• -c, --check writes nothing; it lists files that are not already formatted and exits non-zero — the gate for CI.
• A directory is walked recursively (for the configured extensions, .asm by default) and requires --write or --check.
• --config <file> uses <file> as the .nessemblerc; --no-config ignores any .nessemblerc and uses built-in defaults.

The editor Language Server's "format document" action runs this same formatter, so editors and the CLI produce identical output.

lint [<opt> ...] <path> ...

Reports style problems in nessemble assembly. Where format is Prettier, lint is ESLint: it only reports and never rewrites source.

nessemble lint path/to/file.asm       # report problems for one file
nessemble lint path/to/dir            # walk a tree and report problems

src/prg/07.asm
     42:1   warning  code block `sound_engine` has no nearby comment  require-block-comment
    103:1   warning  unknown comment directive `@nessemble-formt`  unknown-comment-directive

✖ 2 problems (0 errors, 2 warnings)

The rules:

• Each finding prints as LINE:COL severity message rule-id, grouped by file, with a problem-count footer; a clean run prints ✓ No problems.
• Exit code: any error-severity finding fails the run (exit non-zero); warn findings do not, unless --max-warnings <n> is exceeded. This is the CI gate.
• A directory is walked recursively (for the configured extensions, .asm by default), skipping .nessembleignore paths.
• --quiet reports errors only (suppresses warnings).
• --config <file> uses <file> as the .nessemblerc; --no-config ignores any .nessemblerc and uses built-in defaults.

Every rule defaults to warn except require-routine-doc, which defaults to off. Rules, their severities, the comment window, and the label-name ignore list are configured under the lint key of .nessemblerc. The editor Language Server surfaces the same findings inline as you type, including quick fixes for the deprecated directive spelling and for a register missing from a clobber list.

Suppressing a finding

Two directives silence findings at the site, for when a rule is wrong about a particular routine:

; @nessemble-lint-ignore-next-line [rule[, rule...]]
; @nessemble-lint-ignore start|end [rule[, rule...]]

Bare, they suppress every rule. With a comma-separated list of rule ids, only those. An unknown rule name is reported as unknown-comment-directive, so a typo cannot silently silence nothing.

These exist because the clobber analysis has two known blind spots, both of which force an author to choose between a false annotation and a false finding. Suppressing at the site is the third, better option:

Fall-through entry points. A routine's body is read as its own block plus the JSR/JMP targets it names; a routine that falls through into the next one is not followed. So assign_chr_bank below really does clobber A, X, Y — via the routine it falls into — but its own block writes no register, and overdeclared-clobber fires:

; @nessemble-lint-ignore-next-line overdeclared-clobber
; @nessemble-clobbers A, X, Y, [chr_bank_arg]
assign_chr_bank:
    STA <chr_bank_arg
                            ; falls through ↓
; @nessemble-clobbers A, X, Y
find_or_evict_chr_slot:
    ...

Save/restore pairs. A PHA … PLA around a routine's body preserves A, but the restore is not modeled, so undeclared-clobber asks you to declare A clobbered — inverting what the tag means:

; @nessemble-lint-ignore-next-line undeclared-clobber
; @nessemble-clobbers X, Y, [draw_tmp]
ppu_set_xy_addr:
    PHA
    ...
    PLA
    RTS

In both cases the annotation stays truthful — it is what a caller needs to know — and exactly one bogus finding is suppressed.

The rules are the coverage directives' rules, because it is the same mechanism:

• -next-line targets the next significant line, skipping blank and comment lines. That is what lets it sit above a whole @nessemble-param block and still land on the label, which is where the routine rules report.
• start opens a region and end closes it; an unclosed region runs to end of file (the whole-file opt-out), regions do not nest, and a region never crosses into an .included file.
• A directive in a trailing comment is inert, and reported.
• Matching is by the line a finding is reported at. Most rules report at the label — including undeclared-clobber, overdeclared-clobber, and require-block-comment — so -next-line above the label reaches them. invalid-routine-signature and the comment-directive rules report at the annotation line instead, so use the region form to suppress those.
• A suppressed finding is gone, not downgraded: it does not print, does not count toward --max-warnings, and does not affect the exit code, even when the rule's configured severity is error. Severity is your choice in .nessemblerc, so it is not a reason to withhold the escape hatch.
• Suppression applies to lint findings only. It never silences a parse or assembly error.

coverage <infile.asm> --cdl <file.cdl> ...

Reports runtime execution coverage of an assembled ROM against a CDL (Code/Data Logger) capture an emulator wrote after running the ROM, line coverage for the -p Rhai scripts a build runs, or both. It never writes a ROM.

nessemble coverage main.asm --cdl capture.cdl                 # coverage.json + coverage.lcov
nessemble coverage main.asm --cdl capture.cdl --format lcov --out cov.lcov
nessemble coverage main.asm --cdl a.cdl --cdl b.cdl --emulator mesen
nessemble coverage main.asm -p pseudo.txt --scripts           # scripts only, no CDL, no emulator

At least one of --cdl or --scripts is required.

With --cdl, the source assembles with a byte-exact source map and each PRG-emitting line is classified as code (executed), data (read), mixed (both), or unaccessed (present but never touched). Only the PRG section is classified; lines that emit only CHR data are omitted.

• --cdl <file> — the CDL to read; repeatable (multiple files are merged by bitwise OR). Required unless --scripts is given.

• --emulator <fceux|mesen> — the CDL format, default fceux. FCEUX and Mesen flat masks are the same size but bit-incompatible, so there is no auto-detect; state the emulator that produced the file. (BizHawk's container format is not yet supported.)

• --format <json|lcov|all> — report format, default all. JSON carries the full four-way class per line, plus a "kind" of "rom" or "script" per file; LCOV is line hit/not-hit for coverage tools and has no kind.

• --out <path> — output file for a single format, or a directory for all (coverage.json + coverage.lcov); defaults to the current directory.

• -p, --pseudo <pseudo.txt> — custom pseudo-op mapping, as in assemble mode.

• --root <dir> — project root for @/-relative paths, as in assemble mode.

• --max-operations <n> — caps each pseudo-op script's Rhai operation count, as in assemble mode.

• --scripts — also report line coverage for the -p Rhai scripts, so you can see which parts of a custom pseudo-op never ran during assembly. Each project script appears as its own file (each line executed or not); bundled ~/.nessemble scripts are excluded. Available when the binary is built with the coverage feature (on by default).

  Given without --cdl, this reports scripts alone: the source assembles without forcing NES mode or a source map, no CDL is read, and no --emulator is consulted — the shape a CI job without an emulator playthrough can produce. Every script the -p mapping names is included, even one whose directive the build never reaches (reported at 0%, not omitted); a script mapped under two directive names appears once. A run that instruments no script at all — no -p mapping given, or the mapping named nothing readable — prints a warning saying why instead of a silent, unscripted report.

• --no-ignore — report every line, disabling the @nessemble-coverage-ignore… directives.

Source can exclude lines it does not want measured with the coverage ignore directives; excluded lines leave both the numerator and the denominator, and the run reports how many were dropped:

coverage: 812/900 lines (90.2%) — 14 lines, 1 file ignored

When both --cdl and --scripts contribute files, the single percentage above can move for reasons that have nothing to do with the ROM, so the summary also splits the two:

coverage: 812/900 lines (90.2%) — rom 780/840, scripts 32/60

The CDL must be the same size as this ROM's PRG+CHR (it carries no ROM identity of its own); a size mismatch is a hard error. Equal sizes still do not guarantee the CDL came from this exact build, so capture it from the ROM this source assembles to.

Comment directives

Some nessemble tools take instructions from the source itself, written as comment directives: a comment whose first token names the tool and what to do.

; @nessemble-<name> [args]   [; trailing prose]

The rules are the same for every directive:

The routine annotations are described in Documenting routines; the rules below apply to every directive.

• It must be on its own line — a directive in a trailing comment (LDA #$00 ; @nessemble-…) does nothing, and is reported.
• The @… token must come first in the comment, after the ; (or ;;, ;;;) and any spaces. A directive mentioned mid-sentence is prose.
• Names are exact and lower-case; anything after the arguments and a second ; is free-text prose.
• A directive applies to what follows it, and blank lines, comment lines, and label or constant definitions in between are skipped — so a directive can sit above the label that names its subject, and an explanation can follow the directive.
• An unrecognized @nessemble-… name, or a known one with wrong arguments, is reported by lint and in the editor rather than silently ignored — that is what the namespace buys you. Ordinary @-comments (; @todo, ; @param) are never touched.

Excluding lines from coverage

Two directives keep lines out of a coverage report. Excluded lines leave both sides of the ratio — they are not counted as covered, and not counted at all — so the percentage reflects only the lines you meant to measure.

@nessemble-coverage-ignore-next-line excludes the next significant line; blank and comment lines in between are skipped, so an explanation can follow the directive:

; @nessemble-coverage-ignore-next-line
; only reachable from a mapper IRQ we can't trigger in CI
    JMP nmi_stub

@nessemble-coverage-ignore start … end excludes a whole region:

; @nessemble-coverage-ignore start
mapper3_init:
    LDA #$00
    STA mapper_reg
; @nessemble-coverage-ignore end

• An unclosed region runs to the end of the file — put a lone ; @nessemble-coverage-ignore start in the header to opt a whole file out. A file with nothing left to report is dropped from the report entirely (no SF: record) and counted as an ignored file.
• Regions are per file: one does not extend into an .included file, and each included file carries its own directives.
• Regions do not nest. A start inside an open region, or an end with no start, does nothing and is reported by lint.
• Rhai scripts (under --scripts) honor both directives, written as // comments.
• nessemble coverage --no-ignore reports every line regardless — useful in CI, or to see what the directives are hiding. The stdout summary always names how much was excluded, and the JSON report carries ignored / ignoredFiles counts.

Documenting routines

The 6502 has no calling convention: every routine invents its own, and the only record of it is usually a comment, if that. Three directives write that convention down where the tools can read it — which registers a routine takes, what it hands back, and what it destroys:

; Draw one metasprite from `metasprite_table` into the OAM shadow buffer.
;
; @nessemble-param   A  metasprite index into `metasprite_table`
; @nessemble-param   X  screen x, in pixels
; @nessemble-param   Y  screen y, in pixels
; @nessemble-returns C  set when the sprite was clipped off-screen
; @nessemble-clobbers A, X, Y, [oam_cursor]
draw_metasprite:
    ...
    RTS

Hovering any use of draw_metasprite — including the operand of a JSR, in this file or another open one — shows that table, so "does this call eat my Y?" is answered without leaving the call site.

Slots. A slot is a place a value lives across a call. The vocabulary is closed, so a typo is reported rather than silently accepted:

Slot names are case-insensitive (a and A both work) and always render upper-case. Memory needs its brackets or its $: that is what lets @nessemble-clobbers AX be reported as a bad slot instead of quietly becoming a symbol named AX.

What the tags mean.

• @nessemble-param and @nessemble-returns take one slot each, followed by a free-text description (a ; in it is part of the description). Repeat the tag for each slot.
• @nessemble-clobbers takes a list, and means anything not listed is preserved. A returned slot is clobbered by definition and need not be repeated.
• @nessemble-clobbers none claims the routine preserves everything. That is different from writing no @nessemble-clobbers at all, which claims nothing.
• Annotations bind to the first label below them; blank lines and prose comments in between are skipped, so a summary can sit above the tags. A line of code in between binds them to nothing, and is reported.

The declaration is checked. nessemble lint compares each declared clobber list against what the routine actually writes:

src/prg/sprite.asm
     42:1   warning  routine `draw_metasprite` writes Y but does not declare it clobbered  undeclared-clobber

• Only A, X, Y, and S are verified. Flags are documentation — nearly every instruction disturbs N/Z, so checking them would flag everything. Memory slots are documentation too.
• Only routines that declared a clobber list are checked, so a project adopts this one routine at a time.
• A routine's body runs from its label to the next block-opening label. A call to another annotated routine contributes that routine's declared clobbers; a call to an unannotated one, a macro invocation, an indirect jump, or a data run inside the body makes the body "not fully understood", which silences overdeclared-clobber but never undeclared-clobber.
• A routine that falls through into the next one is under-reported rather than over-reported: the analysis prefers a missed warning to a wrong one. Where that costs a wrong finding — a fall-through entry point, or a PHA/PLA pair the analysis does not model — suppress it at the site with @nessemble-lint-ignore… and keep the annotation truthful.
• The stack pointer counts as clobbered only for TXS. Pushes and pulls move S, but routines balance them.

.nessemblerc

Formatting is configurable, Prettier-style, via an optional .nessemblerc (or .nessemblerc.json) file discovered by walking up from the file or directory being formatted. It is JSON; every key is optional and takes the default shown below, so a project with no .nessemblerc still gets fully-formatted output. Unknown keys are rejected (to catch typos early).

{
  "extensions": [".asm"],
  "indentStyle": "space",
  "indentWidth": 4,
  "commaSpacing": true,
  "finalNewline": true,
  "indentDirectives": false,
  "alignContinuations": true,
  "dataPerLine": 8,
  "respectStrideHints": true,
  "blankLineAfterReturn": true,
  "maxConsecutiveBlankLines": 2,
  "mnemonicCase": "preserve",
  "hexDigitCase": "preserve",
  "overrides": []
}

Directive names (.db, .DB) are never re-cased — nessemble is case-sensitive about them.

Stride hints

To override dataPerLine for one data block, place a ; @nessemble-format stride=N comment directive before it. Multiple strides cycle in order and the last one repeats:

; @nessemble-format stride=2
    .db $01, $02
    .db $03, $04

The hint binds to the next data run, skipping blank lines, comment lines, and label or constant definitions on the way — the run's own label and an explanatory comment are both transparent:

; @nessemble-format stride=3
; one row of the tile per line
palette_rows:
    .db $01, $02, $03
    .db $04, $05, $06

If the first thing that is not one of those is anything but a .db/.dw/ .color line, the hint applies to nothing and lint reports it as ineffective-comment-directive. format and lint resolve the target the same way, so a hint the formatter honors is exactly a hint the linter calls effective.

Deprecated spelling. The original ; @fmt stride=N still works and always will — it is an alias, not a removal. It is reported by the deprecated-comment-directive rule, and the editor offers a one-click rename. To migrate a tree in bulk:

grep -rl '@fmt' --include='*.asm' . | xargs sed -i 's/@fmt/@nessemble-format/g'

Continuation alignment

When a statement's operand list wraps onto further lines (a trailing comma continues it onto the next physical line), alignContinuations (on by default) lines up each continuation under the opening line's first argument:

    .metasprite $FA, $02, $00, $FA,
                $FA, $03, $00, $02,
                $02, $0D, $00, $FA

With alignContinuations: false, continuation lines fall to the block indent instead:

    .metasprite $FA, $02, $00, $FA,
    $FA, $03, $00, $02,
    $02, $0D, $00, $FA

The alignment is computed from the opening line's actual indent, so it stays correct together with indentDirectives. Under indentStyle: "tab" the continuation reuses the opening line's leading tab and then pads to the first-argument column with spaces. Only leading whitespace changes, so the assembled output is unaffected.

Overrides

overrides is an ordered list of { "files": <glob>, "options": { … } } entries; for each formatted file, later matching entries layer their options on top of the base config. Globs support *, **, and ?.

{
  "dataPerLine": 8,
  "overrides": [
    { "files": "src/data/**/*.asm", "options": { "dataPerLine": 16 } }
  ]
}

.nessembleignore

A .nessembleignore file (gitignore-style globs, one per line) excludes matching paths from directory walks. It is discovered the same way as .nessemblerc.

lint

The lint subcommand is configured under a lint key in the same .nessemblerc. With no config the linter is on with its defaults (every rule at "warn" except require-routine-doc, which is "off"; a comment window of 3; and no ignores), so nessemble lint is useful out of the box.

{
  "lint": {
    "rules": {
      "require-block-comment": ["warn", { "window": 3 }],
      "unknown-comment-directive": "error",
      "deprecated-comment-directive": "off",
      "require-routine-doc": "warn"
    },
    "ignore": ["^loc_[0-9A-Fa-f]", "^data_[0-9A-Fa-f]"]
  }
}

Severity. A rule at "off" is not run. An "error" finding fails the run (non-zero exit); a "warn" finding does not, unless the CLI's --max-warnings is exceeded. In the editor, findings appear at a gentle severity (Information for error, Hint for warn) with the nessemble-lint source, distinct from the assembler's own errors and warnings.

Rule options. require-block-comment takes a window (default 3): a block label is clean if any line within ±window lines carries a comment. The directive and routine-signature rules take no options.

Ignore patterns. List the name shapes that should never be flagged — most often machine-generated disassembly labels (loc_8000:, data_c123:). No patterns ship by default, so a fresh project flags every undocumented block until you opt specific shapes out. (Ignore patterns match label names, so they do not affect the comment-directive rules; silence those with a severity of "off". They do apply to the routine rules, which are keyed by the routine's label name.)

Per-glob overrides may carry a lint block too, so a data-heavy directory can loosen or disable a rule for its files:

{
  "overrides": [
    { "files": "src/data/**/*.asm",
      "options": { "lint": { "rules": { "require-block-comment": "off" } } } }
  ]
}

Syntax

The examples on this page are interactive: edit the source and click Assemble to build it in your browser (powered by the WebAssembly build of nessemble). Assembled bytes are shown as a hex dump and can be downloaded.

Numbers

Binary, decimal, octal, hexadecimal, and ASCII character are all valid numbers.

Symbols

Mathematical Operators

Comparison Operators

Special

Labels

Named

Named label declarations must be in the follow format:

NAME:

• NAME - Label name, required.

Example:

    LDX #$08
loop:
    DEX
    BNE loop
    BRK

Output:

00000000  a2 08 ca d0 fd 00                                 |......|
00000006

Try it:

A label that names a subroutine can carry its calling convention — the registers it takes, returns, and destroys — in comments the tooling reads. See Documenting routines.

Temporary

Temporary/un-named labels may also be declared by placing only a colon.

:

To jump to a temporary label, the direction and count of the jumps must be given.

JMP :[+-]

[+-] - Direction, required.

N-number of +s means to jump to the temporary label that is N temporary labels further down in the code.

N-number of -s means to jump to the temporary label that is N temporary labels further up in the code.

Example:

    LDX #$08
:
    DEX
    BNE :-
    BRK

Output:

00000000  a2 08 ca d0 fd 00                                 |......|
00000006

Try it:

Mnemonics

All 56 mnemonics are supported:

Read more about 6502 opcodes here.

In addition, 24 illegal/undocumented mnemonics may be used when assembled with the -u, --undocumented flag.

Read more about undocumented 6502 opcodes here.

Addressing Modes

nessemble uses square brackets [] instead of parentheses () in its addressing modes because the latter are used to indicate precedence in mathematical operations.

Read more about 6502 addressing modes here.

Functions

Pseudo-Instructions

.ascii

Convert ASCII string to bytes.

Usage:

.ascii "STRING"[(+/-)NUMBER]

• "STRING" - String, required. ASCII string to turn into bytes. Must be within quotes.
• (+/-)NUMBER - Number, optional. Amount to increase/decrease ASCII values.

Example:

.ascii "When, in disgrace with fortune and men's eyes"

Output:

00000000  57 68 65 6e 2c 20 69 6e  20 64 69 73 67 72 61 63  |When, in disgrac|
00000010  65 20 77 69 74 68 20 66  6f 72 74 75 6e 65 20 61  |e with fortune a|
00000020  6e 64 20 6d 65 6e 27 73  20 65 79 65 73           |nd men's eyes|
0000002d

Try it:

The +/- operators may also be used to increase/decrease the output.

Example:

.ascii "I all alone beweep my outcast state"-32

Output:

00000000  29 00 41 4c 4c 00 41 4c  4f 4e 45 00 42 45 57 45  |).ALL.ALONE.BEWE|
00000010  45 50 00 4d 59 00 4f 55  54 43 41 53 54 00 53 54  |EP.MY.OUTCAST.ST|
00000020  41 54 45                                          |ATE|
00000023

.checksum

Calculate crc32 checksum.

Usage:

.checksum LABEL

• LABEL - Label, required. Label at which to start generating the checksum.

Example:

start:
    LDA #$01
    STA <$02
    .checksum start

Output:

00000000  a9 01 85 02 b8 1f ee 86                           |........|
00000008

The checksum is b8 1f ee 86.

Checksums may only be performed on preceding data.

Try it:

.chr

Set CHR bank index.

Usage:

.chr NUMBER

• NUMBER - Number, required. CHR bank index.

Example:

.chr 0

CHR banks are 2K bytes (0x2000) in size.

.color

Convert hex color to NES color.

Finds the closest valid NES color to the given hex color.

Usage:

.color NUMBER[, NUMBER, ...]

• NUMBER - Number, required. At least one number is required.
• , NUMBER, ... - Number(s), optional. Additional comma-separated numbers may be used.

Example:

.color $FF0000

Output:

00000000  16                                                |.|
00000001

Read more about the NES color palette here.

In an editor connected to the language server, hovering .color previews the palette entries the whole argument list maps to, and hovering a single argument previews just that color.

Try it:

.db

Define 8-bit byte(s).

Usage:

.db NUMBER[, NUMBER, ...]

• NUMBER - Number, required. At least one number is required.
• , NUMBER, ... - Number(s), optional. Additional comma-separated numbers may be used.

Example:

.db $12, $34

Output:

00000000  12 34                                             |.4|
00000002

Try it:

A trailing comma continues the list onto the next line, so a long run of bytes can be wrapped across several indented lines:

.db $00, $01, $02, $03,
    $04, $05, $06, $07

The same line-continuation rule applies to every comma-separated data directive (.dw, .fill, .color, .hibytes, .lobytes, and .defchr).

.defchr

Define CHR tile.

Only numbers from 0-3 may be used: 0 representing black, 1 dark grey, 2 light grey, and 3 representing white.

Usage:

.defchr XXXXXXXX,
        XXXXXXXX,
        XXXXXXXX,
        XXXXXXXX,
        XXXXXXXX,
        XXXXXXXX,
        XXXXXXXX,
        XXXXXXXX

• XXXXXXXX, - Number, required. Must be exactly 8 numbers of 8-characters each.

Example:

.defchr 333333333,
        300000003,
        300000003,
        300000003,
        300000003,
        300000003,
        300000003,
        333333333

Output:

00000000  ff 01 01 01 01 01 01 ff  ff 01 01 01 01 01 01 ff  |................|
00000010

Read more about PPU pattern tables here.

Try it:

.dephase

End a .phase block. Labels defined after .dephase revert to their physical load address. A bank or segment switch (.prg, .chr, .segment) also ends any active phase.

Usage:

.dephase

.dw

Define 16-bit word(s).

Usage:

.dw NUMBER[, NUMBER, ...]

• NUMBER - Number, required. At least one number is required.
• , NUMBER, ... - Number(s), optional. Additional comma-separated numbers may be used.

Example:

.dw $1234, $45678

Output:

00000000  34 12 78 56                                       |4.xV|
00000004

Try it:

.else

Else condition of an .if/.ifdef/.ifndef statement.

Usage:

.else

Example:

.ifdef SOMETHING
    STA $00
.else
    STA $01
.endif

.endenum

End .enum.

Usage:

.endenum

Example:

.enum $0080

TEST_0 .rs 1
TEST_1 .rs 2
TEST_2 .rs 1

.endenum

.endif

End .if/.ifdef/.ifndef statement.

Usage:

.endif

Example:

.ifdef SOMETHING
    STA $00
.else
    STA $01
.endif

.endm

End .macrodef.

Usage:

.endm

Example:

.macrodef TEST_MACRO
    LDA #\1
    STA <\2
.endm

See the section on Macros for more information.

.enum

Start enumerated variable declarations.

Usage:

.enum START[, INC]

• START - Number, required. Value at which to start enumerating.
• , INC - Number, optional. Amount to increment after each enumeration.

Example:

.enum $0080

TEST_0 .rs 1
TEST_1 .rs 2
TEST_2 .rs 1

.endenum

.fill

Fill with bytes.

Usage:

.fill COUNT[, VALUE]

• COUNT - Number, required. Number of bytes to fill.
• , VALUE - Number, optional. Value of each byte. Defaults to $FF.

Example:

.fill 16

Output:

00000000  ff ff ff ff ff ff ff ff  ff ff ff ff ff ff ff ff  |................|
00000010

Try it:

.font

Generate font character tile.

Usage:

.font START[, END]

• START - Character/number, required. Starting ASCII character or code.
• [, END] - Character/number, optional. Ending ASCII character or code. If included, all font tiles from START to [, END] (inclusive) will be generated.

Example:

.font 'A', 'G'

Output:

00000000  38 44 7c 44 44 44 44 00  38 44 7c 44 44 44 44 00  |8D|DDDD.8D|DDDD.|
00000010  78 44 78 44 44 44 78 00  78 44 78 44 44 44 78 00  |xDxDDDx.xDxDDDx.|
00000020  38 44 40 40 40 44 38 00  38 44 40 40 40 44 38 00  |8D@@@D8.8D@@@D8.|
00000030  78 44 44 44 44 44 78 00  78 44 44 44 44 44 78 00  |xDDDDDx.xDDDDDx.|
00000040  7c 40 70 40 40 40 7c 00  7c 40 70 40 40 40 7c 00  ||@p@@@|.|@p@@@|.|
00000050  7c 40 70 40 40 40 40 00  7c 40 70 40 40 40 40 00  ||@p@@@@.|@p@@@@.|
00000060  3c 40 4c 44 44 44 38 00  3c 40 4c 44 44 44 38 00  |<@LDDD8.<@LDDD8.|
00000070

Read more about PPU pattern tables here.

Try it:

.hibytes

Output only the high byte of 16-bit word(s).

Usage:

.hibytes NUMBER[, NUMBER]

• NUMBER - Number, required. At least one number is required.
• , NUMBER, ... - Number(s), optional. Additional comma-separated numbers may be used.

Example:

.hibytes $1234, $5678

Output:

00000000  12 56                                             |.V|
00000002

Try it:

.if

Test if condition.

Can be accompanied by an .else and must be accompanied by an .endif.

Usage:

.if CONDITION

• CONDITION - Condition, required. The code that follows will be processed if the condition is true. See Comparison Operators.

Example:

.if SOMETHING == $01
    LDA #$01
.endif

.ifdef

Test if variable is defined.

Can be accompanied by an .else and must be accompanied by an .endif.

Usage:

.ifdef VARIABLE

• VARIABLE - Variable/constant/etc., required. The code that follows will be processed if the variable has been defined.

Example:

.ifdef SOMETHING
    STA $00
.else
    STA $01
.endif

.ifndef

Test if variable has not been defined.

Can be accompanied by an .else and must be accompanied by an .endif.

Usage:

.ifndef VARIABLE

• VARIABLE - Variable/constant/etc., required. The code that follows will be processed if the variable has not been defined.

Example:

.ifndef SOMETHING
    STA $01
.else
    STA $00
.endif

.incbin

Include binary file.

Usage:

.incbin "FILENAME"[, OFFSET[, LIMIT]]

• "FILENAME" - Path to file, required. Must be within quotes.
• [, OFFSET - File offset index, optional. Index at which to start including binary file.
• [, LIMIT]] - Limit in bytes, optional. Number of total bytes to include.

Example:

.incbin "file.bin"

.include

Include assembly file.

Usage:

.incbin "FILENAME"

• "FILENAME" - Path to file, required. Must be within quotes.

Example:

.include "file.asm"

Included files share a global state with other included files and the main entry point file. That means if a variable is defined in one file, it is available to all other files, provided that they are included after the definition.

Relative filenames in .include — and in every filename-based directive (.incbin, .incpng, .incpal, .incrle, .incwav, .inestrn) — are resolved relative to the directory of the file that contains the directive. A file included from a subdirectory therefore resolves its own includes and assets from that subdirectory, not from the top-level project directory. A path prefixed @/ is the escape from this: see Project-root-relative paths below.

Declaring a filename argument

Any filename argument may be written with a file:// prefix, which declares that the string names an input file:

.incbin "file://logo.chr"
.include "file://defs.asm"

The prefix is stripped before the path is used, so the two spellings load exactly the same file — file:// adds information about the argument rather than changing it. It is a marker, not a URL scheme: there is no host part and no percent-decoding, and file:///path/to/logo.chr is simply the absolute spelling.

The declaration earns its keep on a custom pseudo-instruction, where the assembler otherwise cannot tell that a string is a path. On the built-in directives above it is accepted, harmless, and redundant — their arguments are already known to be filenames — but it lets you write every path in a project the same way. Editors make a declared path clickable either way.

Project-root-relative paths

A filename argument beginning @/ resolves from the project root instead of the containing file's directory:

.include "@/lib/macros.asm"
.incbin  "@/assets/logo.chr"
.incpng  "@/art/tiles.png"

@/lib/macros.asm names the same file no matter which directory the .include sits in — copying that line into a file three levels deeper still finds it, where a relative path would need ../../../lib/macros.asm at that depth and break the moment the file moves again. Everything after the @/ is a path relative to the root:

The project root is found by walking up from the entry file for the nearest .nessemblerc, .nessemblerc.json, or .nessembleignore — the root is the directory containing that marker. A project that already has one of these files gets @/ for free. With no marker anywhere above it, the entry file's own directory is the root, which makes @/foo mean ./foo for a lone source file. The --root CLI flag, and an open editor's workspace folder, both override the walk-up explicitly.

@/ composes with file://: the declaration is stripped first, so "file://@/lib/defs.asm" is a declared, root-relative path — see Declaring a filename argument above and Declaring file arguments for what a custom pseudo-op's script receives.

A @/ path that cannot be resolved is a hard error rather than a silent fallback to file-relative resolution: this happens when no project root can be determined at all (only reachable from the browser playground, which has no filesystem), or when the path climbs back out of the root, e.g. "@/../secret.bin".

.incpal

Include palette from PNG.

Usage:

.incpal "FILENAME"

• "FILENAME" - Path to file, required. Must be within quotes.

Example:

.incpal "palette.png"

The PNG will be scanned, row-by-row/pixel-by-pixel, from the top-left to the bottom-right until it encounters 4 different, but not necessarily unique, colors.

.incpng

Include PNG.

Converts the PNG to CHR tiles. The image must include only 4 colors:

Other colors may be used, but accuracy is not guaranteed.

Usage:

.incpng "FILENAME"

• "FILENAME" - Path to file, required. Must be within quotes.

Example:

.incpng "image.png"

Read more about PPU pattern tables here.

.incrle

Include binary data to be RLE-encoded

The RLE-encoding scheme used is one featured in a few Konami NES titles, known as Konami RLE. The breakdown of bytes:

Usage:

.incrle "FILENAME"

• "FILENAME" - Path to file, required. Must be within quotes.

Read more about NES RLE compression here.

.incwav

Include WAV.

Converts WAV to a 1-bit PCM.

Usage:

.incwav "FILENAME"[, AMPLITUDE]

• "FILENAME" - Path to file, required. Must be within quotes.
• [, AMPLITUDE] - Amplitude, optional. Amplitude of WAV.

Example:

.incwav "audio.wav", 24

.ines2

Emit a NES 2.0 header.

Sets bits 2-3 of Flags 7 to the NES 2.0 identifier (10) and switches the output header from iNES 1.0 to NES 2.0, which widens the mapper (0-4095) and PRG/CHR sizes and repurposes bytes 8-15.

When NES 2.0 mode is active, some existing directives change meaning:

• .inesprg / .ineschr become 12-bit (the byte-9 MSB nibbles are written automatically for counts above 255).
• .inesmap becomes 12-bit (writes byte 8 as well).
• .inesprgram targets the NES 2.0 PRG-RAM field and takes a byte size (not 8 KB units).
• .inestv provides the NTSC/PAL fallback for the .inestiming byte.
• .inesvs / .inespc10 become sugar for the .inesconsole type.

NES 2.0-only directives (.inessubmap, .inesprgnvram, .ineschrram, .ineschrnvram, .inestiming, .inesconsole, .inesvsppu, .inesvshw, .inesmiscrom, .inesexpansion) require this directive.

Usage:

.ines2 FLAG

• FLAG - Number, required. Non-zero to emit a NES 2.0 header.

Example:

.ines2 1

.ines4scr

iNES four-screen VRAM flag.

Sets bit 3 of Flags 6 (the "alternative nametable layout" bit), used by boards that provide four-screen VRAM instead of the hard-wired mirroring selected by .inesmir.

Usage:

.ines4scr FLAG

• FLAG - Number, required. Non-zero to set four-screen VRAM.

Example:

.ines4scr 1

.inesbat

iNES battery / persistent memory flag.

Sets bit 1 of Flags 6, indicating the cartridge contains battery-backed PRG-RAM at $6000-$7FFF (or other persistent memory).

Usage:

.inesbat FLAG

• FLAG - Number, required. Non-zero to indicate persistent memory.

Example:

.inesbat 1

.ineschr

iNES CHR count.

Usage:

.ineschr COUNT

• COUNT - Number, required. Number of CHR banks. In NES 2.0 mode a count above 255 also writes the byte-9 MSB nibble (up to 4095).

Example:

.ineschr 1

.ineschrnvram

NES 2.0 battery CHR-RAM size.

Sets the battery-backed CHR-RAM field (byte 11 bits 4-7) of a NES 2.0 header. Requires .ines2.

Usage:

.ineschrnvram BYTES

• BYTES - Number, required. Size in bytes: 0, or a power-of-two byte count from 128 to 2097152 (stored as the shift count size = 64 << n).

Example:

.ineschrnvram 8192

.ineschrram

NES 2.0 CHR-RAM size.

Sets the volatile CHR-RAM field (byte 11 bits 0-3) of a NES 2.0 header. Requires .ines2.

Usage:

.ineschrram BYTES

• BYTES - Number, required. Size in bytes: 0, or a power-of-two byte count from 128 to 2097152 (stored as the shift count size = 64 << n).

Example:

.ineschrram 8192

.inesconsole

NES 2.0 console type.

Sets bits 0-1 of Flags 7. Requires .ines2. This is the canonical form of .inesvs (value 1) and .inespc10 (value 2); setting a conflicting combination is an error.

Value 3 (extended console type) is not yet supported.

Usage:

.inesconsole NUMBER

• NUMBER - Number, required. Console type (0-3).

Example:

.inesconsole 1

.inesexpansion

NES 2.0 default expansion device.

Sets byte 15 (bits 0-5) of a NES 2.0 header. Requires .ines2.

Usage:

.inesexpansion NUMBER

• NUMBER - Number, required. Expansion device (0-63).

Example:

.inesexpansion 1

.inesmap

iNES mapper number.

Usage:

.inesmap NUMBER

• NUMBER - Number, required. Mapper number. iNES supports 0-255; in NES 2.0 mode the range widens to 0-4095 (byte 8 holds the high nibble). A value above 255 requires .ines2.

Read more about NES mappers here.

.inesmir

iNES mirroring.

Sets bit 0 of Flags 6, the hard-wired nametable arrangement. The other Flags 6 bits are controlled by their own directives: .inesbat (battery), .inestrn (trainer), and .ines4scr (four-screen VRAM).

xxxxxxx0
       |
       +- Mirroring: 0: horizontal (vertical arrangement)
                     1: vertical (horizontal arrangement)

Usage:

.inesmir NUMBER

• NUMBER - Number, required. Mirroring type.

.inesmiscrom

NES 2.0 miscellaneous ROM count.

Sets byte 14 (bits 0-1) of a NES 2.0 header, the number of miscellaneous ROMs present. Requires .ines2.

Usage:

.inesmiscrom NUMBER

• NUMBER - Number, required. Number of miscellaneous ROMs (0-3).

Example:

.inesmiscrom 1

.inespc10

iNES PlayChoice-10 flag.

Sets bit 1 of Flags 7, marking the ROM as a PlayChoice-10 title. This bit is not part of the official specification and most emulators ignore it. In NES 2.0 mode this is sugar for .inesconsole type 2.

Only the header bit is set. The optional 8 KB PlayChoice INST-ROM and PROM data sections are not emitted.

Usage:

.inespc10 FLAG

• FLAG - Number, required. Non-zero to mark a PlayChoice-10 title.

Example:

.inespc10 1

.inesprg

iNES PRG count.

Usage:

.inesprg COUNT

• COUNT - Number, required. Number of PRG banks. In NES 2.0 mode a count above 255 also writes the byte-9 MSB nibble (up to 4095).

Example:

.inesprg 1

.inesprgnvram

NES 2.0 battery PRG-RAM size.

Sets the battery-backed PRG-RAM field (byte 10 bits 4-7) of a NES 2.0 header. Requires .ines2.

Usage:

.inesprgnvram BYTES

• BYTES - Number, required. Size in bytes: 0, or a power-of-two byte count from 128 to 2097152 (stored as the shift count size = 64 << n).

Example:

.inesprgnvram 8192

.inesprgram

iNES / NES 2.0 PRG-RAM size.

In iNES mode, sets byte 8 of the header, the size of PRG-RAM in 8 KB units (a value of 0 infers 8 KB for compatibility).

In NES 2.0 mode, sets the volatile PRG-RAM field (byte 10 bits 0-3) and the argument is a byte size instead — pair it with .inesprgnvram for battery-backed PRG-RAM.

Usage:

.inesprgram SIZE

• SIZE - Number, required. In iNES mode, PRG-RAM size in 8 KB units. In NES 2.0 mode, a byte size: 0, or a power-of-two byte count from 128 to 2097152 (stored as the shift count size = 64 << n).

Example:

.inesprgram 1

.inessubmap

NES 2.0 submapper number.

Sets byte 8 (bits 4-7) of a NES 2.0 header, the submapper that distinguishes variants of a mapper. Requires .ines2.

Usage:

.inessubmap NUMBER

• NUMBER - Number, required. Submapper number (0-15).

Example:

.inessubmap 1

.inestiming

NES 2.0 CPU/PPU timing.

Sets byte 12 of a NES 2.0 header, the region timing. Requires .ines2. When unset, .inestv provides the NTSC/PAL value.

Usage:

.inestiming NUMBER

• NUMBER - Number, required. Timing (0-3).

Example:

.inestiming 0

.inestrn

iNES trainer include.

The assembled trainer must be no larger than 512 (0x200) bytes. The appropriate flag is automatically set in the iNES header to indicate a trainer is present.

Usage:

.inestrn "FILENAME"

• "FILENAME" - Path to file, required. Must be within quotes.

Example:

.inestrn "trainer.asm"

.inestv

iNES TV system.

Sets bit 0 of Flags 9, the TV system the ROM targets. PAL is also mirrored into the unofficial Flags 10 TV-system field (bits 0-1: 0 NTSC, 2 PAL) that some emulators honor. In NES 2.0 mode this instead provides the NTSC/PAL fallback for the .inestiming byte.

xxxxxxx0
       |
       +- TV system: 0: NTSC
                     1: PAL

Usage:

.inestv SYSTEM

• SYSTEM - Number, required. 0 for NTSC, 1 for PAL.

Example:

.inestv 1

.inesvs

iNES VS Unisystem flag.

Sets bit 0 of Flags 7, marking the ROM as a VS Unisystem arcade title. In NES 2.0 mode this is sugar for .inesconsole type 1.

Usage:

.inesvs FLAG

• FLAG - Number, required. Non-zero to mark a VS Unisystem title.

Example:

.inesvs 1

.inesvshw

NES 2.0 VS System hardware type.

Sets byte 13 (bits 4-7) of a NES 2.0 header. Only meaningful when the .inesconsole type is VS (1); ignored otherwise. Requires .ines2.

Usage:

.inesvshw NUMBER

• NUMBER - Number, required. VS System hardware type (0-15).

Example:

.inesvshw 0

.inesvsppu

NES 2.0 VS System PPU type.

Sets byte 13 (bits 0-3) of a NES 2.0 header. Only meaningful when the .inesconsole type is VS (1); ignored otherwise. Requires .ines2.

Usage:

.inesvsppu NUMBER

• NUMBER - Number, required. VS System PPU type (0-15).

Example:

.inesvsppu 0

.lobytes

Output only the low byte of 16-bit word(s).

Usage:

.lobytes NUMBER[, NUMBER]

• NUMBER - Number, required. At least one number is required.
• , NUMBER, ... - Number(s), optional. Additional comma-separated numbers may be used.

Example:

.lobytes $1234, $5678

Output:

00000000  34 78                                             |4x|
00000002

Try it:

.macro

Call macro.

Usage:

.macro MACRO[, NUMBER, ...]

• MACRO - Name, required. Name of previously-defined macro.
• , NUMBER, ... - Number(s), optional. Additional comma-separated numbers may be used.

Example:

.macro TEST_MACRO

See the section on Macros for more information.

.macrodef

Start macro definition.

Usage:

.macrodef MACRO
    CODE...
.endm

• MACRO - Name, required. Name of macro.
• CODE... - Code, required. Assembly code.

Example:

.macrodef TEST_MACRO
    LDA #\1
    STA <\2
.endm

See the section on Macros for more information.

.org

Organize code.

Set the address of the current bank in which to start organizing code.

Usage:

.org ADDRESS

Example:

.org $C000

.phase

Assemble code for a different run-time address.

When a PRG bank is swapped in at a different address than the one it is laid out at, the address labels receive (its .org) does not match where the code actually runs. .phase ADDRESS overrides the address labels receive so it reflects the run-time (post-swap) location, while ROM layout keeps flowing from .org unchanged. This removes the need to subtract the swap offset from every label by hand.

The override stays in effect until .dephase or a bank/segment switch (.prg, .chr, .segment). It applies only to symbol values; branch targets and emitted bytes are unaffected, since the offset cancels in any address difference.

Usage:

.phase ADDRESS

• ADDRESS - Number, required. The run-time address the current location maps to.

Example:

.prg 1
.org $C000       ; laid out at $C000 in ROM
.phase $8000     ; but swapped in at $8000 at run time

label_def:       ; label_def == $8000
    NOP
    JMP label_def

.dephase

.prg

Set PRG bank index.

Usage:

.prg NUMBER

• NUMBER - Number, required. PRG bank index.

Example:

.prg 0

PRG banks are 4K bytes (0x4000) in size.

.random

Output random byte(s).

The algorithm for the PRNG is the suggested POSIX implementation of rand().

Usage:

.random [SEED[, COUNT]]

• [SEED - Number or string, optional. Seeds the random number generator. Defaults to the current system time.
• [, COUNT]] - Number of bytes to output, optional. Defaults to 1.

Example:

.random "Secret Key", 16

.rsset

Set initial value for .rs declarations.

Usage:

.rsset ADDRESS

• ADDRESS - Number, required. Address to start .rs declarations.

Example:

.rsset $0000

.rs

Reserve space for variable declaration.

Usage:

VARIABLE .rs NUMBER

• VARIABLE - Variable name, required. Name of variable to declare.
• NUMBER - Number (in bytes) to reserve, required.

Example:

.rsset $0000

label_01 .rs 1
label_02 .rs 2
label_03 .rs 1

.db label_01, label_02, label_03

Output:

00000000  00 01 03                                          |...|
00000003

Try it:

.segment "SEGMENT[0-9]+"

.segment "PRG1"

.ease FUNCTION[, START[, END[, STEPS]]]

.ease "easeOutBounce", 0, $20, $40

00000000  00 00 00 00 00 01 02 02  03 04 06 07 08 0a 0b 0d  |................|
00000010  0f 11 13 16 18 1a 1d 1f  1e 1d 1c 1b 1a 19 19 18  |................|
00000020  18 18 18 18 18 18 18 19  19 1a 1b 1c 1d 1e 1f 1f  |................|
00000030  1e 1e 1e 1e 1e 1e 1e 1e  1f 1f 1f 1f 1f 1f 1f 20  |............... |
00000040

.macrodef TEST_MACRO
    LDA #$00
    STA $2005
    STA $2005
.endm

.macro TEST_MACRO

00000000  a9 00 8d 05 20 8d 05 20                           |.... .. |
00000008

.macrodef TEST_MACRO
    LDA #\1
    STA \2
    STA \2
.endm

.macro TEST_MACRO, $00, $2005

.macrodef TEST_MACRO
    LDA #\1
    STA \2
    STA \2
.endm

.macro TEST_MACRO, $00, $2005

.macrodef COUNT_PARAMS
    .db \#
.endm

.macro COUNT_PARAMS, $01, $01, $01

00000000  03                                                |.|
00000001

.macrodef TEST_MACRO
    LDX #$08
label_\@:
    DEX
    BNE label_\@:
.endm

.macro TEST_MACRO
.macro TEST_MACRO
.macro TEST_MACRO

00000000  a2 08 ca d0 fd a2 08 ca  d0 fd a2 08 ca d0 fd     |...............|
0000000f

nessemble lsp

vim.api.nvim_create_autocmd('FileType', {
  pattern = 'asm',
  callback = function(args)
    vim.lsp.start({
      name = 'nessemble',
      cmd = { 'nessemble', 'lsp' },
      root_dir = vim.fs.dirname(args.file),
    })
  end,
})

[language-server.nessemble]
command = "nessemble"
args = ["lsp"]

[[language]]
name = "assembly"
language-servers = ["nessemble"]

cargo run -p xtask -- vsix

{
  "[nessemble]": {
    "editor.formatOnSave": true,
    "editor.defaultFormatter": "kevinselwyn.nessemble"
  }
}

(add-to-list 'eglot-server-programs
             '(asm-mode . ("nessemble" "lsp")))

.foo = foo.rhai

.foo 1, 2, 3

nessemble example.asm --pseudo pseudo.txt

fn custom(ints, texts) {
    // ...
}

const SCALE = 3;

fn custom(ints, texts) {
    let out = [];
    for i in ints { out.push(i * SCALE); }
    out
}

fn custom(ints, texts) {
    let product = 0;
    let first = true;
    for i in ints {
        if first { product = i; first = false; } else { product *= i; }
    }
    [product % 256]
}

.product 1, 2, 3   ; emits a single byte: 6

.foo "easeInQuad", 0, 16

fn custom(ints, texts) {
    let name = texts[0];   // "easeInQuad"
    // ...
}

.tilemap "file://map.png", "file://tiles.png"

.tilemap "file://@/art/map.png"

fn custom(ints, texts) {
    if texts.is_empty() {
        throw "No arguments provided";
    }
    []
}

fn custom(ints, texts) {
    let out = "";
    for i in 0..ints[0] {
        out += "frame" + i + ": .db " + (i * 8) + "\n";
    }
    emit_source(out)
}

.frames 3
    LDA frame1   ; a label the emitted source defined, used right after it

fn custom(ints, texts) {
    read_blob("@/assets/shared.bin")
}

fn custom(ints, texts) {
    open_file(texts[0], "r").read_blob()
}

.embed "logo.chr"   ; emits the raw bytes of logo.chr

let img = decode_png(open_file("sprite.png", "r").read_blob());

let img = decode_png_file("sprite.png");

fn custom(ints, texts) {
    decode_png_file(texts[0]).tile(0, 0, 8, 8)   // top-left 8x8 tile's shades
}

fn custom(ints, texts) {
    let map = decode_png_file(texts[0]);
    let tiles = decode_png_file(texts[1]);
    let out = [];
    for row in 0..(map.height / 8) {
        for col in 0..(map.width / 8) {
            let i = tiles.find_cell(map, col, row, 8, 8);
            if i < 0 { i = tiles.nearest_cell(map, col, row, 8, 8); }
            out.push(i);
        }
    }
    out
}

// [43, 128, 213] are the midpoints between the four NES shades (0, 85, 170, 255).
let shades = quantize(img.tile(0, 0, 8, 8), [43, 128, 213]);

let shades = nes_shade(img.tile(0, 0, 8, 8));

fn custom(ints, texts) {
    let doc = parse_xml_file(texts[0]);
    let out = [];
    for row in doc.find_all("row") {
        out += parse_int_list(row.attr("data"), ",");
    }
    out
}

fn custom(ints, texts) {
    let doc = parse_json_file(texts[0]);
    let out = [];
    for tile in doc.tiles {
        out.push(tile.id);
    }
    out
}

fn custom(ints, texts) {
    let table = parse_csv_file(texts[0]);
    let out = [];
    for row in table {
        out.push(parse_int(row["max_speed_x"], 16));  // by column name
        out.push(parse_int(row[1], 16));               // or by position
    }
    out
}

let table = parse_csv_file(texts[0], #{ delimiter: "\t" });

let values = parse_int_list("1, 2,,3 ,", ",");   // [1, 2, 3]
let bytes = parse_int_list("ff,1a", ",", 16);    // [255, 26]

fn custom(ints, texts) {
    let out = [];
    for i in 0..ints[0] {
        out.push(rand(0, 255));
    }
    out
}

.noise 16   ; emits 16 random bytes

.ease "easeInQuad"

cargo build --release

cargo test

rustup target add i686-unknown-linux-gnu
cargo build --release --target i686-unknown-linux-gnu

cargo run -p xtask -- vsix

cargo build --release -p nessemble-cli --no-default-features

# ~/.nessemble/locales/de.ftl
no-errors = Alles gut

NESSEMBLE_LANG=de nessemble -c game.asm
# -> Alles gut

cargo fmt --all
cargo clippy --all-targets
cargo test

This program is free software: you can redistribute it and/or modify
it under the terms of the GNU General Public License as published by
the Free Software Foundation, either version 3 of the License, or
(at your option) any later version.

This program is distributed in the hope that it will be useful,
but WITHOUT ANY WARRANTY; without even the implied warranty of
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
GNU General Public License for more details.

You should have received a copy of the GNU General Public License
along with this program.  If not, see <http://www.gnu.org/licenses/>.