Scripting

GodMode9 has featured a scripting engine since version 1.2.7.

Scripts are formatted as plaintext ASCII with a .gm9 file extension, and allow the automation of complex tasks.

Running a Script

All scripts placed in the /gm9/scripts folder on the SD card will show up on the Scripts menu (HOME button -> Scripts...) and can be conviniently executed from there.

To run a script that's not present in this folder, it can be manually executed by navigating to it and choosing "Execute GM9 Script" from its context menu.

Basics

GodMode9 scripts resemble shell scripts. Comments are denoted by # and work anywhere. Variable are in the format $[VAR] where VAR is the name of the variable. (i.e. $[HAX]). Surround an argument with " if it must contain whitespaces. Any redundant whitespaces outside of " will be treated as a single whitespace. An unknown command will lead to a script abort.

Wildcards

A wildcard is a character that will be seen as any character or sequence of characters in a search. GodMode9 has support for two types of Wildcards, * and ?. * will check for anything of any length, while ? will check for only one character (multiple ? can be used in a row to make a set amount of characters).

-o and -s Switches

You can use -o and/or -s switches on any command, or --optional / --silent respectively. -o Continues on failures of a command, and -s will try to suppress all error messages. Example: ask -o -s "Perform this operation (I will completely ignore your response)?"

Commands

A short description of every command. Click on the command to go to a more detailed page about it. <> Denotes a required parameter. [] denotes an optional parameter. A | in a parameter means that you must choose one of the options on either side of it.

echo command - Outputs data to the screen. Syntax: echo "<text to be outputted>" Example: echo "Hello There!"

qr command - Does the same as echo but also displays a QR on the top screen. Syntax: qr <message> <qr data> Example: qr "Scan for cool stuff! ;)" "https://github.com/d0k3/GodMode9"

chk command - Checks two values against each other. Syntax: chk <value1> <value2> Example: chk $[HAX] a9lh

ask command - Similar to echo, but allows user to abort script. Syntax: ask <message> Example: ask "Continue running this script? Note: using -o command allows you to ignore user response.

set command - allows you to create variables and edit ERRORMSG and SUCCESSMSG Syntax: set <varname> <data> Example: set TESTPATH 0:/3ds/

input command - allows you to prompt the user to enter a string and store it in a variable. Syntax: input <prompt> <varname> Example: input "Choose name for test dir?" DIRNAME Note: the variable can be created beforehand with set to preset the initial value.

filesel command - allows the user to choose a file from in a specific directory / drive. The path is stored in a variable and can be limited via wildcards. -d can be used to allow the user to browse dirs looking for a file. Syntax: filesel <prompt> <path> <var> Example: filesel "Please select NAND backup" 0:/gm9/out/*_$[SERIAL]_???nand_???.bin NANDBAK

dirsel command - same as filesel, but with selecting a directory. Note that a final slash is not expected on the path, and there can be no wildcard patterns. Syntax: dirsel <prompt> <path> <var> Example: dirsel "Select game folder." A:/titles/40000000 GAMEDIR

allow command - unlocks write permission to the specified location. -a will unlock write permissions for all files and directories in that location. Note: without this command, write permissions are still in place, the user will simply be prompted to unlock every time a write is attempted. Syntax: allow <path> Example: allow S:/firm0.bin

mkdir command - creates a dir at the specified location. Syntax: mkdir <path> Example: mkdir 0:/gm9/in

fdummy command - creates a dummy file at the specified location of a specified size. Existing files will not be overwritten. Syntax: fdummy <path> <size in hex> Example: fdummy 0:/testfile.bin FF (FF is 256 in regular numbers)

cp command - copies a file or directory to another place. -h creates a .sha file with the same name containing the file's SHA-256 (only on SD card). -w forces overwrite of existing files (rather than a prompt allowing the user to choose). -k is the same as -w but forces a skip. -n prevents canceling the operation (useful for critical operations). Syntax: cp <path to file> <path to file copy> Example: cp -h -n S:/nand_minsize.bin 0:/gm9/out/NAND_backup.bin

rm command - removes files and directories recursively. Syntax: rm <path-to-remove> Example: rm 9:/*

mv command - used to move and/or rename files. Same switches as cp, except for -h. Syntax: mv <path to file> <path to new location Example: mv 0:/gm9/out/NAND_backup.bin 0:/gm9/out/$[DATESTAMP]_$[SERIAL]_sysnand_000.bin

imgmount command - used to mount an image. An image can be (among other things) FAT, NAND, NCCH, FIRM, BOSS, NCSD, CIA, ticket.db... Syntax: imgmount <path> Example: imgmount 1:/dbs/ticket.db

imgumount command - unmounts the currently mounted image. No parameters.

sha command - checks a file's SHA-256 against the second argument, which can either be a file containing the SHA-256 (.sha files created by GM9), or the SHA-256 string in hex. Syntax: sha <path> <path/sha string> Example: sha S:/sector0x96.bin 82F2730D2C2DA3F30165F987FDCCAC5CBAB24B4E5F65C981CD7BE6F438E6D9D3

shaget command - besides sounding like some a very hairy dog, this command will calculate and store a file's SHA-256 in the second argument, be it a variable or filename. Syntax: shaget <file to calc> <file name / var name> Example: shaget 0:/boot.firm BOOTSHA

[more to come ofc]

Environment Variables

Environment Variables are variables that are always available, no matter what. They are determined when GodMode9 boots, and cannot be changed via scripting commands. Remember, when including a variable in a command, use $[VAR] where VAR is the name of the variable (i.e. $[HAX]).

• GM9VER - the version of the currently running GodMode9 firm. (i.e. v5.0.0)
• REGION - the region of the console's SysNAND. (can be USA, EUR, JPN, KOR, CHN, TWN, or UNK for unknown)
• SERIAL - the serial of the console's SysNAND, not including Check Digit. (i.e. CW13701547)
• GM9OUT - the standard output path (i.e. 0:/gm9/out)
• CURRDIR - the directory the script is running from (i.e. 0:/gm9/scripts)
• HAX - the exploit the system is running from (can be ntrboot, sighax, a9lh, or (empty, would be ""))
• ONTYPE (stands for Old/NewTYPE) - the console type. (O3DS or N3DS)
• RDTYPE (stands for Retail/DevTYPE) - the unit type. (retail or devkit)
• SYSID0 - ID0 of SysNAND.
• EMUID0 - ID0 of EmuNAND (if available).
• TIMESTAMP - the current time in hhmmss format (based on RTC).
• DATESTAMP - the current date in YYMMDD format (based on RTC).