# Asar

A multi-architecture SNES assembler by Alcaro, based on xkas v0.06 by byuu.
This manual was written by RPG Hacker, so if you find something that is wrong or weird, make sure to blame me instead of Alcaro.

As a general rule, the manual uses {} to denote required parameters and [] to denote optional parameters (where optional parameters ending in ... mean "zero or more" of that parameter). Everything else refers to keywords/names.

### Usage

	asar.exe [options] {asm_file} [rom_file]
Argument Type Details Examples
[options] List of optional arguments. The following options are supported:
--version Input Displays Asar version information.
asar.exe --version C:/homebrew/my_game/main.asm
-v
--verbose
Input Enables verbose mode.
asar.exe -v C:/homebrew/my_game/main.asm
asar.exe --verbose C:/homebrew/my_game/main.asm
--no-title-check Input Disables input ROM title and checksum verification when using Asar to apply a patch to an existing ROM file. Note that irresponsible use of this option will likely corrupt your ROM.
asar.exe --no-title-check C:/homebrew/my_game/main.asm
--pause-mode={mode} Input Sets Asar's pause mode, specifying when Asar should pause the application before exit, where {mode} can be one of the following:
never: Don't pause the application (default).
on-error: Pause the application if an error was thrown.
on-warning: Pause the application if an error or a warning was thrown.
always: Always pause the application.
asar.exe --pause-mode=always C:/homebrew/my_game/main.asm
-I{path}
--include {path}
Input Adds an include search path for file-based commands to Asar. Normally, commands like incsrc, incbin etc. look for files relative to the ASM file that is currently being compiled. If those files aren't found, an error is thrown, unless you specify include search paths, in which case Asar will look for the file in each respective directory before throwing an error. For example, imagine you compiled the file
C:/homebrew/my_game.asm
with Asar, adding the include search path
-I"C:/homebrew/binary data"
and the ASM file included the line:
incbin "data/player_gfx.bin"
Asar would now look for a file:
C:/homebrew/data/player_gfx.bin
If this file didn't exist, it would then look for a file:
C:/homebrew/binary data/data/player_gfx.bin
If this file didn't exist, Asar would throw an error, otherwise Asar would include it. See section Includes for details on Asar's handling of file names.
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
-D{identifier}[=value]
--define {identifier}[=value]
Input Adds a define to Asar. When no value is provided, the define is set to an empty string. See section Defines for details.
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
--symbols={format} Input Specifies the format of the symbols output file generated by Asar. The following values are supported for {format}:
none: Don't generate a symbols file (default).
wla: Generate a symbols file in the WLA format. This format additionally includes an address-to-line mapping which can be used by some debuggers to provide source-level debugging.

### Architectures

Asar supports a number of different target architectures for code compilation. They can be activated via the command arch {name}. Going into detail on any of the supported architectures is beyond the scope of this manual. For that, it's recommended to check the SNES Dev Manual or other specialized resources. Asar tries as much as possible to always stick to the known conventions and specifications of each respective architecture (with a few notable exceptions that are hopefully all covered somewhere in this manual).

Architecture Command Supported Opcodes Details
65c816 arch 65816 [+] Expand Default setting. Compiles code for the 65c816 architecture.
SPC700 arch spc700 [+] Expand Compiles code for the SPC700 architecture. Follows the format the SNES Dev Manual recommends, with the exception of mov (x)+,a and mov a,(x)+, which are moved to mov (x+),a and mov a,(x+).
SPC700 arch spc700-inline Same as above, but implements the standard upload system (16bit length, then location, with a terminator at the end) automatically.
Super FX arch superfx [+] Expand Compiles code for the Super FX architecture.

All of Asar's features should be compatible with all of the supported target architectures, but it's not recommended to mix labels between different architectures as that will lead to undefined behavior. Opcodes in Asar are case-insensitive, which means that LDA and lda will be treated equally.
arch 65816
lda $00 arch spc700 mov a,$00

#### Number Literals

Asar supports decimal, hexadecimal and binary number literals. Hexadecimal literals use $ as a prefix, binary literals use % as a prefix. Number literals can be made positive or negative by prefixing a + or a - (without a sign, positive is assumed). They can also be prefixed with a ~ to get their unary complement (a 32-bit integer with all the bits inverted). lda$00
clc
and #%01111111
lda #~$80 ; Equal to lda #$FFFFFF7F
Aditionally, Asar supports character literals by delimiting a single ASCII character with '. Asar will automatically convert them to the integer value currently mapped to them (by default their ASCII value). They can be used in all places where number literals can be used. See section Tables for details on ASCII character mapping.
lda #'a'

### Mapping Modes

Asar supports a number of different mapping modes. They control the address translation used by Asar during compilation (aka where in the output file Asar writes to). Historically, SNES cartridges used a number of different mappers to address data in ROM. Those mappers can be supported by using the respective mapping mode in Asar. It's possible, but not recommended, to use different mapping modes on the same ROM. Detailed explanations on each mapping mode are beyond the scope of this manual, so please check the SNES Dev Manual or other specialized resources for that.
NOTE: Changing the mapper after having previously set it will generate warning W1029.

Command Details
lorom Switch to LoROM mapping mode.
hirom Switch to HiROM mapping mode.
exlorom Switch to ExLoROM mapping mode.
exhirom Switch to ExHiROM mapping mode.
sa1rom [bank_1,bank_2,bank_3,bank_4] Switch to hybrid SA-1 mapping mode. To tell which banks are mapped in (maximum is 7) use the optional parameter, like so:
sa1rom 0,1,4,6
The default is 0,1,2,3.
fullsa1rom Switch to full SA-1 mapping mode.
sfxrom Switch to Super FX mapping mode.
norom Disable Asar's address translation; the SNES address is equal to the PC address. Can be combined with base and macros to implement your own address translation.

When no mapping mode is specified, Asar tries to determine the mapping mode from the output ROM. If that isn't possible, Asar defaults to lorom.
lorom
org $008000 db$FF		; Will write to PC address 0x000000

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

### Compatibility Settings

Compatibility settings determine how Asar operates in certain situations. They can be changed via a number of commands.

#### xkas

The xkas command enables Asar's xkas compatibility mode. In this mode, Asar tries to replicate the behavior of xkas as much as possible and throws warnings whenever it detects the usage of Asar-specific features that are not compatible with xkas. This command has to be used before any other command in the same patch. The intended purpose of the xkas command is to use it in conjunction with ;@ to write patches that can be assembled with both, Asar and xkas. See section Comments for details. Note that as of Asar version 1.40, xkas backwards compatibility is officially deprecated and is no longer guaranteed to work as expected. New features introduced into Asar since then might not throw warnings when attempted to use in xkas compatibility mode and old xkas patches might not assemble correctly with Asar anymore, even when xkas compatibility mode is used.
;@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}
The asar command can be used to specify the minimum Asar version your patch is compatible with. The ver parameter specifies the minimum required Asar version. When a user tries to assemble the patch in an older version of Asar, an error will be thrown, stating that the used Asar version is too old. This should be the first command in your patch, otherwise an error will be thrown.
; This patch uses features from Asar 1.40, so it makes sense to require it as a minimum.
@asar 1.40

; Do something
else
; Do something else
endif

#### warn xkas

warn xkas {on/off}
The warn xkas command determines whether Asar should throw warnings on behavior that is known to be different between xkas and Asar. Use warn xkas on to enable these warnings and warn xkas off to disable them. It's recommended to only enable them when not using xkas compatibility mode. Note that some behavioral changes throw warnings or errors regardless of this setting.

#### math pri

math pri {on/off}
The math pri command tells Asar which order of operations to use in math experssions. When set to off (default), Asar uses left-to-right math, just like xkas v0.06. When set to on, Asar follows the conventional oder of operations (exponentiation before multiplication & division, multiplication & division before addition & subtraction etc.). Parentheses can be used in either mode and tell Asar to calculate the expression inside first. For most intents and purposes, working with this flag enabled is more practical and predictable. It is disabled by default solely for the purpose of xkas backwards compatibility. When writing patches specifially for Asar, it is recommended to always enable this flag.
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}
The math round command tells Asar which rounding behavior to use in math expressions. When set to on (default), Asar truncates all numbers immediately, whereas when set to off, Asar only truncates numbers whenever they need to be cast to an integer type. Note that having this flag enabled will make it practically impossible to work with floating point numbers since calculations will lead to unexpected and impractical results. It is the default setting solely for the purpose of xkas backwards compatibility. When writing patches specifially for Asar, it is recommended to always disable this flag.
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}
The namespace nested command enables (on) or disables (off) nested namespaces. The default is off. See section Namespaces for details.

### Code Formatting

You can use ; to add comments to your code, making it easier to read and understand for other people. Everything from the ; to the end of the line is silently ignored by Asar.
	lda $00 ; Asar only sees the lda$00 and ignores everything else
An exception from this rule are lines starting with ;@, which are assembled normally. The purpose of this is to add code to your patch that can be used with both xkas and Asar. In xkas, lines with ;@ will simply be ignored, whereas in Asar, they will be assembled. If you don't care about backwards-compatibility, you can also just use @, which will make your patch only assemble with Asar and fail with xkas. Aditionally, when Asar finds any unknown command on a line starting with ;@ or @, it will only throw a warning instead of an error. This can, at least in theory, be used to include optional features from newer Asar versions and still have your patch be compatible with older Asar versions. See section Compatibility Settings for details on xkas compatibility.

#### Brackets

Brackets, { and }, may be used to help organize your code structurally. They're treated as commands by the assembler, which means they follow the same rules as other commands, but they otherwise have no effect on code assembly and are silently ignored. Since brackets have no effect on code assembly, they don't even have to match, either. It's entirely up to the coder whether, how and in what quantity brackets are used.
	lda $00 beq .IsZero .GreaterThanZero { dec$00
}

.IsZero
rts

#### Multi-Line Operators

The , and the \ operator are formatting operators which make it possible to split commands in Asar into multiple lines. Both are put at the end of a line and work very similarly with only one key difference. During execution, Asar will concatenate subsequent lines to lines ending with either operator and treat them as a single line. When using the comma operator, the comma itself will actually remain a part of the concatenated string, whereas when using the backslash operator, the backslash itself will be removed from the concatenated string. When using the backslash operator, please note that all whitespace following it is ignored, whereas all whitespace preceeding it is preserved. This is by design, since some commands in Asar require spaces to work, whereas other commands (like math commands) only work without spaces.
%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

Contrary to the multi-line operators, the single-line operator : is a formatting operator which makes it possible to treat a single line of code as multiple lines. It requires a space before and after usage to differentiate it from the : used with certain commands. When used between different commands, Asar interprets it similarly to a new line and treats each command as being on a separate line. This can be used to link multiple commands together into functional blocks and make the code more readable.
lda #$00 : sta$00

; Treated as:
lda #00
sta $00 Return to top ### Program Counter The program counter (short: pc) refers to the position in the ROM at which Asar currently writes assembled code and/or data. It advances automatically whenever Asar writes to the ROM and is affected by the current mapping mode, as well as a number of special commands. Note that all commands affecting the pc that take an address expect an SNES address and thus are also affected by the current mapping mode. #### org org {snes_address} The org command directly sets the pc to snes_address. Most commonly used inside patches to specify which code to hijack or which data to overwrite. org$008000
MainEntryPoint:
; ...

#### base

base {snes_address/off}
The base command makes Asar act as though the pc was currently set to snes_address without actually setting it; base off deactivates this behavior. This can be useful for writing code that you plan to execute from another location (such as RAM).
org $008000 MainEntryPoint: ; Some code which copies SomeRamRoutine to$7E0000 goes here
; ...
jsl $7E0000 ; ... SomeRamRoutine: base$7E0000
; ...
base off
rtl

#### skip

skip {num_bytes}
The skip command moves the pc by num_bytes bytes. By specifying a negative value, the pc can be moved backwards.
org $008000 skip 5 ; pc is now at$008005
skip -1
; pc is now at $008004 #### warnpc warnpc {snes_address} The warnpc command checks if the current pc is > snes_address. If that's the case, it throws an error. This is useful for detecting overflow errors. org$008000
incbin datafile.bin
warnpc $008100 ; Throws an error if datafile.bin is larger than$100 bytes.

#### bank

bank {data_bank/noassume/auto}
The bank command makes Asar's label optimizer act as though the current data bank was set to data_bank. Consider the following example:
bank $FF lda Table,x Table: db$01,$02,$03,$04 Asar will always assemble the lda Table,x with 24-bit addressing, unless the current pc (or base address) is inside bank $FF itself. This is intended for code that uses a data bank register different from the code bank register. You can use bank noassume to make Asar act as though the data bank was always in a different bank. Using bank auto restores the default behavior of assuming that the data bank register and the code bank register are the same. Note that the bank command can't point to freespace areas.
org $008000 phb lda #$FF
pha
plb

bank $FF ; ... bank auto plb #### dpbase dpbase {snes_address} The dpbase command makes Asar's label optimizer assume the Direct Page register is set to the specified address. When used with the optimize dp command, this will cause Asar to use 8-bit addressing where possible. For example, in the following code Asar can assemble lda SpriteTable,x as a direct page address. SpriteTable =$7E0200
dpbase $0200 optimize dp ram org$008000
lda SpriteTable,x

#### optimize dp

optimize dp {none/ram/always}
This command changes how aggressive Asar's direct page access optimizer is. With optimize dp none (the default), the direct page optimizer is disabled and direct page accesses will only be done with the .b instruction suffix or with explicit addresses like lda $42. With optimize dp ram, direct page optimization will be performed according to the dpbase setting, but only on labels in bank $7E. With optimize dp always, direct page optimization will be performed on all labels in banks that have RAM mirrors, i.e. 00-3F and 80-BF, and also on labels in bank 7E.

optimize address {default/ram/mirrors}
TODO: document this

#### pushpc/pullpc

The pushpc command pushes the current pc to the stack, the pullpc command restores the pc by pulling its value from the stack. This can be useful for inserting code in another location and then continuing at the original location.
org $008000 Main: jsl CodeInAnotherBank pushpc org$018000

CodeInAnotherBank:
; ...
rtl

pullpc

bra Main

#### pushbase/pullbase

The pushbase command pushes the current base to the stack, the pullbase command restores the base by pulling its value from the stack.
base $7E2000 InsideRam: jsl OutsideOfRam ; ... pushbase pushpc base off freecode OutsideOfRam: ; ... jsl InRamAgain rtl pullpc pullbase InRamAgain: ; ... rtl base off Return to top ### Math Math is supported in all opcodes, functions and labels. By default, Asar uses left-to-right math for backwards-compatibility with xkas which means that it ignores operator precedence. lda #6*2+5 ; the same as "lda #17" lda #5+6*2 ; the same as "lda #22" This behavior can be changed by using the command math pri on, which makes Asar apply conventional prioritization rules in all math statements. (See math pri) math pri on lda #6*2+5 ; the same as "lda #17" lda #5+6*2 ; the same as "lda #17" In both modes, Asar supports parentheses for explicit control over the order of operations. math pri on lda #5+6*2 ; the same as "lda #17" lda #(5+6)*2 ; the same as "lda #22" Math statements in Asar support the following operators: + : 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) Note that whitespace is not supported inside math statements, but the multi-line operator \ can be used to split them into multiple lines. Using math in labels can be useful when you want to apply an offset to the label: lda .Data+3 ; Will load$03 into A

.Data
db $00,$01,$02 db$03,$02,$03

### Labels

Labels are used to represent a position in the ROM and allow you to code without having to constantly update branches and jumps/calls. They can be used with any opcode, but were specifically designed to be used with branches, jumps, calls, pointer tables etc. When used with branches, they're automatically converted to offsets.

#### Main Labels

[#]{identifier}:
Main labels are the top-most level of labels supported by Asar. They're global and thus can be directly acessed from anywhere. Their identifier can contain any of the following characters
a-z A-Z 0-9 _
org $008000 Main: %do_frame() jmp Main ; Equal to jmp$8000
An alternate form of defining main labels is by directly assigning a value to them. A common use-case for this is to make a label point to an existing address inside a ROM. Syntax:
{identifier} = {snes_address}
where snes_address can be a number or any math statement evaluating to an SNES address. Note that defining a main label this way does not start a new sub label group.
Main:
; ...

SomewhereInRom = $04CA40 .Sub: ; ... Table: dl Main_Sub ; Okay! dl SomewhereInRom_Sub ; Error, label not found Prefixing a label definition (except label assignments) with a # will define the label without modifying existing label hierarchies. This can be useful for defining global routines inside call-anywhere macros without having them break existing label hierarchies. 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 Asar includes a label optimizer which attempts to optimize performance by shortening opcodes accessing labels from 24-bit to 16-bit whenever possible. See section Program Counter for details. #### Sub Labels [#].{identifier}[:] Sub labels are the second-most level of labels supported by Asar. They're local to the last main label declared and their identifiers can contain the same characters as main labels. Proc1: nop .Sub bra .Sub Proc2: nop .Sub: ; Note that the colon is optional bra .Sub Sub labels allow you to reuse redundantly named labels such as Loop, End, etc. without causing label redefinition errors. A new sub label group is automatically started after a main label is declared. Internally, sub labels are converted to MainLabel_SubLabel, which can be used to access them from anywhere. Main1: ; ... .Sub1: ; ... .Sub2: ; ... Main2: ; ... .Sub1: ; ... .Sub2: ; ... Table: dl Main1_Sub1 dl Main1_Sub2 dl Main2_Sub1 dl Main2_Sub2 Sub labels can themselves contain sub labels to an arbitrary depth by prepending additional dots. Main1: ; ... .Sub: ; ... ..Deeper: ; ... ...TheEnd: ; ... Table: dl Main1_Sub_Deeper_TheEnd Prefixing a sub label definition with a # will define the sub label without modifying existing label hierarchies, but there is probably no practical use for this and it's unintuitive, so it should be avoided. #### +/- Labels +[+...][:] -[-...][:] +/- labels are a special type of labels that are different from both main labels and sub labels in that they don't refer to a specific location in code, but rather to a location relative from where they are used. When used inside opcodes etc., + always refers to the next + label and - always refers to the previous - label. You can also chain an arbitrary number of + or an arbitrary number of - to create unique +/- labels that don't overwrite labels with a different number of +/-, for example +++ or -----.  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"
+/- labels are useful in a number of situations. For example: inside a long routine with multiple short loops, where even a sub label like .Loop would get repetitive. +/- labels aren't bound to any scope, which means they can technically be used across different scopes. Just like sub labels, +/- labels are converted to main labels internally. Unlike sub labels, they can not be referenced from code directly since their names depend on where in the code they're used, making it impractical to directly refer to them. This is by design. They can, however, be accessed via the Asar DLL API, and their full name may appear in error messages printed by Asar. The naming format used for them is
:pos_x_y
for + labels and
:neg_x_y
for - labels, where
x = number of chained +/-
and
y = instance of this label within all +/- labels of the same name (starting from 0 for + labels and from 1 for - labels).
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 labels are special variations of the labels mentioned in the previous sections. Functionally, they behave the same as the other labels with the exception of being local to the macro they're used in. This means they can't be referenced from outside the respective macro. Macro labels are created by prefixing any of the other label types with a ? . 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 Prefixing a macro label definition (except for macro label assignments and macro +/- labels) with a # will define the macro label without modifying existing label hierarchies, but there is probably no practical use for this, so it should be avoided. Like all other labels, macro labels are converted to main labels internally and prefixed with an identifier of :macro_x_ where x = total macro call instance. They can't be referenced in code directly, except inside their respective macro and using the respective macro label syntax seen above. They can, however, be accessed via the Asar DLL API, and their full name may appear in error messages printed by Asar. #### Structs Structs are an advanced form of labels with the purpose of making access into structured data blocks easier. The general syntax is as follows struct {identifier} {snes_address} [label...] endstruct [align num] where identifier can contain any of the following characters: a-z A-Z 0-9 _ The snes_address parameter can be any number literal or math statement evaluating to an SNES address. This address marks the start of the struct. The label parameter should be any number of labels, ideally coupled with skip commands. These labels become offsets into the struct. Internally, the struct command will do something similar to this pushpc base snes_address whereas the endstruct command will do something similar to this base off pullpc Take a look at the simple example below: struct ObjectList7E0100
.Type: skip 1
.PosX: skip 2
.PosY: skip 2
.SizeX: skip 1
.SizeY: skip 1
endstruct
This defines a struct called ObjectList at location $7E0100 with a size of 7 (the sum of all skip commands). You can access into this struct like so: lda ObjectList.PosY This is equal to: lda$7E0103		; $7E0100+1+2 The final address is calculated by taking the start of the struct ($7E0100) and adding to that all the skips preceding the .PosY label (1 and 2). Aside from accessing structs directly, it's also possible to access them as arrays. A simple example:
lda ObjectList[2].PosY
The final address in this case is calculated by the equation:
struct_start + (array_index * struct_size) + label_offset
So in this case, our final address is $7E0100 + (2 * 7) + (1 + 2) =$7E0111. When using structs this way, the optional align parameter becomes relevant. This parameter controls the struct's alignment. Simply put, when setting a struct's alignment, Asar makes sure that its size is always a multiple of that alignment, increasing the size as necessary to make it a multiple. Let's take another look at the example above with an added alignment:
struct ObjectList 7E0100 .Type: skip 1 .PosX: skip 2 .PosY: skip 2 .SizeX: skip 1 .SizeY: skip 1 endstruct align 16 With an alignment of 16 enforced, this struct's size becomes 16 (the first multiple of 16 that 7 bytes fit into). So when accessing the struct like this lda ObjectList[2].PosY the final address becomes 7E0100 + (2 * 16) + (1 + 2) = $7E0123. If we add some data into the struct struct ObjectList$7E0100
.Type: skip 1
.PosX: skip 2
.PosY: skip 2
.SizeX: skip 1
.SizeY: skip 1
.Properties: skip 10
endstruct align 16
its original size becomes 17. Since a final size of 16 would now be too small to contain the entire struct, the alignment instead makes the struct's final size become 32 (the first multiple of 16 that 17 bytes fit into), so in our example of
lda ObjectList[2].PosY
we now end up with a final address of $7E0100 + (2 * 32) + (1 + 2) =$7E0143.

Another feature that is unique to structs is the possibility of extending previously defined structs with new data. The general syntax for this is as follows:
struct {extension_identifier} extends {parent_identifier}
[label...]
endstruct [align num]
This adds the struct extension_identifier at the end of the previously defined struct parent_identifier. Consider the following example:
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 The struct ObjectList now contains a child struct Properties which can be accessed like so: lda ObjectList.Properties.FlipX Since extension structs are added at the end of their parent structs, the offset of .FlipX in this example is calculated as parent_struct_start_address + parent_struct_size + extension_struct_label_offset, in other words, our final address is $7E0100 + 7 + (1 + 2) = $7E0109. Note that extending a struct also changes its size, so in this example, the final size of the ObjectList struct becomes 12. Extended structs can also be accessed as arrays. This works on the parent struct, as well as the extension struct. lda ObjectList[2].Properties.FlipX lda ObjectList.Properties[2].FlipX In the first example, our final address is calculated as parent_struct_start_address + (combined_struct_size * array_index) + parent_struct_size + extension_struct_label_offset, whereas in the second example, it's calculated as parent_struct_start_address + parent_struct_size + (extension_struct_size * array_index) + extension_struct_label_offset, so we end up with final addresses of $7E0100 + (12 * 2) + 7 + (1 + 2) = $7E0122 and $7E0100 + 7 + (5 * 2) + (1 + 2) = 7E0114. A few further things to note when using structs in Asar: • 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 Namespaces are a feature which makes it easier to avoid name conflicts between different labels without having to give them long or cryptic names. They work similarly to C++ namespaces and accomplish this by automatically adding a prefix to all labels declared or accessed within them. This prefix consists of an identifier, followed by an underscore _ . Namespaces can be stacked if desired by enabling the namespace nested setting. When you try to access a label from within a namespace and Asar doesn't find it in there, it automatically looks in the upper namespaces (up to the global namespace). Use namespace {identifier} to enter a namspace, where identifier can contain any of the following characters: a-z A-Z 0-9 _ Use namespace off to leave the current namespace (or immediately return to the global namespace when nested namespaces are not enabled). ; 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 Return to top ### Defines Asar supports a define system that functions similarly to defines in other programming languages, such as C++. Defines are identifiers that you can assign any kind of text to and use in other places as substitues for that text. During compilation, Asar replaces each define it encounters with the respective text assigned to it. Defines are prefixed with a ! and declared as follows: !{identifier} = {value} !{identifier} = "{value}" where identifier is a unique identifier that can contain any of the following characters: a-z A-Z 0-9 _ The space on both sides of the = is required, which means that !identifier=value will not work. Since defines are really just placeholders for text, they can contain anything - labels, math formulas, even other defines. !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$1234"

!phr = "pha : phx : phy"

!phr		; Treated as "pha : phx : phy"
To assign text containing whitespace to a define, you must delimit it with two " as shown above with !phr. Besides the regular define operator =, Asar also supports a number of additional define operators with slightly different functionality.

Operator Functionality Example
= The standard define operator. Directly assigns text to a define.
!define = 10
!anotherdefine = !define+1
; !define now contains "10" and !anotherdefine now contains "!define+1"
+= Appends text to the current value of a define.
!define = 10
!define += 1
; !define now contains "101"
:= Equal to the standard =, but resolves all defines in the text to assign before actually assigning it. This makes recursive defines possible.
!define = 10
!define := !define+1
; !define now contains "10+1"
#= Evalutes the text as though it was a math expression, calculates its result and assigns it to the define. The math is done in-place on the same line the operator is used on and is affected by all of Asar's math settings (such as prioritization rules and rouding behavior).
!define = 10
!anotherdefine #= !define+1
; !anotherdefine now contains "11"
?= Equal to the standard =, but only assigns text to a define that doesn't exist yet, otherwise does nothing.
!define ?= 10
!define ?= 1
; !define now contains "10"

Similarly to C's ifdef and undef, Asar allows you to check for a define's existence using the defined("{identifier}") function and to delete a define using the undef "{identifier}" command. Make sure to leave the ! out of the identifier when using these functions, as Asar would otherwise try to resolve the defines.
!define = "hello"

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

undef "define"

if defined("define")
print "This won't be printed!"
endif
Note that Asar tries to replace defines wherever possible, even inside strings. In some occasions, this might be undesirable. See section Tables for details on how to escape certain characters.

#### Nested Defines

By default, the define parser in Asar considers every supported character in a connected string to be a part of the define's name. This may not always be desired as it can lead to a certain define becoming inaccessible in a certain situation. In cases like that, the {} operator makes it possible to still use those defines by resovling everything inside the braces immediately.
!hex = $db !hexFF ; Error - define !hexFF not found db !{hex}FF ; OK Perhaps the more useful feature of this operator is that it can also be nested to allow for the creation of dynamic define names. ; 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 Aside from user defines, Asar also supports a number of built-in defines. These defines are read-only and any attempt to modify them will throw an error. Define Details Example !assembler Contains the value asar. Theoretically can be used to differentiate between different assemblers if other assemblers use this define and a syntax similar to Asar. if not(stringsequal("!assembler", "asar")) warn "This patch was written for Asar and may not be compatible with your current assembler." endif !assembler_ver Contains the version number of Asar in the format (major_version * 10000) + (minor_version * 100) + revision. For Asar version 1.60, this contains 10600. if !assembler_ver < 10600 warn "This patch might not behave correctly due to a bug in Asar versions prior to 1.60." endif Return to top ### Macros Macros are a mechanism for recording a sequence of commands that can be used in other places. The main purpose of this is to include commonly used code in multiple places without actually having to rewrite or copy that code every time. Instead you can move it into a macro and write it only once. Macros, in concept, work similarly to defines in that they are a text-replacement mechanism, but they have a few key differences: • 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. Use the following syntax to define a macro: macro {identifier}([parameter1_identifier[, parameter2_identifier...]][variadic_token]) [command1] [command2...] endmacro where all the identifiers can contain any of the following characters: a-z A-Z 0-9 _ Use the syntax <parameter_identifier> to expand a parameter inside a macro. This works just like placing a !define_identifier anyhwere else in the code. Macros can be recursive (macros calling themselves) and/or nested up to 512 levels deep. This limit only serves the purpose of preventing infinite recursion. The first and last line of the macro definition need to go on their own lines (the single-line operator is not supported here). To call a macro that has already been defined, use the syntax %{identifier}([parameter1[, parameter2...]]) where each individual parameter may be wrapped in double quotes (which is required for parameters that contain any whitespace). 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")

In addition to named substitutions if the variadic token ... is specified as the last parameter asar will allow an arbitrary number of parameters after all prior parameters have been satisfied. To access unnamed arguments of a variadic function they are declared numerically starting from 0 up to the number of provided parameters. To access the number of provided variadic arguments one may use sizeof(...). Lastly, it is important to note that while traditionally macros do not parse defines at their creation variadic macros will. This is to allow iteration of arguments by using defines.

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
%example0(1,2,3,4)
%example1(1,2,3)
%example2(1,2,3,4,5,6,7)


### Functions

Functions in Asar can be considered the math equivalent of macros. They are a convenient way of wrapping commonly used math statements, can include parameters and can be called in all places where math is supported. Use the following syntax to define a function:
function {identifier}([parameter1_identifier[, parameter2_identifier...]]) = {some_math_statement}
where all the identifiers can contain any of the following characters
a-z A-Z 0-9 _
and where some_math_statement can be any math statement supported by Asar (including the use of other functions). Use a parameter's name to expand it inside a function.
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

Function definitions must be on a single line and can't include whitespace in their math statements, except when using the multi line operator \, which can be used to split long function definitions into multiple lines.

#### Built-in Functions

Aside from user-defined functions mentioned above, Asar also supports a number of built-in functions. Some built-in functions take string parameters, which must be wrapped in double quotes.

Function Details Example
read1(pos[, default]) read2(pos[, default]) read3(pos[, default]) read4(pos[, default]) Read one/two/three/four byte(s) from the output ROM at SNES location pos. Mainly intended for detecting the presence of certain hijacks/patches in a ROM. Throws an error when given an invalid address, unless the optional parameter default is provided in which case it is returned.
if read1($00FFD5) ==$23
!is_sa1_rom = 1
else
!is_sa1_rom = 0
endif
readfile1(filename, pos[, default]) readfile2(filename, pos[, default]) readfile3(filename, pos[, default]) readfile4(filename, pos[, default]) Read one/two/three/four byte(s) from file filename at position pos (see section Includes for details on Asar's handling of file names). Throws an error when the referenced file doesn't exist or the given position is out-of-bounds, unless the optional parameter default is provided in which case it is returned.
!readresult = readfile4("datafile.bin", 0, $FFFFFFFF) if !readresult !=$FFFFFFFF
print "Read $",hex(!readresult)," from datafile.bin." endif canread1(pos) canread2(pos) canread3(pos) canread4(pos) canread(pos, num) Returns 1 if reading one/two/three/four/num bytes from the output ROM at SNES location pos would succeed and 0 otherwise. if canread1($00FFD5) == 1
print "Detected ROM type: $",hex(read1($00FFD5))
else
error "Failed to detect ROM type!"
endif
canreadfile1(filename, pos) canreadfile2(filename, pos) canreadfile3(filename, pos) canreadfile4(filename, pos) canreadfile(filename, pos, num) Returns 1 if reading one/two/three/four/num bytes from file filename at position pos would succeed and 0 otherwise (see section Includes for details on Asar's handling of file names).
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 filesize(filename) Returns the size of file filename. Throws an error if the file doesn't exist. !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 getfilestatus(filename) Checks the status of file filename. Returns 0 if the file exists and can be read from, returns 1 if the file doesn't exist and returns 2 if the file exists, but can't be read from for any other reason (like being read-protected, being locked etc.). assert getfilestatus("datafile.bin") != 1, "datafile.bin doesn't seem to exist" sqrt(x) Computes the square root of x. sin(x) cos(x) tan(x) asin(x) acos(x) atan(x) arcsin(x) arccos(x) arctan(x) Various trigonometric functions. Units are in radians. log(x) log2(x) log10(x) Logarithmic functions (base-e, base-2 and base-10 respectively). snestopc(address) pctosnes(address) Functions for converting between SNES and PC addresses. Affected by the current mapping mode. print "SNES address$018000 in the current mapping mode is equivalent to PC address 0x",dec(snestopc($018000)) min(a, b) max(a, b) Return the minimum/maximum of two numbers. !start_index #= max(!current_index-1, 0) clamp(value, minimum, maximum) Makes sure that value stays within the bounds set by minimum and maximum. Equal to min(max(value, minimum), maximum). !used_amount #= clamp(!used_percentage, 0.0, 1.0)*!total_amount safediv(a, b, exception) Returns a/b unless b is 0 in which case exception is returned. Intended for avoiding division by zero errors in functions. !single_sprite_memory = safediv(!total_sprite_memory, !max_num_sprites, 0) select(statement, true, false) Returns false if statement is 0 and true otherwise. Can be considered an if/else conditional that is usable within functions. NOTE: Asar always evaluates all parameters of a function before calling it, so if, for example, you pass an expression that divides by zero to select() as true, Asar will throw a division by zero error even if statement evalutes to 0 and thus false would be returned. To work around this, you can use the safediv() function in place of a regular division. function sprite_size() = select(!extra_bytes_enabled, 16+4, 16) not(value) Returns 1 if value is 0 and 0 in any other case. Useful for negating statements in the select() function. function required_sprite_memory(num_sprites) = not(!sprites_disabled)*sprite_size()*num_sprites bank(value) Returns value>>16  lda #bank(some_label) equal(value, comparand) notequal(value, comparand) less(value, comparand) lessequal(value, comparand) greater(value, comparand) greaterequal(value, comparand) Comparison functions. Return 1 if the respective comparison is true and 0 otherwise. Useful as statements in the select() function. function abs(num) = select(less(num, 0), num*-1, num) and(a, b) or(a, b) nand(a, b) nor(a, b) xor(a, b) Perform the respective logical operation with a and b. Useful for chaining statements in the select() function. function total_sprite_extra_bytes(num_sprites) = select(and(not(!sprites_disabled), !extra_bytes_enabled), 4, 0)*num_sprites round(number, precision) Rounds number to precision decimal places. Pass 0 as precision to round to the nearest integer. 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 floor(number) ceil(number) Rounds a number up (in the case of ceil) or down (in the case of floor) to the nearest integer. !banks_used #= ceil(!data_size/65536) defined(identifier) Takes an identifier as a string parameter and returns 1 if a define with that identifier exists, 0 otherwise. NOTE: Don't include the ! in the identifier as Asar will otherwise try to expand it as a define before calling the function. if defined("include_guard") == 0 !include_guard = 1 ; ... endif sizeof(identifier) Takes the identifier of a struct as a parameter and returns the base size of that struct (without any extension structs). Throws an error if a struct with that name doesn't exist. For backwards compatibility, the identifier can be surrounded with quotes. 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
objectsize(identifier) Takes the identifier of a struct as a parameter and returns the object size of that struct. In the case of an extended struct, this will be the base size of the struct plus the size of its largest extension struct. Throws an error if a struct with that name doesn't exist. For backwards compatibility, the identifier can be surrounded with quotes.
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 datasize(label) Takes a given label and calculates the distance between it and the next label. It will throw a warning if the distance exceeds 0xFFFF or is the last label in the targeted assembly. 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:  stringsequal(string1, string2) Returns 1 if the given string parameters are equal and 0 otherwise. if not(stringsequal("!assembler", "asar")) warn "This patch was only tested in Asar and might not work correctly in your assembler." endif stringsequalnocase(string1, string2) Returns 1 if the given string parameters are equal and 0 otherwise. The comparison is case-insensitive. if not(stringsequalnocase("!assembler", "ASAR")) warn "This patch was only tested in Asar and might not work correctly in your assembler." endif All built-in functions can be overridden by user-defined functions. Prepending an underscore (for example: _read1()) leads to the original function, which can be used to make an overridden function call its original function. function read1(x) = _read1(x+$010000)
While user-defined functions can't use string parameters themselves, passthrough of string parameters to built-in functions is supported.
function readfilenormalized(filename, pos) = readfile4(filename, pos)/2147483648.0
db readfilenormalizd("datafile.bin", 0)

### Conditional Compilation

Conditional compilation allows you to only compile specific sections of code when certain conditions are met. This can be used in a number of ways, but is most commonly used in conjunction with defines to make code easily customizable and/or provide some simple configuration options to end users.

#### if/elseif/else/endif

The most basic form of conditionals are if conditionals. They are given a math statement and only compile their enclosed code if that statement evaluates to a value greater than 0.
if {condition}
{codeblock}
endif
To construct condition statements, you can also make use of a number of comparison operators specific to conditionals. They return 1 if their respective comparison is true and 0 otherwise.

Operator Details
a == b Returns 1 if a is equal to b
a != b Returns 1 if a is not equal to b
a > b Returns 1 if a is greater than b
a < b Returns 1 if a is less than b
a >= b Returns 1 if a is greater than or equal to b
a <= b Returns 1 if a is less than or equal to b
!a Returns 1 if a is 0, and 0 otherwise. Note: this is deprecated and will be removed in a future version. Please use if not(a) instead.

You can use logical operators to chain multiple conditions.

Operator Details
a || b Returns 1 if at least one of a and b evaluates to 1
a && b Returns 1 if both of a and b evaluate to 1

Evaluation is lazy which means that the compiler will stop evaluating a condition as soon as the result can be determined (for example, in the condition 0 && my_function(), my_function() will never be called). Note that only one kind of logical operator can be used in a single condition, but conditionals themselves can be nested to an arbitrary depth, which can be used as a workaround here. Optionally, if conditionals can contain an arbitrary number of elseif branches as well as a single else branch. The compiler checks the if and all elseif branches in succession until a single condition evaluates to > 0 - if none does, the code inside the else branch is compiled.
!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
Alternatively, if conditionals can also be constructed on a single line via the following syntax:
if {condition} : {codeblock}[ : codeblock...]
Note that no endif needs to be used here and that else or elseif are unsupported when using this syntax.
PressedY:
if !fireballs_enabled : %PlaySoundEffect(!fireball_sfx) : jsr ShootFireball
rtl


#### while

A special variation of if conditionals are while loops. Instead of compiling their enclosed code only once, they compile it repeatedly until their condition evaluates to <= 0. Typically, this would be used with a define that is modified inside the loop. This can be useful for generating data tables.
!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 endif Note that for technical reasons, while loops end on an endif, just like if conditionals, but unlike the latter they do not support elseif or else branches. Be warned as improper use of while loops can lead to infinite loops and thus a dead-lock of the compiler, as Asar won't attempt to detect those. Return to top ### Binary Data Asar supports a number of commands which allow you to insert binary data directly into the ROM. #### Tables db {value}[,value...] dw {value}[,value...] dl {value}[,value...] dd {value}[,value...] Table commands let you insert a number or a list of numbers directly into the ROM as raw bytes. Use db for 8-bit numbers, dw for 16-bit numbers, dl for 24-bit numbers and dd for 32-bit numbers respectively, where value can be a number literal, a math statement, a label or an ASCII string delimited by double quotes. When using dw, dl or dd, each number is converted to little-endian. Big numbers are truncated to smaller integers as needed. 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"
By default, each character in an ASCII string used in in a table maps onto the respective ASCII value. This mapping can be customized via the table command:
table {filename}[,ltr/rtl]
Where filename specifies the path to a table file (enclose in double quotes to use file names with spaces, see section Includes for details on Asar's handling of file names) and ltr/rtl specifies whether that file is in left-to-right or right-to left format (default: left-to-right).
Format of left-to-right table files:
{character}={value}
[character=value...]
Format of right-to-left table files:
{value}={character}
[value=character...]
where character represents an ASCII character and value represents a hexadecimal number literal (without a prefix) to map to that ASCII character. Note that the table command initializes the mapping to garbage, so when using it, it's recommended to provide mappings for all ASCII characters. It's also possible to directly map characters inline without using a table file by using the syntax
'{character}' = {value}
where value can be any number literal or math statement.
To reset the current table mapping to a direct ASCII mapping, use the command cleartable. Additionally, the pushtable command lets you push the current table mapping to the stack, whereas the pulltable command lets you restore the mapping from the stack.
; 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' Note that Asar tries to replace defines wherever possible - even inside strings. Sometimes, this might be undesired. In those cases, you can prefix the ! with a \ to escape it. The \ itself can be escaped with another \. In the case of a " it can be escaped with an additional " !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} The fillbyte and fill commands let you write a specific byte value to the ROM multiple times. The byte parameter of fillbyte specifies which value to write, wheres fill writes that value to the output ROM num times. fillbyte$FF
; This writes $FF$FF $FF$FF $FF$FF $FF$FF
fill 8
It's also possible to write 16-bit, 24-bit or 32-bit values with the fill command by using fillword, filllong or filldword instead of fillbyte. Note that the num parameter of fill still specifies the number of bytes to write in those cases. Values might get truncated as needed to exactly reach the specified number of bytes to write.

padbyte {byte}
pad {snes_address}
The padbyte and pad commands let you write a specific byte value to the ROM until the pc reaches a certain SNES address. The byte parameter of padbyte specifies which value to write, wheres pad writes that value to the output ROM until the pc reaches snes_address.
org $008000 padbyte$FF
; This writes $FF$FF $FF$FF
;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  Return to top ### Freespace Freespace is a concept that comes into play when extending an existing ROM. To insert new code or data into a ROM, the ROM must contain enough continuous unused space for everything to fit into. Space like that is referred to as freespace. Many tools attempt to find freespace in a ROM by looking for continuous blocks of a certain value (most commonly$00). This method on its own isn't reliable as freespace finders could erroneously detect binary data or code with a certain pattern as freespace. For this reason, the RATS format was invented to protect data inserted into a ROM (see SMW Wiki for details on the RATS format). When placing RATS tags at the beginning of occupied memory blocks inside a ROM, freespace finders can search for them to know which parts of the ROM not to overwrite. Asar supports a number of commands for working with freespace directly, including freespace finders with automatic RATS tag generation.

#### freespace/freecode/freedata

freespace {ram/noram}[,align][,cleaned][,static][,value]
freecode
freedata
The freespace command makes Asar search the output ROM for a freespace area large enough to contain the following section of code/data. If such an area is found, the pc is placed at its beginning and a RATS tag automatically written. If no such area is found, an error is thrown. The parameters control what kind of freespace to look for.

Parameter Details
ram The freespace finder searches for an area where RAM mirrors are available (banks $10 to$3F). Recommended when inserting code.
noram The freespace finder searches for an area where RAM mirrors aren't available (banks $40 to$6F and $F0 to$FF). If no such area is found, it searches in the remaining banks ($10 to$3F). Recommended when inserting data.
align The freespace finder searches for an area at the beginning of a bank.
cleaned Suppresses the warning about freespace leaking. Useful when Asar's leak detection misbehaves on an autoclean with a complicated math statement or similar.
static Prevents the freespace area from moving once assigned. This also prevents it from growing (an error is thrown if the area would need to grow). Useful in situations where data needs to remain in a certain location (for example: when another tool or another patch needs to access it).
value A number literal or math statement specifying the byte value to look for when searching for freespace (default: $00). To find freespace, Asar will look for continuous areas of this value. When using autoclean on this freespace, this is also the value the area will be cleaned to. The freecode command is an alias of freespace ram, whreas the freedata command is an alias of freespace noram. There are a few things to note when working with freespace in Asar. First of all, if Asar places two freespace areas within the same bank, it will use 24-bit addressing in cases where they reference each other, despite 16-bit addressing being possible in theory. This can be worked around by only using a single freespace area instead. It's not recommended to explicitly use 16-bit addressing in these cases as the two freespace areas are not guaranteed to always end up in the same bank for all users. Secondly, when Asar places two freespace areas close to each other, a few bytes will be wasted between them for technical reasons. In most practical scenarios, the amount of wasted space should be reasonably small (< 1% of the code size), nevertheless this once again can be worked around by only using a single freespace area instead. Lastly, the number of freespace areas a single Asar patch can place is limited to a maximum of 125. ; 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}
The autoclean command makes it possible for Asar to automatically clean up and reuse all of the freespace allocated by a patch when applying that patch again. The purpose of this is to prevent freespace leaks. Normally, applying a patch including a freespace (or similar) command to the same ROM multiple times would allocate a new freespace area each time. Since Asar automatically protects allocated freespace via RATS tags, all freespace areas previously allocated by the same patch would leak and become unusable, making the output ROM run out of freespace eventually. The autoclean command can prevent this by freeing up freespace areas previously allocated by the patch before allocating new ones. How it accomplishes this depends on how it is used:
• 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. When using autoclean with a jml, jsl or dl, Asar will also assemble the respective line of code at the current pc. For simplicity, you can treat the autoclean command like a modifier in those cases. A few more things to note when using the autoclean command: • 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...]
The prot command makes it possible for Asar to automatically clean up a freespace area that is only referenced within another freespace area and thus can't be cleaned via an autoclean directly. It must be used at the beginning of a freespace area (right after the freespace command), where the label parameter must be a label pointing to inside a freespace area (you can pass up to 85 labels separated by commas to a single prot). When a freespace area containing a prot is cleaned by an autoclean, all freespace areas referenced by the prot are also cleaned up.
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
; ...
nop #3

org $009068 nop #3 #### check bankcross check bankcross {on/off} The check bankcross command enables (on) or disables (off) throwing errors when a bank border is crossed while assembling a file. The default is on. Use this with caution as some features may not behave correctly with bank border checking disabled and some places may still check for bank borders, anyways. check bankcross off org$80FFFF

db $00,$00

check bankcross on

print pc	; Will print 818001 when using LoROM mapper

### Warnings

Warnings are messages that Asar outputs to inform the user about potentially unintended or risky code that isn't critical and thus doesn't cause assembly to fail on its own. These messages can be useful for detecting potential problems in the code, but in some situations may be undesirable. For this reason, Asar supports a few methods of explicitly enabling or disabling certain warnings (see section Usage for details on how to configure warnings via the command line). Additionally, there are warnings which may be useful in some situations, but would be intrusive in most other situations. They are disabled by default and have to be enabled explicitly to be used. Commands that enable or disable warnings refer to them via their ID. This ID is in the format WXXXX, where XXXX is a number uniquely identifying a warning. The easiest way of finding the ID for a specific warning is to look at the console output of a patch producing it. Asar will always output the warning ID along with the respective warning.

#### Disabled Warnings

This is a list of all warnings that are disabled by default and have to be enabled explicitly.

Warning ID Details
W1013 Thrown when opcodes are sized implicitly and Asar has to assume a size. An opcode is considered to be sized explicitly when either a length specifier is used or a simple hex constant that can be assumed to be of a specific size (that is, a hex constant with either two or four digits). Opcodes that don't support multiple sizes are always considered to be sized explicitly. Everything else is considered to be sized implicitly and will throw this warning when enabled.
W1024 Only relevant for the DLL API. Thrown when a file is accessed that was either not provided as a memory file or that isn't found in memory. Mainly intended for debugging purposes and can be used to assure that files are actually read from the correct location.

#### warnings {push/pull}

warnings {push/pull}
The warnings push command pushes the current state of enabled and disabled warnings to the stack. The warnings pull command pulls it back from the stack.
warnings push
; Disable "freespace leaked" warning
warnings disable W1011

freecode

; [...]

warnings pull

#### warnings {enable/disable}

warnings {enable/disable} {id}
The warnings enable command enables the warning with the specified ID, the warnings disable command disables it. Warnings enabled or disabled via this command override warnings enabled or disabled via the command line (see section Usage for details). When using these commands inside shared code, it's recommended to do so in conjunction with warnings {push/pull} to prevent the modified settings from leaking into other files.
warnings disable W1012

warn "This text in invisible!"

warn enable W1012