Skip to content

Overworld Scripting ‐ Getting Started

Jump to bottom
haven1433 edited this page Nov 15, 2023 · 4 revisions

Click to return to the main scripting page

What are Event Scripts?

In Pokemon games, there are many characters and objects you can interact with in the overworld.

  • Pick up items from the ground.
  • Talk to NPCs.
  • Make something happen when you stand in a specific spot.

Event Scripts, or Overworld Scripts, are bits of custom instructions that tell the game how to respond to the player in these situations. By editing scripts and writing new ones, you can make shops, rivals, legendary pokemon battles, and more. If maps are about what the game shows you, then event scripts are about what the game does.

Let's look at an example:

image

section0: # 1BEB8C
  find.item POTION 1
  end

This short script from Viridian City in FireRed 1.0 will give the player 1 Potion, then make the item disappear so you can't pick it up again. Even in this small example, you can see that a script can have a few different pieces.

  • A line that has a name followed by a colon is a label. This script has the section0 label at the top.
  • A comment starts with #. Comments can be whatever you want, don't do anything, and aren't saved. HMA will automatically add comments to labels telling you what address they're at in the game.
  • Scripts are made of commands. Most commands have arguments to control what they do. So find.item POTION 1 will give the player 1 Potion.
  • Scripts use commands for everything they do, including ending. Scripts will usually have the end command as the last command, but sometimes other commands are used to end a script instead.

Viewing Existing Scripts in the Game

The easiest way to see an existing script is using the map editor. Try this:

  • Open HMA and load an unedited copy of FireRed.
  • Type "Viridian City" into the Goto menu and click the first option in the maps category.

image

  • Click on the NPC towards the southeast (bottom right) corner of the map:

image

  • Notice details about the NPC in the left panel. You can click the arrow next to the script address to go to the script.

image

You can also double-click an NPC to go to its script.

A Longer Script Example

One of the best ways to learn the available scripting commands is by looking through scripts already in the game. Let's take a moment to examine this NPC's script:

image

This NPC is a bit more complicated, so let's examine some of the commands.

Command Info
lock Makes the NPC not move around or look around until release is called.
faceplayer Makes the NPC face the player.
msgbox.yesno Shows some text (from a pointer) and asks the user to pick yes or no.
if.yes.goto Jumps to another section of the script (or an address) if the user chose 'yes'.
if.no.goto Jumps to another section of the script (or an address) if the user chose 'no'.
msgbox.default Shows some text (from a pointer) and waits for the user to press a button.
release Allows an NPC to move around again after a lock.
end Ends the script and gives control back to the player.

Even just with these commands, the script is able to make the NPC say 2 different things based on a player choice.

Pointers in Scripts

Each script command is expected to be a fixed length. For example, lock is only a single byte, while if.yes.goto is always 11 bytes. If a script has an argument that's always the same number of bytes (like find.item), the argument can just be part of the command. But if the script needs an argument that can be variable length (like text, or items in a shop, or a string of NPC movements), then the script will instead use a "Pointer" to the actual argument.

For example, msgbox.default needs to show some text, so it takes a single argument, a 4-byte address that tells the script where the text is. For your convenience, HMA displays this text in {} curly-braces directly under the command that uses it. If you change the text, HMA will edit the text at that address. If you make the text longer so that it no longer fits at the original address, HMA will repoint it to a new address so you can keep working without interruption.

When writing your own commands, you don't need to worry about picking addresses for your text data. You can just use <auto> like this:

msgbox.default <auto>
{
This is some text!
It will be inserted after your script.
}

HMA will automatically insert the text data directly after your script. You can use <auto> for text data, movement data, pokemart data, and more. But you cannot use it for script sections, only data.

Sections in Scripts

Some special commands let you jump around between different sections of a script, or even jump to entirely different scripts. if.yes.goto's parameter is also a pointer, because it's a 4-byte address. If a command is labeled as goto, then it'll jump to another section, often when some condition is met. call does the same thing as goto, except that it also saves its place within the current script so you can return to it. This is useful if you have a bit of code that you want to jump to from different sections, because you can return back to whichever section called it.

Note that goto and call commands must jump to a section or an address. You cannot use <auto> for goto or call commands.

Explore!

There's a lot more to say about scripts, but at this point you may want to just open up a few scripts and see how they look and how they work. Then maybe try making a simple one yourself. Later tutorials will dive deeper into scripting capabilities.

Clone this wiki locally