|
| 1 | +# Phantom Hourglass Randomizer Developer Documentation |
| 2 | + |
| 3 | +This document provides a general overview of the parts of the randomizer, as well as a brief description of the file structure of the git repo. |
| 4 | + |
| 5 | +Developers who wish to contribute to the randomizer should start here to get a high-level understanding of how the randomizer works, and then |
| 6 | +proceed to `CONTRIBUTING.md` for a lower-level description for how to contribute code. |
| 7 | + |
| 8 | +## Randomizer Architecture |
| 9 | +There are 4 inter-operating components to the randomizer that work together to go from an unmodified, vanilla ROM to a logic-compliant randomized ROM. |
| 10 | + |
| 11 | +### Base ROM patches |
| 12 | +This refers to a collection of code changes and hooks that modify the behavior of the game, prior to any randomization even happening. |
| 13 | +This is necessary to support aspects of the randomizer that aren't possible in the original game. For example, it is not possible to |
| 14 | +have the sword sold in a shop in the original game; this is because the shop has a hardcoded list of items that it can hold. So, we |
| 15 | +have a base patch that modifies the ROM's code to support this. |
| 16 | +Another example is progressive swords; in the original game, there are two distinct sword items - the Oshus Sword and the Phantom Sword. |
| 17 | +Randomizing these items in the vanilla ROM would mean the player can potentially find them in the wrong order. To fix this, most randomizers |
| 18 | +implement progressive swords, where there is only a single sword item that always gives you the "next one up". This is yet another base patch. |
| 19 | + |
| 20 | +These patches consist of, for the most part, code hooks written in either ARM assembly or C. In order to apply them to a ROM several steps must be taken |
| 21 | +(TODO: outline these steps. For now, anyone interested can look at the Dockerfile), some of which require installing various development |
| 22 | +dependencies. To avoid requiring users to install all of these just to run the randomizer, the base patches are pre-generated at compile-time and |
| 23 | +bundled with the randomizer as BPS patches, which are in turn applied to users' ROMs by the patcher at run-time (see Patcher section for more info). |
| 24 | + |
| 25 | +### UI |
| 26 | +The user interface (UI) is the component of the randomizer that the user sees and interacts with directly, and is responsible for calling the other components of the randomizer. |
| 27 | +It provides an interface that lets the user choose the settings they want for the randomizer and to provide their copy of the ROM; after the user provides these, the UI passes this information to the shuffler. It then takes the output of the shuffler and passes it to the patcher, which itself outputs the randomized ROM. |
| 28 | +Note, "the UI" can potentially refer to _any_ user-facing interface to the randomizer; in the early stages of development, this will simply |
| 29 | +be a CLI. Once the randomizer matures and is ready for general use, a GUI will be written to make it more convenient and user-friendly. |
| 30 | + |
| 31 | +### Shuffler |
| 32 | +The shuffler is the component of the randomizer that performs the high-level randomization of the game's items. As input, it takes logic files, aux data files, |
| 33 | +and any settings relevant to randomization that the user specified and were passed by the UI. It parses the logic into a graph data structure and reads the aux data |
| 34 | +files to determine what items are available to be shuffled. It then uses the logic and aux data together to randomly shuffle the items in the game such that it is still |
| 35 | +completable, adhering to user settings where applicable. The final output of the shuffler is a new set of aux data with the items shuffled. |
| 36 | + |
| 37 | +### Patcher |
| 38 | +The patcher is the component of the randomizer that actually changes around the items in the game ROM. To put it simply, it takes in some set of aux data and outputs |
| 39 | +a patched ROM with the items randomized as specified in the aux data. Generally, what will happen is the UI will call the shuffler and pass its output (the |
| 40 | +randomized aux data) to the patcher. |
| 41 | + |
| 42 | +## Structure of git repo |
| 43 | +TODO |
0 commit comments