Asar

Table of Contents

• Usage
  • Standard Includes
  • Standard Defines
• Architectures
  • Number Literals
  • Opcode Length Specification
  • Pseudo Opcodes
  • rep
• Mapping Modes
• Compatibility Settings
  • xkas
  • asar
  • warn xkas
  • math pri
  • math round
  • namespace nested
• Code Formatting
  • Comments
  • Brackets
  • Multi-Line Operators
  • Single-Line Operator
• Program Counter
  • org
  • base
  • skip
  • warnpc
  • bank
  • dpbase
  • optimize dp
  • optimize address
  • pushpc/pullpc
  • pushbase/pullbase
  • The spc700-inline architecture
• Math
• Labels
  • Main Labels
  • Sub Labels
  • +/- Labels
  • Macro Labels
  • Structs
  • Namespaces
  • pushns/pullns
  • Global labels
• Defines
  • Nested Defines
  • Built-in Defines
• Macros
• Functions
  • Built-in Functions
• Conditional Compilation
  • if/elseif/else/endif
  • while
  • for
• Binary Data
  • Tables
  • fillbyte/fill
  • padbyte/pad
  • incbin
• Includes
  • incsrc
  • include/includefrom
  • includeonce
• Freespace
  • freespace/freecode/freedata
  • autoclean
  • prot
• Text Output
  • print
  • warn
  • error
  • assert
• Checks
  • check title
  • check bankcross
• Warnings
  • Disabled Warnings
  • warnings {push/pull}
  • warnings {enable/disable}

Usage

	asar.exe [options] {asm_file} [rom_file]

asar.exe --version C:/homebrew/my_game/main.asm

asar.exe -v C:/homebrew/my_game/main.asm

asar.exe --verbose C:/homebrew/my_game/main.asm

asar.exe --no-title-check C:/homebrew/my_game/main.asm

asar.exe --pause-mode=always C:/homebrew/my_game/main.asm

C:/homebrew/my_game.asm

-I"C:/homebrew/binary data"

incbin "data/player_gfx.bin"

C:/homebrew/data/player_gfx.bin

C:/homebrew/binary data/data/player_gfx.bin

asar.exe -IC:/homebrew/my_game/includes -IC:/homebrew/shared
	C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.sfc

asar.exe --include C:/homebrew/my_game/includes
	C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.sfc

asar.exe -Ddebug -Dskip_title_screen=0
	C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.sfc

asar.exe --define debug=1 --define mytext=" value with whitespace "
	C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.sfc

asar.exe --symbols=wla C:/homebrew/my_game/main.asm

asar.exe --symbols=wla
	--symbols-path=C:/homebrew/my_game/symbols/main.symbols
	C:/homebrew/my_game/main.asm

asar.exe -wW1023 C:/homebrew/my_game/main.asm

asar.exe -wnoW1013 C:/homebrew/my_game/main.asm

asar.exe --fix-checksum=on C:/homebrew/my_game/main.asm

asar.exe C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.sfc

asar.exe C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.sfc

asar.exe C:/homebrew/my_game/main.asm C:/homebrew/my_game/bin/my_game.smc

asar.exe C:/homebrew/my_game/main.asm

Standard Includes

C:/asm/stdlib

    ./debug
../../my_game/libraries
		test/

Standard Defines

!stddefined1=1
 stddefined2=1

stddefined3
stddefined4 = 1 
stddefined5 = " $60,$50,$40 "

Architectures

arch 65816
lda $00

arch spc700
mov a,$00

Number Literals

lda $00
clc
adc #-10
and #%01111111
lda #~$80	; Equal to lda #$FFFFFF7F

lda #'a'
sta $00

db 'x','x'+1,'x'+2

Opcode Length Specification

lda #0		; Could be either lda #$00 or lda #$0000
lda.b #0	; Always lda #$00
lda.w #0	; Always lda #$0000

Pseudo Opcodes

{opcode} #{num}

nop #3
		
inx #2

nop
nop
nop

inx
inx

rep

rep {num} : {code}

macro writeval(val)
	db <val>
endmacro
		
macro memset(val, num)
	rep <num> : %writeval(<val>)
endmacro

rep 16 : %memset($00, 16)

Mapping Modes

sa1rom 0,1,4,6

lorom
org $008000
db $FF		; Will write to PC address 0x000000

hirom
org $008000
db $FF		; Will write to PC address 0x008000

Compatibility Settings

xkas

;@xkas

!is_asar=0	
;@!is_asar=1

;@if !is_asar == 0
	macro do_something()
		; Do something xkas-specific here
	endmacro
;@else
;@	macro do_something()
;@		; Do something asar-specific here
;@	endmacro
;@endif

do_something()

asar

asar {ver}

; This patch uses features from Asar 1.40, so it makes sense to require it as a minimum.
@asar 1.40

if readfile1("data.bin", 0) == 1
	; Do something
else
	; Do something else
endif

warn xkas

warn xkas {on/off}

math pri

math pri {on/off}

math pri off
db 1+(6/3)*5	; db 15

math pri on
db 1+(6/3)*5	; db 11

math round

math round {on/off}

math round on
; 1.75 is immediately truncated to 1, resulting in (3/4)+1
; 3/4 would result in 0.75, which is immediately truncated to 0, resulting in 0+1
; Thus leading to the final result of "db 1"
db (3/4)+1.75

; !some_number contains 0 after this line
!some_number #= 0.75

math round off
; As expected will result in 0.75+1.75, which will result in 2.5
; 2.5 is truncated to 2
; Thus leading to the final result of "db 2"
db (3/4)+1.75

; !some_number contains 0.75 after this line
!some_number #= 0.75

namespace nested

namespace nested {on/off}

Code Formatting

Comments

	lda $00		; Asar only sees the lda $00 and ignores everything else

Brackets

	lda $00
	beq .IsZero
	
.GreaterThanZero
	{
		dec $00
	}

.IsZero
	rts

Multi-Line Operators

%some_macro(!arg1, !arg2, !arg3,
	!arg4, !arg5, !arg6)
; This will be treated as "%some_macro(!arg1, !arg2, !arg3, !arg4, !arg5, !arg6)"

lda \
	$7F0000
; This will be treated as "lda $7F0000"

function func(param) = ((param*param)+1000)\
	/256
; This will be treated as "function func(param) = ((param*param)+1000)/256"

Single-Line Operator

lda #$00 : sta $00
		
; Treated as:
lda #00
sta $00

Program Counter

org

org {snes_address}

org $008000
MainEntryPoint:
	; ...

base

base {snes_address/off}

org $008000
MainEntryPoint:
	; Some code which copies SomeRamRoutine to $7E0000 goes here
	; ...
	jsl $7E0000
	; ...

SomeRamRoutine:
base $7E0000
	; ...
base off
	rtl

skip

skip {num_bytes}
skip align {alignment} [offset {offset}]

org $008000
skip 5
; pc is now at $008005
skip -1
; pc is now at $008004
skip align 16
; pc is now at $008010
skip align 16 offset 5
; pc is now at $008015
skip align $20 offset $17
; pc is now at $008017

warnpc

warnpc {snes_address}

org $008000
incbin datafile.bin
warnpc $008100		; Throws an error if datafile.bin is larger than $100 bytes.

bank

bank {data_bank/noassume/auto}

bank $FF
		
lda DataTable,x

DataTable:
	db $01,$02,$03,$04

org $008000
phb
lda #$FF
pha
plb

bank $FF
; ...
bank auto

plb

dpbase

dpbase {snes_address}

SpriteTable = $7E0200
dpbase $0200
optimize dp ram

org $008000
lda SpriteTable,x

optimize dp

optimize dp {none/ram/always}

optimize address

optimize address {default/ram/mirrors}

pushpc/pullpc

org $008000
		
Main:
	jsl CodeInAnotherBank

pushpc
org $018000

CodeInAnotherBank:
	; ...
	rtl
	
pullpc

bra Main

pushbase/pullbase

base $7E2000
		
InsideRam:
	jsl OutsideOfRam
	; ...

pushbase
pushpc
base off

freecode

OutsideOfRam:
	; ...
	jsl InRamAgain
	rtl

pullpc
pullbase

InRamAgain:
	; ...
	rtl

base off

The spc700-inline architecture

spcdata_start:
arch spc700-inline
org $0400 ; position in APU RAM to copy block to
startpos main ; label (or address in APU RAM) to jump to after uploading
main:
; any spc code here
mov a,$00
ret
org $0600
; this label will end up at $0600 in APU RAM
data:
db $00,$01,$02
arch 65816
spcdata_end:
; now, you can copy each byte from spcdata_start to spcdata_end to $2141
		

Math

lda #6*2+5	; the same as "lda #17"
lda #5+6*2	; the same as "lda #22"

math pri on
		
lda #6*2+5	; the same as "lda #17"
lda #5+6*2	; the same as "lda #17"

math pri on
		
lda #5+6*2	; the same as "lda #17"
lda #(5+6)*2	; the same as "lda #22"

+  : Addition (Also valid as prefix, but a no-op)
-  : Subtraction (Or negation prefix)
*  : Multiplication
/  : Division
%  : Modulo (the remainder of a division, fmod() in C)
<< : Left-shift ( x << y formula: x = x * 2^y )
>> : Right-shift ( x >> y formula: x = x / 2^y )
&  : Bitwise AND
|  : Bitwise OR
^  : Bitwise XOR (Note: not exponentials)
~  : Bitwise NOT (Prefix)
<: : Bitshift right 16, shorthand for isolating address bank (Prefix)
** : Exponentials (2**4 = 2*2*2*2 = pow(2, 4) in C)

lda .Data+3	; Will load $03 into A
		
.Data
	db $00,$01,$02
	db $03,$02,$03

Labels

Main Labels

[#]{identifier}:

org $008000
		
Main:
	%do_frame()
	jmp Main	; Equal to jmp $8000

{identifier} = {snes_address}

Main:
; ...

SomewhereInRom = $04CA40

.Sub:
; ...

Table:
	dl Main_Sub                 ; Okay!
	dl SomewhereInRom_Sub       ; Error, label not found

macro my_new_routine()
	jsl MyNewRoutine
			
	!macro_routine_defined ?= 0
	
	if !macro_routine_defined == 0
		pushpc
		
		freecode cleaned
		
		#MyNewRoutine:
			incsrc routines/mynewroutine.asm
		
		pullpc
	
		!macro_routine_defined = 1
	endif
endmacro

Main:
	%my_new_routine()
.Sub

	; Both of these are found
	dl MyNewRoutine
	dl Main_Sub

Sub Labels

[#].{identifier}[:]

Proc1:
	nop
.Sub
	bra .Sub
	
Proc2:
	nop
.Sub:	; Note that the colon is optional
	bra .Sub

Main1:
	; ...
.Sub1:
	; ...
.Sub2:
	; ...
	
Main2:
	; ...
.Sub1:
	; ...
.Sub2:
	; ...
	
Table:
	dl Main1_Sub1
	dl Main1_Sub2
	dl Main2_Sub1
	dl Main2_Sub2

Main1:
; ...
.Sub:
; ...
..Deeper:
; ...
...TheEnd:
; ...

Table:
	dl Main1_Sub_Deeper_TheEnd

+/- Labels

+[+...][:]

-[-...][:]

	ldx.b #4
		
--			; A
	lda $10,x
	beq +		; Branches to "C"
		
	ldy.b #8
	
-			; B
	%do_something()
	
	dey
	bne -		; Branches to "B"
	
+:			; C - note that +/- labels can also include an optional colon in their declaration
	dex
	bpl --		; Branches to "A"

lorom
org $008000

---			; :neg_3_1
-			; :neg_1_1
	bra -
--			; :neg_2_1
-			; :neg_1_2
	bra ---
	bra --
	bra -
	
	bra ++
	bra +
	bra +++
	
++			; :pos_2_0
+			; :pos_1_0
	bra ++
++			; :pos_2_1
+++			; :pos_3_0

Macro Labels

[#]?{identifier}:

?{identifier} = {snes_address}

[#]?.{identifier}[:]

?+[+...]

?-[-...]

macro do_something()
	?MacroMainLabel:
	?.MacroSubLabel
	?-
		; All of these are fine!
		dl ?MacroMainLabel
		dl ?.MacroSubLabel
		dl ?-
		dl ?+
		dl ?MacroMainLabel_MacroSubLabel
	?+
endmacro

%do_something()

; ERROR! ?MacroMainLabel is undefined, because we're not inside %do_something() anymore.
dl ?MacroMainLabel

Structs

struct {identifier} {snes_address}
	[label...]
endstruct [align num]

pushpc
base snes_address

base off
pullpc

struct ObjectList $7E0100
	.Type: skip 1
	.PosX: skip 2
	.PosY: skip 2
	.SizeX: skip 1
	.SizeY: skip 1
endstruct

lda ObjectList.PosY

lda $7E0103		; $7E0100+1+2

lda ObjectList[2].PosY

struct ObjectList $7E0100
	.Type: skip 1
	.PosX: skip 2
	.PosY: skip 2
	.SizeX: skip 1
	.SizeY: skip 1
endstruct align 16

lda ObjectList[2].PosY

struct ObjectList $7E0100
	.Type: skip 1
	.PosX: skip 2
	.PosY: skip 2
	.SizeX: skip 1
	.SizeY: skip 1
	.Properties: skip 10
endstruct align 16

lda ObjectList[2].PosY

struct {extension_identifier} extends {parent_identifier}
	[label...]
endstruct [align num]

struct ObjectList $7E0100
	.Type: skip 1
	.PosX: skip 2
	.PosY: skip 2
	.SizeX: skip 1
	.SizeY: skip 1
endstruct

struct Properties extends ObjectList
	.Palette: skip 1
	.TileNumber: skip 2
	.FlipX: skip 1
	.FlipY: skip 1
endstruct

lda ObjectList.Properties.FlipX

lda ObjectList[2].Properties.FlipX

lda ObjectList.Properties[2].FlipX

• It's possible to extend a single struct with multiple extension structs. However, this can be counter-intuitive. The size of the extended struct becomes the size of the parent struct plus the size of its largest extension struct, rather than the size of the parent struct plus the sizes of each of its extension structs. This also means that when accessing those extension structs, they all start at the same offset relative to the parent struct. This can be confusing and is often not what's actually intended, so for code clarity, it's recommended to only extend structs with at most a single other struct.
• It's possible to enforce alignments when using extension structs. However, this will only determine the alignment of the parent struct and/or the extension struct(s), depending on where it's specified. It won't determine the alignment of the combined struct. This can be confusing and is usually not what is intended. There currently is no universal workaround for this, so when a certain alignment is required for a struct, it's recommended to not use extension structs with it.
• It's not possible to access both, a parent struct and its extension struct, as arrays simultanously.
• An extension struct can't be extended itself.

Namespaces

namespace {identifier}

namespace off

; All of the below is valid
		
namespace nested on
		
Main:                           ; Main
Main2:                          ; Main2
		
namespace Deep

	Main:                       ; Deep_Main
	
	namespace Deeper
	
		Main:                   ; Deep_Deeper_Main
		Main3:                  ; Deep_Deeper_Main3
		
		namespace Deepest
			
			Main:               ; Deep_Deeper_Deepest_Main
			
			dl Main             ; Deep_Deeper_Deepest_Main
			dl Main2            ; Main2
			dl Main3            ; Deep_Deeper_Main3
			
		namespace off		
			
		dl Main                 ; Deep_Deeper_Main
		
	namespace off	
			
	dl Main                     ; Deep_Main
	
namespace off


namespace nested off

namespace TheFirst

	Main:                       ; TheFirst_Main
	
	dl Main                     ; TheFirst_Main
	
namespace TheSecond

	Main:                       ; TheSecond_Main
	
	dl Main                     ; TheSecond_Main
	
namespace TheThird

	Main:                       ; TheThird_Main
	
	dl Main                     ; TheThird_Main
	
namespace off

			
dl Main                         ; Main
dl Deep_Main                    ; Deep_Main
dl Deep_Deeper_Main             ; Deep_Deeper_Main
dl Deep_Deeper_Deepest_Main     ; Deep_Deeper_Deepest_Main

dl TheFirst_Main                ; TheFirst_Main
dl TheSecond_Main               ; TheSecond_Main
dl TheThird_Main                ; TheThird_Main

pushns/pullns

Global labels

namespace NS
global GlobalLabel:
.Sub: ; this is a sublabel of GlobalLabel

LocalLabel:

global #AnotherGlobal: ; this global won't modify the sublabel hierarchy

.Sub: ; this is a sublabel of LocalLabel
namespace off

; these are all valid:
dl NS_LocalLabel
dl NS_LocalLabel_Sub
dl GlobalLabel
dl GlobalLabel_Sub
dl AnotherGlobal
		

Defines

!{identifier} = {value}

!{identifier} = "{value}"

!x = $00
		
lda !x		; Treated as "lda $00"
lda #!x		; Treated as "lda #$00"
lda [!x],y	; Treated as "lda [$00],y"

!y = $12
!x = !y$34
		
lda !x		; Treated as "lda $12$34" (will throw error)
		
!phr = "pha : phx : phy"
		
!phr		; Treated as "pha : phx : phy"

!define = 10
!anotherdefine = !define+1
; !define now contains "10" and !anotherdefine now contains "!define+1"

!define = 10
!define += 1
; !define now contains "101"

!define = 10
!define := !define+1
; !define now contains "10+1"

!define = 10
!anotherdefine #= !define+1
; !anotherdefine now contains "11"

!define ?= 10
!define ?= 1
; !define now contains "10"

!define = "hello"
		
if defined("define")
	print "This will be printed!"
endif

undef "define"
		
if defined("define")
	print "This won't be printed!"
endif

Nested Defines

!hex = $
		
db !hexFF     ; Error - define !hexFF not found
db !{hex}FF   ; OK

; Please specifiy a mode from 0 to 3
!mode = 1

assert !mode >= 0 && !mode <= 3, "Please specify a mode from 0 to 3!"

!modename0 = "Default"
!modename1 = "Debug"
!modename2 = "Fast"
!modename3 = "Small"

!modenamestring = !{modename!{mode}}

print "Building in mode: !modenamestring"

Built-in Defines

if not(stringsequal("!assembler", "asar"))
	warn "This patch was written for Asar and may not be compatible with your current assembler."
endif

if !assembler_ver < 10600
	warn "This patch might not behave correctly due to a bug in Asar versions prior to 1.60."
endif

Macros

• Macros only record a sequence of commands rather than any kind of text.
• A macro call is itself considered a command and thus needs to go on its on line (or separated via the single-line operator ). This means that unlike a define, a macro can't just be used whereever.
• Macros can include parameters, which are identifiers that are replaced by a text value whenever the respective macro is called. For simplicity, you could consider parameters a macro-specific version of defines.

macro {identifier}([parameter1_identifier[, parameter2_identifier...]][variadic_token])
	[command1]
	[command2...]
endmacro

%{identifier}([parameter1[, parameter2...]])

macro mov(target, source)
	lda <source>
	sta <target>
endmacro

macro swap(first, second)
	%mov($00, <first>)
	%mov(<first>, <second>)
	%mov(<second>, $00)
endmacro

macro use_x_safely(code)
	phx
	<code>
	plx
endmacro

%swap($01, $02)
%use_x_safely("ldx $10 : stx $11 : ldx #10 : stx $12")

macro example0(...)
	db sizeof(...), <...[0]>	;04 01
endmacro
	
macro example1(...)
	!a #= 0
	while !a < sizeof(...)
		db <...[!a]>		;01 02 03
		!a #= !a+1
	endif
endmacro

macro example2(named_parameter, ...)
	!a #= 0
	while !a < sizeof(...)
		db <...[!a]>		;02 03 04 05 06 07
		!a #= !a+1
	endif
	db <named_parameter>	;01
endmacro

macro macro_with_optional_arguments(required, ...)
	db <required>
	if sizeof(...) > 0
		db <...[0]>
	end
end

%example0(1,2,3,4)
%example1(1,2,3)
%example2(1,2,3,4,5,6,7)
%macro_with_optional_arguments(1)
%macro_with_optional_arguments(2, 3)

Functions

function {identifier}([parameter1_identifier[, parameter2_identifier...]]) = {some_math_statement}

function kilobytes_to_bytes(kb) = kb*1024
function megabytes_to_kilobytes(mb) = mb*1024
function megabytes_to_bytes(mb) = kilobytes_to_bytes(megabytes_to_kilobytes(mb))

; Will print "4 MB = 4194304 bytes."
print "4 MB = ",dec(megabytes_to_bytes(x))," bytes."


function data_index_to_offset(index) = index*2

lda .Data+data_index_to_offset(2)	; Will load $0002 into A

.Data
	dw $0000
	dw $0001
	dw $0002

Built-in Functions

if read1($00FFD5) == $23
	!is_sa1_rom = 1
else
	!is_sa1_rom = 0
endif

!readresult = readfile4("datafile.bin", 0, $FFFFFFFF)
				
if !readresult != $FFFFFFFF
	print "Read $",hex(!readresult)," from datafile.bin."
endif

if canread1($00FFD5) == 1
	print "Detected ROM type: $",hex(read1($00FFD5))
else
	error "Failed to detect ROM type!"
endif

if canreadfile4("datafile.bin", 512) == 1
	print "Read $",hex(readfile4("datafile.bin", 512))," from datafile.bin at position 512."
else
	error "datafile.bin either doesn't exist or is too small."
endif

!fsize #= filesize("datafile.bin")
!fpos = 0

assert !fsize >= 0, "datafile.bin doesn't exist or can't be opened".
				
while !fpos < !fsize
	; Do something with datafile.bin here, like calling readfile1("datafile.bin", !fpos)
	;...
	
	!fpos #= !fpos+1
endif

assert getfilestatus("datafile.bin") != 1, "datafile.bin doesn't seem to exist"

print "SNES address $018000 in the current mapping mode is equivalent to PC address 0x",dec(snestopc($018000))

!start_index #= max(!current_index-1, 0)

!used_amount #= clamp(!used_percentage, 0.0, 1.0)*!total_amount

!single_sprite_memory = safediv(!total_sprite_memory, !max_num_sprites, 0)

function sprite_size() = select(!extra_bytes_enabled, 16+4, 16)

function required_sprite_memory(num_sprites) = not(!sprites_disabled)*sprite_size()*num_sprites

lda #bank(some_label)

function abs(num) = select(less(num, 0), num*-1, num)

function total_sprite_extra_bytes(num_sprites) = select(and(not(!sprites_disabled), !extra_bytes_enabled), 4, 0)*num_sprites

if round(!distance, 2) == 0.0
	error "Distance is zero or almost zero. Please choose a bigger value for distance as small values will cause problems."
endif

!banks_used #= ceil(!data_size/65536)

if defined("include_guard") == 0
	!include_guard = 1	
	; ...	
endif

struct parent $0000
	.data1: skip 2
endstruct

struct child extends parent
	.data2: skip 3
endstruct

db sizeof(parent)             ; db 2
db sizeof(parent.child)       ; db 3

struct parent $0000
	.data1: skip 2
endstruct

struct child extends parent
	.data2: skip 3
endstruct

db objectsize(parent)         ; db 5
db objectsize(parent.child)   ; db 3

org $008000
main:

lda #datasize(my_table)		;3
lda #datasize(other_label)	;0x7FF3 (last label, throws a warning. calculated as $FFFFFF-$00800C)
lda #datasize(main)		;9


my_table:
	db $00, $00, $02
other_label:

if not(stringsequal("!assembler", "asar"))
	warn "This patch was only tested in Asar and might not work correctly in your assembler."
endif

if not(stringsequalnocase("!assembler", "ASAR"))
	warn "This patch was only tested in Asar and might not work correctly in your assembler."
endif

function read1(x) = _read1(x+$010000)

function readfilenormalized(filename, pos) = readfile4(filename, pos)/2147483648.0
db readfilenormalizd("datafile.bin", 0)

Conditional Compilation

if/elseif/else/endif

if {condition}
	{codeblock}
endif

!mode = 0	; Supported modes: 0, 1, 2, 3
!verbose = 0	; Set to 1 to enable verbose mode

if !mode == 0
	; ...
elseif !mode == 1
	; ...
elseif !mode == 2
	; ...
elseif !mode == 3
	if !verbose != 0
		print "Oh boy, so you're going with mode 3 today!"
	endif
	; ...
else
	error "Unsupported mode! Please choose 0, 1, 2 or 3!"
endif

if {condition} : {codeblock}[ : codeblock...]

PressedY:
	if !fireballs_enabled : %PlaySoundEffect(!fireball_sfx) : jsr ShootFireball
	rtl
		

FirstLabel = $018000
		
freecode
	lda SecondLabel,x
	
SecondLabel:
	db $00,$01,$02,$03
	
; All good. FirstLabel was statically defined.
if FirstLabel == 0
endif

; Error. The label could move between passes.
if SecondLabel == 0
endif

while

!counter = 0
		
while !counter < $10
	db (!counter<<8)|$00,(!counter<<8)|$01,(!counter<<8)|$02,(!counter<<8)|$03
	db (!counter<<8)|$04,(!counter<<8)|$05,(!counter<<8)|$06,(!counter<<8)|$07
	db (!counter<<8)|$08,(!counter<<8)|$09,(!counter<<8)|$0A,(!counter<<8)|$0B
	db (!counter<<8)|$0C,(!counter<<8)|$0D,(!counter<<8)|$0E,(!counter<<8)|$0F
			
	!counter #= !counter+1
endwhile

for

for i = 1..5
	db !i
	db 2*!i
endfor

Binary Data

Tables

db {value}[,value...]

dw {value}[,value...]

dl {value}[,value...]

dd {value}[,value...]

org $0189AB
Label:

; This will write the following data to the ROM:
; $01  $03  $07  $AB  $41 $42 $43
db $01,$0203,$04050607,Label,"ABC"
; This will write the following data to the ROM:
; $01 $00  $03 $02  $07 $06  $AB $89  $41 $00 $42 $00 $43 $00
dw $01,$0203,$04050607,Label,"ABC"
; $01 $00 $00  $03 $02 $00  $07 $06 $05  $AB $89 $01  $41 $00 $00 $42 $00 $00 $43 $00 $00
dl $01,$0203,$04050607,Label,"ABC"
; $01 $00 $00 $00  $03 $02 $00 $00  $07 $06 $05 $04  $AB $89 $01 $00  $41 $00 $00 $00 $42 $00 $00 $00 $43 $00 $00 $00
dd $01,$0203,$04050607,Label,"ABC"

table {filename}[,rtl/ltr]

{character}={value}
[character=value...]

{value}={character}
[value=character...]

'{character}' = {value}

; Contents of table1.txt:
;A=1A
;B=1B
;C=1C

; Contents of table2.txt:
;1D=A
;1E=B
;1F=C

; This writes $41 $42 $43
db "ABC"

table "table1.txt",ltr

; This writes $1A $1B $1C
db "ABC"

pushtable
table "table2.txt",rtl

; This writes $1D $1E $1F
db "ABC"

pulltable

; This writes $1A $1B $1C
db "ABC"

cleartable

; This writes $41 $42 $43
db "ABC"

'A' = $20
'B' = $20+1
'C' = $20+2

; Those both write $20 $21 $22
db "ABC"
db 'A','B','C'

!define = "text"
		
; This writes "text" to the ROM
db "!define"

; This writes "!define" to the ROM
db "\!define"

; This writes "\text" to the ROM
db "\\!define"
; This writes 'something "cool"' to the ROM
db "something ""cool"""

fillbyte/fill

fillbyte {byte}

fill {num}
fill align {alignment} [offset {offset}]

fillbyte $FF
; This writes $FF $FF $FF $FF $FF $FF $FF $FF
fill 8
org $008005
; this writes $FF until SNES address $00800A (=$8008 + 2)
fill align 8 offset 2

padbyte/pad

padbyte {byte}

pad {snes_address}

org $008000
padbyte $FF
; This writes $FF $FF $FF $FF
pad $008004

incbin

incbin {filename}[:range_start..range_end][ -> label_identifier_or_sness_address]

; datafile.bin contains the following bytes:
; $00 $01 $02 $03 $04 $05 $06 $07 $08 $09 $0A $0B $0C $0D $0E $0F

; This writes $00 $01 $02 $03 $04 $05 $06 $07 $08 $09 $0A $0B $0C $0D $0E $0F
incbin "datafile.bin"

; This writes $09 $0A $0B $0C $0D $0E
incbin "datafile.bin":9-F

; This writes $01 $02 $03 $04
incbin "datafile.bin":($F-$E)-(2+3)

pushpc
freedata align

{label_identifier}:
incbin {filename}

pullpc

pushpc

org {snes_addres}
incbin {filename}

pullpc

Includes

1. If the path is an absolute path:
   1. Asar tries to locate the file directly via the specified path.
   2. If this fails, an error is thrown.
2. If the path is a relative path:
   1. Asar tries to locate the file relatively to the file currently being assembled. (Caution: when used inside macros, paths are relative to the macro definition rather than to the macro call).
   2. If this fails, Asar tries to locate the file relatively to any of the include search paths that were specified, in the order they were specified in, until the file is found. (See section Usage for details on include search paths).
   3. If all of the previous fail, an error is thrown.

incsrc

incsrc {filename}

; Contents of routine.asm:
;AnotherRoutine:
;	lda #$FF
;	sta $00
;	rts

Main:
	jsr AnotherRoutine
	bra Main

incsrc "routine.asm"
		

include/includefrom

include

includefrom {filename}

; Contents of shared.asm:
;@includefrom main.asm
;
;if read1($00FFD5) == $23
;	!is_sa1_rom = 1
;else
;	!is_sa1_rom = 0
;endif


@asar 1.37

incsrc "shared.asm"

if !is_sa1_rom
	; ...
endif

includeonce

includeonce

; Contents of shared.asm:
;
;includeonce
;
;MyRoutine = $018000
;MyOtherRoutine = $028000


; Note that the second include does not throw
; redefinition errors, thanks to the "includeonce".
incsrc "shared.asm"
incsrc "shared.asm"

jsl MyRoutine
jsl MyOtherRoutine

Freespace

freespace/freecode/freedata

freespace {ram/noram}[,align][,cleaned][,static][,value]

freecode [align][,cleaned][,static][,value]

freedata [align][,cleaned][,static][,value]

; Let's assume this to be some location in the ROM originally containing
;lda #$10
;sta $1F
org $01A56B
	autoclean jsl MyNewCode
	
freecode

MyNewCode:
	; Do something here
	; ...
	
.Return:
	; We overwrote some code from the original ROM with our org, so we have to restore it here
	lda #$10
	sta $1F
	
	rtl

autoclean

autoclean jml/jsl/dl {label}

autoclean {snes_address}

• When used with a jml or jsl:
  The label parameter must be a label pointing to inside a freespace area. When the patch is applied and the autoclean is encountered, Asar checks whether the output ROM contains a jml/jsl at the current pc. If it does, Asar checks whether the jml/jsl points to the expanded area of the ROM (banks $10+). If it does, Asar checks whether the jml/jsl points to an area protected by a RATS tag (including the RATS tag itself). If it does, Asar cleans up that area and removes the RATS tag.
• When used with a dl:
  The label parameter must be a label pointing to inside a freespace area. When the patch is applied and the autoclean is encountered, Asar checks whether the output ROM contains an address pointing to the expanded area of the ROM (banks $10+) at the current pc. If it does, Asar checks whether that address points to an area protected by a RATS tag (including the RATS tag itself). If it does, Asar cleans up that area and removes the RATS tag.
• When used with just an address:
  The snes_address parameter must be any label, number literal or math statement evaluating to an SNES address pointing to inside a freespace area. When the patch is applied and the autoclean is encountered, Asar checks whether that address points to the expanded area of the ROM (banks $10+). If it does, Asar checks whether it points to an area protected by a RATS tag (including the RATS tag itself). If it does, Asar cleans up that area and removes the RATS tag.

• The autoclean command itself may not be used inside a freespace area. To automatically clean up freespace that is only referenced within another freespace area, you can use the prot command.
• It is safe to have multiple autoclean commands pointing to the same freespace area.
• You can not use autoclean with a label pointing to the very end of a freespace area.

; Let's assume this to be some location in the ROM containing a function pointer table or similar
org $00A5F2
	autoclean dl MyNewFunction1
	autoclean dl MyNewFunction2
	
freecode

MyNewFunction1:
	; ...
	rtl
	
MyNewFunction2:
	; ...
	rtl

prot

prot {label}[,label...]

org $0194BC
	autoclean jsl MyNewFunction
	
	
freecode
prot SomeLargeData

MyNewFunction:
	ldx.b #0
	
.Loop:
	{
		lda SomeLargeData,x
		cmp #$FF
		beq .Return
		
		; ...
		
		inx
		
		bra .Loop
	}
	
.Return:
	rtl
	
	
freedata

SomeLargeData:
	db $00,$01,$02,$03
	; ...
	db $FF

Text Output

print

print {text_or_function}[,text_or_function...]

reset freespaceuse

reset bytes

warn

warn [text_or_function...]

if read1($00FFD5) == $23
	warn "SA-1 compatibility of this patch is untested, use with caution!"
endif

error

error [text_or_function...]

if read1($00FFD5) == $23
	error "This patch is not SA-1 compatible!"
endif

assert

if {condition}
else
	error [text_or_function...]
endif

assert {condition}[,text_or_function...]

assert read1($00FFD5) != $23,"This patch is not SA-1 compatible!"

Checks

check title

check title "{title}"

; This patch is only for a Super Mario World ROM
check title "SUPER MARIOWORLD     "

; Remove small bonus stars from game
org $009053
	nop #3
	
org $009068
	nop #3

check bankcross

check bankcross {off/half/full}

check bankcross off

org $80FFFF

	db $00,$00
	
check bankcross on

print pc	; Will print 818001 when using LoROM mapper

Warnings

Disabled Warnings

warnings {push/pull}

warnings {push/pull}

warnings push
; Disable "freespace leaked" warning
warnings disable W1011
		
freecode

; [...]
		
warnings pull

warnings {enable/disable}

warnings {enable/disable} {id}

warnings disable W1012
		
warn "This text in invisible!"

warn enable W1012