The VG Language™ - Electry/VitaGrafix GitHub Wiki

To facilitate user-made game patches without having to recompile the whole plugin, a domain specific language was created. Similar, but somewhat simplified to that of VitaCheat.

Written in patchlist.txt, patches are parsed and applied during game boot-up.

A patch for each game starts with a header. Header identifies SKU/region (TITLE ID), the executable name (because several “collections” use the same TITLE ID for multiple games in their series) and the game version (indirectly, in a form of module NID).

[PCSA00001, eboot.bin, 0x12345678]

Executable name/path is used to differentiate between games that share a single TITLE ID (e.g. collections).

NID is used to inform user about potentional version mismatch (e.g. when game gets a new update), instead of applying patches to wrong/old memory addresses and then crashing.

If multiple regions/SKUs share the same offsets, having to duplicate patches would be wasteful. You can freely stack multiple headers after each other, like shown below. Patches will then be applied for all matching games/regions.

[PCSA00001, eboot.bin, 0x12345678]
[PCSB00023, eboot.bin, 0x87654321]
...

Header is followed by patch feature/type marking. This indicates that subsequent patches shall only be applied if user has enabled said feature in their configuration file.

Use one of the following:

@FB
@IB
@FPS
@MSAA

The rules for patches are simple. Each patched memory location is on a separate line, starts with a relative address (segment:offset) followed by the new value.

0:0x1234 0xDEADBEEF

results in 4 bytes at seg000 start + 0x1234 address being patched to EF BE AD DE.

VitaGrafix internally always works with one of the following datatypes:

• Primitive types:
  • int (32-bit signed integer)
  • uint (32-bit unsigned integer)
  • float (32-bit floating point number)
• Raw type:
  • bytes (size up to 32 B)

You can cast between those types freely using casting functions (see Explicit type conversion).

• int – when + or - sign precedes 1 or more decimal digits (with no space inbetween)
  • - +1, -1
  • - + 1
• uint – when:
  • hex number is prefixed with 0x or 0X
  • octal number is prefixed with 0
  • decimal integer does not have prefix or suffix
  • - 0xCAFE, 0876, 123
  • - CAFE
• float – when 1 or more decimal digits (optionally with preceding + or - sign) are followed by:
  • . and optionally:
    • 1 or more digits after the decimal point and optionally f
    • f
  • f
  • - 1., 1.2, 1.2f, 1f, 1.f, -1.0, -2f, +123.4f
  • - .1, .1f, 1 . 0 f
• bytes – when 1 or more (up to 32) 8-bit hex values (without the 0x prefix) are followed by r
  • - DEADr, DE AD r
  • - DEAD, 0xDEADr, 0xDE 0xAD r

The interpreter makes use of implicit conversion when necessary. This is done when applying infix operator or math function (arity >= 2) to following operand types (in no particular order):

While working with values, changing the datatype manually might sometimes be desirable.

To convert value of any type to one of the primitive types use following functions:

To convert value of any type to raw type use:

If you don't wish to cast the value, but rather just reinterpret bytes, use:

Operator precedence is honored, order is similar to C-like languages. Brackets (parentheses) are allowed and evaluated first.

These return values based on user configuration entry (in config.txt) for current game.

These encode few of the commonly used instructions. Result type is always raw, size depends on encoder. All are unconditional.

Register arguments are expected to be decimal integers.
ARM within 0 <= reg <= 14 range, where 0 denotes R0 or A1, 13 = SP and 14 = LR.
VFP within 0 <= reg <= 31 range, where 0 denotes S0.

Comments always start with # character. They can, but don't need to be on a separate line.

# This is a comment
[PCSA00001, eboot.bin, 0x12345678] # This is also a valid comment
...

All older patches are compatible with v5.x, however, support for the old syntax/style might be dropped in future versions. It is highly advised to use the new syntax for new patches.

v4.x: nop() and bkpt() encoders must have brackets
v5.x: nop and bkpt encoders are classified as constants, constants do not have brackets
example:

• nop() => nop

v4.x: no support for math operators/fns/precedence, macros start with < and end with >
v5.x: infix operators and math functions are available
example:

• <+,1,2> => 1 + 2
• <*,<&,<+,<fb_w>,31>,0xFFFFFFE0>,4> => align(fb_w, 32) * 4

v4.x: config-option macros start with < and end with >
v5.x: config-option macros are used just like regular constants and functions
example:

• <fb_w> => fb_w
• <ib_w> => ib_w
• <ib_w,2> => ib_wi(2)

v4.x: no extra spaces are allowed, comments have to be on a separate line
v5.x: spaces are ignored, anything after # too (until EOL)
example:

• t2_mov(1,1,<fb_w>) => t2_mov(1, 1, fb_w)
• # Comment
0:0x1234 nop is valid just like 0:0x1234 nop # Comment

v4.x: bytes() is used to parse raw bytes
v5.x: r suffix is used to parse raw bytes, raw() is used for reinterpreting/conversion
example:

• bytes(DE AD BE EF) => DEADBEEF r

and more...

Here are some examples of valid patches.

[PCSF00243,eboot.bin]            # Killzone Mercenary [EU 1.12]
[PCSF00403,eboot.bin]            # Killzone Mercenary [EU 1.12]
[PCSA00107,eboot.bin,0x0F9D3B7C] # Killzone Mercenary [US 1.12]
[PCSC00045,eboot.bin]            # Killzone Mercenary [JP 1.12]
[PCSD00071,eboot.bin]            # Killzone Mercenary [ASIA 1.12]
@IB
0:0x15A5C8 nop *4
1:0xD728 uint32(ib_w) . uint32(ib_h)
1:0xD730 uint32(ib_w) . uint32(ib_h)

# God of War Collection [EU 1.00]
[PCSF00438,GOW1.self,0x8638ffed]
@FB
0:0x9E212 t2_mov(1, 4, fb_w)
0:0x9E21A t2_mov(1, 2, fb_h)
0:0x9F0F0 t2_mov(1, 0, fb_w)
0:0x9F0F8 t2_mov(1, 1, fb_h)
0:0xA31C6 t2_mov(1, 7, fb_w)
0:0xA31CC t2_mov(1, 1, fb_h)
0:0xCEF06 t2_mov(1, 0, fb_w)
0:0xCEF0E t2_mov(1, 2, fb_h)
0:0xA1098 t2_mov(1, 14, fb_h)
@FPS
0:0x9E228 t1_mov(0, vblank)

# LEGO Star Wars: The Force Awakens [EU 1.00]
[PCSB00877,eboot.bin]
@IB
0:0x2241C4 t2_mov(1, 1, 0xA00000)
0:0x1F313E t2_mov(1, 4, ib_w)
0:0x1F3144 t2_mov(1, 5, ib_h)
1:0x4650 uint32(ib_w) . uint32(ib_h)
# Fix touchscreen/touchpad pos calc
0:0x223AF6 t2_mov(0, 0, 640) . nop *3
0:0x223B36 t2_mov(0, 0, 368) . nop *3

The parser will try to warn you if you make a mistake. Nevertheless, it isn't perfect so you shouldn't rely on it.