Project CARL or ChatHacks Assembly ROM Loader is a tool for injecting ASM snippets into whatever game I'm playing.


CARL uses the standard SNES assembler ASAR. The manual for it can be found here. ASAR can do a lot of fun things with directives, but please don't. Changing the org--loading address--will just make things crash. Changing from lo-rom to hi-rom or whatever, will probably just make my SNES crash when you load it. And a primer on 65C816 Opcodes can be found here. A bunch of common !defines are also available here. You can use these instead of $ADDR in your ASM.

Calling Conventions

Your code will be called once per frame right after V-Blank and will be loaded at whatever address CARL sees fit, so it's important to use the correct calling conventions. At the time of calling, A, X and Y will all be 8 bits wide. You are welcome to change the flags to get 16 bit registers. For initializing your code, you've got the !carl_initialized define that represents the address of a byte that is guaranteed to be 0 when you’re first called. Also, your code will be called with a JSL instruction, so make sure when you return to use RTL.

Loading and Unloading

You can load a new module into the current game by using the chat command !load MODULE_NAME, and unload it by !unload MODULE_NAME. If you've saved a new version of your ASM, you can !reload MODULE_NAME it. This just !unloads and !loads your code, but it's a nice shortcut. MODULE_NAMEs aren't case sensitive.
Modules can also unload themselves by setting A=0xDE, X=0xCO, Y=0xDE and RTLing.