App:Spectrum

Spectrum is a console-based external memory viewer and editor created by mzxrules custom tailored to Ocarina of Time and Majora's Mask. It's initial goal was to map out the heap in order to understand the infamous wrong warp glitch better, but has been expanded to add various features such as dumping the current frame display list task, listing various collision struct data, utility functions that allow you to spawn anywhere in the game, and more.

Prerequisites

Windows 8.1 or higher operating system

Setup Commands

emu

Sets up a profile for an emulator to attach to. Note that Spectrum comes with a small list of emulator settings of it's own

emu <literal> <string> <string> <string>

• literal = Key, used to specify a specific emulator with the mount command. Key must be unique
• string = Process Name, the internal process name of the emulator
• string = Process Description, used to describe the emulator in more detail
• string = Ram Start Expression. Sets an expression to use to point to where the emulated RDRAM is located within the emulator process's memory. Process module names must be enclosed with backticks, as shown in the pj64 example below. See the expression parser for more information on expressions.

Example

emu nemu Nemu64, Nemu64 0.8, 10020000
emu pj64 Project64, Project 64 1.6, [`project64`+d6a1c]

trainer

Auto-generates a profile for the first emulator detected in memory. Requires you to have a copy of OoT 1.0 (Japanese or English will work fine)

trainer

At the moment, this command only works for emulators using the mupen64plus core and Project64. If mupen64plus core is detected, the program should generate a proper expression for the ram's start location, whereas with pj64 the expression will simply store the address that the emulator allocated RDRAM for that specific launch of the program, and thus will likely need to be run again.

mount

Allows you to specify which active emulator process the program will attach itself to.

mount
mount key

mount scans for all supported emulators, while mount key will allow you to specify a specific emulator by the key value set with the emu command. If multiple instances of the same emulator are running, you will given an additional option to select the process to attach to.

Example

mount
mount pj64
mount nemu

game

Sets what game you wish to work with. You can optionally supply a ver here now, or later with the ver command

Examples

game oot
game mm
game oot n0
game mm dbg

ver

Sets what version of Ocarina of Time or Majora's Mask is loaded, without needing to specify the game. If no parameters are passed in, this will show all version codes supported by Spectrum.

help

Lists all available commands. Specifying a command name will give additional info on what arguments a command expects.

help
help mount

Expression Parser

Spectrum comes with a simple expression parser, allowing you to write expressions in place of some numeric parameters. All numbers within an expression are assumed to be in hexadecimal. The expression parser uses C#'s long type to perform calculations. The following operators are supported: + - * / & | ( ) [ ]

• [ ] is used to read in up to a 4 byte value at the address specified between the brackets, making it easy to follow pointer values. With the exception of the emu command's ramStartExpression, the address specified between the brackets will be truncated (value &= 0xFFFFFF).

Commands

• = <expression> - allows you to evaluate an expression

  =[1C84A0]

Memory Layout Viewer Commands

Once you've hooked on to an emulator and chose your game version, pressing Enter on a blank line/invalid command will create a ram map. This memory map is most accurate/useful while the main game state is loaded, but it still has some use during boot/file select. To simplify the data output, RDRAM addresses are truncated to their low three bytes.

Toggles

t <literal>

Literal can be any of the following:

• ll - Toggles on/off link list mapping for actors. By default, this set to off.
• size - Toggles whether the the end address of an item should be replaced with it's size instead. By default, this is set to off.
• actor - Toggles on/off viewing actor files/overlay mapping. By default, this is set to on.
• obj - Toggles on/off object file mapping. By default, this is set to on.
• part - Toggles on/off particle file mapping. By default, this is set to on.

Actor Hiding

• hidea - Hides actor instances and their code files from the memory map by actor id.

  hidea 125

• showalla - Unhides all hidden actors

Memory Viewing Commands

• ram - Dumps the first 0x100 bytes starting from the given address, displaying them as 8 digit hexadecimal numbers. Accepts expressions
• rams16 - Dumps the first 0x100 bytes starting from the given address, displaying them as signed 16 bit numbers. Accepts expressions
• ramu16 - Dumps the first 0x100 bytes starting from the given address, displaying them as unsigned 16 bit numbers. Accepts expressions
• ramf - Dumps the first 0x100 bytes starting from the given address, displaying them as floating point numbers. Accepts expressions
• a - Attempts to find the containing item for a given ram or virtual ram address, and return various applicable info (ram, virtual ram, virtual rom addresses, etc.). Accepts expressions
• r - Attempts to convert a virtual rom address into a ram address, and return various applicable info (ram, virtual ram, virtual rom addresses, etc.). Accepts expressions.

VerboseOcarina Commands

• romloc - Assigns a rom location for the currently assigned version
• vo - Runs a VerboseOcarina command on the rom located at romloc. Currently Supported commands:
  • Scene - Dumps a scene's information. NOTE: indices are interpreted as DECIMAL numbers. To dump Dodongo's Cavern:

    vo scene 1

    To dump room 5 of Dodongo's Cavern

    vo scene 1.5

  • Actor - Dumps all spawn locations of an actor within the scene data. NOTE: indices are interpreted as HEXADECIMAL numbers. To dump all Stalfos spawns:

    vo actor 2

Actor Misc. Commands

• anear - Lists the actors nearest to Link, ordered by distance
• dumpa - Dumps a given actor instance to file, within the "dump" folder

GBI Parser

Spectrum comes with a few commands to facilitate parsing F3DZEX2 GBI, and a limited subset of S2DEX GBI.

• gfx (OoT, Partial/Broken MM support) - Prints out information on the Graphics Context
• gbi interprets the next 0x100 bytes at the address provided as being F3DZEX2 GBI, printing out the result. Accepts expressions.
• gbidump parses every gbi instruction it encounters, and writes it to "dump/{game}_{version}_frame.txt". This command will follow branches, and will stop parsing if it encounters a DL end command without any display lists stored on stack. By default, it will dump the last complete frame's display list, but it can optionally be supplied with an expression.
• gbiclean (OoT, Partial/Broken MM support) - Zero clears 'garbage' gbi instructions written by previous frames. Avoid using this command after a gbi instruction is written, but before the append start or end ptr has been updated.

Spawning and Positioning Commands

Spectrum allows you to warp to any reasonable coordinate in the game with ease, putting the map select to shame.

• sp - Spawns Link at "entrance 0" of the given scene. Uses internal scene numbers.
• sa (Partial MM support) - Spawn anywhere (unless you crash). Enter a scene number, room number, and x, y, z coordinates.
• sr (Partial MM support) - Spawn in a room within a given scene. Enter a room number and an x, y, z coordinate.
• xyz - Sets Link's x, y, z coordinates to the given integer value
• y - Sets's Link's y coordinate to the given integer value
• ent - Spawn using a given entrance index. Due to the way MM's entrance indexes are structured, the last byte of the index can be omitted in MM.