Scripting Basics

The following set of tutorials assumes you've setup a mod folder with Star Rod already. If you haven't, follow this tutorial to completion. Your mod folder should look something like this:

You may also have an out folder if you've compiled your mod before.

Understanding Patch Files

Patch files (.mpat, .bpat) are Star Rod-specific plaintext files. When you compile your mod Star Rod reads these patch files and applies them to your Paper Mario ROM. Do not edit source files (.mscr, .bscr) or your mod will not be able to be distributed properly.

Patch files define how to modify existing data on the ROM. That is the basic premise of romhacking with Star Rod - modify, not create.

Their syntax is as follows:

% comment
/% multiline comment %/

% hexidecimal integers (or address pointers to memory)
FFFFFFFF
8010F29A

% integers
5
18

% floats
2.0
3.14

% strings (syntatic sugar for "#new:ASCII")
"hello"
"mac_02"

% pointers
$Pointer
$Script_Something % "Script" is just convention
$Function_Lol

% adds a new script
#new:Script $Script_Something
  Set *Variable 00000021 % sets value of variable to 21
  Call SomeFunction ( argument argument )
  Bind $Pointer .Trigger:Something 0 1 0 % event binding
  % empty lines are an error, comments are okay though!
  % more on scripts later
  Return
  End

% adds a new dialogue string
#string $String_Something
<dialogue>

% adds a new text string (normally unused in patch files)
#new:ASCII $ASCII_Something
<text>

% adds a new assembly function
#new:Function $Function_Something
<asm>

% REPLACES the data at $Pointer with the following data
% data can be a script, a function, a string; anything
@ $Pointer
<data>

Map IDs and File Structure

Every map/room in the game has a unique map ID in the form of abc_xy. For example, the map ID for Mario's House is kmr_20, so its related files are all called kmr_02.*.

map
├── patch
│   └── kmr_02.mpat
└── src
    ├── kmr_02.map
    ├── kmr_02.midx
    └── kmr_02.mscr

Explanations:

• map/patch/kmr_02.mpat is the map script patch file for Mario's House. These don't exist by default, we need to create this file.
• map/src/kmr_02.map is the source map file for the Mario's House map Star Rod uses.
• map/src/kmr_02.mscr is like the .mpat file, but is the source. Do not edit this file!
• map/src/kmr_02.midx can be safely ignored. It is an internal file used by Star Rod for Star Rod things we don't care about.

Baby's First Patch File

We're going to make a small edit to the game that modifies what happens when the player starts a new game. We can observe that when you start a new game:

1. The game loads Mario's House
2. You enter via entry number 0 (we know this)

3. The Prologue begins

   The map ID for Mario's House is kmr_20, so we will call our mpat file map/patch/kmr_02.mpat. Make this file and open it up in your text editor (e.g. Sublime).

Paste the following contents into this file:

@ $Script_8024FD70
  Call GotoMap ( "mac_00" 00000000 )
  Return
  End

This defines a replacement (@) of $Script_8024FD70, which is originally defined in map/src/kmr_02.mscr:

#new:Script $Script_8024FD70
  Call     DisablePlayerInput   ( .True )
  Thread
    Wait     00000005
    Call     SetMusicTrack  ( 00000000 .Song:MailCall 00000000 00000008 )
  EndThread
  Call     InterpPlayerYaw  ( 0000005A 00000000 )
  ...
  End

$Script_8024FD70 is executed when the game loads entry number 0 in the map, which only ever occurs when a new game first begins.

We are simply replacing this with a single GotoMap function call, which is built-in to the game. GotoMap takes two arguments: map id and entry number, which in this case are equal to "mac_00" and 0000000. In English, that means that when the game executes the script, we will load mac_00 (Toad Town) entry number zero.

You can test this by compiling your mod.