ACE code generator - Documentation

Go back to the code generator: Emerald / FRLG / RS

Main code

A code is composed of two sections:

• The header section: this section defines some parameters that configure the behavior of the code generator. It is also possible to define some constants that will be used later in the ARM commands.
• The ARM commands: this section contains the ARM commands composing the payload of the code.

The header section comes first, followed by a line containing just @@, followed by the ARM commands.

Headers

In the header section, you can define some parameters to configure the code generator. A parameter must be defined this way: @@ parameter_name = value

value must be one of the following:

• The constant null
• A boolean: true or false
• A non-negative integer (in decimal by default, use the prefix 0x/0b/0o for hexadecimal/binary/octal)
• A string, between quotes, with C-like escape characters

Constants and meta-expressions

The header section can also be used to define some constants. A constant must be defined this way: constant_name = meta_expr (no @@ at the beginning).

meta_expr must be an expression that evaluates to an int32:

• It can be a constant int32 (in decimal by default, use the prefix 0x/0b/0o for hexadecimal/binary/octal)
• It can be a constant name previously defined
• It can use the following operators (same semantics as in C for unsigned int32): + - * / % ~ & ^ | << >> == != && || !
• It can be a C-like conditional expression: meta_expr ? meta_expr : meta_expr (the else branch is taken iff the tested expression evaluates to zero)

Please note that if you want to write a definition on several lines, you must end the intermediate lines with a \. You can also ask the generator to print the computed value of a constant by adding an interrogation mark after its name: constant_name ? = meta_expr

Constants (and more generally meta-expressions) can be used in the ARM section. Instead of writing a hard-coded number, you can insert a meta-expression that will be evaluated before assembling the code (just like a preprocessor expression). Meta-expressions used in the ARM section must be put between braces: { meta_expr }.

ARM commands and ARM tweaker

USA/European versions

ARM commands can be written with the syntax defined in the ARM documentation. Comments can be inserted at the end of a line using one of the following: @ %% ; //

Not all of the ARMv4 commands are supported (most of them cannot be written with the european charset anyway). The available commands are:

• LDR (B/SB/H/SH/W/T/BT) and STR (B/H/W/T/BT)
• MOV and MVN
• ADC, SBC, BIC and AND (the latter is writable only if the first operand is r0)
• B and BL

Also note that the register scaling commands (LSL, LSR, ASR, ROR, RRX) are not supported.

If you want to insert a command that is not supported (or if you want to force a specific encoding for a command), you can directly write the int32 corresponding to the command you want (do not write anything else on the same line, except a comment). Do not forget the 0x prefix if you write it in hexadecimal.

Due to the ARM restrictions and the charset restrictions, not all immediate values can be used in commands such as MOV or ADC. In order to help you to write codes and to allow automation, you can ask the code generator to automatically tweak an ADC, SBC, MOV or MVN command (not available for the other commands) into multiple commands that are writable (when it is possible). It will search a solution in up to 5 commands. In order to use this feature, just add a ? (interrogation mark) at the end of the command that should be tweaked. You can also specify a number just after (for instance ?4) if you want to force the result to use a fixed number of commands. Note that the register r12 should be preferred (more constants are writable when using it), followed by register r11. Also note that the ARM tweaker assumes that the carry flag in CPSR is unset.

Japanese version

The information above still applies to the Japanese version. However, as more characters are available in the Japanese version, some additional commands are available:

• ADD, SUB, ORR and EOR
• BX and BLX (only with a register as operand)

When selecting the Japanese language, the tweaker also takes advantage of the extended charset. In particular, it does not assume anymore that the carry flag in CPSR is unset (ADD and SUB commands are used instead of ADC and SBC).

Exit codes

Exit codes are pieces of code that can be included at the end of an ACE code in order to branch back to the game's code without crashing.

The Exit codes textarea contains a library of multiple exit codes. Each exit code is separated from the next by the following separator: ==========

Each exit code contains a header section followed by some ARM code, just like the Main code textarea. The parameters available for exit codes are defined below. The definition and use of constants is possible (the constants defined in the main code can also be accessed in the exit code). Calls to the ARM tweaker are also possible in an exit code, but this practice is discouraged.

Headers