Skip to content

Commit

Permalink
Merge branch 'asar_19' into asar_2_beta
Browse files Browse the repository at this point in the history
  • Loading branch information
randomdude999 committed Jan 21, 2024
2 parents 13c5e58 + 8db52f4 commit 123ad3a
Show file tree
Hide file tree
Showing 7 changed files with 457 additions and 69 deletions.
2 changes: 1 addition & 1 deletion README.md
Original file line number Diff line number Diff line change
@@ -1,7 +1,7 @@
# Asar
[![Windows builds (AppVeyor)](https://ci.appveyor.com/api/projects/status/github/RPGHacker/asar?svg=true)](https://ci.appveyor.com/project/RPGHacker/asar) ![Ubuntu build (GitHub Actions)](https://github.com/RPGHacker/asar/actions/workflows/cmake.yml/badge.svg)

Asar is an SNES assembler designed for applying patches to existing ROM images, or creating new ROM images from scratch. It supports 65c816, SPC700, and Super FX architextures. It was originally created by Alcaro, modelled after [xkas v0.06](https://www.romhacking.net/utilities/269/) by byuu.
Asar is an SNES assembler designed for applying patches to existing ROM images, or creating new ROM images from scratch. It supports 65c816, SPC700, and Super FX architectures. It was originally created by Alcaro, modelled after [xkas v0.06](https://www.romhacking.net/utilities/269/) by byuu.

For a guide on using Asar (including how to write patches), see [`README.txt`](https://github.com/RPGHacker/asar/blob/master/README.txt). This readme was made with tool programmers and contributors in mind.

Expand Down
29 changes: 1 addition & 28 deletions docs/changelog/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -6,34 +6,7 @@
<link rel="stylesheet" href="../shared/highlight_js_asar/styles/default.css"/>
<script src="../shared/highlight_js/highlight.min.js"></script>
<script src="../shared/highlight_js_asar/highlight_js_asar.js"></script>
<script>
hljs.configure(
{
tabReplace: ' ',
}
);
hljs.highlightAll();

hljsAsar.init();

function toggle_visibility(id)
{
var e =document.getElementById(id);
var label = document.getElementById(id.concat("-toggle"));

if(e.style.display == 'none')
{
label.innerHTML = label.innerHTML.replace("[+] Expand","[-] Collapse");
e.style.display = 'block';
}
else
{
label.innerHTML = label.innerHTML.replace("[-] Collapse","[+] Expand");
e.style.display = 'none';

}
}
</script>
<script src="../shared/common.js"></script>
</head>
<body>

Expand Down
232 changes: 232 additions & 0 deletions docs/manual/errors-list.html

Large diffs are not rendered by default.

74 changes: 34 additions & 40 deletions docs/manual/index.html
Original file line number Diff line number Diff line change
Expand Up @@ -6,34 +6,7 @@
<link rel="stylesheet" href="../shared/highlight_js_asar/styles/default.css"/>
<script src="../shared/highlight_js/highlight.min.js"></script>
<script src="../shared/highlight_js_asar/highlight_js_asar.js"></script>
<script>
hljs.configure(
{
tabReplace: ' ',
}
);
hljs.highlightAll();

hljsAsar.init();

function toggle_visibility(id)
{
var e =document.getElementById(id);
var label = document.getElementById(id.concat("-toggle"));

if(e.style.display == 'none')
{
label.innerHTML = label.innerHTML.replace("[+] Expand","[-] Collapse");
e.style.display = 'block';
}
else
{
label.innerHTML = label.innerHTML.replace("[-] Collapse","[+] Expand");
e.style.display = 'none';

}
}
</script>
<script src="../shared/common.js"></script>
</head>
<body>

Expand Down Expand Up @@ -183,8 +156,12 @@ <h1>Asar</h1>
<li><a href="#disabled-warnings">Disabled Warnings</a></li>
<li><a href="#warnings-push-pull">warnings {push/pull}</a></li>
<li><a href="#warnings-enable-disable">warnings {enable/disable}</a></li>
<li><a href="#warnings-list">List of all warnings</a></li>
</ul>
</li>
<li>
<a href="#errors-list">List of all errors</a>
</li>
</ul>
</div>
<hr />
Expand Down Expand Up @@ -283,7 +260,7 @@ <h1>Asar</h1>
<td><code class="powershell">-w{name}</code></td>
<td>Modifier</td>
<td>Enables the warning with the specified name. See section <a href="#warnings">Warnings</a> for details.</td>
<td><pre><code class="powershell">asar.exe -wWmplicitly_sized_immediate C:/homebrew/my_game/main.asm</code></pre></td>
<td><pre><code class="powershell">asar.exe -wWimplicitly_sized_immediate C:/homebrew/my_game/main.asm</code></pre></td>
</tr>
<tr>
<td><code class="powershell">-wno{name}</code></td>
Expand Down Expand Up @@ -1636,7 +1613,7 @@ <h4 id="asar">asar</h4>
<pre><code class="65c816_asar">asar {ver}</code></pre>
The <code class="65c816_asar">asar</code> command can be used to specify the minimum Asar version your patch is compatible with. The <code>ver</code> 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.
<pre><code class="65c816_asar">; This patch uses features from Asar 1.40, so it makes sense to require it as a minimum.
@asar 1.40
asar 1.40

if readfile1(&quot;data.bin&quot;, 0) == 1
; Do something
Expand Down Expand Up @@ -2810,6 +2787,13 @@ <h4 id="if-else">if/elseif/else/endif</h4>
else
error "Unsupported mode! Please choose 0, 1, 2 or 3!"
endif</code></pre>
Alternatively, if statements can also be constructed on a single line via the following syntax:
<pre><code class="65c816_asar">if {condition} : {codeblock}[ : codeblock...] : endif</code></pre>
Note that else or elseif are unsupported when using this syntax.
<pre><code class="65c816_asar">PressedY:
if !fireballs_enabled : %PlaySoundEffect(!fireball_sfx) : jsr ShootFireball : endif
rtl
</code></pre>
If you plan to use labels in if conditions, 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:
<pre><code class="65c816_asar">FirstLabel = $018000

Expand Down Expand Up @@ -2848,8 +2832,8 @@ <h4 id="for">for</h4>
db !i
db 2*!i
endfor</code></pre>
This will write the bytes 01 02 02 04 03 06 04 08.

<p>This will write the bytes 01 02 02 04 03 06 04 08.</p>
<p>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. <code>for i = 0..10 : nop : endfor</code>.</p>
<a href="#contents">Return to top</a></div>
<hr />
<div id="binary-data"><h3>Binary Data</h3>
Expand Down Expand Up @@ -2963,20 +2947,25 @@ <h4 id="pad">padbyte/pad</h4>
pad $008004</code></pre>
It's also possible to write 16-bit, 24-bit or 32-bit values with the pad command by using <code>padword</code>, <code>padlong</code> or <code>paddword</code> instead of padbyte. Note that the <code>snes_address</code> 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.
<h4 id="incbin">incbin</h4>
<pre><code class="65c816_asar">incbin {filename}[:range_start..range_end][ -> label_identifier_or_sness_address]</code></pre>
The incbin command copies a binary file directly into the output ROM. The <code>filename</code> parameter specifies which file to copy (enclose in double quotes to use file names with spaces, see section <a href="#includes">Includes</a> for details on Asar's handling of file names) and the optional <code>range_start</code> and <code>range_end</code> parameters are hexadecimal number literals (without a prefix) 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). If you surround <code>range_start</code> or <code>range_end</code> in parentheses, Asar will interpret it as math, not a hex literal.
<pre><code class="65c816_asar">incbin {filename}[:range_start..range_end]</code></pre>
The incbin command copies a binary file directly into the output ROM. The <code>filename</code> parameter specifies which file to copy (enclose in double quotes to use file names with spaces, see section <a href="#includes">Includes</a> for details on Asar's handling of file names) and the optional <code>range_start</code> and <code>range_end</code> 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 <code>-</code> as the separator of start and end, which caused ambiguities and was thus deprecated.
<pre><code class="65c816_asar">; datafile.bin contains the following bytes:
; $00 $01 $02 $03 $04 $05 $06 $07 $08 $09 $0A $0B $0C $0D $0E $0F

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

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

; This writes $01 $02 $03 $04
incbin "datafile.bin":($F-$E)-(2+3)</code></pre>
When <code>label_name_or_sness_address</code> 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
incbin "datafile.bin":$F-$E..2+3
; Old deprecated syntax:
incbin "datafile.bin":($F-$E)-(2+3)
</code></pre>
Another now-deprecated form is <code>incbin {filename}[range] -&gt; {location}</code>, 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
<pre><code class="65c816_asar">pushpc
freedata align

Expand All @@ -2987,7 +2976,7 @@ <h4 id="incbin">incbin</h4>
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 <a href="#freespace">freespace</a> works. For files with a size of 32767 or lower, no alignment is enforced. When <code>label_name_or_sness_address</code> is set to an SNES address, the code behaves identically to
<pre><code class="65c816_asar">pushpc

org {snes_addres}
org {snes_address}
incbin {filename}

pullpc</code></pre>
Expand Down Expand Up @@ -3034,7 +3023,7 @@ <h4 id="includefrom">include/includefrom</h4>
<pre><code class="65c816_asar">includefrom {filename}</code></pre>
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 <a href="#asar">asar</a> command in the same file.
<pre><code class="65c816_asar">; Contents of shared.asm:
;@includefrom main.asm
;includefrom main.asm
;
;if read1($00FFD5) == $23
; !is_sa1_rom = 1
Expand All @@ -3043,7 +3032,7 @@ <h4 id="includefrom">include/includefrom</h4>
;endif


@asar 1.37
asar 1.37

incsrc &quot;shared.asm&quot;

Expand Down Expand Up @@ -3310,7 +3299,7 @@ <h4 id="disabled-warnings">Disabled Warnings</h4>
This is a list of all warnings that are disabled by default and have to be enabled explicitly.<br/><br/>
<table>
<tr>
<th style="width:150px">Warning ID</th>
<th style="width:150px">Warning name</th>
<th>Details</th>
</tr>
<tr>
Expand Down Expand Up @@ -3344,6 +3333,11 @@ <h4 id="warnings-enable-disable">warnings {enable/disable}</h4>
warn enable Wwarn_command

warn "This text in visible!"</code></pre>
<h4 id="warnings-list">List of all warnings</h4>
<p><a href="warnings-list.html">Here</a> is a list of all warnings Asar can emit (useful to know what to disable).</p>
</div>
<div id="errors-list"><h3>List of all errors</h3>
<p><a href="errors-list.html">Here</a> 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.</p>
<a href="#contents">Return to top</a></div>
</body>
</html>
55 changes: 55 additions & 0 deletions docs/manual/warnings-list.html
Original file line number Diff line number Diff line change
@@ -0,0 +1,55 @@

<!DOCTYPE html>
<!-- generated by generate_manual_tables.py -->
<html lang="en">
<head>
<title>Asar User Manual - Warning list</title>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8">
<link rel="stylesheet" href="../shared/highlight_js_asar/styles/default.css"/>
<script src="../shared/highlight_js/highlight.min.js"></script>
<script src="../shared/highlight_js_asar/highlight_js_asar.js"></script>
<script src="../shared/common.js"></script>
</head>
<body>
<table>

<tr>
<th>Warning name</th>
<th>Warning message</th>
<th>Enabled by default</th>
</tr>
<tr><td>Wrelative_path_used</td><td>Relative %s path passed to asar_patch_ex() - please use absolute paths only to prevent undefined behavior!</td><td>True</td></tr>
<tr><td>Wrom_too_short</td><td>ROM is too short to have a title. (Expected &#x27;%s&#x27;)</td><td>True</td></tr>
<tr><td>Wrom_title_incorrect</td><td>ROM title is incorrect. Expected &#x27;%s&#x27;, got &#x27;%s&#x27;.</td><td>True</td></tr>
<tr><td>W65816_yy_x_does_not_exist</td><td>($yy),x does not exist, assuming $yy,x.</td><td>True</td></tr>
<tr><td>W65816_xx_y_assume_16_bit</td><td>%s $xx,y is not valid with 8-bit parameters, assuming 16-bit.</td><td>True</td></tr>
<tr><td>Wspc700_assuming_8_bit</td><td>This opcode does not exist with 16-bit parameters, assuming 8-bit.</td><td>True</td></tr>
<tr><td>Wcross_platform_path</td><td>This patch may not assemble cleanly on all platforms. Please use / instead.</td><td>True</td></tr>
<tr><td>Wmissing_org</td><td>Missing org or freespace command.</td><td>True</td></tr>
<tr><td>Wset_middle_byte</td><td>It would be wise to set the 008000 bit of this address.</td><td>True</td></tr>
<tr><td>Wunrecognized_special_command</td><td>Unrecognized special command - your version of Asar might be outdated.</td><td>True</td></tr>
<tr><td>Wfreespace_leaked</td><td>This freespace appears to be leaked.</td><td>True</td></tr>
<tr><td>Wwarn_command</td><td>warn command%s</td><td>True</td></tr>
<tr><td>Wimplicitly_sized_immediate</td><td>Implicitly sized immediate.</td><td>False</td></tr>
<tr><td>Wxkas_deprecated</td><td>xkas support is being deprecated and will be removed in a future version of Asar. Please use an older version of Asar (&lt;=1.50) if you need it.</td><td>True</td></tr>
<tr><td>Wxkas_eat_parentheses</td><td>xkas compatibility warning: Unlike xkas, Asar does not eat parentheses after defines.</td><td>True</td></tr>
<tr><td>Wxkas_label_access</td><td>xkas compatibility warning: Label access is always 24bit in emulation mode, but may be 16bit in native mode.</td><td>True</td></tr>
<tr><td>Wxkas_warnpc_relaxed</td><td>xkas conversion warning : warnpc is relaxed one byte in Asar.</td><td>True</td></tr>
<tr><td>Wxkas_style_conditional</td><td>xkas-style conditional compilation detected. Please use the if command instead.</td><td>True</td></tr>
<tr><td>Wxkas_patch</td><td>If you want to assemble an xkas patch, add ;@xkas at the top or you may run into a couple of problems.</td><td>True</td></tr>
<tr><td>Wxkas_incsrc_relative</td><td>xkas compatibility warning: incsrc and incbin look for files relative to the patch in Asar, but xkas looks relative to the assembler.</td><td>True</td></tr>
<tr><td>Wconvert_to_asar</td><td>Convert the patch to native Asar format instead of making an Asar-only xkas patch.</td><td>True</td></tr>
<tr><td>Wfixed_deprecated</td><td>the &#x27;fixed&#x27; parameter on freespace/freecode/freedata is deprecated - please use &#x27;static&#x27; instead.</td><td>True</td></tr>
<tr><td>Wautoclear_deprecated</td><td>&#x27;autoclear&#x27; is deprecated - please use &#x27;autoclean&#x27; instead.</td><td>True</td></tr>
<tr><td>Wcheck_memory_file</td><td>Accessing file &#x27;%s&#x27; which is not in memory while W%d is enabled.</td><td>False</td></tr>
<tr><td>Wif_not_condition_deprecated</td><td>&#x27;if !condition&#x27; is deprecated - please use &#x27;if not(condition)&#x27; instead.</td><td>True</td></tr>
<tr><td>Wfunction_redefined</td><td>Function &#x27;%s&#x27; redefined.</td><td>True</td></tr>
<tr><td>Wdatasize_last_label</td><td>Datasize used on last detected label &#x27;%s&#x27;.</td><td>True</td></tr>
<tr><td>Wdatasize_exceeds_size</td><td>Datasize exceeds 0xFFFF for label &#x27;%s&#x27;.</td><td>True</td></tr>
<tr><td>Wmapper_already_set</td><td>A mapper has already been selected.</td><td>True</td></tr>
<tr><td>Wfeature_deprecated</td><td>DEPRECATION NOTIFICATION: Feature &quot;%s&quot; is deprecated and will be REMOVED in the future. Please update your code to conform to newer styles. Suggested work around: %s.</td><td>True</td></tr>
<tr><td>Wbyte_order_mark_utf8</td><td>UTF-8 byte order mark detected and skipped.</td><td>True</td></tr>

</table>
</body>
</html>
26 changes: 26 additions & 0 deletions docs/shared/common.js
Original file line number Diff line number Diff line change
@@ -0,0 +1,26 @@
hljs.configure(
{
tabReplace: ' ',
}
);
hljs.highlightAll();

hljsAsar.init();

function toggle_visibility(id)
{
var e =document.getElementById(id);
var label = document.getElementById(id.concat("-toggle"));

if(e.style.display == 'none')
{
label.innerHTML = label.innerHTML.replace("[+] Expand","[-] Collapse");
e.style.display = 'block';
}
else
{
label.innerHTML = label.innerHTML.replace("[-] Collapse","[+] Expand");
e.style.display = 'none';

}
}
Loading

0 comments on commit 123ad3a

Please sign in to comment.