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
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
.sfile. 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
.sfile. 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.
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
||A descriptive name for your event. This will appear when users go to select an event for a space.|
||A comma-delimited list of game titles that the event is compatible with.|
||Controls how the event is executed by the engine. For simpler events,
There are optional fields:
||Specifies a parameter that users can set. There can be more than one
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!)
If you need to create an array of spaces, which are usually represented by 16-bit indices, the
.halfword directive would be useful.
Do not use
.orgacurrently. PP64 automatically does an
.orgbased on where your event will be placed in memory.
.orgamay 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
.byteor 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.
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 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.)
The assembler supports a few functions.
A common task will be loading 32-bit addresses into registers. The
lo functions can help with that, as the assembler does not support macros like armips does.
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
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"
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!
- If you type
JALfollowed 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).
.(dot) followed by Ctrl+Space will show you the available assembler directives.
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
coinsnumeric 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:
||An integer, positive or negative, supplied by the board creator.|
||A positive integer supplied by the board creator.|
||A true/false value. The assembly will see
||A reference to a space. A space parameter named
Parameters are specified in the event file with
; PARAM: Number|coins