UTTORI ASM · IN DEVELOPMENT

Source and binary includes

Include source and binary files with checked paths and bounded ranges.

SNES behavior

incsrc, include, and includeonce

incsrc "hardware/registers.asm"
include "code/player.asm"

Both forms assemble another source file inline through the include service. incsrc and include preserve distinct host operations for compatibility, but ordinary source can think of both as source inclusion.

Place includeonce inside an included file to guard it once per assembly stage:

includeonce
!PPU_INIDISP = $2100

Relative paths resolve against the current source and configured include paths. Quoted paths may contain spaces. Defines expand in filenames. Write \! inside a quoted path for a literal exclamation mark. Include cycles and missing files are diagnosed.

includefrom is only an accepted no-op today. It does not assert or change the include graph.

incbin

Embed a whole file:

incbin "tiles.bin"

Use an inclusive start and exclusive end range:

incbin "tiles.bin":$100..$180

An end of 0 means EOF. The deprecated start-end spelling is supported for Asar fixtures, including parenthesized math, but .. is clearer and less likely to make a minus sign audition for the wrong role.

Seek temporarily with -> and then restore the original PC:

incbin "header.bin" -> HeaderLocation

The target may be a label, hexadecimal address, or decimal address. Inverted ranges, out-of-file bounds, malformed expressions, and absent targets are errors. The full grammar is tested in incbin.asm and include-source.test.ts.

6502 family behavior

Source

incsrc "hardware/registers.asm"     ; native
include "code/player.asm"           ; native
.include "a.asm"                  ; ca65; leading dot is the directive prefix

includeonce (native) guards a file once per assembly stage. Relative paths resolve against the current source and configured include paths. Include cycles and missing files are diagnosed.

Binary

Native / Asar-shaped incbin:

incbin "tiles.bin"
incbin "tiles.bin":$100..$180

ca65 .incbin uses filename, optional offset, optional size:

.incbin "data.bin", 2, 3     ; three bytes starting at offset 2

Do not mix the two grammars. incbin "file":$100..$180 is native. .incbin "file", 2, 3 is ca65.