Skip to content

Custom Events

PartyPlanner64 edited this page Jun 2, 2019 · 8 revisions

Support for custom events has been incorporated into PartyPlanner64. Unlike other features of the editor, custom events require knowledge of MIPS assembly in order to create. However, once a custom event is made, it can be shared with others, and will be embedded into the board JSON files for distribution.

Custom event support is currently an "advanced" feature, hidden behind a switch in the Settings page.

Example events are hosted in the events repository.

Creating custom events

The top toolbar displays an Events button. This will take you to the Event List view, where you can see the current events that you have created or imported.

  • Events that are part of the currently viewed board are in the top section.
  • Events in your "library" are towards the bottom. The event library is simply a storage place for events that are not associated with any particular board.

From the top toolbar in the Event List:

  • The Create Event button will take you to the Event Editor. Use this if you want to make your own custom events.
  • The Import Event button will prompt you to open an assembly .s file. Use this if you download an event and want to add it to your board.

In the listing of events:

  • The trash can icon will delete an event from PartyPlanner64.
  • The download icon will export the event as an assembly .s file. Use this if you want to share your event with others.
  • The copy icons will allow you to copy an event between the current board and your event library.
  • Clicking on the event text will bring you to the Event Editor to edit the chosen event.

Event Editor

When you open the Event Editor, you are presented with a programming text area and a few other controls. This text area is enhanced to give you MIPS syntax highlighting and supports autocomplete.

An "event" is a MIPS function that will execute when the player passes or lands on a space. So for your convenience, the text area is pre-populated with an example call stack setup. (The game will JAL your event code starting at the top.)

When you attempt to save your event, it will be test assembled to verify that it is valid. The editor will also test assemble custom events prior to allowing users to overwrite boards with them.

Event file format

For PartyPlanner64 to understand an event file, it must have a comment header with the following fields. The controls beside the programming text area help configure these fields automatically if you fill them in.

; NAME: My Event
; GAMES: MP1_USA,MP2_USA,MP3_USA
; EXECUTION: Direct
Field Description
NAME A descriptive name for your event. This will appear when users go to select an event for a space.
GAMES A comma-delimited list of game titles that the event is compatible with.
EXECUTION Controls how the event is executed by the engine. For simpler events, Direct is usually the right option. Using Process will only be useful for very advanced programmers, as it requires advanced game engine knowledge.

There are optional fields:

Field Description
PARAM Specifies a parameter that users can set. There can be more than one PARAM field in the header. A parameter has the format type|name. See the section on Event Parameters below for more details.

Assembler features

The assembler used is a simple JavaScript assembler, which is loosely based on armips.

Directives

Directives are useful to write extra binary data to the ROM, or to add additional symbols. See the directives assembler documentation.

For example, if you find a function in RAM you want to call, you can use .definelabel to make a symbol for it. (But then also contribute it to the symbols repository!)

.definelabel InRamFunction,0x8012321

If you need to create an array of spaces, which are usually represented by 16-bit indices, the .halfword directive would be useful.

.halfword 0x10,0x20,0x30

Do not use .org or .orga currently. PP64 automatically does an .org based on where your event will be placed in memory. .orga may be supported in the future for you to do additional patches to other places in the ROM, let me know if you want that capability.

Do not put data (from .byte or others) at the top of your event code! As stated, the game will JAL (make a function call) to the top of the assembled data, so you want it to be instruction code.

Static data/code

There are many cases where code or data is essentially static. In other words, no matter how many copies of an event are used on a board, there really only needs to be one copy of some code or data; all the events could share it.

Within your event code, you can define a region as static with the .beginstatic and .endstatic directives.

.beginstatic
some_constant:
.word 0x123
.endstatic

A static region should not be at the top of your event file.

The typical use case for this is to avoid duplication of helper functions. It may also be useful for multiple copies of an event to reference the same data. (Such data would not persist between turns however.)

Functions

The assembler supports a few functions.

A common task will be loading 32-bit addresses into registers. The hi and lo functions can help with that, as the assembler does not support macros like armips does. hi and lo support being passed symbols or raw values.

For example, if I had a string I wanted to pass to the DrawDebugText function, I'd use hi and lo to write the string pointer into the argument register.

LUI A2 hi(message)
ADDIU A2 A2 lo(message)

JAL DrawDebugText
NOP
...
message:
.asciiz "TEST test"

Editor features

Symbols

Symbols defined in the symbols repository will be made available to you automatically. These are existing functions that are in game memory, ready for you to use. If you discover new symbols, please contribute them to the symbols repository so they can be made available to all custom events!

Autocomplete

  • If you type JAL followed by a space, and press Ctrl+Space, you'll be presented with the function symbols that are available based on the Supported Games you've chosen for your event.
  • In other contexts, Ctrl+Space will show all symbols (functions as well as memory addresses with known values).
  • Pressing . (dot) followed by Ctrl+Space will show you the available assembler directives.

Event Parameters

A custom event can be given parameters, which the user will need to specify when they add the event to a space on their board. Parameters allow an event to be reusable in different scenarios. For example:

  • A generic Adjust Current Player Coins event could be written once, and have a coins numeric parameter. Board creators that use the event can specify how many coins are gained or lost each time they add the event.
  • A generic warp event could be written that takes a space parameter. Board creators that use the event can drag to select the warp destination.

A parameter is given a name, which becomes a symbol available to the assembly code. The symbol is given the value the user chooses.

The following types of parameters are supported:

Type Description
Number An integer, positive or negative, supplied by the board creator.
+Number A positive integer supplied by the board creator.
Boolean A true/false value. The assembly will see 1 or 0.
Space A reference to a space. A space parameter named target_space would result in a target_space symbol equal to the space index of the referenced space. Additionally, target_space_chain_index will equal that space's chain index, and target_space_chain_space_index will equal the index of that space in its chain.

Parameters are specified in the event file with PARAM headers.

; PARAM: Number|coins
You can’t perform that action at this time.