Fixed some deprecation warnings not showing up properly. (trillian)
+
Fixed some compiler warnings, and added better versioning info to libasar on linux. This shouldn't matter to most end users. (orbea)
+
Fixed some compiler warnings in MSVC. (Atari2)
+
+
+
+
+
v1.90
+ Release: February 23, 2024
+
+
Contributors:
+
+
RPG Hacker
+
trillian
+
p4plus2
+
Atari2
+
Alcaro
+
spooonsss
+
+
+
Notes:
+
+
The primary purpose of this release is to be a stepping stone towards Asar 2.0. For this purpose, a lot of features have been deprecated and will now throw warnings. Please fix any of those warnings you come across in your patches to assure they will still assemble in Asar 2.0.
+
+
+
New features:
+
+
The error, warn and assert commands now support the same functions as the print command. (RPG Hacker)
+
Static labels (i.e. labels that don't move between passes) can now be used in more places, including if statements. (RPG Hacker)
+
Asar can be built as a static library. (Atari2)
+
Asar now uses named warnings and errors instead of magic numbers as identifiers. (p4plus2, RPG Hacker)
+
Variadic macro parameters now use the syntax <...[math]>, which makes them less ambiguous and helps prevent syntax parsing bugs. (RPG Hacker)
+
HiROM, ExHiROM, and ExLoROM mappers can now use freecode. (p4plus2)
+
check bankcross now allows disabling checking for half-bank crossings (going from $7FFF to $8000). (p4plus2)
+
New pc() and realbase() functions: returns the current SNES address that is being written to. (p4plus2, trillian)
+
Namespaces can now be saved using pushns and pullns. (p4plus2)
+
while loops can now be ended with endwhile. (p4plus2)
+
It's now possible to use macro arguments and macro labels in files that are incsrc'd from macros. (trillian)
+
Added for loops, used like for i = 1..10. These are more convenient than while loops in most cases and are the main replacement for rep. (trillian)
+
incbin now has a new syntax for including a range of the target file which looks like the for loop range syntax and is less ambiguous. (trillian)
+
Added spcblock feature as a replacement for spc-inline, which allows defining blocks of SPC data, but in a more flexible way that can easily be extended in the future. (p4plus2)
+
Added the --error-limit option, which allows raising the limit on the number of errors that Asar will print before stopping. (trillian)
+
freespacebyte command to set the byte value used for searching for freespace and expanding the ROM. (trillian)
+
+
+
Bug fixes:
+
+
Variadic arguments in macros can now also take zero arguments, which can be used to implement optional arguments. (RPG Hacker)
+
Escaping quotes in macro calls now works more reliably. (RPG Hacker)
+
Macro calls & definitions no longer break as easily from including whitespace. (RPG Hacker)
+
For invalid table files, Asar now prints the line number of the first invalid entry. (RPG Hacker)
+
Addr-to-line mappings now include autoclean jml/jsl commands, pseudo opcodes like asl #4, and most other data-writing commands like db/dw/dl. (spooonsss, RPG Hacker, trillian)
+
''' and ';' are now valid can now be used without causing errors. (trillian, RPG Hacker)
+
Fixed some edge case bugs in Asar's virtual filesystem (usable via the DLL) on Windows. (Atari2)
+
The --version commandline flag now causes asar to exit afterwards, which is the expected behavior for command-line flags. (Alcaro)
+
Fixed some bugs with the label optimizer, making it optimize better. (p4plus2)
+
Fixed freespaces sometimes being a few bytes too long. (trillian)
+
Assigning labels with = now puts them in the right namespace. (p4plus2)
+
Fixed some memory leaks and possible crashes in the DLL. (trillian)
+
Fixed some phantom errors when using forward labels. (trillian)
+
Asar should now allow as much recursion as system resources allow, and then throw a nice error instead of crashing. (Atari2.0, trillian, p4plus2)
+
optimize address now works a bit more consistently (new behavior also properly documented in manual). (trillian)
+
Fixed bug where pointing multiple autocleans at the same freespace would sometimes eat some of the data in it. (spooonsss)
+
+
+
Deprecated features:
+
+
Warning and error IDs: Use new name strings instead.
+
xkas compatibility mode: port your patch to asar instead. Everything xkas compatibility mode does should already throw warnings.
+
JMP.l: Use JML instead.
+
Quoted symbolic arguments to functions (e.g. sizeof("my_struct")): Remove the quotes (sizeof(my_struct)).
+
Redefining previously defined functions.
+
math round and math pri: Use parentheses and explicit rounding where xkas-style math emulation is needed instead.
+
if !condition to negate conditions: Use if not(condition) instead.
+
While blocks ending with endif: Use endwhile instead.
+
check bankcross on: Use check bankcross full or check bankcross half instead.
+
rep to repeat commands: Use while loops, unrolled loops or for loops instead.
table command: Assign characters directly instead, like 'a' = $00.
+
+
spc700-inline: Use spcblock and endspcblock instead.
+
spc700-raw: use arch spc700 and norom.
+
fastrom: Has never actually worked and can be removed.
+
header: Doesn't do anything and can be removed.
+
# before numbers in db/dw/dl/dd statements: this was intended for xkas compatibility but was for some reason enabled everywhere without a warning. The # does nothing and can be removed.
+
Non-UTF-8 source files: Re-save your source files as UTF-8 in a text editor of choice.
+
;@command and @command notation: Use command instead.
+
Single-line/inline if statements: Use full if blocks with an if/endif pair instead. (Note that you can still have an if statement entirely on one line, you just need to have an : endif at the end of it.)
+
freespace fixed: Use freespace static instead.
+
<math> syntax for variadic macro parameters: Use <...[math]> instead.
+
incbin with a range like incbin file.bin:0-F: use incbin file.bin:$0..$10 instead. (note that the new syntax is end-exclusive.)
+
incbin file.bin -> target: put an org or freespace command before the incbin.
+
if a = b: use if a == b instead.
+
Comments starting with ;[[ : These mark the start of block comments in Asar 2.0, so either remove the [[ for the time being, or make the commented line end with a ]].
+
Using A as a label name ambiguously, e.g. lda a: in Asar 2 this will be interpreted as trying to use the "A" addressing mode, and will give an error. You can use A+0 if you really must refer to the label as is.
+
The startpos command of the spc700-inline architecture: use the optional execute argument to endspcblock instead.
+
Specifying the byte to use for freespace like freecode $ff. Use the new separate freespacebyte command for it.
+
The warnpc command: use assert pc() <= $xxxxxx instead.
+
+
+
+
+
v1.81
+ Release: January 20, 2021
+
+
Contributors:
+
p4plus2
+
+
Bug fixes:
+
+
Prevent defines from being resolved in false branches of if statements when inside variadic macros
+
Fix a phantom error when referencing a struct before defining it
+
+
+
+
+
v1.80
+ Release: January 18, 2021
+
+
Contributors:
+
+
RPG Hacker
+
randomdude999
+
p4plus2
+
CypherSignal
+
LDAsuku
+
Katrina
+
Atari2.0
+
Vitor Vilela
+
+
+
New features:
+
+
The C DLL binding for Windows should now print a few more details if loading the DLL failed. (RPG Hacker)
+
The print command has a new bin() function. Also, bin(), dec() and hex() now take an optional width argument that allows padding the number with zeroes. (randomdude999)
+
Labels can now be used in the condition of an assert command. (randomdude999)
+
The WLA symbol file now includes an address-to-line mapping, which can be used by some debuggers to provide source-level debugging. (CypherSignal)
+
The sizeof() and objectsize() functions don't need quotes around the struct name anymore. For backwards compatibilty, quotes are still allowed. (p4plus2)
+
There is a new label optimizer, which can convert RAM labels to direct page or word accesses where possible. For this there are 3 new commands: dpbase, optimize dp and optimize address. (p4plus2)
+
The floor() and ceil() functions have been added. (randomdude999)
+
The bank() and <: function and math operator have been added (p4plus2)
+
The datasize() function has been added. (p4plus2)
+
Warning if the mapper mode is changed after being set (p4plus2)
+
Major improvements to internal string handling in asar (makes asar significantly faster) (p4plus2)
+
Variadic macro support (p4plus2)
+
Support for global labels (p4plus2)
+
Errors about crossing banks have been improved, now they print the exact line where the bank border was crossed instead of saying it was "somewhere before this point". (randomdude999)
+
Add fill align and skip align (randomdude999)
+
+
+
Bug fixes:
+
+
The Asar DLL can now be loaded in Windows applications that define UNICODE. (RPG Hacker)
+
Labels can now start with underscores. (LDAsuku)
+
An undef command inside an unexecuted if statement would still get executed. This is now fixed. (randomdude999)
+
The assert command would give strange errors when the condition to test contained a comma. This is now fixed. (randomdude999)
+
Trailing commas can now be used to join lines that contain more than one comma, and the joined lines can now have comments. (randomdude999)
+
An invalid warning ID in a warnings enable command no longer prints the error message three times. (randomdude999)
+
When using the Asar DLL, built-in defines (e.g. !assembler_ver) are now always present. Previously they were missing when the DLL was called without specifying a standard defines file. (randomdude999)
+
Repeatable instructions (like LSR #4 don't accept labels in their argument anymore. (randomdude999)
+
Asar no longer writes an incorrect checksum for ROMs whose size isn't a power of 2, e.g. 2.5MB, 3MB, 6MB. (randomdude999)
+
The "It would be wise to set the 008000 bit" warning has been relaxed and isn't thrown for labels in banks 70-7F. (randomdude999)
+
Overwriting built-in functions now throws a warning. Overwriting user-defined functions now also throws a warning for consistency. (randomdude999)
+
Opcode length specifications were sometimes being ignored in arch spc700. Now adc.w a, $0 properly assembles to 85 00 00 instead of 84 00. (randomdude999)
+
Fixed case sensitivity problem in function calls. (p4plus2)
+
Fixed struct definition with label base corrupting label name. (p4plus2)
+
Fixed missing error on certain types of label. (p4plus2)
+
Fix some phantom errors in math processor (randomdude999)
+
Fixed a memory leak in the cli version of asar (p4plus2)
+
Fixed a memory corruption in spc700 processing (p4plus2)
+
Fixed various memory bugs (found via valgrind/fsanitize) (p4plus2)
+
Fixed a case where if statements wouldn't always throw an error (randomdude999)
+
Fixed a case where you could get invisible errors when prefixing commands with @ (randomdude999)
+
Fixed arch superfx ignoring all commands with more than 2 words (randomdude999)
+
Fixed non-ASCII characters in strings being written as garbage (Katrina)
+
Fixed crashes when getting into an infinite recursion loop (randomdude999)
+
Improvements to syntax highlighting in the Asar manual (Atari2.0)
+
The C# wrapper has been updated to work with Asar versions 1.60 and newer. (Vitor Vilela)
+
Improved error message for SPC instructions with out of range arguments (randomdude999)
+
+
+
+
+
v1.71
+ Release: January 6, 2019
+
+
Contributors:
+
randomdude999
+
+
Bug fixes:
+
+
The Super FX ROM mapping should now properly support freespace.
+
The canread() functions returned true for the first byte after the end of the ROM. That has been fixed.
+
Using check bankcross off now should mess with the PC less (i.e. no forced fastrom addressing).
+
Using the error command now doesn't print the line of code that caused the error. All warnings except for the one from the warn command should now print the line of code that caused the warning. (note that not all warnings or errors are associated with a specific line of code.)
+
+
+
+
+
v1.70
+ Release: January 4, 2019
+
+
Contributors:
+
+
randomdude999
+
boldowa
+
+
+
New features:
+
+
The fullsa1rom mapper now supports automatic freespace searching. (randomdude999)
+
incbin ranges can now use math as an alternative to unprefixed hex. To use this, surround the math with parentheses. For example, incbin file:(4+2)-($F+$10). Note that in math statements, unprefixed numbers are decimal, not hex! (randomdude999)
+
+
+
Bug fixes:
+
+
Fixed quite a few crashes in Asar:
+
Fixed a crash when including a directory (randomdude999, found by Selicre)
+
Fixed a crash when using a macro sublabel outside of a macro (randomdude999)
+
Fixed a crash when having unmatched structs in a weird way (randomdude999)
+
Fixed a crash when appending to a non-existent define (randomdude999, found by Selicre)
+
Fixed a crash when Asar encountered mismatched quotes after define evaluation (randomdude999, found by Alcaro)
+
+
Made Asar about 2x faster than before (randomdude999)
+
Values larger than $80000000 in things like dd should work better (randomdude999)
+
Fixed a freespace leak when using prot (randomdude999, found by WhiteYoshiEgg)
+
Fixed Windows header includes, to make cross-compilation of Asar on Linux work better (boldowa)
+
+
+
+
+
v1.61
+ Release: August 22, 2018
+
+
Contributors:
+
+
randomdude999
+
+
+
Bug fixes:
+
+
Fixed asar quietly skipping assembling a line if it had a label followed by 3 or more spaces and ended with ".
+
In 1.60, if !condition was removed without a proper deprecation process. It has been re-added with a deprecation warning, because a few patches still managed to use it.
Added support for a new type of label declaration: prefixing a label or sub label declaration (including macro labels) with # will create that label without modifying existing label hierarchies. This is mainly intended for hacky incsrc/routine macros as used by GPS, which can break existing label hierarchies when used. (RPG Hacker)
+
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
+ Note that while it's technically possible to use this feature on sub labels, macro labels and macro sub labels, I don't think there's any reasonable use case for this. In most cases, regular macro labels and regular macro sub labels are recommended for usage inside macros.
+
+
Added support for include search paths. (RPG Hacker)
+
Added asar_patch_ex() function to DLL API, which works like asar_patch(), but takes additional parameters. (RPG Hacker)
+
You can now escape ! by doing \! (useful for preventing Asar to replace defines in certain places). (randomdude999)
+
You can now escape \ by doing \\. (RPG Hacker)
+
Added support for pushbase/pullbase. (randomdude999, RPG Hacker)
+
Added check title command which makes Asar verify the title of the output ROM (to assure a patch is applied to the correct ROM). (randomdude999)
+
Added support for nested namespaces. (randomdude999, RPG Hacker)
+ Enable them via the command:
+
namespace nested on
+
+
Added support for check bankcross off which disables checking for bank crossing. Use with caution; might not work with certain features or outright break some stuff. (randomdude999, RPG Hacker)
+
Added a new, simple README. (randomdude999, RPG Hacker)
+
Added a filesize() function and a getfilestatus() function. (randomdude999)
+
Added support for stdincludes.txt and stddefines.txt - see manual for details. (RPG Hacker, randomdude999)
+
Added support for setting defines via the command line or DLL API. See manual (section: usage) for details. (randomdude999)
+
Added includeonce command for shared files which may be included multiple times, but should only be assembled once. (RPG Hacker)
+
Added support for generating a symbols file. Currently, WLA and no$sns format are supported. (KevinCathcart)
+
Opcode length specifiers (.b, .w and .l) are now also supported for the SPC700 architecture. (KungFuFurby)
+
Added stringsequal() and stringsequalnocase() functions. (RPG Hacker)
+
Added support for some built-in defines. Currently, !assembler and !assembler_ver are supported. Trying to modify those defines will throw an error. (RPG Hacker)
+
Added IDs to all warnings and errors, together with functionality to enable or disable specific warnings. (RPG Hacker)
+
Added a new optional warning that has to be enabled manually to throw warnings when opcodes are implicitly sized. (KevinCathcart)
+
Added functionality to allow overriding Asar's default behavior of enabling/disabling checksum generation based on context. (randomdude999)
+
+
+
Bug fixes:
+
+
Fixed various bugs in the DLL interface. It should now hopefully be possible to apply multiple patches in succession via the DLL interface without resorting to hacks. (RPG Hacker, randomdude999, boldowa)
+
Rewrote big parts of test applications once again to make it a lot easier to test a bunch of ASM files and actually get some meaningful information out of it. (RPG Hacker)
+
Fixed the way ;@ works. This command was really meant for backwards-compatibility with xkas and is supposed to assemble everything following it, which it now does again. (RPG Hacker)
+ As a result of this change, any of the following are now valid Asar code:
+
;@asar 1.60
+@asar 1.60
+asar 1.60
+ When Asar finds an unknown command on a line starting with ;@ or @, it only throws a warning instead of an error. You can make use of this fact by using optional features from newer Asar versions and still have your patch assemble in old Asar versions, where those features are ignored (don't know how practicable and useful this really is, but in theory, it should be possible). And of course it can be used for patches that are compatible with both xkas and Asar, not that that's particularly useful anymore in this day and age.
+
Changed format of existing command line arguments for consistency. (RPG Hacker)
+
LoROM banks $70 to $7D can be used correctly. (randomdude999)
+
Struct definitions are cleared correctly in Asar lib. (randomdude999)
+
Fixed a freeze that could occur when using freedata align. (TheBiob)
+
Fixed a bug in pad command that made it not update the pc correctly and also made it trigger a bank cross error before actually writing any data into a new bank. (RPG Hacker)
+
Fixed a rare crash when using the command-line interface in ways you're not supposed to use it. (randomdude999)
+
Fixed readfile()/canreadfile() crashing when reading from more than 16 different files in the same patch. (randomdude999)
+
Fixed the ROM title being reported incorrectly. (randomdude999)
+
Fixed using really large values in math with math round on making the values negative sometimes. (randomdude999)
+
Fixed an SA-1 mapping issue. (Vitor Vilela, randomdude999)
+
Fixed print double() not working when any of their arguments contain commas or parentheses. (randomdude999)
+
Made it possible to pass string parameters to functions like readfile1() via user-defined functions. Previously, this failed as Asar expected all parameters in user-defined functions to be numbers. (KevinCathcart)
+
Fixed a bug related to evaluation of parameters in user-defined functions. In some situations, Asar returned the incorrect parameter. For example: given a user-defined function with a parameter ab and a paramater abc, Asar occasionally returned the parameter abc when referencing the paramter ab. (KevinCathcart)
+
Added more undocumented features to the manual. (RPG Hacker)
+
0x hex literals were supported by Asar on some platforms, which wasn't supposed to be the case. Made sure 0x hex literals throw errors on all platforms. (randomdude999)
+
+
+
Deprecated features:
+
+
Started the process of deprecating xkas compatibility mode. From now on, using xkas compatibility features will throw warnings. In a future version of Asar, xkas compatibility will be removed entirely.
+
Started deprecating autoclear, which is an alias of autoclean. Please use only autoclean from now on.
+
Started deprecating freespace fixed, which is an alias of freespace static. Please use only freespace static from now on.
+
Deprecated and removed support for if !condition. This feature was planned for deprecation as it bites with Asar's define syntax, but it was removed earlier than planned because, after inspecting the code, it was determined that it didn't work properly and probably wasn't even usable in versions prior to 1.60 at all. The only way to use it in Asar 1.60 was by using the new escape sequence for !, which didn't exist in earlier Asar versions. Thus it can be assumed that the feature wasn't used in previous Asar versions and can be removed safely. To negate conditions in Asar 1.60, either use the built-in logic functions (if !(a == 0 && b == 0) becomes if not(and(equal(a, 0),equal(b, 0)))) or directly negate the condition (if !(a == 0 && b == 0) becomes if a != 0 || b != 0).
+
+
+
+
+
+
v1.50
+
+ Release: February 28, 2017
+
+
Contributors:
+
+
RPG Hacker
+
p4plus2
+
+
+
New features:
+
+
Added support for structs.
+
Added API to Asar lib for getting information on all blocks of data written by Asar.
+
Added API to Asar lib for getting the mapper currently used by Asar.
+
Added support for ExLoROM and ExHiROM mappers.
+ NOTE: Based entirely on conversion tables I got from Ladida; don't know if these conversions are actually correct. Some features may not work as intended when using those mappers (such as freedata, for example), but I can't verify this.
+
Added pushtable and pulltable commands, which let you back-up or restore the current character table to the/from the stack.
+
Added ext\notepad-plus-plus\syntax-highlighting.xml. This file can be imported into Notepad++ as a user-defined language to add syntax highlighting for Asar patches, featuring all commands currently supported by Asar. By default, this syntax highlighting is enabled on all files with an extension of .asm or .asr, but this can be customized via Notepad++.
+
+
+
Bug fixes:
+
+
Lines starting with @ or ;@ that don't map to a recognized special command now only throw warnings at best and no errors.
+
Rewrote code of tests a little to make them easier to execute and make them clean up their own mess.
+
C# wrapper for Asar DLL was non-functional since it didn't specify a calling convention, making it always lead to an exception in some scenarios.
+
+
+
Notes:
+
+
Just like the last version, this version of Asar was built in MSVC rather than g++, but this time I also updated the Asar DLL (which I had overlooked last time). I'm not sure if Windows applications are compatible with DLLs that were built by a different compiler, so if you're planning to use the DLL, this is something to watch out for. If you're planning to use a compiler other than MSVC, I recommend just rebuilding the DLL from source in whatever compiler you're using (or directly including the Asar library code in your project).
+
+
+
+
+
+
v1.40
+
+ Release: October 23, 2016
+
+
Contributors:
+
+
RPG Hacker
+
+
+
New features:
+
+
readfile functions: readfile1(filename, offset), readfile2(filename, offset), readfile3(filename, offset), readfile4(filename, offset) - similiar to read1() etc. functions, except data is read from another file instead of from the ROM (note that offset is a PC offset, not a SNES offset). You can pass an optional third value which is returned if the read fails. These functions are primarily intended for reading bytes from another file and then doing math with them. For example: reading bytes from a Lunar Magic .pal file, converting them into a different format and then writing them to the ROM as a table that can directly be DMA'd to CGRAM without further conversions (all conversions happen at compile-time). As an additional bonus, all of those functions cache any file passed to them (up to 16 simultanous files), which means that multiple readfile() calls on the same file will keep the file open rather than repeatedly opening and closing the file.
+
canreadfile functions: canreadfile1(filename, offset), canreadfile2(filename, offset), canreadfile3(filename, offset), canreadfile4(filename, offset), canreadfile(filename, offset, length) - basically the readfile() equivalents of canread1() etc.
+
snestopc(address) and pctosnes(address) functions: for manually converting addresses (note that those functions are dependent on the ROM's current mapping mode, so use them with caution - chances are you will never need them at all).
+
max(a, b), min(a, b) and clamp(value, min, max) functions: max()/min() return the maximum/minimum of two values, whereas clamp() makes sure that that value is >= min and <= max.
+
safediv(dividend, divisor, exception) function: divides dividend by divisor, unless divisor is 0, in which case exception is returned.
+
select(statement, true, false) function: if statement is 0, false is returned, in any other case, true is returned. Basically, a mathematical version of "if/else". Please note that unlike if/else blocks, function arguments in Asar are always evaluated before a function returns. In other words: if you do select(1, 1/1, 1/0), Asar will throw a "division by zero" error, even though the function would return 1/1. In this particular case, it's recommended to simply use the safediv() function in place of a regular division.
+
not(value) function: returns 1 if value is 0 and 0 in any other case.
+
comparison functions: equal(a, b), notequal(a, b), less(a, b), lessequal(a, b), greater(a, b), greaterequal(a, b) - rather self-explanatory, return 1 if the respective comparison is true and 0 otherwise. Primarily intended to be passed as statement to select() function.
+
logical functions: and(a, b), or(a, b), nand(a, b), nor(a, b), xor(a, b) - also self-explanatory, return 1 if the respective logical operation is true and 0 otherwise. Primarily intended to be passed as statement to select() function.
+
while loops: Added compile-time while loops to Asar. Those work similar to if conditionals, with the difference that their blocks are assembled repeatedly until their condition becomes false. For easier implementation and higher compatibility, while loops are terminated with endif, just like if conditionals. When using while loops, be careful not to cause an infinite loop. Asar won't make any effort to detect those.
+
Multiline operator: You can now put \ at the end of any line of source code and Asar will append the next line to it. This is similar to putting a , at the end of a line, with the difference, that the \ itself does not appear in the concatenated string, whereas the , would. This is useful to split long function definitions into multiplie lines, for example. Note that all whitespace following the \ is ignored, whereas whitespace preceeding the \ isn't. Therefore
+
db\
+$FF
+ turns into
+
db$FF
+ for example, whereas
+
db \
+$FF
+ turns into
+
db $FF
+
+
double(num) print function: Can be passed to print to print a double variable with its fractional part. Has a default precision of 5 decimal places, but can be passed an optional second argument to override the precision.
+
round(num, precision) function: Rounds the double variable num to precision decimal places. Pass 0 as precision to round to the nearest integer.
+
+
+
Bug fixes:
+
+
Asar 1.37 officially suppported overloaded versions of read1() to read4(), but always threw "Wrong number of parameters to function" errors when actually using those overloaded versions.
+
Asar 1.37 threw "Wrong number of parameters to function" error for function canread() when passing 2 arguments to it, because it actually treated it as canread1() due to an internal error in string comparison.
+
Using better double -> int conversions in some places - where
+
dd $FFFFFFFF
+ would assemble to 00 00 00 80 ($80000000) in Asar 1.37, it now assembles to FF FF FF FF
+
Defines in elseif conditionals now get properly resolved.
+
The #= define operator now doesn't truncate its value when using math round off, making it possible to do double-precision math with it.
+
Asar 1.37 detected misplaced elses and endifs, but not misplaced elseifs.
+
Putting @xkas : @asar 1.37 on the first line would previously lead to an error, whereas putting @asar 1.37 : @xkas there would not. Both variations lead to an error message now, since it really doesn't make much sense to use them together in any combination.
+
Special commands like @asar or @include could previously be used on the first line only and needed to be chained with a : inbetween. They can now be used on any line as long as no other command comes before or inbetween them.
+
Asar 1.37 fixed a bug in SuperFX compilation, but src/test/arch-superfx.asm was never edited to acknowledge this fix, so the test always failed
+
Added different define operators (=, +=, :=, #=, ?=) to manual.txt. Those have been in Asar for quite a while, but were never documented yet, although they can be quite useful.
+
+
+
Notes:
+
+
This version of Asar was built in MSVC rather than g++, mainly because I already had that installed and use Visual Studo as an IDE, anyways. Functionally, this shouldn't make any difference, unless using Asar in unintended ways, where anything goes. I did build the Linux version in g++ to confirm compatibility, though.
+
+
+
+
+
+
v1.37
+
+ Release: March 26, 2016
+
+
Contributors:
+
+
Raidenthequick
+
+
+
New features:
+
+
New freespace argument added; a $xx byte that will search the ROM for contiguous sections of that byte. Before it was hardcoded to only search for $00. Default is still $00 if not supplied, so past patches should not be broken.
+
In line with this, autoclean was hardcoded to clean using $00. This was fixed also to clean with the byte supplied by freecode, or $00 if not supplied.
+
+
+
Bug fixes:
+
+
Super FX short addressing fixed, and added error checking for valid short address. For example, lms r0,($00D4) used to output 3D A0 D4, which is actually incorrect because short addressing doubles the byte supplied by the instruction to give a range from $0000-$01FE with just one byte (since Super FX reads words). This now outputs 3D A0 6A which is correct. Also, asar now throws an error for anything outside $0000-$01FE as well as all odd-numbered addresses for both sms and lms instructions. (Odd-numbered addresses cannot be accessed using short addressing due to the multiplying by 2.)
+
Super FX and SPC700 labels were broken if used within freespace. This has been fixed by doing what 65816 does: mask the address with 0xFFFFFF because freespace addresses use a high byte to indicate that they're freespace.
+
Fixed SA-1 mapping using wrong Super MMC banks range.
+
+
+
+
+
+
Version information below here was added retroactively and may be incorrect and/or incomplete.
Asar now halts if more than 20 errors are detected.
+
+
+
+
Bug fixes:
+
+
Fixed a warning about $xx,y not existing if $xxxx,y doesn't exist either
+
Fixed sublabels requiring a parent label even in xkas compatibility mode
+
Fixed a memory leak in the DLL
+
+
+
+
+
v1.35
+
+ Release: December 13, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Made freecode print the size of the requested freespace if allocation fails.
+
+
+
Bug fixes:
+
+
Fixed a crash caused by incbin'ing a file and specifying an endpoint beyond the end of the file.
+
Blocked readN on exactly one byte after the end of the input ROM.
+
+
+
Deprecated features:
+
+
fastrom has been removed. It gives far too many problems relative to its advantages (are there any?). In exchange, freespace searching in lorom is now always fastrom enabled. (The command itself still exists, but it does nothing.
+
+
+
+
+
+
v?.??
+
+ Release: November 11, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Added -DTIMELIMIT support on Windows. Note that it's more limited than on Linux; it seems to only check the time limit every seven seconds, it can't print error messages, and it bugs up on anything above 429 seconds. (But you shouldn't need to set it above one or two anyways.)
+
+
+
Bug fixes:
+
+
Missing an org/freespace command now no longer places the first byte at SNES $FFFFFF, but jumps to $008000 directly.
+
Allowed JMP.l in xkas mode...
+
Fixed PC->SNES conversion for 0x380000 and higher.
+
Fixed BEQ a.
+
fastrom : org $8000 : db $01 : warnpc $8001 no longer throws errors.
+
Made bit shifting unsigned, to match how xkas behaves.
+
Made db $0-10 return -10, not -16.
+
Including a file that enables xkas mode, while xkas mode is already enabled, no longer throws errors.
+
Fixed dd $FFFFFFFF acting like dd $7FFFFFFF.
+
Fixed compile errors on GCC 4.7.
+
Made blockreleasedebug and blockdebugrelease not show up anymore.
+
Files saying @asar can no longer be included from files saying ;@xkas.
+
Locked org $F00000.
+
+
+
+
+
+
v1.33b
+
+ Release: October 26, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Rearranged the manual a little to have a more obvious filename.
+
Nuked a debug code that kept printing nonsense.
+
+
+
Notes
+
+
Asar now considers OS X a non-Linux Unix-line and recommends -Dlinux.
+
+
+
+
+
v1.33
+
+ Release: October 22, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Made incbin file.bin -> $123456 possible. This one can go as far as you want; it doesn't mind crossing banks nor exceeding the size of a RATS tag. It does, however, demand to know the SNES position in advance; you can't use labels here. (It also refuses to go outside the ROM)
+
Added a sandbox mode that disables everything that loads external files. Only accessible by recompiling (-DSANDBOX) since it should only be useful for people who have compilers already.
+
Added a way to make the process abort if it runs too long. Linux+recompile (-DTIMELIMIT=60) only.
+
+
+
Bug fixes:
+
+
Nuked some spurious warnings in incsrc/incbin if the base path contains backslashes.
+
Made Asar a little more eager to detect bank crossings. Now those errors appear in the correct file.
+
Made REP #$FFFF throw errors instead of repeating 65535 times.
+
Fixed a bunch of weird code in the freespace finders.
+
Made sure . does not count as a label.
+
Fixed LDA Label,y in emulation mode. Asar tried using 24-bit addressing for that, but there is no such addressing mode.
+
Another accuracy improvement in emulation mode.
+
Detonated some more SPC700 inaccuracies and bugs.
+
Made JMP ($1234)+($3412) assemble to JMP abs, not JMP (abs).
+
+
+
+
+
+
v1.32
+
+ Release: October 8, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Added @xkas, which will revert to maximum xkas compatibility mode and change the behaviour of a couple of commands (as well as throwing warnings on various Asar-only commands).
+
Any line starting with ;@ will now be assembled. This is intended to be combined with the above one to create ;@xkas, which will send Asar into xkas mode while letting xkas ignore it, but you can also use ;@if 0 : org !Freespace : ;@endif : ;@freecode (except with the colons replaced with linebreaks).
+
Replaced bank off with bank auto, and added bank noassume, which always uses long addressing if possible.
+
Removed the @ trick for suppressing warnings. Its only legit use was telling Asar that a freespace is cleaned in a way it can't understand. freecode cleaned is the new way to say that.
+
Whitespace, blank lines and comments are now allowed to exist before @asar, ;@xkas and @include/@includefrom.
+
Added !define ?= value, which sets !define to value if !define is previously undefined.
+
+
+
Bug fixes:
+
+
Blocked \ in incsrc/bin because linux.
+
Reworked prot a bit. You can now use multiple prot statements in the same freespace; Asar has always allowed cleaning them out anyways. The old implementation was rather hacky.
+
Fixed build scripts a little. Some files didn't get included.
+
Fixed the internal ROM size when expanding SA-1 ROMs.
+
Killed some dead code.
+
Made db 0x80 assemble properly with math round on (the default).
+
Killed a phantom error on ALS A and a couple of similar constructions.
+
Squished a possible moving labels error.
+
Fixed a bug where the major version of Asar got compared backwards in @asar.
+
+
+
+
+
+
v1.31
+
+ Release: September 13, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Added incbin file.bin -> Labelname support.
+
Added align detail to freespace/freecode/freedata.
+
Made reset freespaceuse a valid operation.
+
Added arch spc700.
+
+
+
Bug fixes:
+
+
Killed some more Linux compile errors.
+
+
+
Deprecated features:
+
+
Deprecated arch spc700-raw.
+
+
+
+
+
+
v1.30
+
+ Release: August 24, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Added SuperFX mapper and arch superfx.
+
Unlocked $[F0-FF]:[8000-FFFF] in lorom again. Turns out bsnes only maps SRAM to the lower halves of those banks.
+
Added an elseif command.
+
Added && and || support to if/etc conditionals.
+
Reworked the Relative branch out of bounds errors a little, so it tells how far outside the bounds they are.
+
Added print dec($1234) and print hex(1234).
+
Attached test suite in the source zip, in case some other programmers are interested.
+
Added @include and @includefrom, which throws errors if Asar is invoked directly on them.
+
Added a -pause=<action> flag on the command line. Valid actions are "yes", "warn", "err", and "no" (default).
+
Added a couple of synonyms to the single-bit SPC700 opcodes.
+
Added underscore-prefixed versions of all builtin functions.
+
Added error-safe readN and canreadN.
+
+
+
Bug fixes:
+
+
Reworded the 125 freespaces limit to make sure nobody can think there's a limit of 250 labels.
+
Made readN()ing and writing to the same byte in ROM well defined (it gives the same value as it had in the input ROM).
+
Made the size guesser a little smarter. It now assumes .b for LDA #$123456/65536.
+
Killed a phantom error on the very rare code pattern db $80/(Label2-Label1) : Label1: : db 0 : Label2: and similar.
+
Adjusted the error messages read1/etc gives if the address is invalid.
+
Suppressed a couple of useless errors if labels are redefined.
+
Killed a couple of Invalid endif errors if an if statement is invalid.
+
Repaired nested pushpc/freedata.
+
+
+
+
+
+
v1.29
+
+ Release: July 19, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Added -v and -version switches.
+
Removed the lock on $700000-$7DFFFF in HiROM as it's not mapped to SRAM there.
+
Edited the library API a bit.
+
+
+
Bug fixes:
+
+
Added an error message for mov (x)+,a in the SPC700 modes.
+
Nuked a bug making tabs not treated as spaces in all contexts.
+
Fixed a bug where Label = 123 checked that there is an org in front.
+
Fixed a bug where the line number was removed if the last code block on a line crossed a bank border.
+
+
+
+
+
+
v1.28
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Flipped the switch to autocorrect the checksum to on by default.
+
+
+
Bug fixes:
+
+
Nuked some double spaces in outputs.
+
Fixed sa1rom mapping breaking on everything except the first megabyte.
+
Fixed a couple of bugs with valid table files being rejected.
+
+
+
+
+
+
v1.27
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Made freespace fixed a synonym of freespace static.
+
Made Asar try to autodetect whether the ROM is LoROM or HiROM. Homebrews default to LoROM.
+
+
+
Bug fixes:
+
+
Zapped a phantom error if the code arch spc700-raw : org $010000 : db $00 is used.
+
Nuked some pointless errors with static freespaces.
+
Zapped a bunch of bugs with static/fixed freespace.
+
Killed a bug that crashed Asar if a line contained both commas and unmatched quotes.
+
Replaced the Press Enter to continue with the standard Press any key to continue prompt on Windows.
+
Refactored some parts of the math parser, to get rid of some possible escaping NaNs.
+
Added some #errors if no frontend is chosen, and edited some others a bit.
+
Adjusted Linux support a bit. Looks like it bitrotted.
+
Fixed some off-by-one errors in spc700-inline.
+
+
+
+
+
+
v1.26
+
+ Release: April 28, 2012 or earlier
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Added support for db +1. There's no reason not to allow it.
+
+
+
Bug fixes:
+
+
Removed some more files made useless by dropping asar-clr.dll.
+
Fixed a bug where db $12,$34 broke in the spc700 modes.
+
Fixed a bug where an invisible bank border was hit if a base command was used without an org command.
+
+
+
+
+
+
v1.25
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Rewrote the .NET library as a C# wrapper around asar.dll using P/Invokes, for better Linux compatibility (Mono really seems to hate C++/CLI). This also means that asar-clr.dll no longer exists.
+
Made errors not shred the ROM in the library frontend.
+
+
+
Bug fixes:
+
+
Killed a bunch of moving label errors if a PROT is misplaced. No point throwing 300 errors for one misplaced line.
+
Fixed error messages erroneously being printed to stdout instead of stderr.
+
Fixed errors with prot being incompatible with fastrom.
+
Fixed an uninitialized variable.
+
Fixed a buffer underflow Valgrind whined about.
+
Zapped a null pointer bug in the library if a file was not found.
+
Nuked a bug where the library did not clear out previous errors when applying a new patch.
+
+
+
+
+
+
v1.24
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Added SA-1 support. Syntax is sa1rom 0,1,2,3, where the four numbers are the bank numbers, 0 through 7. It's allowed to not give them; that will result in 0,1,2,3 being picked as default.
+
Added freespace finding support for hirom and sa1rom.
+
Made Asar remove extranous quotes around filenames if a file is pulled to the Asar window.
+
Minor adjustment to the ROM title verifier.
+
+
+
Bug fixes:
+
+
Fixed a phantom error if prot isn't used directly after a free* statement.
+
Fixed a bogus error if prot is placed at any of the first eight bytes of a bank.
+
Repaired autoclean, which appears to have broken a few versions ago.
+
Fixed a crash bug if the ROM does not exist and couldn't be created.
+
+
+
+
+
+
v1.23
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Fixed around ten broken SPC700 opcodes.
+
+
+
+
+
+
v1.22
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Added a few special cases for some functions, and adjusted some compiler flags. The result is dramatically improved performance.
+
Adjusted the string table a bit.
+
+
+
Bug fixes:
+
+
Fixed an uninitialized value in the macro handling code that may (but usually doesn't) throw errors if a macro has no arguments.
+
Repaired partial incbin if the filename is quoted.
+
+
+
+
+
+
v1.21
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Fixed: read1() etc. went missing.
+
+
+
+
+
+
v1.20b (?)
+
+ Release: March 4, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Added freecode static and norom to changes.txt.
+
+
+
+
+
+
v1.20 (?)
+
+ Release: March 4, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
freecode/freedata have been expanded: They now take an optional parameter containing comma separated parameters on how to hand out the freespace. Valid parameters are ram, noram, and static. ram tells Asar that this code needs the RAM mirrors and puts the code in banks 10-3F; noram tells Asar that the code (or table) does not need the RAM mirrors, and therefore uses banks 40-6F if possible; static demands that the freespace does not move; if it grows, Asar throws an error. freespace has also been added; freecode is a shortcut to freespace ram.
+
Added hirom support. It works just like in xkas: hirom : org $C00000 : JML Main. Also added norom, where the PC address is the same as the SNES address (not counting SMC headers); use this (and base) if you want to implement your own mapper (preferably in a macro).
+
Simplified table code, and made it accept assigning stuff to the = character.
+
LDY #Label>>16 (and LDA/LDX/etc) is now considered 8bit. This should reduce the need for explicit .b hints.
+
Asar can now use the last byte of the ROM as freespace.
+
Made the default value for untouched table bytes be more random to make errors in usage more obvious.
+
Lowered the recursion limit a bit.
+
You can now drop the extensions on both filenames, if you want to.
+
Asar now tries to no longer parse defines inside if 0 blocks. Note that this doesn't help on single-line if statements; you'll need a multiline if.
+
Added !def := val, which expands everything inside the value before setting it (making !a := a!a a perfectly safe operation).
+
Added !def #= val, which expands the value into an integer and stores it into the define. !a #= 1+1 : L!a: is a valid operation.
+
+
+
Bug fixes:
+
+
Fixed fastrom again again again.
+
Labels before the first org/freecode/etc are now considered to be at $008000, not $FFFFFFFF. (They're still considered invalid.)
+
Some minor fixes in autoclean dl Label.
+
Repaired the ** operator.
+
Calling a function no longer hits a user-defined function starting with the name of called function.
+
Fixed skip command, which previously only edited the base address.
+
+
+
+
+
+
v1.14 (?)
+
+ Release: February 8, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Killed a crash bug.
+
+
+
+
+
+
v1.13 (?)
+
+ Release: February 7, 2012 (?)
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Added a random icon, to fit the Nordic theme of Asar's name.
+
Made asar_patch destroy the ROM if any errors are encountered, to ensure that nobody attempts to use a ROM that may contain subtle breakage.
+
A label can now be on the same line as a macro call.
+
+
+
Bug fixes:
+
+
Fixed the bug that makes macros look like they're called from themselves if the macro call is broken.
+
+
+
+
+
+
v1.12 (?)
+
+ Release: February 6, 2012 or earlier
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Fixed fastrom mode again...
+
Fixed crashes when closing Asar while waiting for input.
+
Macro definitions are now ignored inside if 0 blocks.
+
Macros and incsrc may now be called inside if 1 blocks.
+
Locked banks $F0-$FF from usage. They are not usable.
+
+
+
Deprecated features:
+
+
Removed most of the emulation mode. The only remaining change is that it makes Asar print the errors to stdout instead of stderr, since that quirk isn't fixable by editing the ASM files.
+
+
+
+
+
+
v1.11 (?)
+
+ Release: January 25, 2012 or earlier
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Prefixing a command with @ will now make Asar not print warnings for that line.
+
+
+
Bug fixes:
+
+
JMP and JSR within the current bank with bank active has been fixed.
+
xkas appears to allow sublabels starting with numbers. Asar has been updated to do the same.
+
fastrom no longer messes up branches.
+
autoclean read3($123456) can now be used before the first org.
+
db ($04<<2)|($80>>1) no longer breaks due to unmatched parentheses.
+
Fixed problem with autoclean $123456, where it read a pointer from $123456 instead of removing $123456.
+
Fixed a crash if a freespace block protects itself.
+
+
+
+
+
+
v1.10 (?)
+
+ Release: January 13, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Made asardll.h and asardll.cpp work if compiled as both C and C++, and renamed asardll.cpp to asardll.c, for greater compatibility with other languages (hi, Objective-C). As an effect of this, the library name argument has disappeared from asar_init.
+
base off is now a valid operation. It tosses the base address back to the current code insertion location.
+
New command: bank. It makes the label optimizer act as if it's in another bank. This is not the same as base; LDA Label,x : Label: db $01,$02,$03,$04 will use 24-bit addressing for the LDA if bank is active. It's intended for long codes that assume the data bank register is not the same as the code bank register.
+
Added a copy of GPLv3 to asar.zip, since LGPL is apparently meaningless on its own. These licenses are starting to get a little tricky.
+
+
+
Bug fixes:
+
+
Reworded the documentation for prot.
+
Asar now throws a warning if a freespace block appears to be leaked.
+
Adjusted "autoclean at the end of a RATS tag" error a bit.
+
Made Asar not read uninitialized/garbage memory if there's crappy content at the end of a macro.
+
Fixed infinite loop if a freespace of size 32768 is requested.
+
+
+
+
+
+
v1.09 (?)
+
+ Release: January 6, 2012
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
New command: warn.
+
The math parser now accepts strings like 0.5 if you turn off rounding. It'll break if rounding is on, since that wouldn't make any sense. It'll round down as soon as it's returned from the math parser; db 0.9 is the same as db 0, but db 0.4*0.4 is the same as db 1.
+
assert can now take another parameter. If this is given, it is printed in the error message. (All error-generating blocks are printed, which makes these messages appear twice)
+
Asar now attempts to check if the ROM title looks sane before applying a patch.
+
Added Linux/OSX support to asardll.cpp.
+
Added asar_math() to the library frontend.
+
Now prints a message if patching is successful. However, calling it from the command line makes it remain silent, unless you add -verbose.
+
+
+
Bug fixes:
+
+
Restored documentation of the functions to changes.txt that were forgotten when removing stdlib.asm.
+
Fixed crashes if a macro is called with wrong number of arguments.
+
Fixed silent errors when using LDA Label,y if Label is in another bank.
+
+
+
+
+
+
v1.08 (?)
+
+ Release: December 27, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Added special meaning to the define !assembler: Its value is always "asar", even if you assign something else to it. Intended usage: !assembler = xkas : %freespace_!assembler(), where %freespace_xkas() requires the user to set freespace and %freespace_asar() contains a freecode.
+
+
+
Bug fixes:
+
+
Restored db 1+'a' support to the math parser.
+
Merged the dupe descriptions for the fastrom command in the documentation.
+
Fixed sublabel support, which the new math engine broke as well.
+
+
+
+
+
+
v1.07 (?)
+
+ Release: December 25, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Replaced the math library with a more powerful one.
+
New command: math.
+
Homemade functions can now safely replace builtin ones, to compensate for the possibility that new builtin functions may collide with ones in your codes.
+
Added a few new functions: log, log10, and log2.
+
+
+
Bug fixes:
+
+
Removed #ifdef ALCAROBOT (sandbox mode) from a few source files.
+
Fixed a few more memory leaks.
+
+
+
+
+
+
v1.06 (?)
+
+ Release: December 25, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Sprite Tool compatibility was still broken. Looks like tmpasm.bin is unheadered after all. Repaired again.
+
+
+
+
+
+
v1.05 (?)
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Updated libsmw and libstr to the latest versions from AlcaRobot.
+
+
+
Bug fixes:
+
+
Asar no longer crashes if it tries to open a file of less than 512 bytes if it thinks it's headered. This fixes Sprite Tool compatibility.
+
+
+
+
+
+
v1.04 (?)
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
$xxFFFF can now safely be overwritten.
+
Removed garbage from some errors.
+
+
+
+
+
+
v1.03 (?)
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Renamed the DLL frontend to LIB, since DLLs only exist on Windows and dynamic libraries exist elsewhere too. No point using more Windows terminology than needed.
+
Various edits to the library frontends. asar_i_* has been renamed to asar_*, and errors and warnings now tell where they're called from, if found inside a macro.
+
The command line frontend tells where problematic macros are called from.
+
Made license choice explicit.
+
+
+
+
+
+
v1.02 (?)
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Made it possible to call asar_i_patch() multiple times without calling asar_reset() between them. The errors will remain until you asar_reset() is used, meaning they'll accumulate until they are cleared.
+
+
+
Bug fixes:
+
+
Fixed a crash bug in asar_i_reset() if the function does not create any custom functions.
+
+
+
+
+
+
v1.01 (?)
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Put a few lines back where they should be, to get rid of a crash.
+
+
+
+
+
+
v1.00 (?)
+
+ Release: December 2, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
If an error occurs, it now prints the buggy block, if relevant.
+
Various changes to the DLL API.
+
Crappily cobbled together a hack to make Asar compatible with Sprite Tool (a file called tmpasm.bin is now considered to be headered).
+
Included the script used to compile the .NET DLL.
+
+
+
Bug fixes:
+
+
Fixed a memory allocation mismatch.
+
+
+
Deprecated features:
+
+
Dropped autocolon, since it's useless and never used.
+
The set command has been removed.
+
stdlib.asm has lost its special meaning.
+
+
+
+
+
+
v?.??
+
+ Release: November 29, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
asar-cli.dll has been renamed to asar-clr.dll, and its contents has been moved to namespace AsarCLR instead of asarcli. This will require your tools to be edited, but it shouldn't take longer than a minute or two.
+
Added a function to the DLLs to view the table data.
+
New setting: werror. It makes warnings emit errors if encountered.
+
+
+
Bug fixes:
+
+
pushpc no longer throws idiotic errors everywhere.
+
asar-clr.dll can now return errors/warnings/etc without crashes.
+
Killed off a bunch of memory leaks in asar-clr.dll.
+
STA $12,y warnings now print only once.
+
asar_resolvedefines no longer throws exceptions outside the DLL.
+
Squashed a memory leak bug where the math module allocates some memory without freeing it when the DLL is unloaded.
+
+
+
Deprecated features:
+
+
Removed AsarCLR::Asar::unmanageerrors() from asar-clr.dll. It's an internally used function that shouldn't be exported.
+
+
+
+
+
+
v?.??
+
+ Release: November 21, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Fixed a bug that made + and - labels not be treated as labels under some circumstances.
+
Made "relative branch out of bounds" errors disappear again unless they're supposed to exist.
+
+
+
+
+
+
v?.??
+
+ Release: November 20, 2011
+
+
New features:
+
+
if 0 now blocks label creation.
+
asar-cli.dll now exports a set of functions using .NET types instead of C types.
+
The DLL APIs have been slightly changed with regards to initialization and stdlib.asm.
+
Asar now prints warnings and errors to stderr instead of stdout. (Emulation mode is unaffected.)
+
+
+
Bug fixes:
+
+
Repaired "branch out of bounds" errors.
+
+
+
+
+
+
v?.??
+
+ Release: November 17, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Removed more debug code
+
Fixed org Label if the label is in freespace
+
+
+
+
+
+
v?.??
+
+ Release: November 17, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
You can now use if !condition to negate the statement. Note that you may need an extra set of parentheses due to conflicts with define syntax.
+
Parentheses can now be used inside macro arguments. (Just make sure to close them.)
+
Included a .NET version of asar.dll. Note that it still uses unmanaged types.
+
Asar now accepts org Label if the label is defined prior to use. (It's still not allowed to jump to a label that's defined later in the patch.)
+
+
+
Bug fixes:
+
+
If a relative branch is out of bounds, Asar no longer throws "labels keep moving around" errors.
+
Removed the strange size hex value warnings.
+
+
+
+
+
+
v?.??
+
+ Release: November 14, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
The autoclean warning for the end of a freespace area has been fixed. Again.
+
The freespace finder no longer skips a RATS tag if it's preceeded by an unprotected 00.
+
+
+
+
+
+
v?.??
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
autoclean no longer complains if it attempts to overwrite something that isn't a valid SNES pointer.
+
+
+
+
+
+
v?.??
+
+ Release: November 13, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
if statements have been made much more powerful. The old action if the statement is false was skipping the rest of the line if the statement is false; the new action is skipping the rest of the line, or if the if statement is at the end of the line, it skips everything until an endif. Nested if statements are allowed, as are else statements. (Note that you can't use else on one-line if statements.)
+
New command: prot. If used directly after a freecode or freedata command (that is, at the start of the RATS tag), it may contain a list of labels (up to 80 or something). The freespace blocks pointed to by these labels are removed if the freespace area is cleared by an autoclean. Example: org $008000 : autoclean JSL Main : freecode : prot Mydata : Main: LDA Mydata : RTL : freedata : Mydata: db $12,$34,$56,$78
+
Labels may be defined as Main(), not just Main:. This has been noted in the documentation.
+
Asar can now be built as a DLL file, but it's not tested very throughly.
+
'x' = $1234 is now a valid operation. It's equivalent to table file, but it accepts math and it's one file less to keep track of.
+
db 'x'+4 is now a valid operation.
+
freecode and freedata can now expand the ROM if needed.
+
!a = abc : !{a}def is now valid operation; it's equivalent to abcdef. You can nest defines inside the !{}s; a!{b!{c!def}g}h is accepted (assuming all defines exist).
+
+
+
Bug fixes:
+
+
autoclean now works if called from $008000.
+
autoclean now works if aiming for the last eight bytes of a RATS tag.
+
autoclean now refuses to protect anything that isn't a label, for example math or constants, unless using the two-parameter method.
+
autoclean now refuses to protect a label at the end of a freespace block, since it'll think the RATS tag after that is the one that should be removed.
+
db 1/Label : Label: is now accepted, instead of being treated as a division by zero.
+
($12),x is an error in xkas, since that addressing mode doesn't exist. However, Asar accepts parentheses and treats it as LDA $12,x, which isn't what the user meant. Therefore, it now emits a warning if this happens.
+
+
+
Deprecated features:
+
+
!a equ $1234 is no longer valid.
+
+
+
+
+
+
v?.??
+
+ Release: November 7, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
set fastrom is now documented in stdlib.asm.
+
Minor edits to the documentation.
+
An xkas emulation mode was added, which makes Asar act more like xkas 0.06. It should hopefully be 100% compatible with all previously submitted patches/sprites/etc.
+
Asar can now fix the checksum.
+
The command line options have been edited a bit, including a few bugfixes.
+
+
+
Bug fixes:
+
+
Opcodes that may or may not take an argument (INC, LSR, etc) now work better together with autocolon.
+
"Unknown command" errors have been edited.
+
+
+
Deprecated features:
+
+
set resizable has been removed.
+
+
+
+
+
+
v?.??
+
+ Release: October 25, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
labelopt is no longer off
+
A lone { or } is now treated as a null command (for use with code folding). Note that they're not allowed elsewhere. They don't need to be matched.
+
+
+
Bug fixes:
+
+
autoclean no longer kills inappropriate data if pointed to an unused area. Operator precendence screwed up stuff.
+
+
+
+
+
+
v?.??
+
+ Release: ?
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Asar will no longer place rats tags at any part of the unexpanded area, not even if it's a long list of 00s
+
Fixed a bunch of odd bugs with the automatic size finder and label optimizer, including one that treated LDA.l Label,x as LDA.w Label,x
+
+
+
+
+
+
v?.??
+
+ Release: October 23, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Blank lines are now allowed in macros.
+
+
+
Bug fixes:
+
+
Broken or unknown macro arguments no longer abort assembling the rest of the macro.
+
+
+
Deprecated features:
+
+
Removed the command DIEDIEDIE, a useless command that intentionally froze Asar if it's called from $088000 or later.
+
+
+
+
+
+
v?.??
+
+ Release: October 23, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Fixed relative forward branches in freespace too.
+
+
+
+
+
+
v?.??
+
+ Release: October 23, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
How quickly Asar aborts if it finds errors can be set
+
autocolon now accepts db $20, $30
+
autoclean JSL.l is now valid
+
+
+
Bug fixes:
+
+
Fixed some uninitialized value errors that created garbage error messages if the patch doesn't exist
+
Putting a label in front of an opcode messed up earlier; this has been fixed
+
freecode forgot setting a few variables, which creates a bunch of errors if it's used
+
+
+
+
+
+
v?.??
+
+ Release: October 18, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
Bug fixes:
+
+
Added a missing else statement on the label optimizer disabling flag that made it turn it on, or get values that change in crappy ways, for everything.
+
+
+
+
+
+
v?.??
+
+ Release: October 18, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Asar can now assemble SPC700 code, though very little testing was done on this and a lot of bugs may still be included. Also note that mov a,(x)+ has been moved to mov a,(x+), since that opcode increases X and not the value X points to. Two lines in arch-spc700.cpp can be uncommented to reenable the first syntax.
+
The fastrom command has been moved to set fastrom on.
+
Readded the base command.
+
Other small changes.
+
+
+
Bug fixes:
+
+
The first line of stdlib is no longer ignored (a variable wasn't initialized).
+
Assembling is aborted if errors are detected, instead of continuing. As a side effect from this, errors are no longer printed twice or thrice.
+
+
+
Deprecated features:
+
+
rep Label has been blocked. It was never supposed to be allowed.
+
+
+
+
+
+
v"0.30 or 0.40 or something"
+
+ Release: October 11, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
LDA $9E,y is now treated as LDA $009E,y, but it prints a warning.
+
New command: set. It can set various options, including expected ROM title (the romtitle command has been removed), if the .l->.w optimizer should be active, and if warnings should be shown.
+
Asar can now automatically (try to) add colons where it thinks they should be. Note that this is disabled by default and not recommended for anything serious.
+
As with the colon adder, it should be avoided unless there is a good reason to use it (for example running it from an IRC bot). (Note that a time limit should be enabled when running it from an IRC bot so that noone can freeze the bot with slow patches).
+
+
+
Bug fixes:
+
+
Unknown command errors have been made saner. The old method was some sort of debug code.
+
Carriage returns are now ignored on Linux.
+
Assembling blank patches on nonexistent ROMs or ROMs with length zero has been fixed.
+
+
+
+
+
+
v?.??
+
+ Release: October 9, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
!a += +1 has been implemented.
+
+
+
Bug fixes:
+
+
If you type "freespace", the tool gives a more detailed error message that "Unknown command."
+
A bug related to using pushpc inside a freespace has been fixed.
+
+
+
Notes
+
+
The tool has been renamed to Asar. Pronounciation: The first A is short, and the second is long (as in "Bazaar", except without the B). It doesn't matter if the S is pronounced as S or Z.
+
+
+
+
+
+
v?.??
+
+ Release: October 8, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
It now looks for and assembles stdlib.asm. However, it prints an error if it doesn't find it.
+
Expected ROM title can now be set, see stdlib.asm for details. It defaults to SUPER MARIOWORLD if omitted, and it may not be set outside of stdlib.asm.
+
A 64-bit version has been included.
+
Both autoclean and autoclear works now. They act identically.
+
+
+
+
+
+
v?.?? (Initial Release)
+
+ Release: October 6, 2011
+
+
Contributors:
+
+
Alcaro
+
+
+
New features:
+
+
Parentheses can be used, which allows some previously impossible statements.
+
Defines can be made longer without risk for crashes. This makes it much easier to implement Hijack Everywhere.
+
An if statement has been included, to get rid of the need for including those rep -1 tricks.
+
Freespace can be set automatically (it even includes a simple way to reclaim freespace used by older versions of the patch)
+
+
+
Notes
+
+
In this original release, the tool was named "a.as"
+
+
+
+
+
+
diff --git a/asar_19/index.html b/asar_19/index.html
new file mode 100644
index 00000000..a8125be3
--- /dev/null
+++ b/asar_19/index.html
@@ -0,0 +1,18 @@
+
+
+
+ Asar
+
+
+
+
+
+
diff --git a/asar_19/manual/errors-list.html b/asar_19/manual/errors-list.html
new file mode 100644
index 00000000..50f7fc66
--- /dev/null
+++ b/asar_19/manual/errors-list.html
@@ -0,0 +1,234 @@
+
+
+
+
+
+ Asar User Manual - Error list
+
+
+
+
+
+
+
+
+
+
+
Error name
+
Error message
+
+
Elimit_reached
Over %d errors detected. Aborting.
+
Ewerror
One or more warnings was detected with werror on.
+
E16mb_rom_limit
Can't create ROMs larger than 16MB.
+
Ebuffer_too_small
The given buffer is too small to contain the resulting ROM.
+
Eparams_null
params passed to asar_patch_ex() is null.
+
Eparams_invalid_size
Size of params passed to asar_patch_ex() is invalid.
+
Ecmdl_define_invalid
Invalid define name in %s: '%s'.
+
Ecmdl_define_override
%s '%s' overrides a previous define. Did you specify the same define twice?
+
Ecreate_rom_failed
Couldn't create ROM.
+
Eopen_rom_failed
Couldn't open ROM.
+
Eopen_rom_not_smw_extension
Doesn't look like an SMW ROM. (Maybe its extension is wrong?)
+
Eopen_rom_not_smw_header
Doesn't look like an SMW ROM. (Maybe it's headered?)
+
Estddefines_no_identifier
stddefines.txt contains a line with a value, but no identifier.
+
Estddefine_after_closing_quote
Broken std defines. (Something after closing quote)
+
Efailed_to_open_file
Failed to open file '%s'.
+
Efile_not_found
File '%s' wasn't found.
+
Ereadfile_1_to_4_bytes
Can only read chunks of 1 to 4 bytes.
+
Ecanreadfile_0_bytes
Number of bytes to check must be > 0.
+
Efile_offset_out_of_bounds
File offset %s out of bounds for file '%s'.
+
Erep_at_file_end
rep at the end of a file
+
Emismatched_parentheses
Mismatched parentheses.
+
Einvalid_hex_value
Invalid hex value.
+
Einvalid_binary_value
Invalid binary value.
+
Einvalid_character
Invalid character.
+
Estring_literal_not_terminated
String literal not terminated.
+
Emalformed_function_call
Malformed function call.
+
Einvalid_number
Invalid number.
+
Egarbage_near_quoted_string
Garbage near quoted string.
+
Emismatched_quotes
Mismatched quotes.
+
Erom_too_short
ROM is too short to have a title. (Expected '%s')
+
Erom_title_incorrect
ROM title is incorrect. Expected '%s', got '%s'.
+
Ebank_border_crossed
A bank border was crossed, SNES address $%06X.
+
Estart_of_file
This command may only be used at the start of a file.
+
Exkas_asar_conflict
Using @xkas and @asar in the same patch is not supported.
+
Einvalid_version_number
Invalid version number.
+
Easar_too_old
This version of Asar is too old for this patch.
+
Erelative_branch_out_of_bounds
Relative branch out of bounds. (Distance is %s).
+
Esnes_address_doesnt_map_to_rom
SNES address %s doesn't map to ROM.
+
Esnes_address_out_of_bounds
SNES address %s out of bounds.
+
Einvalid_tcall
Invalid tcall.
+
Euse_xplus
Use (x+) instead.
+
Eopcode_length_too_long
Opcode length is too long.
+
Esuperfx_invalid_short_address
Invalid short address parameter: $%s. (Must be even number and $0000-$01FE)
+
Esuperfx_invalid_register
Invalid register for opcode; valid range is %d-%d.
+
Einvalid_opcode_length
Invalid opcode length specification.
+
Einvalid_mapper
Invalid mapper.
+
Enan
NaN encountered.
+
Edivision_by_zero
Division by zero.
+
Emodulo_by_zero
Modulo by zero.
+
Eunknown_operator
Unknown operator.
+
Einvalid_input
Invalid input.
+
Einvalid_function_name
Invalid function name.
+
Efunction_not_found
Function '%s' wasn't found.
+
Efunction_redefined
Function '%s' redefined.
+
Ebroken_function_declaration
Broken function declaration.
+
Ewrong_num_parameters
Wrong number of parameters to function.
+
Einvalid_param_name
Invalid parameter name.
+
Emath_invalid_type
Wrong type for parameter %s, expected %s.
+
Einvalid_label_name
Invalid label name.
+
Elabel_not_found
Label '%s' wasn't found.
+
Elabel_redefined
Label '%s' redefined.
+
Ebroken_label_definition
Broken label definition.
+
Elabel_cross_assignment
Setting labels to other non-static labels is not valid.
+
Emacro_label_outside_of_macro
Macro label outside of a macro.
+
Elabel_on_third_pass
Internal error: A label was created on the third pass. Please create an issue on the official GitHub repository and attach a patch which reproduces the error.
+
Elabel_moving
Internal error: A label is moving around. Please create an issue on the official GitHub repository and attach a patch which reproduces the error.
+
Einvalid_namespace_name
Invalid namespace name.
+
Einvalid_namespace_use
Invalid use of namespace command.
+
Einvalid_struct_name
Invalid struct name.
+
Estruct_not_found
Struct '%s' wasn't found.
+
Estruct_redefined
Struct '%s' redefined.
+
Estruct_invalid_parent_name
Invalid parent name.
+
Einvalid_label_missing_closer
Invalid label name, missing array closer.
+
Emultiple_subscript_operators
Multiple subscript operators is invalid.
+
Einvalid_subscript
Invalid array subscript after first scope resolution.
+
Elabel_missing_parent
This label has no parent.
+
Earray_invalid_inside_structs
Array syntax invalid inside structs.
+
Estruct_without_endstruct
struct without matching endstruct.
+
Enested_struct
Can not nest structs.
+
Emissing_struct_params
Missing struct parameters.
+
Etoo_many_struct_params
Too many struct parameters.
+
Emissing_extends
Missing extends keyword.
+
Einvalid_endstruct_count
Invalid endstruct parameter count.
+
Eexpected_align
Expected align parameter.
+
Eendstruct_without_struct
endstruct can only be used in combination with struct.
+
Ealignment_too_small
Alignment must be >= 1.
+
Einvalid_define_name
Invalid define name.
+
Edefine_not_found
Define '%s' wasn't found.
+
Ebroken_define_declaration
Broken define declaration.
+
Eoverriding_builtin_define
Trying to set define '%s', which is the name of a built-in define and thus can't be modified.
+
Edefine_label_math
!Define #= Label is not allowed with non-static labels.
+
Emismatched_braces
Mismatched braces.
+
Einvalid_macro_name
Invalid macro name.
+
Emacro_not_found
Macro '%s' wasn't found.
+
Emacro_redefined
Macro '%s' redefined.
+
Ebroken_macro_declaration
Broken macro declaration.
+
Einvalid_macro_param_name
Invalid macro parameter name.
+
Emacro_param_not_found
Macro parameter '%s' wasn't found.
+
Emacro_param_redefined
Macro parameter '%s' redefined
+
Ebroken_macro_usage
Broken macro usage.
+
Emacro_wrong_num_params
Wrong number of parameters to macro.
+
Ebroken_macro_contents
Broken macro contents.
+
Erep_at_macro_end
rep or if at the end of a macro.
+
Enested_macro_definition
Nested macro definition.
+
Emisplaced_endmacro
Misplaced endmacro.
+
Eunclosed_macro
Unclosed macro.
+
Elabel_in_conditional
Non-static label in %s command.
+
Ebroken_conditional
Broken %s command.
+
Einvalid_condition
Invalid condition.
+
Emisplaced_elseif
Misplaced elseif.
+
Eelseif_in_while
Can't use elseif in a while loop.
+
Eelseif_in_singleline
Can't use elseif on single-line statements.
+
Emisplaced_endif
Misplaced endif.
+
Emisplaced_else
Misplaced else.
+
Eelse_in_while_loop
Can't use else in a while loop.
+
Eunclosed_if
Unclosed if statement.
+
Eunknown_command
Unknown command.
+
Ecommand_disabled
This command is disabled.
+
Ebroken_incbin
Broken incbin command.
+
Eincbin_64kb_limit
Can't include more than 64 kilobytes at once.
+
Erecursion_limit
Recursion limit reached.
+
Ecommand_in_non_root_file
This command may only be used in the root file.
+
Ecant_be_main_file
This file may not be used as the main file.%s
+
Eno_labels_here
Can't use non-static labels here.
+
Einvalid_freespace_request
Invalid freespace request.
+
Eno_banks_with_ram_mirrors
No banks contain the RAM mirrors in hirom or exhirom.
+
Eno_freespace_norom
Can't find freespace in norom.
+
Estatic_freespace_autoclean
A static freespace must be targeted by at least one autoclean.
+
Estatic_freespace_growing
A static freespace may not grow.
+
Eno_freespace_in_mapped_banks
No freespace found in the mapped banks. (Requested size: %s)
+
Eno_freespace
No freespace found. (Requested size: %s)
+
Efreespace_limit_reached
A patch may not contain more than %d freespaces.
+
Eprot_not_at_freespace_start
PROT must be used at the start of a freespace block.
+
Eprot_too_many_entries
Too many entries to PROT.
+
Eautoclean_in_freespace
autoclean used in freespace.
+
Eautoclean_label_at_freespace_end
Don't autoclean a label at the end of a freespace block, you'll remove some stuff you're not supposed to remove.
+
Ebroken_autoclean
Broken autoclean command.
+
Epulltable_without_table
Using pulltable when there is no table on the stack yet.
+
Einvalid_table_file
Invalid table file. Invalid entry on line: %i
+
Epad_in_freespace
pad does not make sense in a freespaced code.
+
Eorg_label_invalid
org Label is not valid.
+
Eorg_label_forward
org Label is only valid for labels earlier in the patch.
+
Eskip_label_invalid
skip Label is not valid.
+
Espc700_inline_no_base
base is not implemented for architecture spc700-inline.
+
Ebase_label_invalid
base Label is not valid.
+
Erep_label
rep Label is not valid.
+
Epushpc_without_pullpc
pushpc without matching pullpc.
+
Epullpc_without_pushpc
pullpc without matching pushpc.
+
Epullpc_different_arch
pullpc in another architecture than the pushpc.
+
Epullbase_without_pushbase
pullbase without matching pushbase.
+
Einvalid_math
Invalid math command.
+
Einvalid_warn
Invalid warn command.
+
Einvalid_check
Invalid check command.
+
Ewarnpc_in_freespace
warnpc used in freespace.
+
Ewarnpc_broken_param
Broken warnpc parameter.
+
Ewarnpc_failed
warnpc failed: Current position (%s) is after end position (%s).
+
Ewarnpc_failed_equal
warnpc failed: Current position (%s) is equal to end position (%s).
+
Eassertion_failed
Assertion failed%s
+
Eerror_command
error command%s
+
Einvalid_print_function_syntax
Invalid printable string syntax.
+
Eunknown_variable
Unknown variable.
+
Einvalid_warning_id
Invalid warning ID passed to %s. Expected format is WXXXX where %d <= XXXX <= %d.
+
Epushwarnings_without_pullwarnings
warnings push without matching warnings pull.
+
Epullwarnings_without_pushwarnings
warnings pull without matching warnings push.
+
Efailed_to_open_file_access_denied
Failed to open file '%s'. Access denied.
+
Efailed_to_open_not_regular_file
Failed to open file '%s'. Not a regular file (did you try to use a directory?)
+
Ebad_dp_base
The dp base should be page aligned (i.e. a multiple of 256)
+
Ebad_dp_optimize
Bad dp optimize value %s, expected: [none, ram, always]
+
Ebad_address_optimize
Bad dp optimize value %s, expected: [default, ram, mirrors]
+
Ebad_optimize
Bad optimize value %s, expected: [dp, address]
+
Erequire_parameter
Missing required function parameter
+
Eexpected_parameter
Not enough parameters in calling of function %s
+
Eunexpected_parameter
Too many parameters in calling of function %s
+
Eduplicate_param_name
Duplicated parameter name: %s in creation of function %s
+
Einvalid_alignment
Invalid alignment. Expected a power of 2.
+
Ealignment_too_big
Requested alignment too large.
+
Enegative_shift
Bitshift amount is negative.
+
Emacro_not_varadic
Invalid use of sizeof(...), active macro is not variadic.
+
Evararg_sizeof_nomacro
Invalid use of sizeof(...), no active macro.
+
Emacro_wrong_min_params
Variadic macro call with too few parameters
+
Evararg_out_of_bounds
Variadic macro parameter requested is out of bounds.
+
Evararg_must_be_last
Variadic macro parameter must be the last parameter.
+
Einvalid_global_label
Global label definition contains an invalid label [%s].
+
Espc700_addr_out_of_range
Address %s out of range for instruction, valid range is 0000-1FFF
+
Elabel_ambiguous
Label (%s) location is ambiguous due to straddling optimization border.
+
Efeature_unavaliable_in_spcblock
This feature may not be used while an spcblock is active
+
Eendspcblock_without_spcblock
Use of endspcblock without matching spcblock
+
Emissing_endspcblock
Use of endspcblock without matching spcblock
+
Espcblock_bad_arch
spcblock only valid inside spc700 arch
+
Espcblock_inside_struct
Can not start an spcblock while a struct is still open
+
Espcblock_too_few_args
Too few args passed to spcblock
+
Espcblock_too_many_args
Too many args passed to spcblock
+
Eunknown_spcblock_type
Unknown spcblock format
+
Ecustom_spcblock_missing_macro
Custom spcblock types must refer to a valid macro
+
Espcblock_macro_doesnt_exist
Macro specified to custom spcblock was not found
+
Eextra_spcblock_arg_for_type
Only custom spcblock type takes a fourth argument
+
Espcblock_macro_must_be_varadic
Custom spcblock macros must be variadic
+
Espcblock_macro_invalid_static_args
Custom spcblock macros must have three static arguments
+
Espcblock_custom_types_incomplete
Custom spcblock types are not yet supported. One day.
+
Estartpos_without_spcblock
The startpos command is only valid in spcblocks
+
Einvalid_endspcblock_arg
Invalid argument to endspcblock: "%s"
+
Eunknown_endspcblock_format
Unsupported endspcblock format. Currently supported formats are "endspcblock" and "endspcblock execute [label]"
+
Einternal_error
An internal asar error occured (%s). Send help.
+
Epushns_without_pullns
pushns without matching pullns.
+
Epullns_without_pushns
pullns without matching pushns.
+
Elabel_forward
The use of forward labels is not allowed in this context.
+
Eunclosed_vararg
Variadic macro parameter wasn't closed properly.
+
Einvalid_vararg
Trying to use variadic macro parameter syntax to resolve a non variadic argument.
+
Emacro_param_outside_macro
Reference to macro parameter outside of macro
+
Ebroken_for_loop
Broken for loop declaration.
+
Ebad_single_line_for
Single-line for loop not allowed here.
+
+
+
+
diff --git a/asar_19/manual/index.html b/asar_19/manual/index.html
new file mode 100644
index 00000000..df9b1a19
--- /dev/null
+++ b/asar_19/manual/index.html
@@ -0,0 +1,3407 @@
+
+
+
+ Asar User Manual
+
+
+
+
+
+
+
+
+
Asar
+
+
A multi-architecture SNES assembler by Alcaro, modelled after 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.
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.
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.
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 --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.
+ nocash: Generate a symbols file in the no$sns format.
Specifies the path and file name to use for generating the symbols output file. By default, the path is the path of [rom_file] and the file name is the base name of [rom_file] with an extension of .sym. Ignored when --symbols is set to none.
+ Note that relative paths here are relative from the current working directory, not relative from {asm_file} or [rom_file].
Overrides Asar's default behavior of enabling or disabling checksum generation based on context. When set to on, Asar always generates a checksum. When set to off, Asar never generates a checksum.
+
Path to the ROM file that is modified by Asar. If this file doesn't exist yet, Asar creates a new ROM file instead. When omitted, Asar checks if asm_file_name.sfc or asm_file_name.smc exists and uses the one it finds. When zero or two ROMs with that filename are found, Asar defaults to the .sfc extension. As a convention, Asar always treats .smc files as headered and .sfc files as unheadered ROMs. This means that headered .sfc files or unheadered .smc files cannot be used with Asar unless their extension is changed. This is by design and meant to encourage compliance with the convention.
+
+ For convenience, double-clicking the Asar executable will prompt you to enter paths to an ASM file and a ROM file and thus allow you to directly use Asar without passing any command line arguments to it.
+
Standard Includes
+ Aside from passing include search paths to Asar via the command line, it's possible to also do so via a file called stdincludes.txt. When a file with this name exists next to the Asar executable, Asar automatically opens it and adds every line in it as an include search path (trailing and leading whitespace on a line is ignored, as are lines containing only whitespace). Absolute and relative paths are supported. Relative paths are considered relative to the TXT file. The purpose of this file is to make it easier to distribute standard code libraries for use with Asar by making it possible to just unpack the contents of a ZIP file or similar directly into the Asar directory. Note that include search paths passed in via the command line get priority over paths parsed from this TXT file. See section Includes for details on include search paths.
+ All of the examples below are valid:
+
+ Aside from passing additional defines to Asar via the command line, it's possible to also do so via a file called stddefines.txt. When a file with this name exists next to the Asar executable, Asar automatically opens it and adds every line in it as an additional define. The syntax is similar to Asar's regular define syntax, with a few notable differences. There are no spaces required around the =, the ! of the identifier is optional, whitespace around the identifier is ignored, so is whitespace around the value (unless the value is delimited by double quotes, in which case any whitespace inside is kept in the define), the value itself is optional (when left out, it is set to an emptry string). Lines containing only whitespace are ignored. The purpose of this file is to make it easier to distribute standard code libraries for use with Asar by making it possible to just unpack the contents of a ZIP file or similar directly into the Asar directory. See section Defines for details on defines.
+ All of the examples below are valid:
+
+ 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).
+
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+). See the spcblock section for an alternative way of assembling SPC700 code.
+
+ 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).
+
+ 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'
+sta $00
+
+db 'x','x'+1,'x'+2
+
Opcode Length Specification
+ By appending .b, .w or .l to an opcode, you can specify that opcode's length. This is recommended in cases where the length could be ambiguous.
+
lda #0 ; Could be either lda #$00 or lda #$0000
+lda.b #0 ; Always lda #$00
+lda.w #0 ; Always lda #$0000
+ When no length is specified, Asar tries to guess the length based on the operand. Note that Asar does not use the standard <> for length specifications to avoid ambiguity with other uses of these symbols (such as in macros or math statements). Opcode length specifications are currently supported for the 65c816 and SPC700 architectures.
+
Pseudo Opcodes
+ Pseudo opcodes are a convenience method of repeatedly using opcodes that don't take an operand. Instead of using the opcode multiple times, the following syntax can be used:
+
{opcode} #{num}
+ This assembles opcodenum times in succession. This means that
+
nop #3
+
+inx #2
+ is the same as
+
nop
+nop
+nop
+
+inx
+inx
+
rep
+
rep {num} : {code}
+
+
Warning: this command is deprecated due to conflicting with the 65816 assembly REP instruction. In most cases, you can achieve the same effect with a for loop.
+
+ The rep command lets you compile any bit of code num times. It functions similarly to pseudo opcodes, but without being limited to certain opcodes only. Instead, you can repeat almost any bit of code supported by Asar, even macro calls. Note that in xkas compatibility mode, rep 0 will compile the following code once, whereas rep -1 (or any number < 0) won't compile the following code at all. This is to keep compatibility with old patches, which occasionally used the rep command as a replacement for conditionals. Also note that stacking multiple rep commands is not supported (only the most recent rep will take effect).
+
+ SPC blocks are a convenient way of defining command data meant to be sent to the SPC700 in games using well-known SPC engines (though at this time, only the N-SPC engine is supported). The general format looks like this:
+
+ Inside an spcblock, arch spc700 is automatically active (see section Architectures for details).
+ The target_address parameter specifies the target address (in ARAM) for the command data. The optional execute parameter tells Asar to generate a "start execution" command immediately after this SPC block, with execution_address as the ARAM address to start execution at. The engine_type parameter specifies which SPC engine to use. When omitted, the default value of nspc is used. The following engine types are supported:
+
+
+
Parameter
+
Engine Type
+
Description
+
Output Format
+
Example Code
+
Example Output
+
+
+
nspc
+
N-SPC
+
Implements the format used by the N-SPC engine found in most Nintendo games, as well as by the SPC700's initial program loader.
+ 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 Wmapper_already_set.
+
+
+
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 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 compatibility mode will be fully removed in Asar 2.0, along with the ;@ comments.
+
;@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
+
+if readfile1("data.bin", 0) == 1
+ ; 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 order 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, unless asar 1.9 or a higher version is specified at the start of the file, which will change the default to math pri on. This command will be removed in Asar 2.0, after which math pri on will be the only possible behavior.
+
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. If you specify a minimum supported Asar version using asar 1.9 or higher, the default will be math round off. This command will be removed in Asar 2.0, after which math round off will be the only possible behavior.
+
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.
+ 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
+ Previously, there were exceptions to this rule in the form of lines starting with ;@, which are assembled normally. This functionality is deprecated, Asar 2.0 will treat these lines as regular comments. The purpose of this feature was 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 would 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. (This too is deprecated.) 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.
+
Also note that comments starting with ;[[ are reserved for multi-line comments in a future version of Asar. You should either change the beginning or make sure that there's a ]] (the comment terminator) at the end of the line.
+
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.
+
+ 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.
+
+ 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
+ The skip command moves the pc by num_bytes bytes. By specifying a negative value, the pc can be moved backwards. When alignment is given, skips to the next multiple of alignment, plus offset if it is specified. Note that the alignment must be a power of 2, if specified. Offset can also be negative, in that case it's treated exactly like alignment+offset. The seeked-to position will always be after the current SNES position, but it might be before the next multiple of alignment: see the last example.
+
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}
+ DEPRECATED: you can achieve the exact same thing with assert pc() <= {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 DataTable,x
+
+DataTable:
+ db $01,$02,$03,$04
+ Asar will always assemble the lda DataTable,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.
+
+ 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.
+
+
+ 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
+
optimize address {default/ram/mirrors}
+ This command changes how aggressive Asar's label optimizer is. With optimize address default, references to labels will be shortened to 2 bytes only if the label is in the current data bank. With optimize address ram, additionally labels between $7E:0000-$7E:1FFF will be shortened to 2 bytes if the current data bank has RAM mirrors ($00-$3F and $80-$BF). With optimize address mirrors, additionally labels between $00-3F:2000-7FFF (that is, $00:2000-$00:7FFF all the way up to $3F:2000-$3F:7FFF) will be shortened to 2 bytes whenever the current data bank has RAM mirrors. Note that in freespace, the current bank will be assumed from whether the freespace was started as freecode or freedata, not where the freespace was actually placed in the end.
+
+
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.
+
+ 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 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.
+
+ 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.
+
+ 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
+
+ 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
+
+ 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:
+
+ 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
+
+ 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:
+
+ 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 namespace, 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
+
pushns/pullns
+ pushns saves the current namespace. pullns restores the last-pushed value of the namespace.
+
+
Global labels
+ While in a namespace, you can use the keyword global to define labels outside all namespaces. The syntax is global [#]{identifier}:. For example:
+
+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
+
+ Note that # acts the same way as it does for regular labels.
+ Note that you cannot use the global command with sublabels or macro labels. Outside of a namespace, global acts just like a regular label definition.
+ 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.
+
+ 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"
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).
+ 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
+ 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.
+ 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).
+
+
+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 parameters of a variadic macro, use the syntax <...[{math}]>, where math is any math expression evaluating to the index of a variadic parameter. These 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
+
+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 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 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.
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.
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.
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"
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
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.
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.
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.
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.
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
+
+
+
pc()
+
Returns the current SNES address. This is a shorthand for placing a label right before the current command.
+
assert pc() <= $008123
+
+
+
realbase()
+
Returns the current address in the ROM being written to. This is not the same as the value of a nearby label when the base command is active: it returns the actual address the code will end up at.
+
+
+ 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 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.
+
+ Alternatively, if conditionals can also be constructed on a single line via the following syntax:
+
if {condition} : {codeblock}[ : codeblock...] : endif
+ Note that else or elseif are unsupported when using this syntax. The endif used to be optional, but this functionality is deprecated. It's recommended to always add the endif at the end of the line.
+
+ If you plan to use labels in if commands, note that there's certain restrictions that apply. More specifically, only static labels can be used. That is, only labels whose address can't change between Asar's passes, as demonstrated by the following example:
+
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
+ 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
+endwhile
+ Note that while loops can also end with endif, but this is deprecated. 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.
+
+
for
+ For loops repeat the contents a specified number of times. In the for loop body, you have access to a loop counter as a define. The range is specified as start-inclusive and end-exclusive.
+
+ For example:
+
for i = 1..5
+ db !i
+ db 2*!i
+endfor
+
This will write the bytes 01 02 02 04 03 06 04 08.
+
You can also put for loops on a single line, however in this case due to the order in which Asar parses defines, you will not be able to use the loop counter. E.g. for i = 0..10 : nop : endfor.
+ 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}[,rtl/ltr]
+
Note: this command is deprecated and will be removed in Asar 2.0, see below (direct character assignment syntax) for the replacement.
+ 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. This will be the only way to set the table in Asar 2.0.
+ 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.
+
+ 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}
+fill align {alignment} [offset {offset}]
+ 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. If alignment is specified, the value will be written repeatedly until the SNES address has the specified alignment, similar to skip align.
+
+ 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/pad
+
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.
+
+ It's also possible to write 16-bit, 24-bit or 32-bit values with the pad command by using padword, padlong or paddword instead of padbyte. Note that the snes_address parameter of pad still specifies the end offset of the write in those cases. Values might get truncated as needed to exactly reach the specified end offset.
+
incbin
+
incbin {filename}[:range_start..range_end]
+ The incbin command copies a binary file directly into the output ROM. The filename parameter specifies which file to copy (enclose in double quotes to use file names with spaces, see section Includes for details on Asar's handling of file names) and the optional range_start and range_end parameters are math expressions which specify a range of data to copy from the file (a range_end of 0 copies data until the end of the file; not specifying a range copies the entire file). The older form of this command used - as the separator of start and end, which caused ambiguities and was thus deprecated.
+
+ Another now-deprecated form is incbin {filename}[range] -> {location}, where location is either a label or a SNES address. If it is specified, the contents of the file are written to another location in the ROM. When set to a label identifier, this code behaves identically to
+
+ with the exception that incbin gains special permission to cross bank borders. In this case, the size limit of the included file is 65536 bytes due to how freespace works. For files with a size of 32767 or lower, no alignment is enforced. When label_name_or_sness_address is set to an SNES address, the code behaves identically to
+
+ Includes make it possible for your code to reference other files. This can be done for a number of reasons. The most common scenarios are to split code into multiple source files (see incsrc) or to separate code from data (see incbin). Whenever using a command or function referencing another file, Asar tries to locate that file by applying a set of rules to the file path in a specific order:
+
+
+ If the path is an absolute path:
+
+
Asar tries to locate the file directly via the specified path.
+
If this fails, an error is thrown.
+
+
+
+ If the path is a relative path:
+
+
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).
+
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).
+
If all of the previous fail, an error is thrown.
+
+
+
+
incsrc
+
incsrc {filename}
+ The incsrc command makes Asar assemble the file referenced by the filename parameter (enclose in double quotes to use file names with spaces, see section Includes for details on Asar's handling of file names). The file is assembled in-place which means that Asar instantly switches to the new file and only returns to the previous file once assembling the new file has finished. All of Asar's state (labels, defines, functions, pc etc.) is shared between files. When including other files, there is a recursion limit of 512 levels. This limit only serves the purpose of preventing infinite recursion. For an easier understanding of incsrc, you can visualize it as a command which pastes the contents of another file directly into the current file (although that's not actually how it's implemented and there are differences in the way relative file paths are handled).
+
; Contents of routine.asm:
+;AnotherRoutine:
+; lda #$FF
+; sta $00
+; rts
+
+Main:
+ jsr AnotherRoutine
+ bra Main
+
+incsrc "routine.asm"
+
+
include/includefrom
+
include
+
includefrom {filename}
+ The include and includefrom commands specify that a file is only to be included in another file and not to be assembled directly. When a user tries to assemble a file containing include or includefrom directly, an error is thrown. The includefrom command behaves identically to the include command with the exception that it is passed the name of the file it is meant to be included from (note that Asar doesn't verify whether it's actually included from that file, it only checks whether it's included from another file at all). When making use of include or includefrom, they must be the first command within their respective file and can't be used in combination with the asar or xkas command in the same file.
+
+ The includeonce command places an include guard on the file that is currently being assembled. This prevents it from being assembled again in the same pass. This is intended for shared files which may be included from multiple source files, but should only be assembled once to prevent redefinition errors etc.
+
; 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 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.
+
+ 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. Note that specifying the byte like this is deprecated. You should use the separate freespacebyte command instead.
+
+
+ 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
+
freespacebyte
+
freespacebyte {value}
+ This command sets the byte which Asar considers to be free space. This value will be used for searching for freespace, as padding when resizing the ROM, or when cleaning up old freespaces.
+
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.
+
+ Text output functions allow you to communicate certain information, states, warnings, errors etc. to end users of your code.
+
print
+ The print command lets you output general-purpose text to the user. Most commonly this is used to inform the user about certain states or to output debug information. Usage:
+
print {text_or_function}[,text_or_function...]
+ where text_or_function can be either a string delimited by double quotes or one of the print-specific functions below:
+
+
+
Function
+
Details
+
+
+
bin(x[, width])
+
Prints x as a binary (base-2) integer, where x can be any math statement. If width is provided, the output is padded to at least this many digits using zeroes.
+
+
+
dec(x[, width])
+
Prints x as a decimal (base-10) integer, where x can be any math statement. If width is provided, the output is padded to at least this many digits using zeroes.
+
+
+
hex(x[, width])
+
Prints x as a hexadecimal (base-16) integer, where x can be any math statement. If width is provided, the output is padded to at least this many digits using zeroes.
+
+
+
double(x[, precision])
+
Prints x as a decimal number with precision decimal places (default: 5), where x can be any math statement. Affected by the math round setting.
+
+
+
pc
+
Prints the current PC.
+
+
+
freespaceuse
+
Prints the total number of bytes used by commands that acquire freespace (such as freespace, freecode, freedata etc.).
+ You can use the command
+
reset freespaceuse
+ to reset this value.
+
+
+
bytes
+
Prints the total number of bytes written to the output ROM.
+ You can use the command
+
reset bytes
+ to reset this value.
+
+
+
warn
+ The warn command lets you output a warning message to the user. Usage:
+
warn [text_or_function...]
+ where custom_warning_text can be a custom warning text and uses the same format as the print command. A warning does not cause compilation to fail, so it can be used to inform the user about potential dangers. Warning messages are printed to stderr by default, but are printed to stdout if the Asar executable is renamed to xkas.exe. This is intended for compatibility purposes.
+
if read1($00FFD5) == $23
+ warn "SA-1 compatibility of this patch is untested, use with caution!"
+endif
+
error
+ The error command lets you output an error message to the user. Usage:
+
error [text_or_function...]
+ where custom_error_text can be a custom error text and uses the same format as the print command. An error causes compilation to fail, so it should be used to inform the user about irrecoverable error states. Error messages are printed to stderr by default, but are printed to stdout if the Asar executable is renamed to xkas.exe. This is intended for compatibility purposes.
+
if read1($00FFD5) == $23
+ error "This patch is not SA-1 compatible!"
+endif
+
assert
+ An assert can be considered a short version of the code
+
if {condition}
+else
+ error [text_or_function...]
+endif
+ and is used via the syntax
+
assert {condition}[,text_or_function...]
+ where custom_error_text can be a custom error text and uses the same format as the print command. If condition evaluates to <= 0, an error is thrown, otherwise nothing happens.
+
assert read1($00FFD5) != $23,"This patch is not SA-1 compatible!"
+ Checks allow Asar to monitor certain states and throw warnings or errors when certain criteria are met. This can be helpful for catching or preventing certain problems.
+
check title
+
check title "{title}"
+ The check title command verifies that the title stored in the output ROM is identical to title. If it isn't, an error is thrown (unless --no-title-check is passed to the application, in which case only a warning is thrown - see section Usage for details). The purpose of this command is to assure that patches are applied to the correct output ROM.
+
; 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}
+ The check bankcross command enables (full or half) or disables (off) throwing errors when a bank border is crossed while assembling a file. The default is full, which checks whether the code crosses from pc $FFFF to $0000 in the next bank, and throws an error if that happens. With half, Asar will additionally check crossings from $7FFF to $8000. Use off 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 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 names. The easiest way of finding the name of a specific warning is to look at the console output of a patch producing it. Asar will always output the warning name along with the respective warning. Warnings also have ID numbers, but those are deprecated and will be removed in Asar 2.0. It is recommended to use the warning names instead (which are more descriptive anyways).
+
Disabled Warnings
+ This is a list of all warnings that are disabled by default and have to be enabled explicitly.
+
+
+
Warning Name
+
Details
+
+
+
Wimplicitly_sized_immediate
+
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.
+
+
+
Wcheck_memory_file
+
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.
+
+ The warnings enable command enables the warning with the specified name, 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 Wwarn_command
+
+warn "This text in invisible!"
+
+warn enable Wwarn_command
+
+warn "This text in visible!"
+
List of all warnings
+
Here is a list of all warnings Asar can emit (useful to know what to disable).
+
+
List of all errors
+
Here is a list of all errors Asar can emit. This is really only useful when using the DLL API, where you can use the names to check which exact error was thrown. Note that error names might change between Asar versions.
+
+
diff --git a/asar_19/manual/warnings-list.html b/asar_19/manual/warnings-list.html
new file mode 100644
index 00000000..2c8ef6e2
--- /dev/null
+++ b/asar_19/manual/warnings-list.html
@@ -0,0 +1,56 @@
+
+
+
+
+
+ Asar User Manual - Warning list
+
+
+
+
+
+
+
+
+
+
+
Warning name
+
Warning message
+
Enabled by default
+
+
Wrelative_path_used
Relative %s path passed to asar_patch_ex() - please use absolute paths only to prevent undefined behavior!
True
+
Wrom_too_short
ROM is too short to have a title. (Expected '%s')
True
+
Wrom_title_incorrect
ROM title is incorrect. Expected '%s', got '%s'.
True
+
W65816_yy_x_does_not_exist
($yy),x does not exist, assuming $yy,x.
True
+
W65816_xx_y_assume_16_bit
%s $xx,y is not valid with 8-bit parameters, assuming 16-bit.
True
+
Wspc700_assuming_8_bit
This opcode does not exist with 16-bit parameters, assuming 8-bit.
True
+
Wcross_platform_path
This patch may not assemble cleanly on all platforms. Please use / instead.
True
+
Wmissing_org
Missing org or freespace command.
True
+
Wset_middle_byte
It would be wise to set the 008000 bit of this address.
True
+
Wunrecognized_special_command
Unrecognized special command - your version of Asar might be outdated.
True
+
Wfreespace_leaked
This freespace appears to be leaked.
True
+
Wwarn_command
warn command%s
True
+
Wimplicitly_sized_immediate
Implicitly sized immediate.
False
+
Wxkas_deprecated
xkas support is being deprecated and will be removed in a future version of Asar. Please use an older version of Asar (<=1.50) if you need it.
True
+
Wxkas_eat_parentheses
xkas compatibility warning: Unlike xkas, Asar does not eat parentheses after defines.
True
+
Wxkas_label_access
xkas compatibility warning: Label access is always 24bit in emulation mode, but may be 16bit in native mode.
True
+
Wxkas_warnpc_relaxed
xkas conversion warning : warnpc is relaxed one byte in Asar.
True
+
Wxkas_style_conditional
xkas-style conditional compilation detected. Please use the if command instead.
True
+
Wxkas_patch
If you want to assemble an xkas patch, add ;@xkas at the top or you may run into a couple of problems.
True
+
Wxkas_incsrc_relative
xkas compatibility warning: incsrc and incbin look for files relative to the patch in Asar, but xkas looks relative to the assembler.
True
+
Wconvert_to_asar
Convert the patch to native Asar format instead of making an Asar-only xkas patch.
True
+
Wfixed_deprecated
the 'fixed' parameter on freespace/freecode/freedata is deprecated - please use 'static' instead.
True
+
Wautoclear_deprecated
'autoclear' is deprecated - please use 'autoclean' instead.
True
+
Wcheck_memory_file
Accessing file '%s' which is not in memory while W%d is enabled.
False
+
Wif_not_condition_deprecated
'if !condition' is deprecated - please use 'if not(condition)' instead.
True
+
Wfunction_redefined
Function '%s' redefined.
True
+
Wdatasize_last_label
Datasize used on last detected label '%s'.
True
+
Wdatasize_exceeds_size
Datasize exceeds 0xFFFF for label '%s'.
True
+
Wmapper_already_set
A mapper has already been selected.
True
+
Wfeature_deprecated
DEPRECATION NOTIFICATION: Feature "%s" is deprecated and will be REMOVED in the future. Please update your code to conform to newer styles. Suggested work around: %s.
True
+
Wbyte_order_mark_utf8
UTF-8 byte order mark detected and skipped.
True
+
Woptimization_settings
In Asar 2.0, the default optimization settings will change to `optimize dp always` and `optimize address mirrors`, which changes this instruction's argument from %d to %d bytes. Either specify the desired settings manually or use explicit length suffixes to silence this warning.