diff --git a/mm/docs/BUILDING_DOCKER.md b/mm/docs/BUILDING_DOCKER.md deleted file mode 100644 index 5fa7b4865..000000000 --- a/mm/docs/BUILDING_DOCKER.md +++ /dev/null @@ -1,47 +0,0 @@ -# Building using Docker - -## Dependencies - -You will need [Docker](https://docs.docker.com/get-docker/) Follow the instructions for your operating system. - -## 1. Clone the Repository - -You will need to prepare a local version of the project with a copied base ROM (see steps [2](../README.md#2-clone-the-repository) and [4](../README.md#4-prepare-a-base-rom) of the Linux instructions). - -## 2. Create the Docker image - -From inside your local project, run the following command: - -```bash -docker build . -t mm -``` - -This will build a docker image with the name of `mm`, to verify the image was made you can run the command - -```bash -docker image ls -``` - -and look for `mm` under the "REPOSITORY" column. - -## 3. Start the container - -To start the container, you can mount your local filesystem into the Docker container and run an interactive bash session. - -```bash -docker run -it --rm --mount type=bind,source="$(pwd)",destination=/mm mm /bin/bash -``` - -- The `-it` flags Keep STDIN open even if not attached to the container and allocates a pseudo-tty terminal. -- The `--rm` flags causes Docker to automatically remove the container when it exits. -- The `--mount` flag allows you to mount volumes and host-directories in a container. By specifying the type to be a bind, we are saying there are files to be mounted from the host machine (the one that runs your docker daemon) onto the container. Source is specifying where we are mounting the files from in this case, we want the `mm` folder created earlier. The $(pwd) sub-command expands to the current working directory. The destination takes as its value the path where the file or directory is mounted in the container. This makes it so that the image should rarely change and will reduce the need to rebuild with any change to the codebase. - -## 4. Setup and Build the ROM - -Once inside the container, you will need to set the repository as a trusted repository with the following command: - -```bash -git config --global --add safe.directory /mm -``` - -After that continue with step [5. Make and Build the ROM](../README.md#5-make-and-build-the-rom) of the Linux instructions to setup and build the ROM, or run any other command you need. diff --git a/mm/docs/BUILDING_MACOS.md b/mm/docs/BUILDING_MACOS.md deleted file mode 100644 index cf93acbf2..000000000 --- a/mm/docs/BUILDING_MACOS.md +++ /dev/null @@ -1,92 +0,0 @@ -# Building on macOS - -**N.B. C++17 is required to build the asset processing program that we use (ZAPD), so check your OS version can support this before proceeding** - -## Dependencies - -For macOS, use Homebrew to install the following dependencies: - -* coreutils -* make -* python3 -* libpng -* bash - -You can install them with the following commands: - -```bash -brew update -brew install coreutils make python3 libpng bash -``` - -(The repository expects Homebrew-installed programs to be either linked correctly in `$PATH` etc. or in their default locations.) - -Homebrew does not have clang-format-14 but MacPorts does - -(Have been unable to confirm actual commands with somone that has a Mac) - -## Building mips-linux-binutils - -The following instructions are written for MacOS users but should apply to any Unix-like system, with maybe some modifications at the end regarding the bash_profile. - -Create destination dir for binutils - -```bash -sudo mkdir -p /opt/cross -``` - -Create and enter local working dir - -```bash -mkdir ~/binutils-tmp -cd ~/binutils-tmp -``` - -Get and extract binutils source - -```bash -wget https://ftp.gnu.org/gnu/binutils/binutils-2.35.tar.bz2 -tar xjf binutils-2.35.tar.bz2 -``` - -(You may find this command does not work: if so, just access the URL in a browser and save it to `~/binutils-tmp`.) - -Create and enter a build directory - -```bash -mkdir build-binutils -cd build-binutils -``` - -Configure the build - -```bash -../binutils-2.35/configure --target=mips-linux-gnu --prefix=/opt/cross --disable-gprof --disable-gdb --disable-werror -``` - -Make and install binutils - -```bash -make -j -sudo make install -``` - -Edit your `~/.bash_profile`/`~/.zsh_profile` (or whichever shell you use) to add the new binutils binaries to the system PATH - -```bash -echo "export PATH=$PATH:/opt/cross/bin" >> ~/.bash_profile -``` - -Reload ~/.bash_profile (or just launch a new terminal tab) - -```bash -source ~/.bash_profile -``` - -If this worked, you can now delete the temporary directory `~/binutils-tmp`. - -## Final note - -Apple's version of `make` is very out-of-date, so you should use the brew-installed `gmake` in place of `make` in this repo from now on. - -You should now be able to continue from [step 2](../README.md#2-clone-the-repository) of the Linux instructions. diff --git a/mm/docs/CONTRIBUTING.md b/mm/docs/CONTRIBUTING.md deleted file mode 100644 index f5a042846..000000000 --- a/mm/docs/CONTRIBUTING.md +++ /dev/null @@ -1,149 +0,0 @@ -# Contributing to the Majora's Mask Decompilation Project - -Thanks for helping us reverse engineer *The Legend of Zelda: Majora's Mask* for the N64! -All contributions are welcome. This is a group effort, and even small contributions can make a difference. Some tasks also don't require much knowledge to get started. - -This document is meant to be a set of tips and guidelines for contributing to the project. -For general information about the project, see [our readme](https://github.com/zeldaret/mm/blob/main/README.md). - -Most discussions happen on our [Discord Server](https://discord.zelda64.dev) where you are welcome to ask if you need help getting started, or if you have any questions regarding this project and other decompilation projects. - -## Useful Links - -- [Installation guide](https://github.com/zeldaret/mm/blob/main/README.md#installation) - Instructions for getting this repository set up and built on your machine. -- [Style Guide](STYLE.md) - Description of the project style that we ask contributors to adhere to. -- [Code Review Guidelines](REVIEWING.md) - These are the guidelines that reviewers will be using when reviewing your code. Good to be familiar with these before submitting your code. - -- [Zelda 64 Reverse Engineering Website](https://zelda64.dev/games/mm) - Our homepage, with FAQ and progress graph :chart_with_upwards_trend:. -- [MM decomp tutorial](tutorial/contents.md) Detailed tutorial for learning in general how decomp works and how to decompile a small, simple file. -- [Introduction to OOT decomp](https://github.com/zeldaret/oot/blob/main/docs/tutorial/contents.md) - The tutorial the MM one was based on. For OOT, but largely applicable to MM as well. Covers slightly different topics, including how to get your data OK with `vbindiff`. -- The `#resources` channel on the Discord contains many more links on specific details of decompiling IDO MIPS code. - -## Getting Started - -### What should I know to take part? - -Basic knowledge of C, particularly arrays and pointers, is extremely useful. Knowledge of MIPS is not required initially, you can pick it up as you work through some decompilation. - -You should be familiar with using git and GitHub. There are a number of tutorials available online, [such as this one](https://github.com/firstcontributions/first-contributions) which can help you get started. - -The most useful knowledge to have is a general understanding of how the game works. An afternoon of constructive mucking about in the [MM Practice Rom](https://kz.zeldacodes.org/) (aka KZ) or the [OoT Practice Rom](http://practicerom.com/) (aka GZ) will be very beneficial if you have not looked at either of the N64 Zelda's internals before. - -The [OoT Decompilation Project](https://github.com/zeldaret/oot) is farther along than this project, so it can also be a great resource. - -This project only uses *publicly available code*. - -**N.B.** Anyone who wishes to contribute to the OOT or MM projects **must not have accessed leaked source code at any point in time** for Nintendo 64 SDK, iQue player SDK, libultra, Ocarina of Time, Majora's Mask, Animal Crossing/Animal Forest, or any other game that shares the same game engine or significant portions of code to a Zelda 64 game or any other console similar to the Nintendo 64. - -### Environment Setup - -Get started by following the [installation guide in the readme](https://github.com/zeldaret/mm/blob/main/README.md#installation). -You should be able to build a matching ROM before you start making any changes. - -### First Contribution - -Usually, the best place to get started is to decompile an actor overlay. -An *actor* is any thing in the game that moves or performs actions or interactions. This includes things like Link, enemies, NPCs, doors, pots, etc. Actors are good for a first file because they are generally small, self-contained systems. - -We recommend that you [join the Discord](https://discord.zelda64.dev/) to say hello and get suggestions on where to start on the `#mm-decomp` channel. - -We track who is working on what on some Google Sheets available in the Discord. Once you've decided on or been recommended a good first file, mark it as Reserved. - -The workflow is: - -- Reserve a file, -- decompile it, -- submit a PR, -- repeat while addressing review comments. - -The expectation is that one reservation goes to one file which ends up in a one file PR, although naturally some files are more sensibly worked on as a group, for example two actors that work together. This also does not apply to large asset files like `gameplay_keep`: you can just reserve the parts that are used in your files. - -If possible, we expect reserved files to be completed. If you find you cannot complete a file, because it is intractable for one reason or another, or real-life circumstances get in the way, please talk to one of the leads in Discord; we may find someone else interested in helping you finish, or who is happy to take over the file from you completely. If you unreserve a file on which you have useful progress, please leave a link to your branch in the Notes column on the Google Sheet that the next person who works on the file can use. - -## Style Guide & Conventions - -See the [Style Guide](STYLE.md). - -## `NON_MATCHING` and `NON_EQUIVALENT` - -If you make significant progress on decompiling a function, but can't get it to match perfectly, you can use a `NON_MATCHING` block to commit your code but have it excluded from the build, like so: - -```c -#ifdef NON_MATCHING -void CollisionCheck_SpawnWaterDroplets(PlayState* play, Vec3f* v) { - // ... -} -#else -void CollisionCheck_SpawnWaterDroplets(PlayState* play, Vec3f* v); -#pragma GLOBAL_ASM("asm/non_matchings/code/z_collision_check/CollisionCheck_SpawnWaterDroplets.s") -#endif -``` - -Before PRing with a `NON_MATCHING`, you can try - -- using the [decomp-permuter](https://github.com/simonlindholm/decomp-permuter) to find a closer match, -- Asking in `#mm-decomp-help` in Discord; the easiest way to allow other people to play around with the function you are stuck on is to make a scratch on [decomp.me](http://decomp.me). - -`NON_EQUIVALENT` can be used with the same syntax as `NON_MATCHING`, but it is used to mark sections of code which do not match *and* do not have the same behavior as the original code. - -## Matching and Documenting - -Usually, the first step of decompiling a section of code is to get it *matching*: to produce a C version of the code that can be compiled into an identical ROM. - -However, the goal of this project is to produce a codebase that can be understood and modified. -Therefore once C code produces matching assembly, the next step is to *document* the code. - -Documenting is more than just adding comments. Documenting also includes: - -- Renaming functions, variables, and struct members -- Using (or adding) constants, enums, and macros when possible -- Explaining sections of code that are not straightforward - -Overlays are not required to be documented at this time, but files from `code/` and `boot/` should be documented. When documentation on a file has been started it should be as complete as reasonable. - -See the [Style Guide](STYLE.md) for more details on documentation style. - -## Pull Requests (PRs) - -### Checklist - -Before opening a PR, walk through the following steps to ensure that your code conforms to the style guide and conventions. - -- `make` successfully builds a matching ROM. -- `./format.py` was run to apply standard formatting. -- No new compiler warnings were introduced during the build process. - - Can be verified locally by running `tools/warnings_count/check_new_warnings.sh` -- New variables & functions should follow standard naming conventions. -- Comments and variables have correct spelling. - -Feel free to reach out on the Discord if you have any questions about these steps or encounter any issues. - -### Pull Request Process - -After opening a PR, the Jenkins agent will test formatting, the contents of the spec, build the rom and check for warnings. -If there is an error, double-check that you can successfully - -```bash -make disasm -./extract_assets.py -f -make clean -make -``` - -locally. If the build is `OK`, the next thing to check is that all added/modified files were `git add`-ed to your commit. The final check before posting on Discord for help is that there are no new warnings added to the code causing Jenkins to fail. You can check this by running: `tools/warnings_count/check_new_warnings.sh`. - -Each PR needs a review from two reviewers, at least one a project lead, and final approval from Kenix. - -If the PR author agrees with a reviewer's suggestion, they make the change and resolve the conversation. If they disagree, have a better idea, or want to comment on something, they should at least leave a comment, and discuss it in Discord if it's not going to be resolved quickly, since long conversations on GitHub are hard to read. - -Once all comments is addressed and all reviewers have approved, the PR will be merged. - -Project leads are responsible for ensuring that these conventions are followed. - -### Some git notes - -- You should work on a branch on your fork separate from your copy of main: it is always useful to have a clean main branch around if you need to fix something. -- When a PR is merged into main, it may conflict with your work. While your branch is private (in particular, not used for a PR), you can rebase, but when your branch is public/used for a PR always merge main instead of rebasing: it makes it much easier for people to understand what you changed since the last review. -- We squash commits when merging, so your commit history does not have to be completely spotless. - -Throughout the PR process, you (the author) should update the rows on the appropriate Google Sheets with the appropriate information as the decompilation process progresses. diff --git a/mm/docs/REVIEWING.md b/mm/docs/REVIEWING.md deleted file mode 100644 index 3fc160729..000000000 --- a/mm/docs/REVIEWING.md +++ /dev/null @@ -1,58 +0,0 @@ -# Reviewing Pull Requests to the Majora's Mask Decompilation Project - -Thanks for helping us reverse engineer *The Legend of Zelda: Majora's Mask*! -We encourage all contributors to participate in code review: this is your codebase too! -Every review submitted helps us keep code quality high and code merged in more quickly. - -This document is meant to be a set of tips and guidelines for reviewers of pull requests to the project. -For general information about the project, see [our readme](https://github.com/zeldaret/mm/blob/main/README.md). - -Most discussions happen on our [Discord Server](https://discord.zelda64.dev) where you are welcome to ask if you need help getting started, or if you have any questions regarding this project and other decompilation projects. - -Other links are available in the [CONTRIBUTING.md](CONTRIBUTING.md) - -## Getting Started - -### What should I know to take part in the review process? - -You should first famiiarise yourself with our [Contributing guide](CONTRIBUTING.md) and [Style guide](STYLE.md). It is also recommended that you have already successfully submitted a merged pull request to understand how the process works before submitting a review. - -## Pull Requests (PRs) - -### How to review a Pull Request - -- When reviewing a PR it is suggested that you follow the checklist outlined in this section. -- You are not required to go through *every* item in the checklist. It is meant as a guide; if you have only one thing you want to mention, that's fine too. -- Once the PR author has addressed all of your comments, you should add a review with approval to the PR to signify to the project leads that this PR has been through peer review. -- If someone does not address your comments and expresses that a different way is better than yours, look for feedback from other contributors (we encourage discussing this sort of thing in Discord, since long GitHub conversations get hard to read). The project leads will have final say in these situations. All decisions are generally guided by a consensus of contributors. - -### Reviewer Checklist - -- [ ] Jenkins build is successful. - - [ ] `make` builds a matching ROM. - - [ ] `format.py` was run. - - [ ] `spec` contains correct relocation files. - - [ ] Any new compiler warnings that were added are required for matching. Ensure there is good reason if the warnings files have changed. -- [ ] Files with `NON_MATCHING` functions have equivalent behaviour. -- [ ] `code` and `boot` segment files should be documented as much as possible. Overlays with documentation should be as complete as is reasonable. - - [ ] Overlays should have macros to define access to parameters if the parameter uses bitwise access. The params should have an enum when it makes sense. -- [ ] Comments and variables have correct spelling. -- [ ] The following should be declared in an Actor header file. There should be nothing else in the Actor header file. - - [ ] Main Actor struct - - [ ] Extern'd initVar data. - - [ ] Types used in the actor struct. Specific example would be actionFunc typedefs. - - [ ] Param field macros and/or enums. - - [ ] For any other additional `enum`/`struct`/`define`/`function`/`global`, there needs to be evidence it is needed in another file. -- [ ] New variables and functions should follow standard naming conventions. - - [ ] Constants are converted to whichever looks best in context: hexadecimal, decimal, or float - - [ ] Rotation angles should always be in hexadecimal - - [ ] Colour values should always be in decimal. - - [ ] Functions, structs, unions, enums, and typedefs are `TitleCase` (`DmRavine`) - - [ ] Functions within a system separate the system from the function's own subname with an underscore (`DmRavine_Init`) - - [ ] Variable names are `camelCase` (`actionFunc`) - - [ ] Global variables start with `g` (`gSaveContext`) - - [ ] Static global variables start with `s` (`sSphereInit`) - - [ ] Macros and enum constants are `SCREAMING_SNAKE_CASE` (`DM_RAVINE_STATE_ACTIVE`) - - [ ] Trailing commas in array and struct definitions chosen to make it look best (see e.g. `EnJcMatoDamageTable`) - -etc. diff --git a/mm/docs/STYLE.md b/mm/docs/STYLE.md deleted file mode 100644 index 616c4a8cc..000000000 --- a/mm/docs/STYLE.md +++ /dev/null @@ -1,249 +0,0 @@ -# Majora's Mask decompilation style guide - -In general, completed documented files are a good place to look to understand project style in general. - -## Types - -Use the types from `ultratypes.h`, not the standard C types: i.e. `u8`,`s8`,`s16`,`u16`,`s32`,`u32`,`f32` rather than `char`, `short`, `int`, `float` and their `signed`/`unsigned` varieties. - -We always write our enums and structs as `typedef`s. (Usually one can't use an enum typedef as a function argument since enum typedefs are implicitly `s32`.) - -## Naming - -Names are "big-endian": the most significant/largest part of the system goes first, e.g. `DM_RAVINE_STATE_ACTIVE` rather than `DM_RAVINE_ACTIVE_STATE`. - -| Type | Style | Example | -| -------------------- | ----------------------- | ----------------------- | -| Local variables | camelCase | `yawToPlayer` | -| Global variables | gCamelCase | `gSaveContext` | -| Static variables[^1] | sCamelCase | `sZeroVec` | -| Struct members | camelCase | `actionFunc` | -| Struct names | PascalCase | `EnFirefly` | -| Enum types | PascalCase | `EnFireflyMainType` | -| Enum values | SCREAMING_SNAKE_CASE | `AT_ON` | -| Defines/macros | SCREAMING_SNAKE_CASE | `SCREEN_WIDTH`,`ABS(x)` | -| Functions | SystemName_FunctionName | `Actor_SpawnAsChild` | -| Files | snake_case | `z_en_firefly.c` | - -[^1]: including in-function static - -Action functions are usually named with a simple present-tense verb or verb phrase: `{...}_Talk`, `{...}_Wait`, `{...}_FallToGround`, etc. Setup functions are `Setup{name of action}`. - -Ideally names should be both short and clear, although it's better to be clear than short. - -## Formatting - -A lot of formatting is done by clang-format, such as - -- indent is 4 spaces, tabs are not used -- case labels indented -- 120 column limit -- brackets go on the same line (`if (1) {`) -- pointer goes on type (`s32* var;` not `s32 *var;`) - -There are various other conventions that it does not catch, though: - -- Blank line between declarations and code: - - ```c - s32 var; - - func(); - ``` - -- combine declarations and definitions if possible: - - ```c - s32 var = 0; - - func(); - ``` - - instead of - - ```c - s32 var; - - var = 0; - func(); - ``` - -- blank lines between switch cases if they're long (use your judgement). - -## Numbers - -### dec(imal) - -- timers -- colours and alpha -- Usually array accesses and sizes - -### hex(adecimal) - -- angles (for now; the code itself is very inconsistent with round hex, round dec, and degrees) -- Addresses -- Bitmasks (i.e. `& 0x80` etc.) -- Struct offset comments - -Numbers below `10`/`0xA` do not need the `0x` if by themselves in code. - -### Booleans - -If a function returns only `0` or `1`, and is used as a boolean (i.e. in conditionals), replace the returns by `false` and `true`. (We do not use `bool`, partly because is a C99 thing, and partly because the original has used almost every integer type as a boolean return at some point!) - -### Floats - -Floats usually need an `f` on the end to match, or IDO will use doubles. Our floats are always of the form `1.0f`, even when the decimal part is zero. - -## Conditionals/Loops - -- Spacing out conditional or loop blocks from surrounding code often makes them easier to read. -- Avoid assigning or mutating variables in conditionals if possible (including `++`/`--`), avoid side effects in the loop increment slot (i.e. incrementing/assigning to loop variables is fine, something like `*a = b++` is not). -- We *always* use `{}` on conditional/loop blocks, even if they're one line (clang-tidy will enforce this). -- When conditions are `&&`d or `||`d together, use brackets around each that includes an arithmetic comparison or bitwise operator (i.e. not `!var` or `func()`, but ones with `==` or `&` etc.) -- Flag checks or functions that return booleans do not need the `== 0`/`!= 0`. -- Prefer `if-else` over `if { return; }`, i.e. - - ```c - if (cond) { - foo(); - } else { - bar(); - } - ``` - - over - - ```c - if (cond) { - foo(); - return; - } - bar(); - ``` - -**Exception**: After `Actor_Kill` or sometimes setting the action function, if it makes sense to do so (this expresses the finality a bit better). - -## Macros and enums - -Become familiar with the various defines and enums we have available. There are too many to list all of them here, but the following are common: - -- Those in `macros.h` - - `ABS`, `ABS_ALT`, - - `CLAMP` and friends, - - `BINANG_*`, which are used for angles, especially when there's a lot of `s16` casts around -- `MTXMODE` for many of the `sys_matrix` functions -- CollisionCheck flags: `AT_ON` and so on. Pick the appropriate one for the collider type. -- Actor flags, `ACTOR_FLAG_N`. - -Damage flag enums are not being used at present: we want to wait until we have a better idea what the common groupings should be. - -Pre-C99, commas at the end of the last item in an enum will cause a compiler warning, so leave them off. - -All compound flag lists (e.g. `ACTOR_FLAG_UNFRIENDLY | ACTOR_FLAG_FRIENDLY`) should be listed in *ascending* order - -## Arrays - -- It's better to not hardcode array sizes (easier to mod) -- Use `sizeof` or `ARRAY_COUNT`/`ARRAY_COUNTU` where it makes sense, e.g. in loops that are using an array. -- clang-format sometimes does weird things to array formatting. Experiment with and without a comma after the last element and see which looks better. - -## Play2 - -In some particular instances, IDO requires the function argument `play` to be cast to a second variable of the same type to match. In these particular instances, the function argument should be renamed to `play2` and than this `play2` just assigned to a stack variable called `play`. This cast should occur before the actor `THIS` cast is made. For example in `z_en_firefly.c` -```c -void EnFirefly_Update(Actor* thisx, PlayState* play2) { - PlayState* play = play2; - EnFirefly* this = THIS; -``` - -In other places the cast is actually not explictly needed, but a stack `pad` variable is still needed. For this there should just be a stack variable called `pad` of type `s32` before the actor `THIS` cast. For example in `z_bg_goron_oyu` - -```c -void BgGoronOyu_Init(Actor* thisx, PlayState* play) { - s32 pad; - BgGoronOyu* this = THIS; - CollisionHeader* colHeader = NULL; -``` - -In general, pads should be `s32`, or `s16`/`s8` if required. - -## Documentation and Comments - -Documentation includes: - -- Naming functions -- Naming struct variables -- Naming data -- Naming local variables -- Describing the general purpose of the file -- Describing any unusual, interesting or strange features of how the file or parts of its content work -- Labelling and explaining bugs -- Making enums or defines for significant numbers for the file, like actor params values. -- Naming the contents of the asset file(s) the file may use (for an actor, the object(s) it uses) - -If you are not sure what something does, it is better to leave it unnamed than name it wrongly. It is fine to make a note of something you are not sure about when PRing, it means the reviewers will pay special attention to it. - -We use comments for: - -- Top of file: a short description of the system. For actors there is already a brief description of our current understanding, but feel free to add to it. -- For function descriptions, we use multiline comments, - - ```c - /** - * Describe what the function does - */ - ``` - - These are *optional*: if you think the code is clear enough, you do not need to put a comment. You can use Doxygen formatting if you think it adds something, but it is also not required. -- If something in a function is strange, or unintuitive, do leave a comment explaining what's going on. We use `//` for this. -- We also use `//` for temporary comments above a function. Feel free to use `TODO:` in these if appropriate. -- A bug should be commented with an `//! @bug Bug description` above the code that causes the bug. - -## What goes where - -This section mostly applies to actors. - -### Functions - -All functions should go in the main C file in the same order as the assembly (the latter is required to match anyway). (We may make exceptions for particularly large files with a particular organisational structure, but we ask that you check on Discord first before doing this) - -### Data - -- If in doubt, leave all the data at the top of the file. Reviewers will decide for you. -- Data must go in the same order as in the assembly files, but is only constrained by other data, not functions or rodata. -- Some data has to be inline static to match. Generally it's better to not use `static` on data outside funtions until the file is matching, since `static` data is left out of the mapfile and this makes debugging harder. -- *This is even more true of bss, where we have trouble with IDO unpredictably reordering it in certain files.* -- For small arrays or simple data that is used in only one function, we usually inline it, if it fits in the ordering. -- Generally data that is only used by the draw functions is put down near them: this is one of the few consistencies in ordering of actors' functions. - -### Enums and defines - -- Actors that bitpack params should have macros made for each access or write that is made. `z_en_dg.h` has an undocumented example, - - ```c - #define ENDG_GET_FC00(thisx) (((thisx)->params & 0xFC00) >> 0xA) - #define ENDG_GET_3E0(thisx) (((thisx)->params & 0x3E0) >> 5) - ``` - - while `z_en_firefly.h` has a documented one, - - ```c - #define KEESE_INVISIBLE (1 << 0xF) - #define KEESE_GET_MAIN_TYPE(thisx) ((thisx)->params & 0x7FFF) - ``` - -- In a similar manner, actors that use `home.rot.(x|y|z)` like params should also macros made for accesses and writes. (See, e.g. `z_obj_bean.h`.) -- Stuff that only the actor itself will use goes in the C file unless needed in the header. -- Anything actor-specific that might be used by another file goes in the header, in particular params access macros. -- Anything that is expected to have widespread use should go in `macros.h` or an appropriate header in `include`. - -### Objects - -Are covered in the [ZAPD extraction xml spec](../tools/ZAPD/docs/zapd_extraction_xml_reference.md). Symbol names are `gPrefixDescriptionSuffix` for symbols accessed from the header (they will be global). Texture OutNames are in snake_case since they are filenames. - -## Above all else - -*All of the above is subservient to matching.* Sometimes IDO cares about newlines, for example. - -If you are not sure about any of the above, please ask in Discord. diff --git a/mm/docs/images/En_Firefly.png b/mm/docs/images/En_Firefly.png deleted file mode 100644 index ed3258592..000000000 Binary files a/mm/docs/images/En_Firefly.png and /dev/null differ diff --git a/mm/docs/images/diff.png b/mm/docs/images/diff.png deleted file mode 100644 index c93a5ac9f..000000000 Binary files a/mm/docs/images/diff.png and /dev/null differ diff --git a/mm/docs/tools.md b/mm/docs/tools.md deleted file mode 100644 index c307382f9..000000000 --- a/mm/docs/tools.md +++ /dev/null @@ -1,311 +0,0 @@ -# Table of Contnets - -- [Table of Contnets](#table-of-contnets) - - [Introduction](#introduction) - - [In the repository](#in-the-repository) - - [`diff.py`](#diffpy) - - [`tools/m2ctx.py`](#toolsm2ctxpy) - - [`tools/overlayhelpers/actor_symbols.py`](#toolsoverlayhelpersactor_symbolspy) - - [`first_diff.py`](#first_diffpy) - - [`sym_info.py`](#sym_infopy) - - [`extract_assets.py`](#extract_assetspy) - - [`tools/assist.py`](#toolsassistpy) - - [`tools/get_actor_sizes.py`](#toolsget_actor_sizespy) - - [`tools/progress.py`](#toolsprogresspy) - - [`tools/regconvert.py`](#toolsregconvertpy) - - [`tools/rename_global_asm.py`](#toolsrename_global_asmpy) - - [`tools/rename_sym.sh`](#toolsrename_symsh) - - [`tools/actorfixer.py`](#toolsactorfixerpy) - - [`tools/timeconv.py`](#toolstimeconvpy) - - [`tools/sfx_convert.py`](#toolssfx_convertpy) - - [`tools/vt_fmt.py`](#toolsvt_fmtpy) - - [`tools/graphovl.py`](#toolsgraphovlpy) - - [`tools/warnings_count/check_new_warnings.sh`](#toolswarnings_countcheck_new_warningssh) - - [`tools/warnings_count/update_current_warnings.sh`](#toolswarnings_countupdate_current_warningssh) - - [`fixle.sh`](#fixlesh) - - [`format.py`](#formatpy) - - [External tools](#external-tools) - - [mips_to_c](#mips_to_c) - - [Permuter](#permuter) - - [vbindiff](#vbindiff) - - [Texture64](#texture64) - - [Z64Utils](#z64utils) - - [Retired tools](#retired-tools) - - [`tools/overlayhelpers/ichaindis.py`](#toolsoverlayhelpersichaindispy) - - [`tools/overlayhelpers/colliderinit.py`](#toolsoverlayhelperscolliderinitpy) - - [`tools/overlayhelpers/colchkinfoinit.py`](#toolsoverlayhelperscolchkinfoinitpy) - - [`tools/overlayhelpers/damage_table.py`](#toolsoverlayhelpersdamage_tablepy) - - [`tools/vtxdis`](#toolsvtxdis) - - [Reservation Tracking](#reservation-tracking) - -## Introduction - -There are a variety of tools that are used to assist in the decompilation process. This guide is an introduction to some of the tools that are used. Most of these tools are located in the `mm/tools` directory, others are either in the project root, or are separate programs entirely. Almost all of these programs have more information available via running them with `-h`. - -## In the repository - -### `diff.py` - -Your best friend for most of the decompilation work. Compares the original assembly extracted from the ROM instruction-for-instruction with what the code you have written compiles to. - -To use `diff.py`, you need a copy of a matching build folder to diff against. In MM, this can be made with `make diff-init`, which will rebuild both ROMs, check for OK, and copy the build folder and the roms. - -`diff.py` takes the function symbol name as the main argument: - -```bash -./diff.py ObjTree_Init -``` - -`diff.py` reads the respective `mm.map` files to find the function. If the function has been renamed, it will not be able to find it. You should not edit map files yourself, but instead rerun `make diff-init` (it is possible to copy the build folder manually, but it's better not to, since `make diff-init` guarantees an OK `expected` folder). - -The recommended flags used are `-mwo`, `-mwo3`, or `-mwob`: - -- `-m` ("make") builds the file used for diffing automatically when `diff.py` is run. -- `-w` ("watch") will watch the C file containing the function (and only the C file!) and automatically recompile when it changes. -- `-o` ("object file") uses only the `.o` file. This is faster than without, and means you can see symbol names, but obscures the data behind relative addresses: if you have differences in the .text section that are invisible with `-o`, or you suspect the data is shifted in some way, try without -- `-3` creates a three-way diff: TARGET/CURRENT/PREVIOUS, which is particularly useful for seeing changes. -- `-b` creates a three-way diff: TARGET/CURRENT/BASE, where BASE is the version from when the program was started. -- `-s` ("stop") stops diffing at the next `jr $ra`, commonly the end of the function. Beware that some functions with conditionals may have multiple `jr $ra`s, so this feature can chop the bottom off the diff. - -There are numerous other options that are not used as often (changing the diffing algorithm, viewing the source code in the diff, ...), and the various flags have dependencies among themselves, so check its documentation with `-h` to get fuller information. - -Colour explanations (sadly GitHub markdown does not allow for fancy colouring here): - -- white/grey is matching instructions -- red is missing instructions -- green is extra instructions -- blue means something in the instruction is wrong, be it numerical differences in the immediates, or the whole thing. Not all blue is meaningful: using `-o` to get symbols, the addresses of imported data will be blue since the relative address looks different from the absolute one. -- yellow means the instruction itself is correct, but the registers used are not (*regalloc*, register allocation) -- Each register gets its own colour when the regalloc is wrong, which makes it much easier to follow their usage. -- a branch is indicated by coloured `~>`s on the right of the instruction, and their targets by the same colour `~>` on the left of the instruction (remember delay slots!). The colours matching is a good indication that the branches are correct, although not infallible, since there are only so many colours it will use. -- occasionally instructions will be coloured a dark grey. You should consider this the same as blue. - -Example Diff: - -![Diff](images/diff.png) - -### `tools/m2ctx.py` - -Pass it the path to a C file to generate the context for that C file, to help [mips_to_c](#mips_to_c). Writes to a file called `ctx.c` in the root directory of the repo. - -### `tools/overlayhelpers/actor_symbols.py` - -Takes a VRAM or VROM address to get overlay file and offset for an Actor. - -### `first_diff.py` - -Gives you the addresses of first difference in the ROM, the difference, and a count of how many bytes differ, or if the whole ROM is shifted. - -### `sym_info.py` - -Can be given a symbol (function or variable name, for example), and will find its ROM, VRAM, and file using the map file. E.g. - -```bash -$ ./sym_info.py ObjTree_Init -Symbol ObjTree_Init (RAM: 0x80B9A0B0, ROM: 0xFFF210, build/src/overlays/actors/ovl_Obj_Tree/z_obj_tree.o) -``` - -### `extract_assets.py` - -A tool that will use ZAPD to extract assets from the baserom. - -### `tools/assist.py` - -Searches for similar functions to the one you are passing, and it tells you which one are decompiled. You can pass the name of an overlay and it will search for similar functions for every function in said overlay. - -(Still a little broken) - -### `tools/get_actor_sizes.py` - -Generates a list of actors with various statistics about their function sizes. Run with `-h` for information on flags. - -(nonmatching does not work currently: we need to adapt it to MM's assembly files) - -### `tools/progress.py` - -Gives the progress output that the website uses. Run for that warm glow. - -### `tools/regconvert.py` - -Convert `mips2c`'s `gRegEditor->data[n]` output (or a raw offset) into the appropriate variable in the REG pages. Can also be run on a file to mass-convert them: run with `-h` for details. - -### `tools/rename_global_asm.py` - -Will rename the single-function assembly files in `asm/non_matchings` when the function they contain has been renamed. Should mean you have to run `make disasm` far less frequently. - -### `tools/rename_sym.sh` - -Will rename a symbol throughout the codebase. **Be very careful with this script**: it has no sanity checks, so you can do a lot of damage if you're not careful. Best to commit before using it. - -### `tools/actorfixer.py` - -Provided it is kept up-to-date with function renames, you can run this to automatically update your branch with the new names. `.` will cause it to replace in the whole repo, or you can pass it a specific file path to run it on only that file. - -### `tools/timeconv.py` - -Changes a raw `u16` value into a macro for clock time in-game: - -```bash -$ ./tools/timeconv.py 0x4800 -6,45 -> 0x4800 -CLOCK_TIME(6, 45) -``` - -Either dec or hex input will work. It will warn if the macro output will not match: - -```bash -$ ./tools/timeconv.py 44102 -16,09 -> 0xAC44 -CLOCK_TIME(16, 9) -Warning: Result does not match as-is -``` - -### `tools/sfx_convert.py` - -Replaces sfx ids by their corresponding defines from `sfx.h`. Run on a single file to replace all of them. - -### `tools/vt_fmt.py` - -Replaces VT symbols by their corresponding macros. Not many files in MM need this; ask if you need help with it. - -### `tools/graphovl.py` - -Creates a graph of action functions (black and green arrows) and function calls (blue arrows) for a given overlay file. For best results, run this from the root directory - -Example: `./tools/graphovl/graphovl.py En_Firefly` - -This will save a `.png` of the overlay in the `/graphs` directory. - -See Example below. - -![Graph](images/En_Firefly.png) - -### `tools/warnings_count/check_new_warnings.sh` - -Runs a make from clean and checks if new warnings have been produced: we use Jenkins to check this as well, but you should run this before opening a PR. - -You can specify how many threads you would like this to run with by adding the `-jN` flag. Where N is the number of threads. By default this will run using 1 thread (i.e. `-j1`). - -Run `check_new_warnings.sh -h` for more information. - -### `tools/warnings_count/update_current_warnings.sh` - -If you have to add new warnings, **and have permission from the leads**, run this to update the file used for warnings comparison. - -### `fixle.sh` - -Fixes line endings in the repo to Linux style (LF), which is required for the build process to work. (You may be better off creating a new clone directly in Linux/WSL, though) - -### `format.py` - -Formats all C files in the repo using `clang-format-14`, `clang-tidy`, and `clang-apply-replacements` (when multiprocessing). This will touch all files in the repo, so the next `make` will take longer. - -You can specify how many threads you would like this to run with by adding the `-jN` flag. Where N is the number of threads. By default this will run using 1 thread (i.e. `-j1`). - -`clang-14` is available in many native package managers, but if not try: - -Linux: -Download llvm's setup script, run it, than install normally -```bash -wget https://apt.llvm.org/llvm.sh -chmod +x llvm.sh -sudo ./llvm.sh 14 -rm llvm.sh -sudo apt install clang-format-14 clang-tidy-14 clang-apply-replacements-14 -``` - -Mac: -Brew does not have clang-format-14, but MacPorts does. - -(Have been unable to confirm actual commands with somone that has a Mac) - - -## External tools - -### mips_to_c - -mips_to_c (or mips2c) is a tool that takes MIPS assembly and will attempt to convert it to C. - -There are different ways you can run mips2c: - -- Clone the repo and run it loclly on your own machine. Follow set up instructions at -- An online version is available at . - -mips_to_c's accuracy can be improved when some context to what the existing C source code is like. See more on how to generate this in [m2ctx](#m2ctx.py) - -### Permuter - -Use when you're low on ideas for matching a function. This goes through a series of heuristic random replacements known to help improve matching, although often at the expense of clarity. - -To set up the permuter, clone the repository in a directory of your choice. Follow the usage section of the README and ensure you have all the prerequisites installed. - -```bash -./import.py -``` - -on the files to import the code on which to run the permuter to `nonmatchings/func`, and then - -```bash -./permuter.py -``` - -will run the permuter - -Flags: - -- `-jN` for multithreading -- `-J` for using permuter@home (ask in Discord for someone to vouch for you to use this). (Can be combined with `-jN`.) -- `--better-only` only report improvements on base score (and not ties) -- `--best-only` only report improvements on current best score -- `--stack-diffs` take into account differences in placement on the stack (ignored by default) - -More information on these can be found in the permuter's own documentation. There are macros that can be added to the C to get the permuter to run particular types of transformation; these are also detailed in its manual. - -### vbindiff - -Your fallback for anything that you need to correct that is not visible in `diff.py`. Typically you use it to open the nonmatching uncompressed ROM and the uncompressed baserom and look at the differences highlighted in red. `first_diff.py` will usually tell you where to look. Controls are detailed in the program itself. - -### Texture64 - -Probably the best of the Nintendo 64 texture viewing programs. It is quite simple, but very good for the one thing that it does. - -### Z64Utils - -Basically essential for convenient analysis of object files. Can analyse and display DisplayLists, some textures, skeletons, animations, and a few other resources. Download from . - -## Retired tools - -The following tools are hopefully rendered obsolete by the data extraction that has already been done. - -### `tools/overlayhelpers/ichaindis.py` - -Used for extracting the InitChain information automatically from the ROM. - -### `tools/overlayhelpers/colliderinit.py` - -Used for decompliling the Collider struct of an actor. To use colliderinit, you will need to know the address (VRAM or VROM) of the struct, and the type of collider. There are different types of colliderinits: `ColliderJntSph, ColliderTrisInit, ColliderQuadInit, ColliderSphereInit`. - -### `tools/overlayhelpers/colchkinfoinit.py` - -Similar to `colliderinit.py` but for `CollisionCheckInfoInit`s. - -### `tools/overlayhelpers/damage_table.py` - -Extracts a damagetable from its address. Can also reconvert existing damagetables should the format change. - -### `tools/vtxdis` - -Extracts vertex data from a file. Essentially irrelevant since MM requires extracting this data with ZAPD anyway. - -### Reservation Tracking - -We use a [Google Sheet](https://docs.google.com/spreadsheets/d/1X83YCPRa532v-Zo0WgUsJ2kB1X9RxBta5_p9aWA8uro/edit#gid=0) to keep track of all the files' decompilation statuses and their function statistics. On this board one can reserve a file to work on. The columns are - -- **Actor Id**: The enum that uniquely identifies the actor for spawning etc., useful for looking in KZ/VerboseOcarina/Spectrum. For `boot`/`code`, the VRAM of the file's .text start is given instead. -- **Overlay/File name**: Name of the Overlay or File in the codebase. -- **Function size statistics**: Intended as a crude estimate of how hard a file will be. Beginners should look for small largest function size and total size; the columns give a rough estimate of the distribution of function sizes without getting unnecessarily statistically descriptive. As you become more experienced, you should work on larger files to leave the smaller ones for other beginners. -- **Description**: What the file is. It's helpful if you can fill this in if you know! They should be synchronised with the short top-of-file descriptions. -- **Status**: (Free)/Reserved/PR/Merged. To be kept up-to-date by the reserver. -- **Reserved**: To reserve a file, put your Discord name in the "Reserved" column. It is common courtesy to not work on a file that is being worked on by another contributor, so ensure the "Reserved" column is blank before working on a file. If it is not, you can ask the reserver(s) if they want to release it or collaborate on it, but don't expect them to agree. More information on what is expected when you reserve a file is available in the [CONTRIBUTING.md](CONTRIBUTING.md). -- **Interested**: If you would like to work on a file, but don't want to reserve it, or would be interested in collaboration, etc. You should talk to any Interested people if you want to work on the file. -- **Notes**: Any other useful information: partial progress by someone unable to finish the file, other files it works with, etc. diff --git a/mm/docs/tutorial/advanced_control_flow.md b/mm/docs/tutorial/advanced_control_flow.md deleted file mode 100644 index 896edcb1d..000000000 --- a/mm/docs/tutorial/advanced_control_flow.md +++ /dev/null @@ -1,749 +0,0 @@ -# Advanced control flow - -Nice as `EnRecepgirl` was, she was somewhat lacking in complexity. In this document, we'll look at something rather more complicated than any of the functions she had. - -Again our example will be taken from a small NPC: this time, `EnMs` (Bean Seller). Most of its functions are even simpler than `EnRecepgirl`'s, and fairly quickly we can get to - -
- - Large code block, click to show. - - -```C -#include "z_en_ms.h" - -#define FLAGS 0x00000009 - -#define THIS ((EnMs*)thisx) - -void EnMs_Init(Actor* thisx, PlayState* play); -void EnMs_Destroy(Actor* thisx, PlayState* play); -void EnMs_Update(Actor* thisx, PlayState* play); -void EnMs_Draw(Actor* thisx, PlayState* play); - -void func_80952734(EnMs* this, PlayState* play); -void func_809527F8(EnMs* this, PlayState* play); -void func_809529AC(EnMs* this, PlayState* play); -void func_80952A1C(EnMs* this, PlayState* play); - -ActorInit En_Ms_InitVars = { - /**/ ACTOR_EN_MS, - /**/ ACTORCAT_NPC, - /**/ FLAGS, - /**/ OBJECT_MS, - /**/ sizeof(EnMs), - /**/ EnMs_Init, - /**/ EnMs_Destroy, - /**/ EnMs_Update, - /**/ EnMs_Draw, -}; - -static ColliderCylinderInitType1 D_80952BA0 = { - { COLTYPE_NONE, AT_NONE, AC_ON | AC_TYPE_PLAYER, OC1_ON | OC1_TYPE_ALL, COLSHAPE_CYLINDER, }, - { ELEMTYPE_UNK0, { 0x00000000, 0x00, 0x00 }, { 0xF7CFFFFF, 0x00, 0x00 }, TOUCH_NONE | TOUCH_SFX_NORMAL, BUMP_ON, OCELEM_ON, }, - { 22, 37, 0, { 0, 0, 0 } }, -}; - -static InitChainEntry D_80952BCC[] = { - ICHAIN_U8(targetMode, 2, ICHAIN_CONTINUE), - ICHAIN_F32(targetArrowOffset, 500, ICHAIN_STOP), -}; - - -extern ColliderCylinderInitType1 D_80952BA0; -extern InitChainEntry D_80952BCC[]; - -extern AnimationHeader D_060005EC; -extern FlexSkeletonHeader D_06003DC0; - -void EnMs_Init(Actor* thisx, PlayState* play) { - EnMs* this = THIS; - - Actor_ProcessInitChain(thisx, D_80952BCC); - SkelAnime_InitFlex(play, &this->skelAnime, &D_06003DC0, &D_060005EC, this->jointTable, this->morphTable, 9); - Collider_InitCylinder(play, &this->collider); - Collider_SetCylinderType1(play, &this->collider, &this->actor, &D_80952BA0); - ActorShape_Init(&this->actor.shape, 0.0f, ActorShadow_DrawCircle, 35.0f); - Actor_SetScale(&this->actor, 0.015f); - this->actor.colChkInfo.mass = 0xFF; - this->actionFunc = func_80952734; - this->actor.speed = 0.0f; - this->actor.velocity.y = 0.0f; - this->actor.gravity = -1.0f; -} - -void EnMs_Destroy(Actor* thisx, PlayState* play) { - EnMs* this = THIS; - - Collider_DestroyCylinder(play, &this->collider); -} - -void func_80952734(EnMs* this, PlayState* play) { - s16 temp_v1 = this->actor.yawTowardsPlayer - this->actor.shape.rot.y; - - if (gSaveContext.save.saveInfo.inventory.items[10] == ITEM_NONE) { - this->actor.textId = 0x92E; - } else { - this->actor.textId = 0x932; - } - - if (Actor_ProcessTalkRequest(&this->actor, &play->state) != 0) { - this->actionFunc = func_809527F8; - return; - } - - if (this->actor.xzDistToPlayer < 90.0f) { - if (ABS_ALT(temp_v1) < 0x2000) { - Actor_OfferTalk(&this->actor, play, 90.0f); - } - } -} - -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Ms/func_809527F8.s") - -void func_809529AC(EnMs* this, PlayState* play) { - if (Actor_HasParent(&this->actor, play)) { - this->actor.textId = 0; - Actor_OfferTalkExchange(&this->actor, play, this->actor.xzDistToPlayer, this->actor.playerHeightRel, 0); - this->actionFunc = func_80952A1C; - } else { - Actor_OfferGetItem(&this->actor, play, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel); - } -} - -void func_80952A1C(EnMs* this, PlayState* play) { - if (Actor_ProcessTalkRequest(&this->actor, &play->state)) { - Message_ContinueTextbox(play, 0x936U); - this->actionFunc = func_809527F8; - } else { - Actor_OfferTalkExchange(&this->actor, play, this->actor.xzDistToPlayer, this->actor.playerHeightRel, -1); - } -} - -void EnMs_Update(Actor* thisx, PlayState* play) { - s32 pad; - EnMs* this = THIS; - - Actor_SetFocus(&this->actor, 20.0f); - this->actor.targetArrowOffset = 500.0f; - Actor_SetScale(&this->actor, 0.015f); - SkelAnime_Update(&this->skelAnime); - this->actionFunc(this, play); - Collider_UpdateCylinder(&this->actor, &this->collider); - CollisionCheck_SetOC(play, &play->colChkCtx, &this->collider.base); -} - -void EnMs_Draw(Actor* thisx, PlayState* play) { - EnMs* this = THIS; - - Gfx_SetupDL25_Opa(play->state.gfxCtx); - SkelAnime_DrawFlexOpa(play, this->skelAnime.skeleton, this->skelAnime.jointTable, this->skelAnime.dListCount, NULL, - NULL, &this->actor); -} - -``` - -
- -(Skipping any documentation we might have done.) Indeed, this actor is so simple so far that you can see why it wasn't worth using most of it for the rest of the tutorial. `func_809527F8` is a different story, however. We know it's an action function since it's set to the `actionFunc` in `func_80952A1C`. But mips2c gives us - -```bash -$ ../mips_to_c/mips_to_c.py asm/non_matchings/overlays/ovl_En_Ms/func_809527F8.s --context ctx.c --gotos-only -``` - -```C -void func_809527F8(EnMs* this, PlayState* play) { - u8 temp_v0; - u8 temp_v0_2; - - temp_v0 = Message_GetState(&play->msgCtx); - if (temp_v0 != 4) { - if (temp_v0 != 5) { - if ((temp_v0 == 6) && (Message_ShouldAdvance(play) != 0)) { - this->actionFunc = func_80952734; - return; - } - // Duplicate return node #17. Try simplifying control flow for better match - return; - } - if (Message_ShouldAdvance(play) != 0) { - Message_CloseTextbox(play); - Actor_OfferGetItem((Actor *) this, play, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel); - this->actionFunc = func_809529AC; - return; - } - // Duplicate return node #17. Try simplifying control flow for better match - return; - } - if (Message_ShouldAdvance(play) != 0) { - temp_v0_2 = play->msgCtx.choiceIndex; - if (temp_v0_2 != 0) { - if (temp_v0_2 != 1) { - - } - Audio_PlaySfx_MessageCancel(); - Message_ContinueTextbox(play, 0x934U); - // Duplicate return node #17. Try simplifying control flow for better match - return; - } - Message_CloseTextbox(play); - if ((s32) gSaveContext.save.saveInfo.playerData.rupees < 0xA) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x935U); - return; - } - if ((s32) gSaveContext.save.saveInfo.inventory.ammo[gItemSlots[0xA]] >= 0x14) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x937U); - return; - } - Audio_PlaySfx_MessageDecide(); - Actor_OfferGetItem((Actor *) this, play, 0x35, 90.0f, 10.0f); - Rupees_ChangeBy(-0xA); - this->actionFunc = func_809529AC; - } -} -``` - -which is long, messy, and contains some rather nasty-looking control flow, including horrors like - -```C - temp_v0 = Message_GetState(&play->msgCtx); - if (temp_v0 != 4) { - if (temp_v0 != 5) { - if ((temp_v0 == 6) && (Message_ShouldAdvance(play) != 0)) { - this->actionFunc = func_80952734; - return; - } - // Duplicate return node #17. Try simplifying control flow for better match - return; - } -``` - -If you read the OoT tutorial, you'll know these nested negated ifs all using the same variable are a good indicator that there's a switch. The problem is working out how to write it. - -## Goto-only mode - -For didactic purposes, we'll use a feature of mips2c called goto-only mode to examine this. *This is not the only way of doing it*, but it is good practice for a beginner to this sort of control flow. Running - -```bash -../mips_to_c/mips_to_c.py asm/non_matchings/overlays/ovl_En_Ms/func_809527F8.s --context ctx.c --gotos-only -``` - -instead will produce - -```C -void func_809527F8(EnMs* this, PlayState* play) { - u8 temp_v0; - u8 temp_v0_2; - - temp_v0 = Message_GetState(&play->msgCtx); - if (temp_v0 == 4) { - goto block_7; - } - if (temp_v0 == 5) { - goto block_5; - } - if (temp_v0 != 6) { - goto block_17; - } - if (Message_ShouldAdvance(play) == 0) { - goto block_17; - } - this->actionFunc = func_80952734; - return; -block_5: - if (Message_ShouldAdvance(play) == 0) { - goto block_17; - } - Message_CloseTextbox(play); - Actor_OfferGetItem((Actor *) this, play, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel); - this->actionFunc = func_809529AC; - return; -block_7: - if (Message_ShouldAdvance(play) == 0) { - goto block_17; - } - temp_v0_2 = play->msgCtx.choiceIndex; - if (temp_v0_2 == 0) { - goto block_11; - } - if (temp_v0_2 == 1) { - goto block_16; - } - goto block_16; -block_11: - Message_CloseTextbox(play); - if ((s32) gSaveContext.save.saveInfo.playerData.rupees >= 0xA) { - goto block_13; - } - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x935U); - return; -block_13: - if ((s32) gSaveContext.save.saveInfo.inventory.ammo[gItemSlots[0xA]] < 0x14) { - goto block_15; - } - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x937U); - return; -block_15: - Audio_PlaySfx_MessageDecide(); - Actor_OfferGetItem((Actor *) this, play, 0x35, 90.0f, 10.0f); - Rupees_ChangeBy(-0xA); - this->actionFunc = func_809529AC; - return; -block_16: - Audio_PlaySfx_MessageCancel(); - Message_ContinueTextbox(play, 0x934U); -block_17: - return; -} -``` - -which in many ways looks worse: you can see why the use of gotos in code is strongly discouraged. However, if you throw this in `diff.py`, you'll find it's rather closer than you'd have thought. Goto-only mode has the advantages that - -- code is always in the right order: mips2c has not had to reorder anything to get the ifs to work out -- it is often possible to get quite close with gotos, then start removing them, checking the matching status at each point. This is usually easier than trying to puzzle out the way it's trying to jump out of an `if ( || )` or similar. -- if you're trying to keep track of where you are in the code, the gotos mean that it is closer to the assembly in the first place. - -## Eliminating the gotos - -The simplest sort of block label to eliminate is one that is only used once, and where the corresponding goto jumps over a simple block of code with no extra internal control flow structure. There are two obvious examples of this here, the first being - -```C - if ((s32) gSaveContext.save.saveInfo.playerData.rupees >= 0xA) { - goto block_13; - } - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x935U); - return; -block_13: -``` - -Currently, this says to jump over the code block `Audio_PlaySfx...` if the condition in the if is satisfied. In non-goto terms, this means that the block should be run if the condition is *not* satisfied. This also illustrates a general property of goto-only mode: you have to reverse the senses of all of the ifs. Therefore the appropriate approach is to swap the if round, put the code block inside, and remove the goto and the label: - -```C - if (gSaveContext.save.saveInfo.playerData.rupees < 0xA) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x935U); - return; - } -``` - -Likewise, one can do this with `block_15`. - -If you examine appropriate part of the diff, you will usually find that such eliminations make no, or very little, difference to the compiled code. - -```C -void func_809527F8(EnMs* this, PlayState* play) { - u8 temp_v0; - u8 temp_v0_2; - - temp_v0 = Message_GetState(&play->msgCtx); - if (temp_v0 == 4) { - goto block_7; - } - if (temp_v0 == 5) { - goto block_5; - } - if (temp_v0 != 6) { - goto block_17; - } - if (Message_ShouldAdvance(play) == 0) { - goto block_17; - } - this->actionFunc = func_80952734; - return; -block_5: - if (Message_ShouldAdvance(play) == 0) { - goto block_17; - } - Message_CloseTextbox(play); - Actor_OfferGetItem((Actor *) this, play, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel); - this->actionFunc = func_809529AC; - return; -block_7: - if (Message_ShouldAdvance(play) == 0) { - goto block_17; - } - temp_v0_2 = play->msgCtx.choiceIndex; - if (temp_v0_2 == 0) { - goto block_11; - } - if (temp_v0_2 == 1) { - goto block_16; - } - goto block_16; -block_11: - Message_CloseTextbox(play); - - if (gSaveContext.save.saveInfo.playerData.rupees < 0xA) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x935U); - return; - } - if (gSaveContext.save.saveInfo.inventory.ammo[gItemSlots[0xA]] >= 0x14) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x937U); - return; - } - - Audio_PlaySfx_MessageDecide(); - Actor_OfferGetItem((Actor *) this, play, 0x35, 90.0f, 10.0f); - Rupees_ChangeBy(-0xA); - this->actionFunc = func_809529AC; - return; -block_16: - Audio_PlaySfx_MessageCancel(); - Message_ContinueTextbox(play, 0x934U); -block_17: - return; -} -``` - -We can't apply this rule any more, so we need to move on to the next: `block_17` just contains a `return`. So we can replace it by `return` everywhere it appears. - -```C -void func_809527F8(EnMs* this, PlayState* play) { - u8 temp_v0; - u8 temp_v0_2; - - temp_v0 = Message_GetState(&play->msgCtx); - if (temp_v0 == 4) { - goto block_7; - } - if (temp_v0 == 5) { - goto block_5; - } - if (temp_v0 != 6) { - return; - } - if (Message_ShouldAdvance(play) == 0) { - return; - } - this->actionFunc = func_80952734; - return; -block_5: - if (Message_ShouldAdvance(play) == 0) { - return; - } - Message_CloseTextbox(play); - Actor_OfferGetItem((Actor *) this, play, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel); - this->actionFunc = func_809529AC; - return; -block_7: - if (Message_ShouldAdvance(play) == 0) { - return; - } - temp_v0_2 = play->msgCtx.choiceIndex; - if (temp_v0_2 == 0) { - goto block_11; - } - if (temp_v0_2 == 1) { - goto block_16; - } - goto block_16; -block_11: - Message_CloseTextbox(play); - - if (gSaveContext.save.saveInfo.playerData.rupees < 0xA) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x935U); - return; - } - if (gSaveContext.save.saveInfo.inventory.ammo[gItemSlots[0xA]] >= 0x14) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x937U); - return; - } - - Audio_PlaySfx_MessageDecide(); - Actor_OfferGetItem((Actor *) this, play, 0x35, 90.0f, 10.0f); - Rupees_ChangeBy(-0xA); - this->actionFunc = func_809529AC; - return; -block_16: - Audio_PlaySfx_MessageCancel(); - Message_ContinueTextbox(play, 0x934U); -} -``` - -Our next rule is about non-crossing blocks. If two code blocks do not contain any jumps between them, we can treat them separately. This is *almost* true for the code after `block_7`, were it not for the returns; of course returns are a special case because they can be used to be escape from a function at any point. This doesn't get us very far in this case, unfortunately, but it *does* tell us we can look at the second half of the function separately. - -Now let's start thinking about switches. A good indicator of a switch in goto-only mode is something like - -```C - temp_v0_2 = play->msgCtx.choiceIndex; - if (temp_v0_2 == 0) { - goto block_11; - } - if (temp_v0_2 == 1) { - goto block_16; - } - goto block_16; -``` - -because - -- there are multiple ifs that are simple numeric comparisons of the same argument -- the goto blocks are in the same order as the ifs -- there is one last goto at the end that triggers if none of the ifs does: this sounds an awful lot like a `default`! - -So let us rewrite the entire second half as a switch: - -```C - switch (play->msgCtx.choiceIndex) { - case 0: - Message_CloseTextbox(play); - - if (gSaveContext.save.saveInfo.playerData.rupees < 0xA) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x935U); - return; - } - if (gSaveContext.save.saveInfo.inventory.ammo[gItemSlots[0xA]] >= 0x14) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x937U); - return; - } - - Audio_PlaySfx_MessageDecide(); - Actor_OfferGetItem((Actor *) this, play, 0x35, 90.0f, 10.0f); - Rupees_ChangeBy(-0xA); - this->actionFunc = func_809529AC; - return; - break; - - case 1: - default: - Audio_PlaySfx_MessageCancel(); - Message_ContinueTextbox(play, 0x934U); - break; - } -``` - -There's a couple of other obvious things here: - -- the last `return` in `case 0` is unnecessary since there is no other code after the switch, so breaking is equivalent to the return` -- a common pattern everywhere, a sequence of ifs with returns as the last thing inside is the same as an if-else chain, so we can rewrite these as - -```C - switch (play->msgCtx.choiceIndex) { - case 0: - Message_CloseTextbox(play); - - if (gSaveContext.save.saveInfo.playerData.rupees < 0xA) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x935U); - } else if (gSaveContext.save.saveInfo.inventory.ammo[gItemSlots[0xA]] >= 0x14) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x937U); - } else { - Audio_PlaySfx_MessageDecide(); - Actor_OfferGetItem((Actor *) this, play, 0x35, 90.0f, 10.0f); - Rupees_ChangeBy(-0xA); - this->actionFunc = func_809529AC; - } - break; - - case 1: - default: - Audio_PlaySfx_MessageCancel(); - Message_ContinueTextbox(play, 0x934U); - break; - } -``` - -Well, at least the bottom half looks respectable now. Again, there is no code after the switch, so the next thing up, namely - -```C - if (Message_ShouldAdvance(play) == 0) { - return; - } -``` - -can be swapped round and made to wrap the switch. This leaves us with - -```C -void func_809527F8(EnMs* this, PlayState* play) { - u8 temp_v0; - - temp_v0 = Message_GetState(&play->msgCtx); - if (temp_v0 == 4) { - goto block_7; - } - if (temp_v0 == 5) { - goto block_5; - } - if (temp_v0 != 6) { - return; - } - if (Message_ShouldAdvance(play) == 0) { - return; - } - this->actionFunc = func_80952734; - return; -block_5: - if (Message_ShouldAdvance(play) == 0) { - return; - } - Message_CloseTextbox(play); - Actor_OfferGetItem((Actor *) this, play, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel); - this->actionFunc = func_809529AC; - return; -block_7: - if (Message_ShouldAdvance(play) != 0) { - switch (play->msgCtx.choiceIndex) { - case 0: - Message_CloseTextbox(play); - - if (gSaveContext.save.saveInfo.playerData.rupees < 0xA) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x935U); - } else if (gSaveContext.save.saveInfo.inventory.ammo[gItemSlots[0xA]] >= 0x14) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x937U); - } else { - Audio_PlaySfx_MessageDecide(); - Actor_OfferGetItem((Actor *) this, play, 0x35, 90.0f, 10.0f); - Rupees_ChangeBy(-0xA); - this->actionFunc = func_809529AC; - } - break; - - case 1: - default: - Audio_PlaySfx_MessageCancel(); - Message_ContinueTextbox(play, 0x934U); - break; - } - } -} -``` - -Now, the top of the function also looks like a switch: - -```C - temp_v0 = Message_GetState(&play->msgCtx); - if (temp_v0 == 4) { - goto block_7; - } - if (temp_v0 == 5) { - goto block_5; - } - if (temp_v0 != 6) { - return; - } -``` - -Interestingly, this time the blocks are the other way round. Also, the last statement is a `!=` rather than an `==`: this should be the default this time. The code order takes priority over the check order, because the compiler likes to put those in numerical order. There will be cases 4,5,6, but in the order 6,5,4, because that's how the code ordering goes. Also, notice that every case returns at the end: this means there's nothing else in the function after this switch, so everything after `block_7` is actually part of `case 4`. - -Putting all this together, we write down a function with no gotos in it: - -```C -void func_809527F8(EnMs* this, PlayState* play) { - switch (Message_GetState(&play->msgCtx)) { - case 6: - this->actionFunc = func_80952734; - break; - - case 5: - if (Message_ShouldAdvance(play) == 0) { - return; - } - Message_CloseTextbox(play); - Actor_OfferGetItem((Actor *) this, play, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel); - this->actionFunc = func_809529AC; - break; - - case 4: - if (Message_ShouldAdvance(play) != 0) { - switch (play->msgCtx.choiceIndex) { - case 0: - Message_CloseTextbox(play); - - if (gSaveContext.save.saveInfo.playerData.rupees < 0xA) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x935U); - } else if (gSaveContext.save.saveInfo.inventory.ammo[gItemSlots[0xA]] >= 0x14) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x937U); - } else { - Audio_PlaySfx_MessageDecide(); - Actor_OfferGetItem((Actor *) this, play, 0x35, 90.0f, 10.0f); - Rupees_ChangeBy(-0xA); - this->actionFunc = func_809529AC; - } - break; - - case 1: - default: - Audio_PlaySfx_MessageCancel(); - Message_ContinueTextbox(play, 0x934U); - break; - } - } - break; - - default: - break; - } -} -``` - -Lastly, we can simplify `case 5` to replace the return in the if by the rest of the code, and we end up with - -```C -void func_809527F8(EnMs* this, PlayState* play) { - switch (Message_GetState(&play->msgCtx)) { - case 6: - this->actionFunc = func_80952734; - break; - - case 5: - if (Message_ShouldAdvance(play) != 0) { - Message_CloseTextbox(play); - Actor_OfferGetItem((Actor *) this, play, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel); - this->actionFunc = func_809529AC; - } - break; - - case 4: - if (Message_ShouldAdvance(play) != 0) { - switch (play->msgCtx.choiceIndex) { - case 0: - Message_CloseTextbox(play); - - if (gSaveContext.save.saveInfo.playerData.rupees < 0xA) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x935U); - } else if (gSaveContext.save.saveInfo.inventory.ammo[gItemSlots[0xA]] >= 0x14) { - Audio_PlaySfx(0x4806U); - Message_ContinueTextbox(play, 0x937U); - } else { - Audio_PlaySfx_MessageDecide(); - Actor_OfferGetItem((Actor *) this, play, 0x35, 90.0f, 10.0f); - Rupees_ChangeBy(-0xA); - this->actionFunc = func_809529AC; - } - break; - - case 1: - default: - Audio_PlaySfx_MessageCancel(); - Message_ContinueTextbox(play, 0x934U); - break; - } - } - break; - - default: - break; - } -} -``` - -And this matches! - -We will not document this now, although even with so few function named it seems pretty clear that it's to do with buying beans (and indeed, Magic Beans cost 10 Rupees and have Get Item ID `0x35`) You might like to try to match this function without using goto-only mode, to compare. It is also an interesting exercise to see what each elimination does to the diff: sometimes it will stray surprisingly far for a small change. diff --git a/mm/docs/tutorial/beginning_decomp.md b/mm/docs/tutorial/beginning_decomp.md deleted file mode 100644 index 8e67b91bf..000000000 --- a/mm/docs/tutorial/beginning_decomp.md +++ /dev/null @@ -1,707 +0,0 @@ -# Beginning decompilation: the Init function and the Actor struct - -- Up: [Contents](contents.md) - -Open the C file and the H file with your actor's name from the appropriate directory in `src/overlays/actors/`. These will be the main files we work with. We will be using EnRecepgirl (the rather forward Mayor's receptionist in the Mayor's residence in East Clock Town) as our example: it is a nice simple NPC with most of the common features of an NPC. - -Each actor has associated to it a data file and one assembly file per function. During the process, we will transfer the contents of all or most of these into the main C file. VSCode's search feature usually makes it quite easy to find the appropriate files without troubling the directory tree. - -## Anatomy of the C file - -The actor file starts off looking like: - -```C -// --------------- 1 --------------- -// --------------- 2 --------------- -#include "z_en_recepgirl.h" - -#define FLAGS 0x00000009 - -#define THIS ((EnRecepgirl*)thisx) - -// --------------- 3 --------------- -void EnRecepgirl_Init(Actor* thisx, PlayState* play); -void EnRecepgirl_Destroy(Actor* thisx, PlayState* play); -void EnRecepgirl_Update(Actor* thisx, PlayState* play); -void EnRecepgirl_Draw(Actor* thisx, PlayState* play); - -// --------------- 4 --------------- -#if 0 -ActorInit En_Recepgirl_InitVars = { - /**/ ACTOR_EN_RECEPGIRL, - /**/ ACTORCAT_NPC, - /**/ FLAGS, - /**/ OBJECT_BG, - /**/ sizeof(EnRecepgirl), - /**/ EnRecepgirl_Init, - /**/ EnRecepgirl_Destroy, - /**/ EnRecepgirl_Update, - /**/ EnRecepgirl_Draw, -}; - -// static InitChainEntry sInitChain[] = { -static InitChainEntry D_80C106C0[] = { - ICHAIN_U8(targetMode, 6, ICHAIN_CONTINUE), - ICHAIN_F32(targetArrowOffset, 1000, ICHAIN_STOP), -}; - -#endif - -// --------------- 5 --------------- -extern InitChainEntry D_80C106C0[]; - -extern UNK_TYPE D_06001384; -extern UNK_TYPE D_06009890; -extern UNK_TYPE D_0600A280; - -// --------------- 6 --------------- -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Init.s") - -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Destroy.s") - -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C100DC.s") - -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10148.s") - -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C1019C.s") - -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10290.s") - -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C102D4.s") - -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Update.s") - -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10558.s") - -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10590.s") - -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Draw.s") - -``` - -It is currently divided into six sections as follows: - -1. Description of the actor. This is not present for all actors, (and indeed, is not present here) but gives a short description based on what we know about the actor already. It may be inaccurate, so feel free to correct it after you understand the actor better, or add it. It currently has the form - -```C -/* - * File: z_en_recepgirl.c - * Overlay: ovl_En_Recepgirl - * Description: Mayor's receptionist - */ -``` - -2. Specific `include`s and `define`s for the actor. You may need to add more header files, but otherwise this section is unlikely to change. - -3. These are prototypes for the "main four" functions that almost every actor has. You add more functions here if they need to be declared above their first use. - -4. `if`'d-out section containing the `InitVars` and a few other common pieces of data. This can be ignored until we import the data. - -5. A set of `extern`s. These refer to the data in the previous section, and, data that comes from other files, usually in the actor's corresponding object file. The latter point to addresses in the ROM where assets are stored (usually collision data, animations or display lists). These can simply be replaced by including the object file (see [Object Decompilation](object_decomp.md) for how this process works). - -6. List of functions. Each `#pragma GLOBAL_ASM` is letting the compiler use the corresponding assembly file while we do not have decompiled C code for that function. The majority of the decompilation work is converting these functions into C that it looks like a human wrote. - -## Header file - -The header file looks like this at the moment: - -```C -#ifndef Z_EN_RECEPGIRL_H -#define Z_EN_RECEPGIRL_H - -#include "global.h" - -struct EnRecepgirl; - -typedef void (*EnRecepgirlActionFunc)(struct EnRecepgirl*, PlayState*); - -typedef struct EnRecepgirl { - /* 0x0000 */ Actor actor; - /* 0x0144 */ char unk_144[0x164]; - /* 0x02A8 */ EnRecepgirlActionFunc actionFunc; - /* 0x02AC */ char unk_2AC[0x8]; -} EnRecepgirl; // size = 0x2B4 - -#endif // Z_EN_RECEPGIRL_H -``` - -The struct currently contains a variable that is the `Actor` struct, which all actors use one way or another, plus other items. Currently we don't know what most of those items are, so we have arrays of chars as padding instead, just so the struct is the right size. As we understand the actor better, we will be able to gradually replace this padding with the actual variables that the actor uses. - -The header file is also used to declare structs and other information about the actor that is needed by other files (e.g. by other actors): one can simply `#include` the header rather than `extern`ing it. - -## Order of decompilation - -The general rule for order of decompilation is - -- Start with `Init`, because it usually contains the most information about the structure of the actor. You can also do `Destroy`, which is generally simpler than `Init`. -- Next, decompile any other functions from the actor you have found in `Init`. You generally start with the action functions, because they return nothing and all take the same arguments, - -```C -void func_80whatever(EnRecepgirl* this, PlayState* play); -``` - -- Decompile each action function in turn until you run out. Along the way, do any other functions in the actor for which you have discovered the argument types. (You are probably better doing depth-first on action functions than breadth-first: it's normally easier to follow along one branch of the actions than be thinking about several at once.) - -- After you've run out, do `Update`. This usually provides the rest of the function tree, apart from possibly some draw functions. - -- Finally, do the draw functions. - -The above is a rough ordering for the beginner. As you become more experienced, you can deviate from this scheme, but the general principle remains that you should work on functions that you already know something about. (This is why it's good to start on actors: they are self-contained, we already know a lot about some of the functions, and the function flow tends to be both logical and provide information about every function.) - -## Data - -![Fresh actor data](images/fresh_actor_data.png) - -Associated to each actor is a `.data` file, containing data that the actor uses. This ranges from spawn positions, to animation information, to even assets that we have to extract from the ROM. Since the structure of the data is very inconsistent between actors, automatic importing has been very limited, so the vast majority must be done manually. - -There are two ways of transfering the data into an actor: we can either - -- import it all naively as words (`s32`s), which will still allow it to compile, and sort out the actual types later, or -- we can extern each piece of data as we come across it, and come back to it later when we have a better idea of what it is. - -We will concentrate on the second here; the other is covered in [the document about data](data.md). Thankfully this means we essentially don't have to do anything to the data yet. Nevertheless, it is often quite helpful to copy over at least some of the data and leave it commented out for later replacement. *Data must go in the same order as in the data file, and data is "all or nothing": you cannot only import some of it*. - -**WARNING** The way in which the data was extracted from the ROM means that there are sometimes "fake symbols" in the data, which have to be removed to avoid confusing the compiler. Thankfully it will turn out that this is not the case here. - -(Sometimes it is useful to import the data in the middle of doing functions: you just have to choose an appropriate moment.) - -Some actors also have a `.bss` file. This is just data that is initialised to 0, and can be imported immediately once you know what type it is, by declaring it without giving it a value. (bss is a significant problem for code files, but not *usually* for actors.) - -## Init - -The Init function sets up the various components of the actor when it is first loaded. It is hence usually very useful for finding out what is in the actor struct, and so we usually start with it. (Some people like starting with Destroy, which is usually shorter and simpler, but gives some basic information about the actor, but Init is probably best for beginners.) - -### mips2c - -The first stage of decompilation is done by a program called mips_to_c, often referred to as mips2c, which constructs a C interpretation of the assembly code based on reading it very literally. This means that considerable cleanup will be required to turn it into something that firstly compiles at all, and secondly looks like a human wrote it, let alone a Zelda developer from the late '90s. - -The web version of mips2c can be found [here](https://simonsoftware.se/other/mips_to_c.py). This was [covered in the OoT tutorial](https://github.com/zeldaret/oot/blob/main/docs/tutorial/beginning_decomp.md). We shall instead use the repository. Clone [the mips_to_c repository](https://github.com/matt-kempster/mips_to_c) into a separate directory (we will assume on the same level as the `mm/` directory). Since it's Python, we don't have to do any compilation or anything in the mips_to_c directory. - -Since the actor depends on the rest of the codebase, we can't expect to get much intelligible out of mips2c without giving it some context. We make this using a Python script in the `tools` directory called `m2ctx.py`, so run - -``` -$ ./tools/m2ctx.py -``` - -from the main directory of the repository. In this case, the C file is `src/overlays/actors/ovl_En_Recepgirl/z_en_recepgirl.c`. This generates a file called `ctx.c` in the main directory of the repository. - -To get mips_to_c to decompile a function, the bare minimum is to run - -``` -$ ../mips_to_c/mips_to_c.py -``` - -(from the root directory of `mm`). We can tell mips2c to use the context file we just generated by adding `--context ctx.c`. If we have data, mips2c may be able to assist with that as well. - -In this case, we want the assembly file for `EnRecepgirl_Init`. You can copy the path to the file in VSCode or similar, or just tab-complete it once you know the directory structure well enough: it turns out to be `asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Init.s`. - -**N.B.** You want the file in `nonmatchings`! the files in the other directories in `asm/` are the *unsplit* asm, which can be used, but is less convenient (you would need to include the rodata, for example, and it will do the whole file at once. This is sometimes useful, but we'll go one function at a time today to keep things simple). - -We shall also include the data file, which is located at `data/overlays/ovl_En_Recepgirl/ovl_En_Recepgirl.data.s`. Hence the whole command will be - -``` -$ ../mips_to_c/mips_to_c.py asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Init.s data/ovl_En_Recepgirl/ovl_En_Recepgirl.data.s --context ctx.c -? func_80C10148(EnRecepgirl *); // extern -extern FlexSkeletonHeader D_06011B60; -static void *D_80C106B0[4] = {(void *)0x600F8F0, (void *)0x600FCF0, (void *)0x60100F0, (void *)0x600FCF0}; -static s32 D_80C106C8 = 0; -InitChainEntry D_80C106C0[2]; // unable to generate initializer - -void EnRecepgirl_Init(EnRecepgirl* this, PlayState* play) { - EnRecepgirl* this = (EnRecepgirl *) thisx; - void **temp_s0; - void **phi_s0; - - Actor_ProcessInitChain((Actor *) this, D_80C106C0); - ActorShape_Init(&this->actor.shape, -60.0f, NULL, 0.0f); - SkelAnime_InitFlex(play, (SkelAnime *) this->unk_144, &D_06011B60, (AnimationHeader *) &D_06009890, this + 0x188, this + 0x218, 0x18); - phi_s0 = D_80C106B0; - if (D_80C106C8 == 0) { - do { - temp_s0 = phi_s0 + 4; - temp_s0->unk-4 = Lib_SegmentedToVirtual(*phi_s0); - phi_s0 = temp_s0; - } while (temp_s0 != D_80C106C0); - D_80C106C8 = 1; - } - this->unk_2AC = 2; - if (Flags_GetSwitch(play, (s32) this->actor.params) != 0) { - this->actor.textId = 0x2ADC; - } else { - this->actor.textId = 0x2AD9; - } - func_80C10148(this); -} -``` - -Comment out the `GLOBAL_ASM` line for `Init`, and paste all of this into the file just underneath it: - -```C -[...] -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Init.s") -? func_80C10148(EnRecepgirl *); // extern -extern FlexSkeletonHeader D_06011B60; -static void *D_80C106B0[4] = {(void *)0x600F8F0, (void *)0x600FCF0, (void *)0x60100F0, (void *)0x600FCF0}; -static s32 D_80C106C8 = 0; -InitChainEntry D_80C106C0[2]; // unable to generate initializer - -void EnRecepgirl_Init(Actor* thisx, PlayState* play) { - EnRecepgirl* this = (EnRecepgirl *) thisx; - void **temp_s0; - void **phi_s0; - - Actor_ProcessInitChain((Actor *) this, D_80C106C0); - ActorShape_Init(&this->actor.shape, -60.0f, NULL, 0.0f); - SkelAnime_InitFlex(play, (SkelAnime *) this->unk_144, &D_06011B60, (AnimationHeader *) &D_06009890, this + 0x188, this + 0x218, 0x18); - phi_s0 = D_80C106B0; - if (D_80C106C8 == 0) { - do { - temp_s0 = phi_s0 + 4; - temp_s0->unk-4 = Lib_SegmentedToVirtual(*phi_s0); - phi_s0 = temp_s0; - } while (temp_s0 != D_80C106C0); - D_80C106C8 = 1; - } - this->unk_2AC = 2; - if (Flags_GetSwitch(play, (s32) this->actor.params) != 0) { - this->actor.textId = 0x2ADC; - } else { - this->actor.textId = 0x2AD9; - } - func_80C10148(this); -} -[...] -``` - - - -Typically for all but the simplest functions, there is a lot that needs fixing before we are anywhere near seeing how close we are to the original code. You will notice that mips2c creates a lot of temporary variables. Usually most of these will turn out to not be real, and we need to remove the right ones to get the code to match. - -To allow the function to find the variables, we need another correction. Half of this has already been done at the top of the file, where we have - -```C -#define THIS ((EnRecepgirl*)thisx) -``` - -To do the other half, replace the recast at the beginning of the function, before any declarations: - -```C -EnRecepgirl* this = THIS; -``` - -Now everything points to the right place, even though the argument of the function seems inconsistent with the contents. - -(Again: this step is only necessary for the "main four" functions, and sometimes functions that are used by these: it relates to how such functions are used outside the actor.) - -While we are carrying out initial changes, you can also find-and-replace any instances of `(Actor *) this` by `&this->actor`. The function now looks like this: - -```C -? func_80C10148(EnRecepgirl *); // extern -extern FlexSkeletonHeader D_06011B60; -static void *D_80C106B0[4] = {(void *)0x600F8F0, (void *)0x600FCF0, (void *)0x60100F0, (void *)0x600FCF0}; -static s32 D_80C106C8 = 0; -InitChainEntry D_80C106C0[2]; // unable to generate initializer - -void EnRecepgirl_Init(Actor* thisx, PlayState* play) { - EnRecepgirl* this = THIS; - void **temp_s0; - void **phi_s0; - - Actor_ProcessInitChain(&this->actor, D_80C106C0); - ActorShape_Init(&this->actor.shape, -60.0f, NULL, 0.0f); - SkelAnime_InitFlex(play, (SkelAnime *) this->unk_144, &D_06011B60, (AnimationHeader *) &D_06009890, this + 0x188, this + 0x218, 0x18); - phi_s0 = D_80C106B0; - if (D_80C106C8 == 0) { - do { - temp_s0 = phi_s0 + 4; - temp_s0->unk-4 = Lib_SegmentedToVirtual(*phi_s0); - phi_s0 = temp_s0; - } while (temp_s0 != D_80C106C0); - D_80C106C8 = 1; - } - this->unk_2AC = 2; - if (Flags_GetSwitch(play, (s32) this->actor.params) != 0) { - this->actor.textId = 0x2ADC; - } else { - this->actor.textId = 0x2AD9; - } - func_80C10148(this); -} -``` - -### (Not) dealing with Data - -For now, we do not want to consider the data that mips2c has kindly imported for us: it will only get in the way when we want to rebuild the file to check for OK (`diff.py` will not care, but `make` will complain if it notices a symbol defined twice, and if some data is included twice the ROM will not match anyway). Therefore, put it in the `#if`'d out section and add some externs with the types: - -```C -#if 0 -ActorInit En_Recepgirl_InitVars = { - /**/ ACTOR_EN_RECEPGIRL, - /**/ ACTORCAT_NPC, - /**/ FLAGS, - /**/ OBJECT_BG, - /**/ sizeof(EnRecepgirl), - /**/ EnRecepgirl_Init, - /**/ EnRecepgirl_Destroy, - /**/ EnRecepgirl_Update, - /**/ EnRecepgirl_Draw, -}; - -static void* D_80C106B0[4] = { (void*)0x600F8F0, (void*)0x600FCF0, (void*)0x60100F0, (void*)0x600FCF0 }; - -// static InitChainEntry sInitChain[] = { -static InitChainEntry D_80C106C0[] = { - ICHAIN_U8(targetMode, 6, ICHAIN_CONTINUE), - ICHAIN_F32(targetArrowOffset, 1000, ICHAIN_STOP), -}; - -static s32 D_80C106C8 = 0; - -#endif - -extern void* D_80C106B0[]; -extern InitChainEntry D_80C106C0[]; -extern s32 D_80C106C8; -``` - -**N.B.** As is covered in more detail in [the document about data](data.md), the data *must* be declared in the same order in C as it was in the data assembly file: notice that the order in this example is `En_Recepgirl_InitVars`, `D_80C106B0`, `D_80C106C0`, `D_80C106C8`, the same as in `data/ovl_En_Recepgirl/ovl_En_Recepgirl.data.s`. - -In the next sections, we shall sort out the various initialisation functions that occur in Init. This actor contains several of the most common ones, but it does not have, for example, a collider. The process is similar to what we discuss below, or you can check the OoT tutorial. - - - -### Init chains - -Almost always, one of the first items in `Init` is a function that looks like - -```C -Actor_ProcessInitChain(&this->actor, D_80C106C0); -``` - -which initialises common properties of actor using an InitChain, which is usually somewhere near the top of the data, in this case in the variable `D_80C106C0`. This is already included in the `#if`'d out data at the top if the file, so we don't have to do anything for now. We can correct the mips2c output for the extern, though: I actually did this when moving the rest of the data in the previous section. - -### SkelAnime - -This is the combined system that handles actors' skeletons and their animations. It is the other significant part of most actor structs. We see its initialisation in this part of the code: - -```C - Actor_ProcessInitChain(&this->actor, D_80C106C0); - ActorShape_Init(&this->actor.shape, -60.0f, NULL, 0.0f); - SkelAnime_InitFlex(play, (SkelAnime *) this->unk_144, &D_06011B60, (AnimationHeader *) &D_06009890, this + 0x188, this + 0x218, 0x18); - phi_s0 = D_80C106B0; -``` - -An actor with SkelAnime has three structs in the Actor struct that handle it: one called SkelAnime, and two arrays of `Vec3s`, called `jointTable` and `morphTable`. Usually, although not always, they are next to one another. - -There are two different sorts of SkelAnime, although for decompilation purposes there is not much difference between them. Looking at the prototype of `SkelAnime_InitFlex` from `functions.h` (or even the definition in `z_skelanime.c`), - -```C -void SkelAnime_InitFlex(PlayState* play, SkelAnime* skelAnime, FlexSkeletonHeader* skeletonHeaderSeg, - AnimationHeader* animation, Vec3s* jointTable, Vec3s* morphTable, s32 limbCount); -``` - -we can read off the types of the various arguments: - -- The `SkelAnime` struct is at `this + 0x144` -- The `jointTable` is at `this + 0x188` -- The `morphTable` is at `this + 0x218` -- The number of limbs is `0x18 = 24` (we use dec for the number of limbs) -- Because of how SkelAnime works, this means that the `jointTable` and `morphTable` both have `24` elements - -Looking in `z64animation.h`, we find that `SkelAnime` has size `0x44`, and looking in `z64math.h`, that `Vec3s` has size `0x6`. Since ` 0x144 + 0x44 = 0x188 `, `jointTable` is immediately after the `SkelAnime`, and since `0x188 + 0x6 * 0x18 = 0x218`, `morphTable` is immediately after the `jointTable`. Finally, `0x218 + 0x6 * 0x18 = 0x2A8`, and we have filled all the space between the `actor` and `actionFunc`. Therefore the struct now looks like - -```C -typedef struct EnRecepgirl { - /* 0x0000 */ Actor actor; - /* 0x0144 */ SkelAnime skelAnime; - /* 0x0188 */ Vec3s jointTable[24]; - /* 0x0218 */ Vec3s morphTable[24]; - /* 0x02A8 */ EnRecepgirlActionFunc actionFunc; - /* 0x02AC */ char unk_2AC[0x8]; -} EnRecepgirl; // size = 0x2B4 -``` - -The last information we get from the SkelAnime function is the types of two of the externed symbols: `D_06011B60` is a `FlexSkeletonHeader`, and `D_06009890` is an `AnimationHeader`. So we can change/add these at the top of the C file: - -```C -extern InitChainEntry D_80C106C0[]; - -extern UNK_TYPE D_06001384; -extern AnimationHeader D_06009890; -extern UNK_TYPE D_0600A280; -extern FlexSkeletonHeader D_06011B60; -``` - -As with the data, these externed symbols should be kept in increasing address order. - -They are both passed to the function as pointers, so need `&` to pass the address instead of the actual data. Hence we end up with - -```C - SkelAnime_InitFlex(play, &this->skelAnime, &D_06011B60, &D_06009890, this->jointTable, this->morphTable, 24); -``` - -note that `this->jointTable` and `this->morphTable` are arrays, so are already effectively pointers and don't need a `&`. - -### More struct variables: a brief detour into reading some assembly - -This function also gives us information about other things in the struct. The only other reference to `this` (rather than `this->actor` or similar) is in - -```C -this->unk_2AC = 2; -``` - -This doesn't tell us much except that at `this + 0x2AC` is a number of some kind. What sort of number? For that we will have to look in the assembly code. This will probably look quite intimidating the first time, but it's usually not too bad if you use functions as signposts: IDO will never change the order of function calls, and tends to keep code between functions in roughly the same place, so you can usually guess where you are. - -In this case, we are looking for `this + 0x2AC`. `0x2AC` is not a very common number, so hopefully the only mention of it is in referring to this struct variable. Indeed, if we search the file, we find that the only instruction mentioning `0x2AC` is here: - -```mips -/* 0000B0 80C10080 24090002 */ addiu $t1, $zero, 2 -/* 0000B4 80C10084 A24902AC */ sb $t1, 0x2ac($s2) -``` - -`addiu` ("add unsigned immediate") adds the last two things and puts the result in the register in the first position. So this says `$t1 = 0 + 2`. The next instruction, `sb` ("store byte") puts the value in the register in the first position in the memory location in the second, which in this case says `$s2 + 0x2ac = $t1`. We can go and find out what is in `$s2` is: it is set *all* the way at the top of the function, in this line: - -```mips -/* 000008 80C0FFD8 00809025 */ move $s2, $a0 -``` - -This simply copies the contents of the second register into the first one. In this case, it is copying the contents of the function's first argument into `$s2` (because it wants to use it later, and the `$a` registers are assumed to be cleared after a function call). In this case, the first argument is a pointer to `this` (well, `thisx`, but the struct starts with an `Actor`, so it's the same address). So line `B4` of the asm really is saving `2` into the memory location `this + 0x2AC`. - -Anyway, this tells us that the variable is a byte of some kind, so `s8` or `u8`: if it was an `s16/u16` it would have said `sh`, and if it was an `s32/u32` it would have said `sw`. Unfortunately this is all we can determine from this function: MIPS does not have separate instructions for saving signed and unsigned bytes. - -At this point you have two options: guess based on statistics/heuristics, or go and look in the other functions in the actor to find out more information. The useful statistic here is that `u8` is far more common than `s8`, but let's look in the other functions, since we're pretty confident after finding `0x2ac` so easily in `Init`. So, let us grep the actor's assembly folder: - -``` -$ grep -r '0x2ac' asm/non_matchings/overlays/ovl_En_Recepgirl/ -asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Draw.s:/* 00065C 80C1062C 921902AC */ lbu $t9, 0x2ac($s0) -asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C100DC.s:/* 000114 80C100E4 908202AC */ lbu $v0, 0x2ac($a0) -asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C100DC.s:/* 00012C 80C100FC A08E02AC */ sb $t6, 0x2ac($a0) -asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C100DC.s:/* 000134 80C10104 A08002AC */ sb $zero, 0x2ac($a0) -asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C100DC.s:/* 00015C 80C1012C 909802AC */ lbu $t8, 0x2ac($a0) -asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C100DC.s:/* 000164 80C10134 A09902AC */ sb $t9, 0x2ac($a0) -asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Init.s:/* 0000B4 80C10084 A24902AC */ sb $t1, 0x2ac($s2) -``` - -in which we clearly see `lbu` ("load byte unsigned"), and hence this variable really is a `u8`. Hence we can add this to the actor struct too: - -```C -typedef struct EnRecepgirl { - /* 0x0000 */ Actor actor; - /* 0x0144 */ SkelAnime skelAnime; - /* 0x0188 */ Vec3s jointTable[24]; - /* 0x0218 */ Vec3s morphTable[24]; - /* 0x02A8 */ EnRecepgirlActionFunc actionFunc; - /* 0x02AC */ u8 unk_2AC; - /* 0x02AD */ char unk_2AD[0x7]; -} EnRecepgirl; // size = 0x2B4 -``` - -You might think that was a lot of work for one variable, but it's pretty quick when you know what to do. Obviously this would be more difficult with a more common number, but it's often still worth trying. - -Removing some of the declarations for data that we have accounted for, the function now looks like this: - -```C -? func_80C10148(EnRecepgirl *); // extern - -void EnRecepgirl_Init(Actor* thisx, PlayState* play) { - EnRecepgirl* this = THIS; - void **temp_s0; - void **phi_s0; - - Actor_ProcessInitChain(&this->actor, D_80C106C0); - ActorShape_Init(&this->actor.shape, -60.0f, NULL, 0.0f); - SkelAnime_InitFlex(play, &this->skelAnime, &D_06011B60, &D_06009890, this->jointTable, this->morphTable, 24); - - phi_s0 = D_80C106B0; - if (D_80C106C8 == 0) { - do { - temp_s0 = phi_s0 + 4; - temp_s0->unk-4 = Lib_SegmentedToVirtual(*phi_s0); - phi_s0 = temp_s0; - } while (temp_s0 != D_80C106C0); - D_80C106C8 = 1; - } - - this->unk_2AC = 2; - if (Flags_GetSwitch(play, (s32) this->actor.params) != 0) { - this->actor.textId = 0x2ADC; - } else { - this->actor.textId = 0x2AD9; - } - func_80C10148(this); -} -``` - -We have one significant problem and a few minor ones left. - -### Casts and boolean functions - -mips2c likes casting a lot: this is useful for getting types, less so when the type is changed automatically, such as in `Flags_GetSwitch(play, (s32) this->actor.params)`. Also, if we look at this function's definition, we discover it will only return `true` or `false`, so we can remove the `!= 0`. - -### Functions called - -One minor problem is what `func_80C10148` is: C needs a prototype to compile it properly. mips2c has offered us `? func_80C10148(EnRecepgirl *); // extern`, but this is obviously incomplete: there's no `?` type in C! We shall guess for now that this function returns `void`, for two reasons: - -1. It's not used as a condition in a conditional or anything -2. It's not used to assign a value - -To this experience will add a third reason: -3. This is probably a setup function for an actionFunc, which are usually either `void (*)(ActorType*)` or `void (*)(ActorType*, PlayState*)`. - -The upshot of all this is to remove mips2c's `? func_80C10148(EnRecepgirl *); // extern`, and add a `void func_80C10148(EnRecepgirl* this);` underneath the declarations for the main four functions: - -```C -void EnRecepgirl_Init(Actor* thisx, PlayState* play); -void EnRecepgirl_Destroy(Actor* thisx, PlayState* play); -void EnRecepgirl_Update(Actor* thisx, PlayState* play); -void EnRecepgirl_Draw(Actor* thisx, PlayState* play); - -void func_80C10148(EnRecepgirl* this); -``` - -(we usually leave a blank line after the main four, and put all further declarations in address order). - -### Loops - -Loops are often some of the hardest things to decompile, because there are many ways to write a loop, only some of which will generate the same assembly. mips2c has had a go at the one in this function, but it usually struggles with loops: don't expect it to get a loop correct, well, at all. - -The code in question is - -```C - void **temp_s0; - void **phi_s0; - -[...] - - phi_s0 = D_80C106B0; - if (D_80C106C8 == 0) { - do { - temp_s0 = phi_s0 + 4; - temp_s0->unk-4 = Lib_SegmentedToVirtual(*phi_s0); - phi_s0 = temp_s0; - } while (temp_s0 != D_80C106C0); - D_80C106C8 = 1; - } -``` - -`D_80C106B0` is the array that mips2c has declared above the function, a set of 8-digit hex numbers starting `0x06`. These are likely to be *segmented pointers*, but this is not a very useful piece of information yet. `D_80C106C0` is the InitChain, though, and it seems pretty unlikely that it would be seriously involved in any sort of loop. Indeed, if you tried to compile this now, you would get an error: - -``` -cfe: Error: src/overlays/actors/ovl_En_Recepgirl/z_en_recepgirl.c, line 61: Unacceptable operand of == or != - } while (temp_s0 != D_80C106C0); - -------------------------^ -``` - -so this can't possibly be right. - -So what on earth is this loop doing? Probably the best thing to do is manually unroll it and see what it's doing each time. - -1. `phi_s0 = D_80C106B0`, aka `&D_80C106B0[0]`, to `temp_s0 = D_80C106B0 + 4`, i.e. `&D_80C106B0[1]`. But then `temp_s0->unk-4` is 4 backwards from `&D_80C106B0[1]`, which is back at `&D_80C106B0[0]`; the `->` means to look at what is at this address, so `temp_s0->unk-4` is `D_80C106B0[0]`. Equally, `*phi_s0` is the thing at `&D_80C106B0[0]`, i.e. `D_80C106B0[0]`. So the actual thing the first pass does is - -```C - D_80C106B0[0] = Lib_SegmentedToVirtual(D_80C106B0[0]); -``` - -it then proceeds to set `phi_s0 = &D_80C106B0[1]` for the next iteration. - -2. We go through the same reasoning and find the inside of the loop is - -```C - temp_s0 = &D_80C106B0[2]; - D_80C106B0[1] = Lib_SegmentedToVirtual(D_80C106B0[1]); - phi_s0 = &D_80C106B0[2]; -``` - -3. - -```C - temp_s0 = &D_80C106B0[3]; - D_80C106B0[2] = Lib_SegmentedToVirtual(D_80C106B0[2]); - phi_s0 = &D_80C106B0[3]; -``` - -4. - -```C - temp_s0 = &D_80C106B0[4]; - D_80C106B0[3] = Lib_SegmentedToVirtual(D_80C106B0[3]); - phi_s0 = &D_80C106B0[4]; -``` - -But now, `&D_80C106B0[4] = D_80C106B0 + 4 * 4 = D_80C106B0 + 0x10`, and `0x10` after this array's starting address is `D_80C106C0`, i.e. the InitChhain. Hence at this point the looping ends. - -So what this loop actually does is run `Lib_SegmentedToVirtual` on each element of the array `D_80C106B0`. - -At this point, I confess that I guessed what this loop does, and rewrote it how I would have written it, namely how one usually iterates over an array: - -```C - s32 i; -[...] - for (i = 0; i < 4; i++) { - D_80C106B0[i] = Lib_SegmentedToVirtual(D_80C106B0[i]); - } -``` - -This is a dangerous game, since there is no guarantee that what you think is the right way to write something bears any relation to either what the original was like, or more importantly, what will give the same codegen as the original. This is a significant leap, since the original appears to be using a pointer iterator! - -However, this is certainly at least equivalent to the original (or at least, to what mips2c gave us: it's not infallible): we can be certain of this because we wrote the thing out in its entirety to understand it! This also allows us to eliminate one of the temps: you'll find with even simple loops mips2c will usually make two temps for the loop variable. - -Hence we end up with - -```C -void func_80C10148(EnRecepgirl* this); -[...] - -void EnRecepgirl_Init(Actor* thisx, PlayState* play) { - EnRecepgirl* this = THIS; - - Actor_ProcessInitChain(&this->actor, D_80C106C0); - ActorShape_Init(&this->actor.shape, -60.0f, NULL, 0.0f); - SkelAnime_InitFlex(play, &this->skelAnime, &D_06011B60, &D_06009890, this->jointTable, this->morphTable, 24); - - if (D_80C106C8 == 0) { - for (i = 0; i < 4; i++) { - D_80C106B0[i] = Lib_SegmentedToVirtual(D_80C106B0[i]); - } - D_80C106C8 = 1; - } - - this->unk_2AC = 2; - - if (Flags_GetSwitch(play, this->actor.params)) { - this->actor.textId = 0x2ADC; - } else { - this->actor.textId = 0x2AD9; - } - - func_80C10148(this); -} -``` - -as our first guess. This doesn't look unreasonable... the question is, does it match? - -## Diff - -Once preliminary cleanup and struct filling is done, most time spent matching functions is done by comparing the original code with the code you have compiled. This is aided by a program called `diff.py`. - -In order to use `diff.py` with the symbol names, we need a copy of the code to compare against. In MM this is done as part of `make init`, and you can regenerate the `expected` directory (which is simply a known-good copy of `build` directory) by running `make diff-init`, which will check for an OK ROM and copy the build directory over. (Of course you need an OK ROM to do this; worst-case, you can checkout main and do a complete rebuild to get it). (You need to remake `expected` if you want to diff a function you have renamed: `diff.py` looks in the mapfiles for the function name, which won't work if the name has changed!) - -Now, we run diff on the function name: in the main directory, - -``` -$ ./diff.py -mwo3 EnRecepgirl_Init -``` - -(To see what these arguments do, run it with `./diff.py -h` or look in the scripts documentation.) - -![FeelsOKMan completely white diff](images/EnRecepgirl_Init_diff_matching.png) - -And err, well, everything is white, so it matches. Whoops. Guess we'll cover `diff.py` properly next time! (Notice that even though the diff is completely white, there are some differences in the `%hi`s and `%lo`s that access data, because it is now accessed with a relative address rather than an absolute one. If you have the data in the file in the right order, this shouldn't matter.) - -And with that, we have successfully matched our first function. - -**N.B** Notice that we don't yet have much idea of what this code actually does: this should be clarified by going through the rest of the actor's functions, which is discussed in the next document. - -Next: [Other functions in the actor](other_functions.md) diff --git a/mm/docs/tutorial/contents.md b/mm/docs/tutorial/contents.md deleted file mode 100644 index bb703f5c7..000000000 --- a/mm/docs/tutorial/contents.md +++ /dev/null @@ -1,63 +0,0 @@ -# Getting started - -## [Introduction to decomp](introduction.md) - -- What we are doing -- Structure of the code - -## Pre-decompilation - -- [Introduction to git](intro_to_git.md) -- Building the repo (follow the instructions in the [README.md](../../README.md)) -- Most of us use VSCode. Some useful information is [here](vscode.md). - -- Choosing a first actor (You want something small that has simple interactions with the environment. A simple NPC can also work, and is what we will use as an illustration for most of the tutorial. There is a collection of actors we think are suitable for beginners on the spreadsheet or Trello) - -## Decompilation - -- [Begining decompilation: order, Init and the actor struct](beginning_decomp.md) - - Order of decompilation - - Init and common actor features - - Initchains - - Actors and dynapoly actors - - Colliders - - Skelanime - -- [The rest of the functions in the actor](other_functions.md) - - Order of decompilation - - Action Functions and other functions - -- [Draw functions](draw_functions.md) - -- [Data, migration and non-migration](data.md) - - Importing the data: early and late - - Segmented pointers - - Fake symbols - - Inlining - -- [Documenting a decompiled file](documenting.md) - -## [Object Decompilation](object_decomp.md) - -- Object files -- How we decompile objects - -## After Decompilation - -- See the [CONTRIBUTING.md](../CONTRIBUTING.md) for most of the details for submitting PRs. Remember to format again after making adjustments from reviews! -- More information about specific preparations is in [this document](merging.md). - -## Appendices - -- [Types, Structs and Padding](types_structs_padding.md) (a miscellany of useful stuff) -- [Advanced control flow](advanced_control_flow.md) (an example of a more complex function which mips2c is not so good at) -- [Using the diff script and the permuter](diff_and_permuter.md) (using the diff script and the permuter to match something) - - control flow (branches) -> instruction ordering -> register allocation -> stack -- [Helper scripts] TODO: link when merged - -To be written, maybe - -- How we use git and GitHub -- Some notes on the basic structure of N64 MIPS -- Glossary -- Conventions diff --git a/mm/docs/tutorial/data.md b/mm/docs/tutorial/data.md deleted file mode 100644 index 2c3f1d2e2..000000000 --- a/mm/docs/tutorial/data.md +++ /dev/null @@ -1,177 +0,0 @@ -# Data - -- Up: [Contents](contents.md) -- Previous: [Draw functions](draw_functions.md) - -## Table of Contents - -- [Data](#data) - - [Table of Contents](#table-of-contents) - - [Data first](#data-first) - - [Extern and data last](#extern-and-data-last) - - [Segmented pointers and object symbols](#segmented-pointers-and-object-symbols) - - [Fake symbols](#fake-symbols) - - [Inlining](#inlining) -- [Finally: .bss](#finally-bss) - -Each actor's data is stored in a separate file. EnRecepgirl's data is in `data/overlays/ovl_En_Recepgirl/ovl_En_Recepgirl.data.s`, for example. At some point in the decompilation process we need to convert this raw data into recognisable information for the C to use. - -There are two main ways to do this: either - -1. import the data first and type it later, or -2. wait until the data appears in functions, extern it, then import it at the end - -Sometimes something between these two is appropriate: wait until the largest or strangest bits of data appear in functions, get some typing information out of that, and then import it, but for now, let's stick to both of these. - -Both approaches have their advantages and disadvantages. - -## Data first - -This way is good for smaller actors with little data. The OoT tutorial [covers this in plenty of detail](https://github.com/zeldaret/oot/blob/main/docs/tutorial/data.md), and the process in MM is essentially identical, so we won't go over it here. - -## Extern and data last - -Externing is explained in detail in the document about the [Init function](beginning_decomp.md). To summarize, every time a `D_address` appears that is in the data file, we put a - -```C -extern UNK_TYPE D_address; -``` - -at the top of the file, in the same order that the data appears in the data file. We can also give it a type if we know what the type actually is (e.g. for colliders, initchains, etc.), and convert the actual data and place it commented-out under the corresponding line. This means we don't have to do everything at once at the end. - -Once we have decompiled enough things to know what the data is, we can import it. The advantage of doing it this way is we should know what type everything is already: in our work on EnRecepgirl, for example, we ended up with the following data at the top of the file - -```C -#if 0 -ActorInit En_Recepgirl_InitVars = { - /**/ ACTOR_EN_RECEPGIRL, - /**/ ACTORCAT_NPC, - /**/ FLAGS, - /**/ OBJECT_BG, - /**/ sizeof(EnRecepgirl), - /**/ EnRecepgirl_Init, - /**/ EnRecepgirl_Destroy, - /**/ EnRecepgirl_Update, - /**/ EnRecepgirl_Draw, -}; - -static void* D_80C106B0[4] = { (void*)0x600F8F0, (void*)0x600FCF0, (void*)0x60100F0, (void*)0x600FCF0 }; - -// static InitChainEntry sInitChain[] = { -static InitChainEntry D_80C106C0[] = { - ICHAIN_U8(targetMode, 6, ICHAIN_CONTINUE), - ICHAIN_F32(targetArrowOffset, 1000, ICHAIN_STOP), -}; - -static s32 D_80C106C8 = 0; - -#endif -``` - -and the main thing we need to understand is `D_80C106B0` - -*Before doing anything else, make sure `make` gives `OK`.* - -First, we tell the compiler to ignore the original data file. To do this, open the file called `spec` in the main directory of the repository, and search for the actor name. You will find a section that looks like - -``` -beginseg - name "ovl_En_Recepgirl" - compress - include "build/src/overlays/actors/ovl_En_Recepgirl/z_en_recepgirl.o" - include "build/data/ovl_En_Recepgirl/ovl_En_Recepgirl.data.o" - include "build/data/ovl_En_Recepgirl/ovl_En_Recepgirl.reloc.o" -endseg -``` - -We will eventually remove both of the bottom two lines and replace them with our own reloc file, but for now, just comment out the data line: - -``` -beginseg - name "ovl_En_Recepgirl" - compress - include "build/src/overlays/actors/ovl_En_Recepgirl/z_en_recepgirl.o" - //include "build/data/ovl_En_Recepgirl/ovl_En_Recepgirl.data.o" - include "build/data/ovl_En_Recepgirl/ovl_En_Recepgirl.reloc.o" -endseg -``` - -Next remove all the externs, and uncomment their corresponding commented data: - -```C -ActorInit En_Recepgirl_InitVars = { - /**/ ACTOR_EN_RECEPGIRL, - /**/ ACTORCAT_NPC, - /**/ FLAGS, - /**/ OBJECT_BG, - /**/ sizeof(EnRecepgirl), - /**/ EnRecepgirl_Init, - /**/ EnRecepgirl_Destroy, - /**/ EnRecepgirl_Update, - /**/ EnRecepgirl_Draw, -}; - -static void* D_80C106B0[4] = { (void*)0x600F8F0, (void*)0x600FCF0, (void*)0x60100F0, (void*)0x600FCF0 }; - -// static InitChainEntry sInitChain[] = { -static InitChainEntry D_80C106C0[] = { - ICHAIN_U8(targetMode, 6, ICHAIN_CONTINUE), - ICHAIN_F32(targetArrowOffset, 1000, ICHAIN_STOP), -}; - -static s32 D_80C106C8 = 0; -``` - -That should be everything, and we should now be able to `make` without the data file with no issues. - -## Segmented pointers and object symbols - -The game has a convenient system that allows it to sometimes effectively use offsets into a file instead of raw memory addresses to reference things. This is done by setting a file address to a *segment*. A segmented address is of the form `0x0XYYYYYY`, where `X` is the segment number. There are 16 available segments, and actors always set segment 6 to their object file, which is a file containing assets (skeleton, animations, textures, etc.) that they use. This is what all those `D_06...` are, and it is also what the entries in `D_80C106B0` are: they are currently raw numbers instead of symbols, though, and we would like to replace them. - -There is an obvious problem here, which is that is that these symbols have to be defined *somewhere*, or the linker will complain (indeed, if we change the ones in the array to `D_...`, even if we extern them, we get - -``` -mips-linux-gnu-ld: build/src/overlays/actors/ovl_En_Recepgirl/z_en_recepgirl.o:(.data+0x20): undefined reference to `D_0600F8F0' -``` - -As we'd expect, of course: we didn't fulfil our promise that they were defined elsewhere.) - -For actors which have yet to be decompiled, this is mitigated by use of the file `undefined_syms.txt`, which feeds the linker the raw addresses to use as the symbol definitions. However, we want to replace these segmented addresses with proper object symbols whenever possible. In `En_Recepgirl_InitVars`, we can see that this actor uses the object `OBJECT_BG`: - -```c -ActorInit En_Recepgirl_InitVars = { - /**/ ACTOR_EN_RECEPGIRL, - /**/ ACTORCAT_NPC, - /**/ FLAGS, - /**/ OBJECT_BG, -}; -``` - -If we open up `assets/objects/object_bg.h`, we can see a bunch of different names corresponding to every asset in the object. You may notice that some of these names look a bit familiar; `object_bg_Tex_00F8F0` seems very close to the segmented address `(void*)0x600F8F0`. This is the proper object symbol for this segmented address, so we should `#include` this header in our actor and use these object symbols like so: - -```c -static void* D_80C106B0[4] = { object_bg_Tex_00F8F0, object_bg_Tex_00FCF0, object_bg_Tex_0100F0, object_bg_Tex_00FCF0 }; -``` - -After replacing every segmented pointer with an object symbol, you should go ahead and delete every segmented pointer associated with this actor from `undefined_syms`. - -We will come back and name these later when we do the object. - -## Fake symbols - -Some symbols in the data have been decompiled wrongly, being incorrectly separated from the previous symbol due to how it was accessed by the actor's functions. However, most of these have now been fixed. Some more detail is given in [Types, structs and padding](types_structs_padding.md) If you are unsure, ask! - -## Inlining - -After the file is finished, it is possible to move some static data into functions. This requires that: - -1. The data is used in only one function -2. The ordering of the data can be maintained - -Additionally, we prefer to keep larger data (more than a line or two) out of functions anyway. - -# Finally: .bss - -A .bss contains data that is uninitialised (actually initialised to `0`). For most actors all you need to do is declare it at the top of the actor file without giving it a value, once you find out what type it is. In `code`, it's much more of a problem. - -Next: [Documenting](documenting.md) \ No newline at end of file diff --git a/mm/docs/tutorial/diff_and_permuter.md b/mm/docs/tutorial/diff_and_permuter.md deleted file mode 100644 index e8d0f59f7..000000000 --- a/mm/docs/tutorial/diff_and_permuter.md +++ /dev/null @@ -1,145 +0,0 @@ -# `diff.py` and the permuter - -This document is intended as a step-by-step demonstration of matching a reasonably complex function using the diff script `diff.py` and the decomp permuter, both included in the repo. For general information on both see [the tools documentation](../tools.md). - -Until such time as someone finds a suitable function, you can look at the OoT tutorial: [here for diff.py](https://github.com/zeldaret/oot/blob/main/docs/tutorial/beginning_decomp.md#diff) and [here for the permuter](https://github.com/zeldaret/oot/blob/main/docs/tutorial/other_functions.md#the-permuter). - - - - diff --git a/mm/docs/tutorial/disassembly_quirks.md b/mm/docs/tutorial/disassembly_quirks.md deleted file mode 100644 index 34a01a6f3..000000000 --- a/mm/docs/tutorial/disassembly_quirks.md +++ /dev/null @@ -1,31 +0,0 @@ -# Disassembly quirks - -As MM's disassembly is automatic, there are certain unique problems it has. - -## Renaming functions and variables - -A function must be renamed in `tools/disasm/functions.txt` in addition to the source code, for the disassembler to know what to call the symbol at that address when it sees it. - -Variables must be renamed in `tools/disasm/variables.txt`. It may also be necessary to change their type, count or size to stop the disassembler misusing them. - -You can avoid having to redisassemble every time by running `rename_global_asm.py`, which will rename the individual functions' assembly files in `asm/nonmatchings/` to the name of the function they contain. - -## Fake and incorrect symbols - -TODO - -## Resplitting a file - -The files `boot` and `code` are each divided up into dozens of separate files, that are all joined together into one text, data, rodata and bss section when building the ROM. As such, it has been necessary to guess where the file boundaries are, and not every file contains the correct functions or the correct data (rodata is mostly the exception since it is automatically split). - -To change a split for a file, find its entry in `tools/disasm/files.txt`, and change or create entries to accurately reflect where the file(s) should start. For example, it was found that the last function in `z_nmi_buff.c` had nothing to do with the rest, so it should be split into its own file. Looking up the address of the last function, it was found to be at `0x8010C1B0`, so adding the line: - -```diff - 0x8010C0C0 : "z_nmi_buff", -+++ 0x8010C1B0 : "code_8010C1B0", - 0x8010C230 : "z_olib", -``` - -to the file will extract it correctly as a separate file. It also is necessary to make a new C file and move the `GLOBAL_ASM` declaration into it. - -Unfortunately you essentially have to redisassemble after telling the disassembler to resplit a file. diff --git a/mm/docs/tutorial/documenting.md b/mm/docs/tutorial/documenting.md deleted file mode 100644 index 619b30c06..000000000 --- a/mm/docs/tutorial/documenting.md +++ /dev/null @@ -1,595 +0,0 @@ -# Documenting - -- Up: [Contents](contents.md) -- Previous: [Data](data.md) - -Decompilation is only the first step: since the point of this project is to understand the game better than ever before, the code needs documentation. In this document, we will go through the basic stuff that it's good to do for any actor: we will not try to understand every single thing the actor does in full detail, but try to name the functions and variables usefully for a full documentation pass later to take advantage of. - -It is helpful to document the functions and variables in the actor before you Pull Request it. The aim is to provide code that is sufficiently clear to be self-documenting, but it is worth leaving a comment on anything you find obscure or confusing. (Pull Request reviews will let you know if you are leaving too many comments.) Useful things to do documentation-wise: - -- Name all (or most) of the functions. -- Name all the variables in the actor struct. -- Create enums for params, and any other numbers that would benefit from that sort of clarity. - -You can test things using the practice rom for a retail version (watches and memory view is especially helpful), as well as the generated rom with Project 64 and something like Spectrum. - -If you want to use `diff.py` after renaming anything, particularly functions, remember to rerun `make diff-init` so it can use the correct symbols. - -Finally, *if you are not sure what something does, either ask or leave it unnamed: it will be less confusing later if things are unnamed than if they are wrongly named* - -## Renaming things - -Because MM needs to regenerate the assembly code, it is necessary to tell the disassembler the names of functions and variables, so it knows what symbols to assign in the code. This is done via `functions.txt` and `variables.txt`. The best way to rename functions and symbols is via global rename in an editor like VSCode. The next best way is to run `tools/rename_sym.sh`. You should be careful with this script: it has no error-checking! - -Renaming symbols in theory requires re-disassembly. This can often be avoided in the case of functions by running `tools/rename_global_asm.py`, which will rename any individual functions' assembly files with the wrong names, so that the `GLOBAL_ASM`s can spot them. Renaming variables *may* require redisassembly (and if fake symbols are removed, it *will*). - -## EnRecepgirl - -Currently, the file looks like this: -
- -Large code block, click to show - - -```C -#include "z_en_recepgirl.h" - -#define FLAGS 0x00000009 - -#define THIS ((EnRecepgirl*)thisx) - -void EnRecepgirl_Init(Actor* thisx, PlayState* play); -void EnRecepgirl_Destroy(Actor* thisx, PlayState* play); -void EnRecepgirl_Update(Actor* thisx, PlayState* play); -void EnRecepgirl_Draw(Actor* thisx, PlayState* play); - -void func_80C10148(EnRecepgirl* this); -void func_80C1019C(EnRecepgirl* this, PlayState* play); -void func_80C10290(EnRecepgirl* this); -void func_80C102D4(EnRecepgirl* this, PlayState* play); - -ActorInit En_Recepgirl_InitVars = { - /**/ ACTOR_EN_RECEPGIRL, - /**/ ACTORCAT_NPC, - /**/ FLAGS, - /**/ OBJECT_BG, - /**/ sizeof(EnRecepgirl), - /**/ EnRecepgirl_Init, - /**/ EnRecepgirl_Destroy, - /**/ EnRecepgirl_Update, - /**/ EnRecepgirl_Draw, -}; - -static void* D_80C106B0[4] = { object_bg_Tex_00F8F0, object_bg_Tex_00FCF0, object_bg_Tex_0100F0, object_bg_Tex_00FCF0 }; - -// static InitChainEntry sInitChain[] = { -static InitChainEntry D_80C106C0[] = { - ICHAIN_U8(targetMode, 6, ICHAIN_CONTINUE), - ICHAIN_F32(targetArrowOffset, 1000, ICHAIN_STOP), -}; - -static s32 D_80C106C8 = 0; - -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Init.s") -void EnRecepgirl_Init(Actor* thisx, PlayState* play) { - EnRecepgirl* this = THIS; - s32 i; - - Actor_ProcessInitChain(&this->actor, D_80C106C0); - ActorShape_Init(&this->actor.shape, -60.0f, NULL, 0.0f); - SkelAnime_InitFlex(play, &this->skelAnime, &object_bg_Skel_011B60, &object_bg_Anim_009890, this->jointTable, this->morphTable, 24); - - if (D_80C106C8 == 0) { - for (i = 0; i < 4; i++) { - D_80C106B0[i] = Lib_SegmentedToVirtual(D_80C106B0[i]); - } - D_80C106C8 = 1; - } - - this->unk_2AC = 2; - - if (Flags_GetSwitch(play, this->actor.params)) { - this->actor.textId = 0x2ADC; - } else { - this->actor.textId = 0x2AD9; - } - - func_80C10148(this); -} - -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Destroy.s") -void EnRecepgirl_Destroy(Actor* thisx, PlayState* play) { -} - -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C100DC.s") -void func_80C100DC(EnRecepgirl *this) { - if (this->unk_2AC != 0) { - this->unk_2AC++; - if (this->unk_2AC == 4) { - this->unk_2AC = 0; - return; - } - return; - } - if (Rand_ZeroOne() < 0.02f) { - this->unk_2AC++; - } -} - -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10148.s") -void func_80C10148(EnRecepgirl *this) { - if (this->skelAnime.animation == &object_bg_Anim_001384) { - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_00AD98, 5.0f); - } - this->actionFunc = func_80C1019C; -} - -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C1019C.s") -void func_80C1019C(EnRecepgirl* this, PlayState* play) { - if (SkelAnime_Update(&this->skelAnime) != 0) { - if (this->skelAnime.animation == &object_bg_Anim_00A280) { - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_00AD98, 5.0f); - } else { - Animation_ChangeTransitionRepeat(&this->skelAnime, &object_bg_Anim_009890, -4.0f); - } - } - - if (Actor_ProcessTalkRequest(&this->actor, &play->state) != 0) { - func_80C10290(this); - } else if (Actor_IsFacingPlayer(&this->actor, 0x2000)) { - Actor_OfferTalk(&this->actor, play, 60.0f); - if (Player_GetMask(play) == 2) { - this->actor.textId = 0x2367; - } else if (Flags_GetSwitch(play, this->actor.params)) { - this->actor.textId = 0x2ADC; - } else { - this->actor.textId = 0x2AD9; - } - } -} - -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10290.s") -void func_80C10290(EnRecepgirl *this) { - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_00A280, -4.0f); - this->actionFunc = func_80C102D4; -} - -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C102D4.s") -void func_80C102D4(EnRecepgirl* this, PlayState* play) { - u8 temp_v0_2; - - if (SkelAnime_Update(&this->skelAnime) != 0) { - if (this->skelAnime.animation == &object_bg_Anim_00A280) { - Animation_ChangeDefaultRepeat(&this->skelAnime, &object_bg_Anim_001384); - } else if (this->skelAnime.animation == &object_bg_Anim_00AD98) { - if (this->actor.textId == 0x2ADA) { - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_000968, 10.0f); - } else { - Animation_ChangeTransitionRepeat(&this->skelAnime, &object_bg_Anim_009890, 10.0f); - } - } else if (this->actor.textId == 0x2ADA) { - Animation_ChangeTransitionRepeat(&this->skelAnime, &object_bg_Anim_009890, 10.0f); - } else { - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_00A280, -4.0f); - } - } - - temp_v0_2 = Message_GetState(&play->msgCtx); - if (temp_v0_2 == 2) { - this->actor.textId = 0x2ADC; - func_80C10148(this); - return; - } - - if ((temp_v0_2 == 5) && (Message_ShouldAdvance(play) != 0)) { - if (this->actor.textId == 0x2AD9) { - Flags_SetSwitch(play, this->actor.params); - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_00AD98, 10.0f); - if ((gSaveContext.save.saveInfo.weekEventReg[63] & 0x80)) { - this->actor.textId = 0x2ADF; - } else { - this->actor.textId = 0x2ADA; - } - } else if (this->actor.textId == 0x2ADC) { - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_00AD98, 10.0f); - this->actor.textId = 0x2ADD; - } else { - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_000968, 10.0f); - if (this->actor.textId == 0x2ADD) { - this->actor.textId = 0x2ADE; - } else if (this->actor.textId == 0x2ADA) { - this->actor.textId = 0x2ADB; - } else { - this->actor.textId = 0x2AE0; - } - } - Message_ContinueTextbox(play, this->actor.textId); - } -} - -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Update.s") -void EnRecepgirl_Update(Actor* thisx, PlayState* play) { - s32 pad; - EnRecepgirl* this = THIS; - Vec3s sp30; - - this->actionFunc(this, play); - Actor_TrackPlayer(play, &this->actor, &this->unk_2AE, &sp30, this->actor.focus.pos); - func_80C100DC(this); -} - -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10558.s") -s32 func_80C10558(PlayState* play, s32 limbIndex, Gfx **dList, Vec3f *pos, Vec3s *rot, Actor *thisx) { - EnRecepgirl* this = THIS; - - if (limbIndex == 5) { - rot->x += this->unk_2AE.y; - } - return false; -} - -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10590.s") -void func_80C10590(PlayState* play, s32 limbIndex, Actor *thisx) { - EnRecepgirl* this = THIS; - - if (limbIndex == 5) { - Matrix_RotateYS(0x400 - this->unk_2AE.x, MTXMODE_APPLY); - Matrix_MultVecX(500.0f, &this->actor.focus.pos); - } -} - -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Draw.s") -void EnRecepgirl_Draw(Actor* thisx, PlayState* play) { - EnRecepgirl* this = THIS; - - OPEN_DISPS(play->state.gfxCtx); - - Gfx_SetupDL25_Opa(play->state.gfxCtx); - - gSPSegment(POLY_OPA_DISP++, 0x08, D_80C106B0[this->unk_2AC]); - - SkelAnime_DrawTransformFlexOpa(play, this->skelAnime.skeleton, this->skelAnime.jointTable, this->skelAnime.dListCount, func_80C10558, NULL, func_80C10590, &this->actor); - - CLOSE_DISPS(play->state.gfxCtx); -} - -``` - -
- -(We can delete the `GLOBAL_ASM` lines now.) - -The worst part of documentation is finding somewhere to start. We have a decent place to start here, though, in that we already know the function (or rather, the use) of a couple of the functions, namely the LimbDraws. So we can rename `func_80C10558` to `EnRecepgirl_OverrideLimbDraw` and `func_80C10590` to `EnRecepgirl_TransformLimbDraw`. Remember to do a global rename so that the functions in the assembly are renamed, use `rename_global_asm`, - -``` -$ ./tools/rename_global_asm.py -asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10558.s --> asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_OverrideLimbDraw.s -asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10590.s --> asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_UnkLimbDraw.s -``` - -as well as the mentions in this chunk of `functions.txt`: - -``` - 0x80C0FFD0:("EnRecepgirl_Init",), - 0x80C100CC:("EnRecepgirl_Destroy",), - 0x80C100DC:("func_80C100DC",), - 0x80C10148:("func_80C10148",), - 0x80C1019C:("func_80C1019C",), - 0x80C10290:("func_80C10290",), - 0x80C102D4:("func_80C102D4",), - 0x80C104E8:("EnRecepgirl_Update",), - 0x80C10558:("func_80C10558",), - 0x80C10590:("func_80C10590",), - 0x80C105EC:("EnRecepgirl_Draw",), -``` - -That's probably as much as we can do on functions for now. Next let's think about some of the variables. We have essentially 3 sorts of variable here - -- struct variables -- data/bss -- intrafunction/stack variables - -and this is roughly the order of preference for naming them (although not necessarily the logical order to determine what they do). This actor is quite limited in the last category: only `sp30` is unnamed at the moment. Even though `Actor_TrackPlayer` is decomped, the purpose of the argument in which `sp30` is placed is not clear (and, indeed, is not named), so it's probably best to leave it unnamed for now. (With greater experience, you might analyse `Actor_TrackPlayer` to work out what this argument is for, but let's not worry about that for now.) - -As for the struct, there are two unnamed variables at the moment: - -```C -typedef struct EnRecepgirl { - /* 0x000 */ Actor actor; - /* 0x144 */ SkelAnime skelAnime; - /* 0x188 */ Vec3s jointTable[24]; - /* 0x218 */ Vec3s morphTable[24]; - /* 0x2A8 */ EnRecepgirlActionFunc actionFunc; - /* 0x2AC */ u8 unk_2AC; - /* 0x2AE */ Vec3s unk_2AE; -} EnRecepgirl; // size = 0x2B4 -``` - -Let's start with `unk_2AC`. This is set to `2` in `Init`, something interesting happens to it in `func_80C100DC`, but it is used in the `Draw`, here: - -```C - gSPSegment(POLY_OPA_DISP++, 0x08, D_80C106B0[this->unk_2AC]); -``` - -So it is used as an index into the array `D_80C106B0`, and the element with that index is placed on segment `8`. So we need to work out what this array is to name `unk_2AC`. - -As we discussed last time, `D_80C106B0` is an array of [segmented pointers](data.md#segmented-pointers). Since they are in segment `6`, they are in the actor's object file. Which object? The InitVars tell us: namely, - -```C -ActorInit En_Recepgirl_InitVars = { - /**/ ACTOR_EN_RECEPGIRL, - /**/ ACTORCAT_NPC, - /**/ FLAGS, - /**/ OBJECT_BG, -``` - -the fourth element is the object (it is actually an enum, but the file itself has the same name as the object enum). So, we need to look at the object file. We are very lucky that a custom tool has been written for such a thing: Z64Utils. - -## Z64Utils - -The latest release of Z64Utils can be downloaded from [https://github.com/zeldaret/Z64Utils/releases]. It should work on Wine. Some graphics cards don't love it, but the 3D graphical part is only required for skeleton and animations. - -Having downloaded and unzipped it, open the baserom file. This will populate the main window with a list: - -![Z64Utils' main window](images/z64utils_main.png) - -Search for the object file, then either double-click it or right-click it and select "Open in Object Analyzer" to open it. It will ask you to choose a segment: this is the segment that the file is put on, and allows Z64Utils to resolve the segmented addresses it references into symbols. The json already knows it should be segment `6`, so just click okay. This will open this window; displaylists and other data will automatically be analyzed when the object is opened: - -![Z64Utils, with an analyzed object](images/z64utils_object_analyzed.png) - -We will talk about what all these types of data are next time, but for now, all we want to know is what - -```C -static void* D_80C106B0[4] = { object_bg_Tex_00F8F0, object_bg_Tex_00FCF0, object_bg_Tex_0100F0, object_bg_Tex_00FCF0 }; -``` - -actually are. We know they are set on segment 8, so we need to find where the skeleton uses them. We know from `object_bg_Skel_011B60` that this is at `0x06011B60`, so scroll down to it and either double-click on it or right-click on it and choose "Open in Skeleton Viewer". Pick an animation that we know it uses (sometimes Z64Utils misidentifies other things for animations), such as `object_bg_Anim_000968`, and you will get this error: - -![Z64Utils, error when viewing skeleton](images/z64utils_skeleton_error.png) - -It needs something to be set to segment `8`. Well, that's good, we know that the code does that! Let's find out what. Z64Utils tells you the address, so we can look up the displaylist that wants it: the relevant block is - -```C -[...] -// Multi Command Macro Found (6 instructions) -0600DE70: gsDPLoadTLUT(256, 0x100, D_0600F6F0), -// Multi Command Macro Found (7 instructions) -0600DEA0: gsDPLoadTextureBlock(D_08000000, G_IM_FMT_CI, G_IM_SIZ_8b, 32, 32, 0, G_TX_MIRROR | G_TX_CLAMP, G_TX_NOMIRROR | G_TX_CLAMP, 5, 5, 0, 0), -0600DED8: gsDPSetTileSize(G_TX_RENDERTILE, 0, 0, (63<<2), (31<<2)), -0600DEE0: gsSPVertex(D_0600B3F0, 19, 0), -0600DEE8: gsSP2Triangles(0, 1, 2, 0, 3, 4, 5, 0), -0600DEF0: gsSP2Triangles(6, 7, 5, 0, 8, 4, 3, 0), -0600DEF8: gsSP2Triangles(7, 6, 9, 0, 5, 10, 3, 0), -0600DF00: gsSP2Triangles(5, 7, 10, 0, 11, 9, 6, 0), -0600DF08: gsSP2Triangles(11, 12, 9, 0, 4, 1, 13, 0), -0600DF10: gsSP2Triangles(6, 14, 11, 0, 13, 5, 4, 0), -0600DF18: gsSP2Triangles(5, 14, 6, 0, 15, 14, 5, 0), -0600DF20: gsSP2Triangles(8, 1, 4, 0, 2, 1, 8, 0), -0600DF28: gsSP2Triangles(13, 16, 5, 0, 13, 14, 17, 0), -0600DF30: gsSP2Triangles(18, 11, 14, 0, 12, 11, 18, 0), -0600DF38: gsSP1Triangle(13, 1, 0, 0), -0600DF40: gsDPPipeSync(), -[...] - -``` -so we see that segment `8` is expecting a texture (we'll go into more detail about precisely what when we talk about making the XML file to extract the object). Therefore, `D_80C106B0` is a set of textures. We have a special type for textures, namely `TexturePtr`. - -## Back to the data - -But what sort of textures? This is an NPC, so what textures on the model would it want to change? The answer is of course the eyes: most NPCs have eye textures, with some sort of routine for changing them to appear to blink. We can set the different textures onto segment `8` and see which is which, but this is enough to know that `D_80C106B0` can be `sEyeTextures` (`s` for `static`: they essentially have to be static so that we can name them like this without the names clashing), and that `unk_2AC` is `eyeTexIndex` (these names are not completely standard, but it's best to be as consistent as possible). - -**N.B.** static data should not be renamed in the assembly or `variables.txt`, since assembly has no notion of file locality and there can be symbol clashes. Therefore it should only be renamed in its respective file, not globally. - -```C -static TexturePtr sEyeTextures[] = { object_bg_Tex_00F8F0, object_bg_Tex_00FCF0, object_bg_Tex_0100F0, object_bg_Tex_00FCF0 }; -``` - -And now it's rather more obvious what - -```C -void func_80C100DC(EnRecepgirl* this) { - if (this->eyeTexIndex != 0) { - this->eyeTexIndex++; - if (this->eyeTexIndex == 4) { - this->eyeTexIndex = 0; - } - } else if (Rand_ZeroOne() < 0.02f) { - this->eyeTexIndex++; - } -} -``` - -is doing: it's running a kind of blink routine. This is slightly nonstandard: usually there is a separate timer, but this one simply perturbs the index away from `0` every frame with a 2% chance. This sort of function is usually called `Blink` or `UpdateEyes`. Since it is explicitly called in `Update`, we'll call it `UpdateEyes`, but either is fine; we'll standardise later. - -We have two other pieces of data. There is a suggested name for the InitChain in the code already; just replace it and replace the first line in the definition. - -This leaves one piece of data unnamed, `D_80C106C8`. This is initially set to `0`, checked in `Init` to decide whether to run the loop, and then set to `1` after the loop is finished: - -```C - if (D_80C106C8 == 0) { - for (i = 0; i < 4; i++) { - sEyeTextures[i] = Lib_SegmentedToVirtual(sEyeTextures[i]); - } - D_80C106C8 = 1; - } -``` - -What is this doing? We need to understand that to name this variable. - -The N64's processors cannot use segmented addresses: they need actual RAM addresses. Therefore the segmented addresses have to be converted before being placed on a segment: this is what `Lib_SegmentedToVirtual` does. So (somewhat unusually) this loop is modifying the addresses in the actor's actual data in RAM. Having converted the addresses once, it wouldn't make any sense to convert them again, but `Init` would run every time an instantiation of the actor is created. Therefore `D_80C106C8` is present to ensure that the addresses only get converted once: it is really a boolean that indicates if the addresses have been converted. So let's call it `sTexturesDesegmented`, and replace its values by `true` and `false`. - -Finally, clearly `4` is linked to the data over which we're iterating: namely it's the size of the array. We have a macro for this, `ARRAY_COUNT(sEyeTextures)`. - -We've got one struct variable left. To find out what it does, we can look at a function that uses it, for example - -```C -s32 EnRecepgirl_OverrideLimbDraw(PlayState* play, s32 limbIndex, Gfx** dList, Vec3f* pos, Vec3s* rot, - Actor* thisx) { - EnRecepgirl* this = THIS; - - if (limbIndex == 5) { - rot->x += this->unk_2AE.y; - } - return false; -} - -void EnRecepgirl_UnkLimbDraw(PlayState* play, s32 limbIndex, Actor* thisx) { - EnRecepgirl* this = THIS; - - if (limbIndex == 5) { - Matrix_RotateYS(0x400 - this->unk_2AE.x, MTXMODE_APPLY); - Matrix_MultVecX(500.0f, &this->actor.focus.pos); - } -} -``` - -It is used to do a rotation of whatever limb `5` is. (The `+=` is because `rot->x` is the base rotation of the limb, and we have to add the same thing to it every frame to keep the angle changed and constant.) We can use Z64Utils to figure this out: setting segment `8` to one of what we know now are the eye textures, we can view the model in the skeleton viewer. The limb numbers in the object are one smaller than those in the actor (the root limb is only a concept for the code, not the object), so we find limb 4: - -![Z64Utils highlighting a limb](images/z64utils_skeleton_head.png) - -Hence this is changing the head rotation. An obvious name is `headRot`. - -## Functions - -Finally, we have to name the rest of the functions. Setup functions are usually named as `_Setup`, so we really only have to name two functions. They are both related to text. if we annotate all the textIds (do not quote the whole message, just give an unambiguous summary), the flow becomes a bit clearer: - -```C -void func_80C10148(EnRecepgirl* this) { - if (this->skelAnime.animation == &object_bg_Anim_001384) { - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_00AD98, 5.0f); - } - this->actionFunc = func_80C1019C; -} - -void func_80C1019C(EnRecepgirl* this, PlayState* play) { - if (SkelAnime_Update(&this->skelAnime) != 0) { - if (this->skelAnime.animation == &object_bg_Anim_00A280) { - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_00AD98, 5.0f); - } else { - Animation_ChangeTransitionRepeat(&this->skelAnime, &object_bg_Anim_009890, -4.0f); - } - } - - if (Actor_ProcessTalkRequest(&this->actor, &play->state) != 0) { - func_80C10290(this); - } else if (Actor_IsFacingPlayer(&this->actor, 0x2000)) { - Actor_OfferTalk(&this->actor, play, 60.0f); - if (Player_GetMask(play) == PLAYER_MASK_KAFEIS_MASK) { - this->actor.textId = 0x2367; // "... doesn't Kafei want to break off his engagement ... ?" - } else if (Flags_GetSwitch(play, this->actor.params)) { - this->actor.textId = 0x2ADC; // hear directions again? - } else { - this->actor.textId = 0x2AD9; // "Welcome..." - } - } -} - -void func_80C10290(EnRecepgirl* this) { - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_00A280, -4.0f); - this->actionFunc = func_80C102D4; -} - -void func_80C102D4(EnRecepgirl* this, PlayState* play) { - u8 temp_v0_2; - - if (SkelAnime_Update(&this->skelAnime)) { - if (this->skelAnime.animation == &object_bg_Anim_00A280) { - Animation_ChangeDefaultRepeat(&this->skelAnime, &object_bg_Anim_001384); - } else if (this->skelAnime.animation == &object_bg_Anim_00AD98) { - if (this->actor.textId == 0x2ADA) { // Mayor's office is on the left (meeting ongoing) - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_000968, 10.0f); - } else { - Animation_ChangeTransitionRepeat(&this->skelAnime, &object_bg_Anim_009890, 10.0f); - } - } else if (this->actor.textId == 0x2ADA) { // Mayor's office is on the left (meeting ongoing) - Animation_ChangeTransitionRepeat(&this->skelAnime, &object_bg_Anim_009890, 10.0f); - } else { - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_00A280, -4.0f); - } - } - - temp_v0_2 = Message_GetState(&play->msgCtx); - if (temp_v0_2 == 2) { - this->actor.textId = 0x2ADC; // hear directions again? - func_80C10148(this); - } else if ((temp_v0_2 == 5) && (Message_ShouldAdvance(play) != 0)) { - if (this->actor.textId == 0x2AD9) { // "Welcome..." - Flags_SetSwitch(play, this->actor.params); - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_00AD98, 10.0f); - if (gSaveContext.save.saveInfo.weekEventReg[63] & 0x80) { // showed Couple's Mask to meeting - this->actor.textId = 0x2ADF; // Mayor's office is on the left (meeting ended) - } else { - this->actor.textId = 0x2ADA; // Mayor's office is on the left (meeting ongoing) - } - } else if (this->actor.textId == 0x2ADC) { // hear directions again? - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_00AD98, 10.0f); - this->actor.textId = 0x2ADD; // "So..." - } else { - Animation_MorphToPlayOnce(&this->skelAnime, &object_bg_Anim_000968, 10.0f); - - if (this->actor.textId == 0x2ADD) { // "So..." - this->actor.textId = 0x2ADE; // Mayor's office is on the left, drawing room on the right - } else if (this->actor.textId == - 0x2ADA) { // Mayor's office is on the left (meeting ongoing) - this->actor.textId = 0x2ADB; // drawing room on the right - } else { - this->actor.textId = 0x2AE0; // drawing room on the right, don't go in without an appointment - } - } - Message_ContinueTextbox(play, this->actor.textId); - } -} -``` -All this branching is to make the conversation look more diverse and interesting. Notably, though, `func_80C1019C` is set to start with, and is only changed when `Actor_ProcessTalkRequest(&this->actor, &play->state) != 0`. This is something to do with talking. The other function handles the rest of the conversation, and hands back to the first if `Message_GetState(&play->msgCtx) == 2`. This function is *something* to do with the text state, which will require `z_message` to be decomped. However, observation in-game will reveal this is something to do with ending dialogue. So we can conclude that the action functions are `EnRecepgirl_Wait` and `EnRecepgirl_Talk`. The setup functions are thus `EnRecepgirl_SetupWait` and `EnRecepgirl_SetupTalk`. - -For more complex actors, we have a tool called `graphovl.py` that can produce function flow graphs for actors: running - -``` -$ ./tools/graphovl/graphovl.py En_Recepgirl -``` - -produces - -![EnRecepgirl's function flow graph](images/En_Recepgirl.gv.png) - -## Miscellaneous other documentation - -We like to make macros for reading an actor's `params` (indeed, this is required even if you don't know what the params are for). A simple example is `ObjTree`, which has the following code in its `Init` function: - -```c - if (this->dyna.actor.params & 0x8000) { - Actor_SetScale(&this->dyna.actor, 0.15f); - this->dyna.actor.uncullZoneForward = 4000.0f; - } else { - Actor_SetScale(&this->dyna.actor, 0.1f); - DynaPolyActor_Init(&this->dyna, 1); - CollisionHeader_GetVirtual(&object_tree_Colheader_001B2C, &colHeader); - this->dyna.bgId = DynaPoly_SetBgActor(play, &play->colCtx.dyna, &this->dyna.actor, colHeader); - } -``` - -Looking through the rest of the actor, it becomes apparent that `params & 0x8000` is only used for changing the size of the tree: ones with this bit set are larger. So we make a macro in the header: - -```c -#define OBJTREE_ISLARGE(thisx) ((thisx)->params & 0x8000) -``` - -Notice that we use `thisx`: this makes the form of every one of these macros the same. However, we only use `thisx` if required for matching, so when we add it to the actor, we use `&this->dyna.actor` (in this case, since `ObjTree` is a dynapoly actor). - -```c - if (OBJTREE_ISLARGE(&this->dyna.actor)) { - Actor_SetScale(&this->dyna.actor, 0.15f); - this->dyna.actor.uncullZoneForward = 4000.0f; - } else { - Actor_SetScale(&this->dyna.actor, 0.1f); - DynaPolyActor_Init(&this->dyna, 1); - CollisionHeader_GetVirtual(&object_tree_Colheader_001B2C, &colHeader); - this->dyna.bgId = DynaPoly_SetBgActor(play, &play->colCtx.dyna, &this->dyna.actor, colHeader); - } -``` - -Much clearer! - -We have now essentially documented this as far as we can without the object, so we'd better do that next. - -Next: [Analysing object files](object_decomp.md) diff --git a/mm/docs/tutorial/draw_functions.md b/mm/docs/tutorial/draw_functions.md deleted file mode 100644 index e551907d3..000000000 --- a/mm/docs/tutorial/draw_functions.md +++ /dev/null @@ -1,330 +0,0 @@ -# Draw functions - -- Up: [Contents](contents.md) -- Previous: [The rest of the functions in the actor](other_functions.md) - -Draw functions behave completely differently from the other functions in an actor. They often use a lot of macros. - -This document will be a bit different: we will look at the draw functions in EnRecepgirl, then consider some more complicated examples. - -## A first example - -Unless it is completely invisible, an actor usually has a draw function as one of the main four actor functions. Hence its prototype looks like - -```C -void EnRecepgirl_Draw(Actor* thisx, PlayState* play); -``` - -From now on, the process is rather different from the decompilation process used for the other functions. Here is the output of mips2c after sorting out the actor struct from Init, and with the arguments set back to `Actor* thisx`: -```C -s32 func_80C10558(PlayState* play, s32 limbIndex, Gfx **dList, Vec3f *pos, Vec3s *rot, Actor *actor); // extern -void func_80C10590(PlayState* play, s32 limbIndex, Actor *actor); // extern -void *D_80C106B0[4] = {(void *)0x600F8F0, (void *)0x600FCF0, (void *)0x60100F0, (void *)0x600FCF0}; - -void EnRecepgirl_Draw(Actor* thisx, PlayState* play) { - EnRecepgirl* this = (EnRecepgirl *) thisx; - GraphicsContext *sp30; - Gfx *temp_v1; - GraphicsContext *temp_a0; - - temp_a0 = play->state.gfxCtx; - sp30 = temp_a0; - Gfx_SetupDL25_Opa(temp_a0); - temp_v1 = sp30->polyOpa.p; - sp30->polyOpa.p = temp_v1 + 8; - temp_v1->words.w0 = 0xDB060020; - temp_v1->words.w1 = (u32) D_80C106B0[this->unk_2AC]; - SkelAnime_DrawTransformFlexOpa(play, this->skelAnime.skeleton, this->skelAnime.jointTable, (s32) this->skelAnime.dListCount, func_80C10558, NULL, func_80C10590, (Actor *) this); -} -``` - -Notable features are the GraphicsContext temps, and blocks of the form - -```C - temp_v1 = sp30->polyOpa.p; - sp30->polyOpa.p = temp_v1 + 8; - temp_v1->words.w0 = 0xDB060020; - temp_v1->words.w1 = (u32) D_80C106B0[this->unk_2AC]; -``` - -(This is a particularly simple example, since there's only one of these blocks. We will give a more involved example later.) - -Each of these blocks converts into a graphics macro. They are usually (but not always) straightforward, but manually converting them is a pain, and there are sometimes special cases. To deal with them easily, we will use a tool from glank's N64 tools. To install these, follow the instructions [here](https://practicerom.com/public/packages/debian/howto.txt). - -For our purposes, we only need one of the programs this provides: `gfxdis.f3dex2`. - -Graphics are actually 64-bit on the Nintendo 64. This code block is a result of instructions telling the processor what to do with the graphics pointer. There are two main types of graphics pointer (there are a couple of others used in `code`, but actors will only use these two), - -- polyOpa ("opaque") for solid textures -- polyXlu ("Xlucent" i.e. "translucent") for translucent textures - -Our example is polyOpa, not surprisingly since our receptionist is solid. - -`words.w0` and `words.w1` contain the actual graphics instruction, in hex format. Usually, `w0` is constant and `w1` contains the arguments. To find out what sort of macro we are dealing with, we use `gfxdis.f3dex2`. `w1` is variable, but we need to give the program a constant placeholder. A common word to use is 12345678, so in this case we run - -``` -gfxdis.f3dex2 -x -g "POLY_OPA_DISP++" -d DB06002012345678 -``` - -- `-x` uses hex instead of the default qu macros (never mind what those are, MM doesn't use them) -- `-g` is used to specify which graphics pointer macro to use -- `-d` is for the graphics dword - -Our standard now is to use decimal colors. If you have a constant second argument rather than a variable one, you can also use `-dc` to get decimal colors instead of the default hex. - -The output looks like - -``` -gSPSegment(POLY_OPA_DISP++, 0x08, 0x12345678); -``` - -We can now replace the `0x12345678` by the actual second word, namely `D_80C106B0[this->unk_2AC]`. We can see mips2c has pulled in this data again: we saw it before in the `Init`. - -The words look like pointers to assets in the actor's object segment, which would make sense if we're looking for textures to draw. Because this data is used in a graphics macro, it will be either a displaylist or a texture; it may as well stay as `void*` until we come back to it later. - -```C -gSPSegment(POLY_OPA_DISP++, 0x08, D_80C106B0[this->unk_2AC]); -``` - -You repeat this for every block in the function. - -If you have worked on OoT, you will be aware of the functions `Graph_OpenDisps` and `Graph_CloseDisps`, and might be surprised to see them missing here. These functions are actually a debug feature: the `OPEN_DISPS` and `CLOSE_DISPS` macros still exist, but they don't expand to functions. Of course this means you have to guess where they go. A sensible guess for `OPEN_DISPS` is where the `gfxCtx` temp assignment first happens; `CLOSE_DISPS` is a bit harder, although it's basically just a `}`, so it *shouldn't* matter as much. - -It's sensible to eliminate all the `gfxCtx` temps and reintroduce as needed. Also remember to change the prototype and function definition back! - -```C -s32 func_80C10558(PlayState* play, s32 limbIndex, Gfx **dList, Vec3f *pos, Vec3s *rot, Actor *actor); -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10558.s") - -void func_80C10590(PlayState* play, s32 limbIndex, Actor *actor); -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10590.s") - -// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Draw.s") -void EnRecepgirl_Draw(Actor* thisx, PlayState* play) { - EnRecepgirl* this = THIS; - - OPEN_DISPS(play->state.gfxCtx); - - Gfx_SetupDL25_Opa(play->state.gfxCtx); - - gSPSegment(POLY_OPA_DISP++, 0x08, D_80C106B0[this->unk_2AC]); - - SkelAnime_DrawTransformFlexOpa(play, this->skelAnime.skeleton, this->skelAnime.jointTable, this->skelAnime.dListCount, func_80C10558, NULL, func_80C10590, &this->actor); - - CLOSE_DISPS(play->state.gfxCtx); -} -``` - -And this matches. - -The last two functions in the actor are used as arguments in `SkelAnime_DrawTransformFlexOpa`. This is a `SkelAnime` function, except unlike the OoT ones, it has three function callback arguments instead of two: in `functions.h` or `z_skelanime.c`, we find - -```C -void SkelAnime_DrawTransformFlexOpa(PlayState* play, void** skeleton, Vec3s* jointTable, s32 dListCount, - OverrideLimbDrawOpa overrideLimbDraw, PostLimbDrawOpa postLimbDraw, TransformLimbDrawOpa transformLimbDraw, Actor* actor) -``` - -The typedefs of the callbacks it uses are in `z64animation.h`: - -```C -typedef s32 (*OverrideLimbDrawOpa)(struct PlayState* play, s32 limbIndex, Gfx** dList, Vec3f* pos, Vec3s* rot, - struct Actor* thisx); - -typedef void (*PostLimbDrawOpa)(struct PlayState* play, s32 limbIndex, Gfx** dList, Vec3s* rot, - struct Actor* thisx); - -[...] - -typedef void (*TransformLimbDrawOpa)(struct PlayState* play, s32 limbIndex, struct Actor* thisx); -``` - -which is where mips2c got them from. - -In this case, only two of them are used, and it is these that are the last functions standing between us and a decompiled actor. - -## OverrideLimbDraw, PostLimbDraw, TransformLimbDraw - -Well, we don't have a PostLimbDraw here, but as we see from the prototype, it's much the same as the OverrideLimbDraw but without the `pos` argument and no return value. - -```C -s32 func_80C10558(PlayState* play, s32 limbIndex, Gfx **dList, Vec3f *pos, Vec3s *rot, Actor *actor) { - if (limbIndex == 5) { - rot->x += actor->unk2B0; - } - return 0; -} -``` - -Only two things to do here: we need to use `EnRecepgirl` to get to `actor + 0x2B0`, and the return value is used as a boolean, so we replace `0` by `false` (`true` means "don't draw the limb", and is hardly ever used). - -```C -s32 func_80C10558(PlayState* play, s32 limbIndex, Gfx **dList, Vec3f *pos, Vec3s *rot, Actor *thisx) { - EnRecepgirl* this = THIS; - - if (limbIndex == 5) { - rot->x += this->unk_2AE.y; - } - return false; -} -``` - -As for the TransformLimbDraw, it has a much simpler prototype. mips2c gives - -```C -void func_80C10590(PlayState* play, s32 limbIndex, Actor *actor) { - if (limbIndex == 5) { - Matrix_RotateYS((s16) (0x400 - actor->unk2AE), 1); - Matrix_MultVecX(500.0f, (Vec3f *) &actor->focus); - } -} -``` - -There is only minor cleanup needed here: - -- recasting the last argument, -- replacing the last argument of `Matrix_RotateYS` by the enum `MTXMODE_APPLY` (which means "use the current matrix instead of starting from a new identity matrix"), and the first argument by `0x400 - this->unk_2AE.x`. -- `(Vec3f *) &actor->focus` to `&actor->focus.pos` (this is the same issue as `(Actor*)this`, where mips2c doesn't climb deep enough into the struct). - -```C -void func_80C10590(PlayState* play, s32 limbIndex, Actor *thisx) { - EnRecepgirl* this = THIS; - - if (limbIndex == 5) { - Matrix_RotateYS(0x400 - this->unk_2AE.x, MTXMODE_APPLY); - Matrix_MultVecX(500.0f, &this->actor.focus.pos); - } -} -``` - -## Some more examples: ObjTree - -Since EnRecepgirl was a bit light on graphics macros, we will look at an example that has a few more. A nice simple one is `ObjTree_Draw`: the original mips2c output is - -```C -void ObjTree_Draw(Actor* thisx, PlayState* play) { - s16 sp36; - s16 sp34; - Gfx *sp28; - Gfx *sp20; - Gfx *temp_v0; - Gfx *temp_v0_2; - Gfx *temp_v0_3; - Gfx *temp_v0_4; - GraphicsContext *temp_a0; - GraphicsContext *temp_s0; - - sp36 = (s16) (s32) (f32) thisx->shape.rot.x; - sp34 = (s16) (s32) (f32) thisx->shape.rot.z; - temp_a0 = play->state.gfxCtx; - temp_s0 = temp_a0; - Gfx_SetupDL25_Opa(temp_a0); - temp_v0 = temp_s0->polyOpa.p; - temp_s0->polyOpa.p = temp_v0 + 8; - temp_v0->words.w0 = 0xDA380003; - sp28 = temp_v0; - sp28->words.w1 = Matrix_NewMtx(play->state.gfxCtx); - temp_v0_2 = temp_s0->polyOpa.p; - temp_s0->polyOpa.p = temp_v0_2 + 8; - temp_v0_2->words.w1 = (u32) &D_06000680; - temp_v0_2->words.w0 = 0xDE000000; - Matrix_RotateZYX(sp36, 0, sp34, 1); - temp_v0_3 = temp_s0->polyOpa.p; - temp_s0->polyOpa.p = temp_v0_3 + 8; - temp_v0_3->words.w0 = 0xDA380003; - sp20 = temp_v0_3; - sp20->words.w1 = Matrix_NewMtx(play->state.gfxCtx); - temp_v0_4 = temp_s0->polyOpa.p; - temp_s0->polyOpa.p = temp_v0_4 + 8; - temp_v0_4->words.w1 = (u32) &D_060007C8; - temp_v0_4->words.w0 = 0xDE000000; -} -``` - -We can see there are four blocks here, although only two different macros: - -```C - temp_v0 = temp_s0->polyOpa.p; - temp_s0->polyOpa.p = temp_v0 + 8; - temp_v0->words.w0 = 0xDA380003; - sp28 = temp_v0; - sp28->words.w1 = Matrix_NewMtx(play->state.gfxCtx); -``` - -gfxdis gives - -``` -$ gfxdis.f3dex2 -x -g POLY_OPA_DISP++ -d DA38000312345678 -gSPMatrix(POLY_OPA_DISP++, 0x12345678, G_MTX_NOPUSH | G_MTX_LOAD | G_MTX_MODELVIEW); -``` - -so it becomes - -```C -gSPMatrix(POLY_OPA_DISP++, Matrix_NewMtx(play->state.gfxCtx), G_MTX_NOPUSH | G_MTX_LOAD | G_MTX_MODELVIEW); -``` - -```C - temp_v0_2 = temp_s0->polyOpa.p; - temp_s0->polyOpa.p = temp_v0_2 + 8; - temp_v0_2->words.w1 = (u32) &D_06000680; - temp_v0_2->words.w0 = 0xDE000000; -``` - -``` -$ gfxdis.f3dex2 -x -g POLY_OPA_DISP++ -d DE00000012345678 -gSPDisplayList(POLY_OPA_DISP++, 0x12345678); -``` - -so this one is - -```C -gSPDisplayList(POLY_OPA_DISP++, D_06000680); -``` - -```C - temp_v0_3 = temp_s0->polyOpa.p; - temp_s0->polyOpa.p = temp_v0_3 + 8; - temp_v0_3->words.w0 = 0xDA380003; - sp20 = temp_v0_3; - sp20->words.w1 = Matrix_NewMtx(play->state.gfxCtx); -``` - -This is the same as the first one. Indeed, it's identical. - -```C - temp_v0_4 = temp_s0->polyOpa.p; - temp_s0->polyOpa.p = temp_v0_4 + 8; - temp_v0_4->words.w1 = (u32) &D_060007C8; - temp_v0_4->words.w0 = 0xDE000000; -``` - -This is the same as the second one, but with a different second word. - -Tidying up and inserting `OPEN_DISPS` and `CLOSE_DISPS`, we end up with - -```C -void ObjTree_Draw(Actor* thisx, PlayState* play) { - s16 sp36 = (f32) thisx->shape.rot.x; - s16 sp34 = (f32) thisx->shape.rot.z; - - OPEN_DISPS(play->state.gfxCtx); - - Gfx_SetupDL25_Opa(play->state.gfxCtx); - gSPMatrix(POLY_OPA_DISP++, Matrix_NewMtx(play->state.gfxCtx), G_MTX_NOPUSH | G_MTX_LOAD | G_MTX_MODELVIEW); - gSPDisplayList(POLY_OPA_DISP++, D_06000680); - - Matrix_RotateZYX(sp36, 0, sp34, MTXMODE_APPLY); - gSPMatrix(POLY_OPA_DISP++, Matrix_NewMtx(play->state.gfxCtx), G_MTX_NOPUSH | G_MTX_LOAD | G_MTX_MODELVIEW); - gSPDisplayList(POLY_OPA_DISP++, D_060007C8); - - CLOSE_DISPS(play->state.gfxCtx); -} -``` - -## RGB macros and bitpacking - -TODO: find some examples for this one. - -For even more examples, you can consult [the OoT tutorial](https://github.com/zeldaret/oot/blob/main/docs/tutorial/draw_functions.md) - -Next: [Data](data.md) diff --git a/mm/docs/tutorial/images/EnRecepgirl_Init_diff_matching.png b/mm/docs/tutorial/images/EnRecepgirl_Init_diff_matching.png deleted file mode 100644 index 9fc473019..000000000 Binary files a/mm/docs/tutorial/images/EnRecepgirl_Init_diff_matching.png and /dev/null differ diff --git a/mm/docs/tutorial/images/EnRecepgirl_stack_diff.png b/mm/docs/tutorial/images/EnRecepgirl_stack_diff.png deleted file mode 100644 index c5de5f366..000000000 Binary files a/mm/docs/tutorial/images/EnRecepgirl_stack_diff.png and /dev/null differ diff --git a/mm/docs/tutorial/images/En_Recepgirl.gv.png b/mm/docs/tutorial/images/En_Recepgirl.gv.png deleted file mode 100644 index fe3040869..000000000 Binary files a/mm/docs/tutorial/images/En_Recepgirl.gv.png and /dev/null differ diff --git a/mm/docs/tutorial/images/broken_texture.png b/mm/docs/tutorial/images/broken_texture.png deleted file mode 100644 index 6f79f1872..000000000 Binary files a/mm/docs/tutorial/images/broken_texture.png and /dev/null differ diff --git a/mm/docs/tutorial/images/custom_texture_in_game.png b/mm/docs/tutorial/images/custom_texture_in_game.png deleted file mode 100644 index 92fa53811..000000000 Binary files a/mm/docs/tutorial/images/custom_texture_in_game.png and /dev/null differ diff --git a/mm/docs/tutorial/images/dns_custom_texture.png b/mm/docs/tutorial/images/dns_custom_texture.png deleted file mode 100644 index 3b8cf4d57..000000000 Binary files a/mm/docs/tutorial/images/dns_custom_texture.png and /dev/null differ diff --git a/mm/docs/tutorial/images/fresh_actor_data.png b/mm/docs/tutorial/images/fresh_actor_data.png deleted file mode 100644 index c887ce451..000000000 Binary files a/mm/docs/tutorial/images/fresh_actor_data.png and /dev/null differ diff --git a/mm/docs/tutorial/images/func_80C100DC_diff1.png b/mm/docs/tutorial/images/func_80C100DC_diff1.png deleted file mode 100644 index 1f899b1b5..000000000 Binary files a/mm/docs/tutorial/images/func_80C100DC_diff1.png and /dev/null differ diff --git a/mm/docs/tutorial/images/func_80C100DC_diff2.png b/mm/docs/tutorial/images/func_80C100DC_diff2.png deleted file mode 100644 index db4404d8f..000000000 Binary files a/mm/docs/tutorial/images/func_80C100DC_diff2.png and /dev/null differ diff --git a/mm/docs/tutorial/images/func_80C100DC_diff3.png b/mm/docs/tutorial/images/func_80C100DC_diff3.png deleted file mode 100644 index b0d25c693..000000000 Binary files a/mm/docs/tutorial/images/func_80C100DC_diff3.png and /dev/null differ diff --git a/mm/docs/tutorial/images/func_80C102D4_diff1.png b/mm/docs/tutorial/images/func_80C102D4_diff1.png deleted file mode 100644 index 2b4147999..000000000 Binary files a/mm/docs/tutorial/images/func_80C102D4_diff1.png and /dev/null differ diff --git a/mm/docs/tutorial/images/func_80C102D4_diff2.png b/mm/docs/tutorial/images/func_80C102D4_diff2.png deleted file mode 100644 index 0fefcb43c..000000000 Binary files a/mm/docs/tutorial/images/func_80C102D4_diff2.png and /dev/null differ diff --git a/mm/docs/tutorial/images/z64utils_dns_deku_flower.png b/mm/docs/tutorial/images/z64utils_dns_deku_flower.png deleted file mode 100644 index 66b40a3fd..000000000 Binary files a/mm/docs/tutorial/images/z64utils_dns_deku_flower.png and /dev/null differ diff --git a/mm/docs/tutorial/images/z64utils_dns_display_list.png b/mm/docs/tutorial/images/z64utils_dns_display_list.png deleted file mode 100644 index 31cbd5794..000000000 Binary files a/mm/docs/tutorial/images/z64utils_dns_display_list.png and /dev/null differ diff --git a/mm/docs/tutorial/images/z64utils_dns_head_limb.png b/mm/docs/tutorial/images/z64utils_dns_head_limb.png deleted file mode 100644 index dcb658fe8..000000000 Binary files a/mm/docs/tutorial/images/z64utils_dns_head_limb.png and /dev/null differ diff --git a/mm/docs/tutorial/images/z64utils_dns_limb_dlist.png b/mm/docs/tutorial/images/z64utils_dns_limb_dlist.png deleted file mode 100644 index 0f24d0225..000000000 Binary files a/mm/docs/tutorial/images/z64utils_dns_limb_dlist.png and /dev/null differ diff --git a/mm/docs/tutorial/images/z64utils_dns_skeletonheader.png b/mm/docs/tutorial/images/z64utils_dns_skeletonheader.png deleted file mode 100644 index 4f0222673..000000000 Binary files a/mm/docs/tutorial/images/z64utils_dns_skeletonheader.png and /dev/null differ diff --git a/mm/docs/tutorial/images/z64utils_main.png b/mm/docs/tutorial/images/z64utils_main.png deleted file mode 100644 index 972c9c4a5..000000000 Binary files a/mm/docs/tutorial/images/z64utils_main.png and /dev/null differ diff --git a/mm/docs/tutorial/images/z64utils_object_analyzed.png b/mm/docs/tutorial/images/z64utils_object_analyzed.png deleted file mode 100644 index 9a2de8dac..000000000 Binary files a/mm/docs/tutorial/images/z64utils_object_analyzed.png and /dev/null differ diff --git a/mm/docs/tutorial/images/z64utils_open_dns.png b/mm/docs/tutorial/images/z64utils_open_dns.png deleted file mode 100644 index 84533270e..000000000 Binary files a/mm/docs/tutorial/images/z64utils_open_dns.png and /dev/null differ diff --git a/mm/docs/tutorial/images/z64utils_set_segment_8.png b/mm/docs/tutorial/images/z64utils_set_segment_8.png deleted file mode 100644 index 46b2f1cff..000000000 Binary files a/mm/docs/tutorial/images/z64utils_set_segment_8.png and /dev/null differ diff --git a/mm/docs/tutorial/images/z64utils_skeleton_error.png b/mm/docs/tutorial/images/z64utils_skeleton_error.png deleted file mode 100644 index 821ff69f6..000000000 Binary files a/mm/docs/tutorial/images/z64utils_skeleton_error.png and /dev/null differ diff --git a/mm/docs/tutorial/images/z64utils_skeleton_head.png b/mm/docs/tutorial/images/z64utils_skeleton_head.png deleted file mode 100644 index 263f06642..000000000 Binary files a/mm/docs/tutorial/images/z64utils_skeleton_head.png and /dev/null differ diff --git a/mm/docs/tutorial/intro_to_git.md b/mm/docs/tutorial/intro_to_git.md deleted file mode 100644 index e6f3c5a8f..000000000 --- a/mm/docs/tutorial/intro_to_git.md +++ /dev/null @@ -1,402 +0,0 @@ -# Introduction to git for decomp - -`git` is a version control system: it allows you to keep different versions of files at the same time. It does this using a tree system: - -- A *repository* is directory containing files managed by git. -- A repository has one or more *branches*. A branch can be thought of as a pointer to a specific commit. -- A *commit* is one set of changes, the most basic "unit" when working with git. The key point about git is that it is possible to have several commits based on the same one -- A *remote* is another copy of the same repository, usually on another computer or the Internet. - -For example, - -```bash -Remote ----o---o---o---o - -Local - main - v ----o---o---o---o - \ - o---o - ^ - A -``` - -Each `o` is a commit. The lines show the commit that each commit was based on: we can see in the local there is one commit with two commits based on it. The local has two branches, `main` and `A`, and they currently both point to the commits furthest along their respective chains. - -Throughout this guide, stuff in `SCREAMING_SNAKE_CASE` represents fields for you to fill in with the appropriate text, e.g. FILE should be replaced with a particular filename. - -## Setting up git - -If you are on an ordinary Linux distribution (i.e. not Arch or similar) or WSL, you probably already have git installed, and if not, can get it by running `sudo apt install git` in a terminal window. - -git commits are signed with the committer's name and email (if you don't want an actual email address attached to it, GitHub will generate a fake one for you). To set these up for any repository you work on, run - -```bash -git config --global user.name "NAME" -git config --global user.email "EMAIL_ADDRESS" -``` - -(omitting `--global` will set these only for the repository in the current folder). - -To make a new repository in a directory: - -```bash -git init -``` - -The repository is considered to have the same name as the directory in which it lives. - -The default branch is set to be called `main`. If you want to call it something else, do - -```bash -git init -b DEFAULT_BRANCH_NAME -``` - -Usually when working on decomp you will instead be cloning a repository from GitHub, though. - -## Cloning a repository from GitHub - -```bash -git clone REMOTE_URL -``` - -This will clone the repository associated with that URL into a subdirectory of the one you are currently in, with a name based on the repository name. For example, - -```bash -git clone git@github.com:zeldaret/mm.git -``` - -will clone the MM repository into the subdirectory `mm`. - -git will automatically name the original remote as `origin`, so for decomp you probably want to use a different name so your own fork on GitHub is `origin`. You can do this: - -```bash -git clone -o REMOTE_NAME REMOTE_URL -``` - -so - -```bash -git clone -o upstream git@github.com:zeldaret/mm.git -``` - -## Configuring remotes - -View all remotes associated to this repository. Each remote has a name and an address. - -```bash -git remote -v -``` - -Rename remote `OLD` to `NEW` - -```bash -git remote rename OLD NEW -``` - -Add a new remote - -```bash -git remote add NAME URL -``` - -For example, a typical workflow to get a repository from GitHub is to fork it, then - -```bash -git clone -o upstream git@github.com:zeldaret/mm.git -cd mm -git add git@github.com:yourgithubaccount/mm.git -``` - -## Managing branches - -You should always work on a branch, to retain a clean copy of the repository that you know works on the main/main branch, and to enable you to switch between unrelated work easily. - -To list the branches you currently have: - -```bash -git branch -``` - -To make a new branch: - -```bash -git branch NEW_BRANCH_NAME -``` - -To change branch: - -```bash -git checkout BRANCH_NAME -``` - -To make a new branch and change to it in one command: - -```bash -git checkout -b NEW_BRANCH_NAME -``` - -To delete a branch (e.g. if definitely no longer needed) - -```bash -git branch -d BRANCH_NAME -``` - -## Committing - -To make git remember your changes, you need to make a commit. Ordinarily a commit applies to only files that are *staged*. - -To add files to staging: - -```bash -git add FILES -``` - -To commit staged files: - -```bash -git commit -``` - -This will open a text editor to write a commit message. It is generally expected that commit messages are informative and short. If you want to write the commit message in the terminal instead, - -```bash -git commit -m "COMMIT_MESSAGE" -``` - -To unstage a file (but keep the changes) - -```bash -git reset FILE -``` - -(To unstage everything, `git reset`) - -To revert a file to its state at the last commit: - -```bash -git reset --hard FILE -``` - -## Merging and Rebasing - -Having worked separately on a branch A, you often want to incorporate changes from branch B into branch A. Considering the tree/commit structure, there are two possible ways to do this: - -- Stick the two branches back together at their current commits. This is called *merging* B into A: diagrammatically, - -```bash ----o---o---o---o A - \ - o---o---o B -``` - -to - -```bash ----o---o---o---o---m A - \ / - o-----o-----o B -``` - -where `m` is a *merge commit*. - -- Go back to the common ancestor of A and B, take all the commits on A since then, and attempt to apply them to the tip of B. This is called *rebasing* A on B. - -```bash ----o---o---o---o A - \ - o---o---o B -``` - -to - -```bash ----o - \ - o---o---o---o---o---o A - ^ - B -``` - -(Notice that in neither case is B itself destroyed.) - -Both have advantages and disadvantages. - -- Merging is conceptually simpler, but generates an additional commit. -- Rebasing results in cleaner history and is usually easier to do because there are fewer changes in each commit, but makes it much harder to follow what has changed between commits before and after: *you should not rebase a branch other people are looking at* (e.g. in GitHub reviews, but also in other collaboration). - -If you realise you have made a mistake while still merging, you can run - -```bash -git merge --abort -``` - -or - -```bash -git rebase --abort -``` - -as appropriate to stop attempting to merge/rebase. - -As such, if you only want to learn one of these, learn merging. - -### Conflict resolution - -If the two branches have both touched the same or nearby lines, git will not know which you want to keep. It will therefore pause the merge/rebase and tell you to decide. You will find a section of the file that looks like this: - -```bash -<<<<<<< A -Some code -======= -Some other code ->>>>>>> B -``` - -from which you should pick one (or combine parts of both as appropriate), then delete the rest. (You definitely do not want the git artefacts left in!) - -Notice also that the changes are applied in opposite ways in each case: merging B into A, the incoming changes are from B, whereas when rebasing, they come from A. *This means the conflict resolution in one is in the opposite order from the other.* - -## Keeping up to date with remotes - -To update git's information about remotes: - -```bash -git fetch REMOTE_NAME -``` - -Not specifying `REMOTE_NAME` will fetch from the remote with the branch that tracks the current one. - -To fetch a remote branch's changes and merge them into the current branch: - -```bash -git pull REMOTE_NAME BRANCH_NAME -``` - -To fetch and rebase the current branch on a remote branch: - -```bash -git pull --rebase REMOTE_NAME BRANCH_NAME -``` - -It's generally better to use fetch and then merge/rebase separately, though, at least until you're more experienced with git. - -To update a remote with changes from the current branch: - -```bash -git push -``` - -To send changes ignoring any changes to the remote branch since local and remote went out of sync, - -```bash -git push --force -``` - -To push a new branch to a remote and set up a branch that *tracks* it on there, you need to specify which remote to push it to: - -```bash -git branch -u REMOTE_NAME -``` - -## Stashing - -You may want to store your current changes without actually committing thhem, for example if you're halfway through something but want new changes from a remote. Running - -```bash -git stash -``` - -will save changes to a "stash" that can be applied later, even to a different branch, with - -```bash -git stash apply -``` - -which keeps the stash, or - -```bash -git stash pop -``` - -which applies, and deletes it if application was successful. - -You can also name and delete stashes and so on. - -## Repository information - -To get general information about what branch you are on, staged and modified files: - -```bash -git status -``` - -This will also indicate any files with merge conflicts. - -To see a line-by-line description of the changes currently made: - -```bash -git diff -``` - -(you can also diff 2 branches or 2 commits) - -git's most general and powerful information command is `log`, which is far too extensive to cover here. - -## GitHub - -Things are a little different on GitHub compared to working locally. - -To make your own copy of a repository, click `Fork`. - -Most repositories do not let people push to them directly. Instead, you make a Pull Request (PR) for merging your branch into one of theirs: this also allows other people to review your work. A Pull Request cannot be merged unless it has no conflicting files. We also use a continuous integration system called Jenkins to ensure that the branch's files are correctly formatted, the it builds the rom correctly, and produces no new warnings; this will usually automatically run whenever you push new changes. - -*A branch used for a PR is a public branch, so do not rebase it.* Apart from the usual problems with other people looking at your changes, it will detach all the GitHub review comments from where they are in the code. - -It is possible to fix merge conflicts on GitHub, but not recommended. GitHub can do a few other git-related things, but most of the time it's just simpler to do it locally. - -### Fetch and Merge - -To fetch and merge on GitHub, navigate to your personal fork of the repository `(e.g. github.com//mm)`. On this page there is a bar that will state whether or not the repository is up to date or not. If it is not up to date it will inform what is different. On the right side of that bar there is a drop down menu labeled "Fetch upstream", you can click this and there will be a button to "Fetch and Merge". Once this is done a `git pull` can be done locally to get all the new changes. - -### Code Reviews - -GitHub has the ability to review changes in a pull request one file at a time. When reviewing, you can review specific changes or comment on the file overall. To start a review: - -- Go to the repository and click "Pull Requests" - -- Click on a pull request to review - -On the conversation tab you can leave general comments and reply to any other comments that have been made. - -On the "Files changed" tab you will see the files changed in the pull request. You can change the format of the diff view in this tab by clicking the gear and choosing the unified or split view. - -To leave a comment, hover over the line of code where you'd like to add a comment, and click the blue "+" icon. To comment on a block of multiple lines, click and drag the range of lines you wish to comment, then click the blue icon. - -Optionally, to suggest a specific change to the line(s) , click the `+/-` icon then edit the text within the suggestion block. - -Once finished, click the "Review changes" and type a comment summarizing proposed changes and comments. - -### Giving credit to others - -If you want to credit other people who have contributed to a PR you have made, you can use the "Co-authored-by" - -```bash -NORMAL_COMMIT_MESSAGE - -Co-authored-by: GITHUB_USERNAME -``` - -Note the blank line and the `<>` around the email. More information on precisely how to do this can be found in GitHub's own docs: - -## More information - -This guide has only covered the basics that are required to work with git on a decomp repository. For more information - -- Run a command with `--help` -- Ask in Discord -- consult a reference such as https://git-scm.com/docs or https://www.atlassian.com/git/tutorials - -*Always ask or research before doing anything drastic, git is sophisticated enough that usually it has a way to resolve problems itself* diff --git a/mm/docs/tutorial/introduction.md b/mm/docs/tutorial/introduction.md deleted file mode 100644 index 58a74fbb4..000000000 --- a/mm/docs/tutorial/introduction.md +++ /dev/null @@ -1,89 +0,0 @@ -# Introduction - -In this project, we are decompiling The Legend of Zelda: Majora's Mask. This means that we take the assembly language that is on the cartridge, - -``` -glabel func_809529AC -/* 00038C 809529AC 27BDFFE0 */ addiu $sp, $sp, -0x20 -/* 000390 809529B0 AFBF001C */ sw $ra, 0x1c($sp) -/* 000394 809529B4 AFA40020 */ sw $a0, 0x20($sp) -/* 000398 809529B8 0C02E27E */ jal Actor_HasParent -/* 00039C 809529BC AFA50024 */ sw $a1, 0x24($sp) -/* 0003A0 809529C0 8FA40020 */ lw $a0, 0x20($sp) -/* 0003A4 809529C4 1040000C */ beqz $v0, .L809529F8 -/* 0003A8 809529C8 8FA50024 */ lw $a1, 0x24($sp) -/* 0003AC 809529CC A4800116 */ sh $zero, 0x116($a0) -/* 0003B0 809529D0 8C860098 */ lw $a2, 0x98($a0) -/* 0003B4 809529D4 8C87009C */ lw $a3, 0x9c($a0) -/* 0003B8 809529D8 AFA40020 */ sw $a0, 0x20($sp) -/* 0003BC 809529DC 0C02E140 */ jal Actor_OfferTalkExchange -/* 0003C0 809529E0 AFA00010 */ sw $zero, 0x10($sp) -/* 0003C4 809529E4 8FA40020 */ lw $a0, 0x20($sp) -/* 0003C8 809529E8 3C0E8095 */ lui $t6, %hi(func_80952A1C) -/* 0003CC 809529EC 25CE2A1C */ addiu $t6, $t6, %lo(func_80952A1C) -/* 0003D0 809529F0 10000006 */ b .L80952A0C -/* 0003D4 809529F4 AC8E01F4 */ sw $t6, 0x1f4($a0) -.L809529F8: -/* 0003D8 809529F8 C484009C */ lwc1 $f4, 0x9c($a0) -/* 0003DC 809529FC 8C870098 */ lw $a3, 0x98($a0) -/* 0003E0 80952A00 24060035 */ addiu $a2, $zero, 0x35 -/* 0003E4 80952A04 0C02E287 */ jal Actor_OfferGetItem -/* 0003E8 80952A08 E7A40010 */ swc1 $f4, 0x10($sp) -.L80952A0C: -/* 0003EC 80952A0C 8FBF001C */ lw $ra, 0x1c($sp) -/* 0003F0 80952A10 27BD0020 */ addiu $sp, $sp, 0x20 -/* 0003F4 80952A14 03E00008 */ jr $ra -/* 0003F8 80952A18 00000000 */ nop -``` - -(the commented numbers on the left are the original machine code, the middle the translation into MIPS assembly, the right useful information about the numbers in the code) -and turn it into compilable C code: - -```C -void func_809529AC(EnMs* this, PlayState* play) { - if (Actor_HasParent(&this->actor, play)) { - this->actor.textId = 0; - Actor_OfferTalkExchange(&this->actor, play, this->actor.xzDistToPlayer, this->actor.playerHeightRel, 0); - this->actionFunc = func_80952A1C; - } else { - Actor_OfferGetItem(&this->actor, play, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel); - } -} -``` - -which is intended to be as close to the original code as we can get just by looking at the assembly. We are doing *matching* decomp: in the right context, and with the right compiler settings, the above C compiles into *precisely* the assembly code above, not just equivalent code. - -N.B. We are using only publicly available code. In particular, we are not looking at any of the recent Nintendo source code leaks. - -Progress of the project can be found at [https://zelda64.dev]. The long-term goal of this project is to obtain a complete compilable version of the code for every publicly released version of Majora's Mask (in the same way as the Ocarina of Time project and many other Zelda games). *We are not working on a PC Port, and neither this project nor the ZeldaRET organisation will not be making one*, although the resulting code will be very useful if someone does intend to make such a port. - -Most of the discussion on the project takes place on the Zelda Decompilation Discord (linked in the [README.md](../../README.md)). We are very welcoming to newcomers and are happy to help you with any problems you might have with the decompilation process. - -## What do I need to know to take part? - -Basic knowledge of C, particularly arrays and pointers, is extremely useful. Knowledge of MIPS is not required initially, but if you are serious about decompilation you will soon pick up a lot of it. - -Knowledge of the fundamentals of git and GitHub is required. There are a number of tutorials available online, and a later document in this tutorial describes how you contribute to this project outside the actual decompilation process. - -The most useful knowledge to have is a general understanding of how the game works. An afternoon of constructive mucking about in the [Practice Rom](https://kz.zeldacodes.org/) (aka KZ) will be very beneficial if you have not looked at the game's subsurface workings before. - -## Structure of the code - -A lot of work has already been done on the code to bring it into a format that is easy to decompile. I will discuss actors, since this is where the majority of new people should begin. - -An *actor* is any thing in the game that moves or performs actions or interactions: Link is an actor, enemies are actors, NPCs are actors, props like grass are actors. The vast majority of actors are *overlays*, which means they are loaded only when the game needs them. - -In the code, each actor is associated to several files: there is - -- the main .c file, e.g. `src/overlays/actors/ovl_En_Ms/z_en_ms.c` -- the actor's Header file, e.g. `src/overlays/actors/ovl_En_Ms/z_en_ms.h` -- various .o files that tell the `make` script how to incorporate it into building the ROM, - -and then for undecompiled actors, various assembly (.s) files, generally including: - -- one for the actor's *data* (this usually includes things like its collision information about how to draw it, and various other stuff that is used in it), e.g. `data/overlays/actors/ovl_En_Ms.data.s` -- one for each function in the actor, e.g. `asm/non_matchings/overlays/actors/ovl_En_Ms/func_809529AC.s` - -(In this project, all assembly code and asset files are extracted from a user-provided ROM: if you look in the GitHub repository, you will see that only decompiled source code is present.) - -The basic process of decomp is to take one or more of the .s files, run it through a decompilation program (mips_to_c) that reads the ASM very literally, and then, through human ingenuity, reshape it into code that not only compiles in the first place, but completely matches the assembly generation of the original code (well-written or otherwise; it's also very likely that our constructed code differs significantly from the original, even if it still compiles to the same thing). diff --git a/mm/docs/tutorial/merging.md b/mm/docs/tutorial/merging.md deleted file mode 100644 index 88664494d..000000000 --- a/mm/docs/tutorial/merging.md +++ /dev/null @@ -1,94 +0,0 @@ -# The merging process - -- Up: [Contents](contents.md) -- Previous: [Documenting](documenting.md) - -## Preparing to PR - -### Change the `spec` - -Specifically, to use the automatically generated reloc, rather than the original. In the case of an entirely matched actor, you find the section relating to the actor that you edited before: - -``` -beginseg - name "ovl_En_Recepgirl" - include "build/src/overlays/actors/ovl_En_Recepgirl/z_en_recepgirl.o" - //include "build/data/overlays/actors/ovl_En_Recepgirl.data.o" - include "build/data/overlays/actors/ovl_En_Recepgirl.reloc.o" -endseg -``` - -and change to use our reloc: - -``` -beginseg - name "ovl_En_Recepgirl" - include "build/src/overlays/actors/ovl_En_Recepgirl/z_en_recepgirl.o" - include "build/src/overlays/actors/ovl_En_Recepgirl/ovl_En_Recepgirl_reloc.o" -endseg -``` - -(copy the path, then copy the directory name and put `_reloc.o` after it). - -### Non-matchings - -If you can't match a function even with everyone's help in the `mm-decomp-help` discord channel, don't worry overlong about it. Hopefully you can get it to do the same thing as the original (non-matching), and then you set it up to use the original asm for the matching build, and your code for the non-matching. This looks like - -```c -#ifdef NON_MATCHING -// Helpful comment about the nature of the nonmatching -void function() { - // ... -} -#else -#pragma GLOBAL_ASM(asm/.../function.s) -#endif -``` - -in the C file. Also, due to the way `GLOBAL_ASM` works, we also cannot use generated reloc for overlays with nonmatchings, so we have to do the same thing for the reloc file in the spec: - -``` -beginseg - name "ovl_En_Recepgirl" - compress - include "build/src/overlays/actors/ovl_En_Recepgirl/z_en_recepgirl.o" -#ifdef NON_MATCHING - include "build/src/overlays/actors/ovl_En_Recepgirl/ovl_En_Recepgirl_reloc.o" -#else - include "build/data/overlays/actors/ovl_En_Recepgirl.reloc.o" -#endif -endseg -``` - -Ideally you should at least be able to get a function to have equivalent behaviour; if not, and you have exhausted all other avenues of getting help, it should be marked in the C file as `NON_EQUIVALENT`, in the same way as a nonmatching. We do not change the spec for non-equivalents: they are treated the same as undecompiled code from a building perspective, lest they break things. - -### Format - -Run the formatting script `format.py`, to format the C files in the standard way we use. If you have some arrays or struct definitions in your file, check that they have not been obnoxiously padded out: you can usually get a better format without a final comma for short things. - -**N.B.** this is now essential: the CI will fail immediately if it detects files that change when formatted. - -### Merge main - -To make sure the PR builds correctly with the current main, you need to merge `upstream/main` before you make the PR. This tends to break things, that you have to fix to get it to compile correctly again. - -## Pull Requests - -Push commits to your fork of the repository on GitHub, and then open a pull request. Name the PR something sensible, like - -- `EnRecepgirl OK and documented` (if all the functions match and your documentation is fairly complete) -- `EnRecepgirl OK` (if all the functions match) -- `EnRecepgirl (n nonmatching)` (if you couldn't get one or more functions to match, but to the best of your knowledge they are equivalent code) -- `EnRecepgirl (n nonequivalent)` (if you couldn't get one or more functions to match, and do not believe the code in them has the same effect) - -and so on, although these four tend to cover most cases. Feel free to add a comment describing anything interesting you had to do or issues in non-matchings. - -Please also update the status of the file on Trello/the spreadsheet. - -### Reviews - -Pull requests may be reviewed by anyone (who knows enough about the conventions of the project), and all must be reviewed and approved by two leads and one extra contributor. - -To implement suggestions made in reviews, it is generally easier to be consistent if you push more commits from your local branch. It is also quite possible that in the meantime some other PR has gone in, and git will ask you to merge main before you add more commits. This is normally fairly painless, although often you have to resolve merge conflicts. If in doubt, backup your work before doing anything, and ask in Discord before doing anything drastic, or if you don't understand what git is telling you. - -There is no need to wait for your PR to be approved and committed before working on your next file. diff --git a/mm/docs/tutorial/object_decomp.md b/mm/docs/tutorial/object_decomp.md deleted file mode 100644 index c33d5dba1..000000000 --- a/mm/docs/tutorial/object_decomp.md +++ /dev/null @@ -1,161 +0,0 @@ -# Object Decompilation - -- Up: [Contents](contents.md) -- Previous: [Documenting](documenting.md) - -Object decompilation is the process of taking an object file and writing instructions to extract the various assets from it in the correct format, with appropriate labelling to distinguish their nature and/or use. - -## What is an object file? - -An object file is generally where most of the information used by overlays is stored. Its contents can include - -- Vertices (positional/normal/color data used by displaylists) -- Textures -- DisplayLists (instructions to the graphics processor on how to put together textures and vertices) -- Skeleton (The underlying structure of an actor's shape, that can be manipulated to change its "pose") -- Animations -- Texture Animations (instructions to scroll/cycle textures or change colors) - -## How we work with objects - -These objects are considered assets so they are not included in the repository directly. Instead we use the Zelda Asset Processor for Decompilation (ZAPD) to extract them from the ROM. As input, ZAPD takes an XML file that describes what and how to extract. Each object already has an autogenerated XML created in the `assets/xml/objects` directory, though they are incomplete with just autogenerated names. The goal of object decompilation is to complete these files by identifying any remaining blobs and giving everything proper names. - -## How to decomp an object - -Choose an object to decomp. As usual, some will be easier than others. For reasons explained shortly, it is much easier to decomp an object if all actors that use it are decompiled. - -### Files and folders - -Select the XML file of your selected object, which should be in `assets/xml/objects/object_name.xml`. - -The ZAPD output will go in the folder `assets/objects/object_name/`. You'll want this folder open later to check the output is correct. - -### Examining actor files - -All objects have had their XML generated in an automated way, so most constituent parts of each object are already identified, but will still need to be named and documented properly. Further, these objects usually have some blobs unreferenced by the object's own contents and hence not automatically extracted; most of the time these can be identified by looking at references in the actor which uses said object. - -### Extracting assets - -You can run `extract_assets.py` to extract the object's assets. Running it with no arguments extracts all files that have been updated since the last time it was run. You can also run it with `-s` (for single file), and give it the location of the object you want to extract relative to `assets`, i.e. - -```bash -./extract_assets.py -s objects/object_name -``` - -This should populate the folder you created earlier. ZAPD produces a C file containing the extracted object data, which will be `assets/objects/object_name/object_name.c`. Any data that you have not specified the type of, or is not referenced elsewhere in the object, is extracted as unknown blobs (usually named `unaccounted_XXXXXX`). Open the C file to see if there are any such blobs. (Some are just padding with 0s and can be ignored.) - -You now have to try and decipher these blobs using the [list of tools given below](#tools) to work out what they might be. In the case of unused parts of the object, this can be very difficult. - -### Naming - -You'll want to name everything that exists in the XML, but it helps to break it down into separate steps. After each step, extract the single asset again. - -1. First, name every piece of data that is directly accessed by another part of the repo (generally, but not always, actors). For most objects, this includes several of a skeleton, animations, some textures, and collision information. - -2. Then, name the limbs associated with each skeleton. This is usually straightforward, providing Z64Utils can show the skeleton properly. Note that when naming limbs, you should name them *from the object's perspective*, so the "left arm" is the one that is to the *object's* left. As part of this step, you should also replace the autogenerated enum values associated with each limb with an appropriate name. Another thing to note is that some limbs are considered "Root" limbs that are simply parents to other limbs and don't actually render anything themselves. In these cases, you can simply add `Root` to the limb name, e.g., `gGibdoRightLegRootLimb`. - -3. Next, name the display lists that are associated to limbs in the skeleton. Z64Utils can show you which display list is associated with a given limb. - -4. If any non-limb display lists still lack a name, try naming them now. - -5. Lastly, try to name every texture in the object. This can be a bit tricky just by looking at the textures, so it helps to see how they're used in the display lists. You can also try manipulating the textures, recompiling the game, and loading up the resulting ROM to see what your changes look like in-game. - -You'll notice that we didn't mention vertices in this list. This is because, for the most part, vertices are not used outside the object itself, and so are not required to have names. However, some actors have code that manipulates or otherwise interacts with vertices; in these cases, the vertices should be added to the XML and named. - -Current naming practice is to name each item in the xml using camelCase as usual, with the `g` prefix (for "global"), and the type of data last (`Skel`, `Anim`, `DL`, `Tex`, `TLUT`, `Vtx`, `TexAnim`, etc.), while output texture files are named in `snake_case`. TLUTs (texture look-up tables) should always have their output file end in `tlut`. For more info on which suffixes to use, check out the [ZAPD documentation on extraction XML](https://github.com/zeldaret/mm/blob/main/tools/ZAPD/docs/zapd_extraction_xml_reference.md). - -### Textures - -Since all objects have an autogenerated XML, most textures in the game already have an entry in an XML file. However, some did not get automatically detected, and textures can be especially troublesome due to the abundance of formats they can be in. Some are simple RGBA textures, while others use external palettes, and can look meaningless without. If the texture is used in a displaylist, it will tell you the format, but if not, you have to use your best judgement based on anything you know about its context. - -The order of operations is that palettes are loaded first, then the texture, and then the vertices to which it is applied. - -The first argument of `gsDPLoadTextureBlock` tells you the offset, the second the format, the third the bit depth, fourth the width and fifth the height - -The following is a list of the texture formats the Nintendo 64 supports, with their gfxdis names and ZAPD format names. - -| Format name | Typing in `gsDPLoadTextureBlock` | "Format" in xml | -| ----------------------------------------------- | -------------------------------- | --------------- | -| 4-bit intensity (I) | `G_IM_FMT_I, G_IM_SIZ_4b` | i4 | -| 4-bit intensity with alpha (I/A) (3/1) | `G_IM_FMT_IA, G_IM_SIZ_4b` | ia4 | -| 4-bit color index (CI) | `G_IM_FMT_CI, G_IM_SIZ_4b` | ci4 | -| 8-bit I | `G_IM_FMT_I, G_IM_SIZ_8b` | i8 | -| 8-bit IA (4/4) | `G_IM_FMT_IA, G_IM_SIZ_8b` | ia8 | -| 8-bit CI | `G_IM_FMT_CI, G_IM_SIZ_8b` | ci8 | -| 16-bit red, green, blue, alpha (RGBA) (5/5/5/1) | `G_IM_FMT_RGBA, G_IM_SIZ_16b` | rgba16 | -| 16-bit IA (8/8) | `G_IM_FMT_IA, G_IM_SIZ_16b` | ia16 | -| 16-bit YUV (Luminance, Blue-Y, Red-Y) | `G_IM_FMT_YUV, G_IM_SIZ_16b` | (not used) | -| 32-bit RGBA (8/8/8/8) | `G_IM_FMT_RGBA, G_IM_SIZ_32b` | rgba32 | - -The 4-bit formats are loaded using `gDPLoadTextureBlock_4b`. The others use `gDPLoadTextureBlock`. - -For example, - -```c -gsDPLoadTextureBlock(D_06006110, G_IM_FMT_RGBA, G_IM_SIZ_16b, 16, 16, 0, G_TX_NOMIRROR | G_TX_CLAMP, G_TX_NOMIRROR | G_TX_CLAMP, 4, 4, 0, 0), -``` - -says that there is a texture at offset `0x6110`, its Format is `rgba16`, Width is `16` and Height is `16`, so we can declare - -```XML - -``` - -See [this web page](http://n64devkit.square7.ch/tutorial/graphics/3/3_3.htm) for more information about these formats, and [gSP functions](http://n64devkit.square7.ch/n64man/gsp/gSP_INDEX.htm) and [gDP functions](http://n64devkit.square7.ch/n64man/gdp/gDP_INDEX.htm) for more about the graphics functions used. - -The `ci` formats use palettes, which are declared separately. The shape you give the palette does not matter, but to avoid overlap errors it needs to fit into a rectangle; choose the one you think looks best, and if in doubt, just do height 1 and appropriate width. - -If in doubt, look at completed objects in the repo, and if still in doubt, ask. - -## Tools - -We are very fortunate that several nice tools have been written recently that are excellent for documenting asset files: - -- [Z64Utils](https://github.com/zeldaret/Z64Utils/releases), for looking at displaylists, textures they reference, the skeleton, animations, etc. -- [Texture64](https://github.com/queueRAM/Texture64/releases), for looking at textures in all the common N64 formats (needed since Z64Utils cannot interpret textures not explicitly referenced in displaylists currently) - -## Building and investigative modding - -Thankfully it is not necessary to do a full make from clean to check that a particular object file has been decompiled successfully. - -- With a valid xml file, run `extract_assets.py -s` on its object. -- `make` - -If you want to change a texture, for example to see precisely where it is used, the following steps ensure it will be used in the build - -- Change and save the texture. You can simply open the texture's PNG file in most image editors (e.g., Photoshop, GIMP, Paint, etc.) and edit it to your liking, though you'll need to keep the original palette in mind for palettized textures. -- Touch the object's main C file (in the same directory) -- make -- Ironically, ERROR 1 implies success (your new texture has changed the checksum). - -If you'd rather not have it tell you about the checksum, you can run `make COMPARE=0` instead. - ---- - -To revert to the original texture, you can just run `extract_assets.py -s` on the object again. - -N.B. doing this will overwrite every custom texture, as will running `make setup`. - -## Example - -An example of decompiling a particular object is given [here](object_decomp_example.md). - -## Tips and Tricks - -### Fixing improper-looking textures - -For CI4 and CI8 textures, you might see improper-looking textures like so: - -![An improper-looking CI8 texture](images/broken_texture.png) - -The reason this happens is because ZAPD couldn't determine the TLUT for the texture, so it couldn't use the proper palette. To fix this, you can supply a `TlutOffset` to the texture like so: - -```xml - -``` - -### Understanding texture animations - -Texture animations are new to Majora's Mask, and they can be pretty tricky to understand. Luckily, there's some extensive documentation on how they're structured [here](https://github.com/zeldaret/mm/blob/main/tools/ZAPD/ZAPD/ZTextureAnimation.cpp). One useful thing to remember is that empty texture animations take the form of `00 00 00 06 00 00 00 00`. The process that automatically generated all the object XMLs sometimes failed to recognize this as an empty texture animation, so it puts it in various blobs or fails to account for it at all. - -Next: [The merging process](merging.md) diff --git a/mm/docs/tutorial/object_decomp_example.md b/mm/docs/tutorial/object_decomp_example.md deleted file mode 100644 index 10fcf2766..000000000 --- a/mm/docs/tutorial/object_decomp_example.md +++ /dev/null @@ -1,282 +0,0 @@ -# Object Decompilation Example - -- Previous: [Object Decompilation](object_decomp.md) - -Let's take a look at `object_dns`, which is a pretty typical NPC object. It's used by one actor: `ovl_En_Dns`. - -## Step 1: Naming the skeleton and limbs - -We already went through the steps of opening an object file in Z64Utils in the [documenting step](documenting.md#z64utils), but we'll do it in more detail here. First, search for the object file, then either double-click on it or right-click it and select "Open in Object Analyzer". It will ask you to choose a segment: this is the segment that the file is put on, and allows Z64Utils to resolve the segmented addresses it references into symbols. The json already knows it should be segment 6, so just click OK. - -![Opening object_dns in Z64Utils](images/z64utils_open_dns.png) - -In the resulting window, you'll see displaylists, textures, and other assets. We're looking for the skeleton, so scroll down to the SkeletonHeader, then either double-click on it or right-click it and select "Open in Skeleton Viewer": - -![Finding object_dns's SkeletonHeader in Z64Utils](images/z64utils_dns_skeletonheader.png) - -When you open the Skeleton Viewer, you'll see a list of animations off to the side. Selecting one of them will display an error that says something like `RENDER ERROR AT 0x06001A98! (Could not read 0x80 bytes at address 08000000)`. This is because one of the display lists in the skeleton is expecting something to be set at segment 8. From the actor, we know that it's expecting the eye textures to be loaded into segment 8 like so: - -```c -static TexturePtr D_8092DE1C[] = { &D_060028E8, &D_06002968, &D_060029E8, &D_06002968 }; -[...] -gSPSegment(POLY_OPA_DISP++, 0x08, Lib_SegmentedToVirtual(sEyeTextures[this->eyeIndex])); -``` - -Let's set segment 8 to be one of the eye textures listed here. Click on "Segments", then for segment 08, click "Edit" and select "Address" as the source. Input "060028E8" as the address, then hit OK. This should result in the window looking as follows: - -![Setting segment 8 to one of the eye textures in Z64Utils](images/z64utils_set_segment_8.png) - -Now that we've gotten around the error, we can see what each limb in the skeleton corresponds to by clicking on it in the Hierarchy. Clicking on any given limb will highlight what part of the model it represents in red. In the below example, this limb is clearly the head: - -![Showing the head limb in Z64Utils](images/z64utils_dns_head_limb.png) - -Note that some limbs don't actually render anything, so sometimes clicking on a limb will not turn anything red; this may indicate a "Root" limb that has no associated display list, or it may indicate something like an eye limb that doesn't have the right textures loaded to display anything in Z64Utils. It may be useful to skip ahead to [Step #5](#step-5-naming-limb-display-lists) to learn how to check if the limb has a display list. If it doesn't have a display list, then it's a "Root" limb that will never be highlighted. - -We can now start naming the skeleton and individual limbs. Since we know this particular skeleton is the King's Chamber Deku Guard, we can name the skeleton `gKingsChamberDekuGuardSkel`. For the LimbNone name, we can call it something like `KINGS_CHAMBER_DEKU_GUARD_LIMB_NONE`, and we can name the LimbMax similarly. For the EnumName, we can name it `KingsChamberDekuGuardLimb`. For each individual limb, we can name them based on what we see in Z64Utils; just make sure to update both the Name and the EnumName. After naming everything, we have something that looks like this: - -```xml - - - - - - - - - - - - - -``` - -Now we can run `./extract_assets.py -s objects/object_dns` to extract the object again, this time with our new names. What can we do with this? Quite a bit actually. In `z_en_dns.h`, we can add this to the top of the file to start using these new names in our code: - -```c -#include "objects/object_dns/object_dns.h" -``` - -Now, we can redefine the `jointTable` and `morphTable` in terms of the limb enum we defined before, like so: - -```c -/* 0x22A */ Vec3s jointTable[KINGS_CHAMBER_DEKU_GUARD_LIMB_MAX]; -/* 0x278 */ Vec3s morphTable[KINGS_CHAMBER_DEKU_GUARD_LIMB_MAX]; -``` - -We can also use our new skeleton name and limb enum when initialization the skeleton like so: - -```c -SkelAnime_Init(play, &this->skelAnime, &gKingsChamberDekuGuardSkel, NULL, this->jointTable, this->morphTable, KINGS_CHAMBER_DEKU_GUARD_LIMB_MAX); -``` - -Lastly, we can use our limb enum in `EnDns_PostLimbDraw`. Where the code originally had: - -```c -if (limbIndex == 2) { - [...] -} -``` - -We can instead write: - -```c -if (limbIndex == KINGS_CHAMBER_DEKU_GUARD_LIMB_HEAD) { - [...] -} -``` - -## Step 2: Naming the animations - -Now that we have the skeleton figured out, it's time to name all the animations. In the Skeleton Viewer, you can hit the "play" button on any animation to see what it looks like. Note that some objects have multiple skeletons, and selecting an animation that is associated with a different skeleton than the one you're looking at can cause odd behavior. Try to give each animation a descriptive name based on what it looks like. If you're struggling; - -- Try viewing the animation in game. In what contexts does this animation play? -- Try analyzing the code for the actor to see when the animation is used. Is this animation ever referenced? -- If you're still really struggling, Majora's Mask 3D contains the original animation names for the majority of animations in the game. These original names can help you figure out what the developers were originally intending. Explaining how to find these animations in MM3D is outside of the scope of this document, so just ask in Discord if you want to try this. - -After naming the animations, the end result will look something like this: - -```xml - - - - - - -[...] - - -``` - -Once again, we can run `./extract_assets.py -s objects/object_dns` to extract the object, and we can update the animation names in `z_en_dns.c` to use our new names like so: - -```c -static AnimationInfoS sAnimationInfo[] = { - { &gKingsChamberDekuGuardIdleAnim, 1.0f, 0, -1, ANIMMODE_LOOP, 0 }, - { &gKingsChamberDekuGuardIdleAnim, 1.0f, 0, -1, ANIMMODE_LOOP, -4 }, - { &gKingsChamberDekuGuardWalkAnim, 1.0f, 0, -1, ANIMMODE_LOOP, 0 }, - { &gKingsChamberDekuGuardWalkAnim, 1.0f, 0, -1, ANIMMODE_LOOP, -4 }, - { &gKingsChamberDekuGuardSurpriseStartAnim, 1.0f, 0, -1, ANIMMODE_ONCE, 0 }, - { &gKingsChamberDekuGuardSurpriseLoopAnim, 1.0f, 0, -1, ANIMMODE_LOOP, 0 }, - { &gKingsChamberDekuGuardRunStartAnim, 1.0f, 0, -1, ANIMMODE_ONCE, 0 }, - { &gKingsChamberDekuGuardRunLoopAnim, 1.0f, 0, -1, ANIMMODE_LOOP, 0 }, - { &gKingsChamberDekuGuardDanceAnim, 1.0f, 0, -1, ANIMMODE_ONCE, 0 }, - { &gKingsChamberDekuGuardFlipAnim, 1.0f, 0, -1, ANIMMODE_ONCE, 0 }, -}; -``` - -## Step 3: Identifying the blob - -In the XML, you may notice undefined blobs like this: - -```xml - -``` - -You might already have an idea as to what this is based on what you've seen before. Recall that the eye textures are referenced in the actor's code like this: - -```c -static TexturePtr D_8092DE1C[] = { &D_060028E8, &D_06002968, &D_060029E8, &D_06002968 }; -``` - -Do you notice how the "28E8" in `D_060028E8` also appears as the Offset in that blob? That's because the blob is just the eye textures; the process for automatically creating the XML wasn't able to figure it out on its own, so we'll need to do it ourselves. But how should we define these textures in the XML? Recall that the eye textures were loaded into segment 8; let's take a look in `object_dns.c` and see if we can find something that uses this segment. This display list has the answer: - -```c -Gfx object_dns_DL_001A50[] = { - [...] - gsDPLoadTextureBlock(0x08000000, G_IM_FMT_RGBA, G_IM_SIZ_16b, 8, 8, 0, G_TX_NOMIRROR | G_TX_CLAMP, G_TX_NOMIRROR | - G_TX_CLAMP, 3, 3, G_TX_NOLOD, G_TX_NOLOD), - [...] -}; -``` - -Using `0x08000000` with `gsDPLoadTextureBlock` signals that this display list is expecting a texture in segment 8. What kind of texture is it expecting? We can look at the arguments after the `0x08000000`. It's looking for an RGBA16 texture with dimensions of 8x8, so we can define these textures in the XML like so: - -```xml - - - -``` - -Now, we just have to name them. In [Step #1](#step-1-naming-the-skeleton-and-limbs), we set segment 8 to one of the eye textures; we can use that same technique with the other two eye textures to see what they are. Like most NPCs, these various eye textures are used for handling blinking, so we can name them based on how open the eye is: - -```xml - - - -``` - -Like with previous steps, we can run `./extract_assets.py -s objects/object_dns` and then update `z_en_dns.c` with our new names: - -```c -static TexturePtr sEyeTextures[] = { - gKingsChamberDekuGuardEyeOpenTex, - gKingsChamberDekuGuardEyeHalfTex, - gKingsChamberDekuGuardEyeClosedTex, - gKingsChamberDekuGuardEyeHalfTex, -}; -``` - -Note that this step might be tricky to do if multiple things in the actor use the same segment. It's okay to wait to do this until you've named all the display lists in the actor, since that will make it easier to find the display list associated with a given texture. - -## Step #4: Naming anything else in the actor - -For some actors, there may be a few other things left to name that are directly referenced in the actor's code. In our case, there is one display list that we still need to name: - -```c -gSPDisplayList(POLY_OPA_DISP++, &D_06002C48); -``` - -In Z64Utils, scroll to find this display list, then either double-click it or right-click it and select "Open in Dlist Viewer": - -![Opening dlist_00002C48 in Z64Utils](images/z64utils_dns_display_list.png) - -We can see this is the guard's Deku Flower: - -![Showing the guard's Deku Flower in Z64Utils](images/z64utils_dns_deku_flower.png) - -We can name the display list as such in the XML: - -```xml - -``` - -Then, like all steps before, we can run `./extract_assets.py -s objects/object_dns` and then update `z_en_dns.c` with our new name: - -```c -gSPDisplayList(POLY_OPA_DISP++, gKingsChamberDekuGuardDekuFlowerDL); -``` - -## Step #5: Naming limb display lists - -Now that we've named everything that's used externally by the actor, we just need to clean up the rest of the unnamed stuff in the XML. Let's start by naming the display lists for each limb. There are two ways you can determine which display list is associated with a given limb. One way is to click on the limb in Z64Utils; it will tell you what display list is used for that limb: - -![Showing the head limb's display list in Z64Utils](images/z64utils_dns_limb_dlist.png) - -Another way is to simply check `object_dns.c`. Each limb lists its own display list like this: - -```c -StandardLimb gKingsChamberDekuGuardHeadLimb = { - { 0, 1300, 0 }, KINGS_CHAMBER_DEKU_GUARD_LIMB_STALK - 1, KINGS_CHAMBER_DEKU_GUARD_LIMB_LEFT_FOOT - 1, - object_dns_DL_0018B8 -}; -``` - -Either way you go about it, you should be able to name all the limb display lists like so: - -```xml - - - - - - - - - - - - -``` - -Run `./extract_assets.py -s objects/object_dns` once again, since it will help in the next step to have all of our display lists named. - -### Step #6: Naming remaining textures - -With every display list named, it's now a lot easier to name the remaining textures. In the `assets/objects/object_dns/` folder, you can see all the textures in the object as various PNG files. For some of the textures, just looking at them will give you a good idea as to what they should be named. For other textures, it may help to see how the texture is used in the object's display lists. Let's take a look at `object_dns_Tex_002868`, which is only used in one display list: - -```c -Gfx gKingsChamberDekuGuardSnoutDL[] = { - [...] - gsDPLoadTextureBlock(object_dns_Tex_002868, G_IM_FMT_RGBA, G_IM_SIZ_16b, 8, 8, 0, G_TX_MIRROR | G_TX_CLAMP, - G_TX_MIRROR | G_TX_CLAMP, 3, 3, G_TX_NOLOD, G_TX_NOLOD), - [...] -}; -``` - -Since `tex_002868.rgba16.png` looks like the inside of the Deku Guard's mouth, and it's *only* used in the snout display list, you can probably name this something like `gKingsChamberDekuGuardMouthTex`. But rather than guessing, we can confirm it by editing the texture ourselves and then viewing it in-game. Using an image editor, let's change `tex_002868.rgba16.png` to this: - -![Our custom mouth texture](images/dns_custom_texture.png) - -Now, rebuild the game using [the steps described here](object_decomp.md#building-and-investigative-modding) and look at the guard in-game. You should see something like this: - -![Our custom mouth texture being shown in-game](images/custom_texture_in_game.png) - -This confirms our suspicion that this is indeed the mouth texture, so we can name it as such. We can use similar strategies to name all the other textures like so: - -```xml - - - -``` - -### Step #7: Finishing up - -If you have any other unnamed assets, now's the time to identify them. Otherwise, finish up the file by putting a comment at the top above the `` node: - -```xml - - - -``` - -And we're done! Hopefully, you found this example helpful when decompiling your own objects. diff --git a/mm/docs/tutorial/other_functions.md b/mm/docs/tutorial/other_functions.md deleted file mode 100644 index dd2de5538..000000000 --- a/mm/docs/tutorial/other_functions.md +++ /dev/null @@ -1,653 +0,0 @@ -# The rest of the functions in the actor - -- Up: [Contents](contents.md) -- Previous: [Beginning decompilation: the Init function and the Actor struct](beginning_decomp.md) - -## Now what? - -At this point we have a choice to make. Either we could follow the main function flow and decompile `func_80C10148`, or take a look at `Destroy`, which for smaller actors can often be done straight after Init, since it usually just removes colliders and deallocates dynapoly. - -## Destroy - -Destroy will be a dead end, but we might as well do it now. Usually we would regenerate the context first and apply it to mips2c as with `Init`, but if we look at the assembly... - -```mips -glabel EnRecepgirl_Destroy -/* 0000FC 80C100CC AFA40000 */ sw $a0, ($sp) -/* 000100 80C100D0 AFA50004 */ sw $a1, 4($sp) -/* 000104 80C100D4 03E00008 */ jr $ra -/* 000108 80C100D8 00000000 */ nop -``` - -It doesn't seem to do anything. Indeed, chucking it in mips2c, - -``` -$ ../mips_to_c/mips_to_c.py asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Destroy.s -void EnRecepgirl_Destroy(s32 arg0, ? arg1) { - -} -``` - -so it really does do nothing. It is worth staying on this briefly to understand what is is doing, though. Even with no context, mips2c knows it takes two arguments because it does two saves onto the stack: the calling convention the N64 uses requires the first four arguments be saved from the registers onto the stack, since the registers are expected to be cleared when a function call happens. It's done a bad job of guessing what they are, but that's to be expected: the assembly only tells us they're words. Thankfully we already know in this case, so we can just replace the `GLOBAL_ASM` by - -```C -void EnRecepgirl_Destroy(Actor* thisx, PlayState* play) { - -} -``` - -and cross this function off. - -## `func_80C10148` - -We don't really have a choice now, we have to look at this function. Remake the context (no need to change the function type this time), and run mips2c on the function's assembly file: - -``` -$ ../mips_to_c/mips_to_c.py asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C10148.s data/ovl_En_Recepgirl/ovl_En_Recepgirl.data.s --context ctx.c -extern AnimationHeader D_0600AD98; -extern ? func_80C1019C; - -void func_80C10148(EnRecepgirl *this) { - SkelAnime *temp_a0; - - temp_a0 = &this->skelAnime; - if (&D_06001384 == this->skelAnime.animation) { - this = this; - Animation_MorphToPlayOnce(temp_a0, &D_0600AD98, 5.0f); - } - this->actionFunc = &func_80C1019C; -} -``` - -This gives us some information immediately: `D_0600AD98` is an `AnimationHeader`, and `func_80C1019C` is set as the action function. This means that we know its type, even though mips2c does not: looking in the header, we see the typedef is - -```C -typedef void (*EnRecepgirlActionFunc)(struct EnRecepgirl*, PlayState*); -``` - -and so we prototype `func_80C1019C` as - -```C -void func_80C1019C(EnRecepgirl* this, PlayState* play); -``` - -at the top (were it above the function we're currently working on, the prototype could eventually be replaced by the function definition itself, but since it isn't, it goes at the top with the others). - -There are several rather odd things going on here: - -- `temp_a0` is only used once. As such it's probably fake. -- There's a weird `this = this` that does nothing -- `if (&D_06001384 == this->skelAnime.animation)` is a bit of a funny way to write the condition: it seems more likely it would be the other way round. -- Also, if we look up `animation`, we find it is an `AnimationHeader*`, so `D_06001384` can be externed as `AnimationHeader`. -- `func_80C1019C` is already a pointer, so the `&` is ineffectual. Our style is to not use `&` on function pointers. - -If we tackle these, we end up with - -```C - -void func_80C10148(EnRecepgirl* this); -void func_80C1019C(EnRecepgirl* this, PlayState* play); - -[...] - -extern AnimationHeader D_06001384; -extern AnimationHeader D_06009890; -extern UNK_TYPE D_0600A280; -extern AnimationHeader D_0600AD98; -extern FlexSkeletonHeader D_06011B60; - -[...] - -void func_80C10148(EnRecepgirl *this) { - if (this->skelAnime.animation == &D_06001384) { - Animation_MorphToPlayOnce(&this->skelAnime, &D_0600AD98, 5.0f); - } - this->actionFunc = func_80C1019C; -} -``` - -This is a common type of function called a setup (action) function. It runs once and prepares the ground for its corresponding actionfunction to run, whereas the actionfunction is usually run every frame by `Update` (but more on that later). Running `make`, we get OK again. - -Again we have only one way to go - -## `func_80C1019C` - -Remake the context and run mips2c on this function's assembly file. We get - -```C -? func_80C10290(EnRecepgirl *); // extern - -void func_80C1019C(EnRecepgirl* this, PlayState* play) { - SkelAnime *sp24; - SkelAnime *temp_a0; - - temp_a0 = &this->skelAnime; - sp24 = temp_a0; - if (SkelAnime_Update(temp_a0) != 0) { - if (&D_0600A280 == this->skelAnime.animation) { - Animation_MorphToPlayOnce(temp_a0, &D_0600AD98, 5.0f); - } else { - Animation_ChangeTransitionRepeat(temp_a0, &D_06009890, -4.0f); - } - } - if (Actor_ProcessTalkRequest((Actor *) this, play) != 0) { - func_80C10290(this); - return; - } - if (Actor_IsFacingPlayer((Actor *) this, 0x2000) != 0) { - Actor_OfferTalk((Actor *) this, play, 60.0f); - if (Player_GetMask(play) == 2) { - this->actor.textId = 0x2367; - return; - } - if (Flags_GetSwitch(play, (s32) this->actor.params) != 0) { - this->actor.textId = 0x2ADC; - return; - } - this->actor.textId = 0x2AD9; - // Duplicate return node #12. Try simplifying control flow for better match - } -} -``` - -This is a bit juicier! We can do some preliminary cleanup, then worry about the control flow. - -- `sp24` does nothing, so is almost certainly fake. -- `temp_a0` is used in 3 different places, but they're all right next to one another and are unlikely to be required since there's no nontrivial calculation or anything happening. Let's remove it too and see what happens. -- We've got another reversed comparison, `&D_0600A280 == this->skelAnime.animation`. -- `D_0600A280` is an `AnimationHeader`. -- `(Actor *) this` should be replaced by `&this->actor`. -- `Flags_GetSwitch is a boolean and we don't need to cast the argument, as we have discussed before. (We don't know about the other functions in the conditions, so leave them for now.) -- Prototype `func_80C10290`: it is reasonable to guess it's another setup function, so `void func_80C10290(EnRecepgirl* this);`. - -Changing all these, we end up with - -```C -void func_80C10148(EnRecepgirl* this); -void func_80C1019C(EnRecepgirl* this, PlayState* play); -void func_80C10290(EnRecepgirl* this); - -[...] - -extern AnimationHeader D_06001384; -extern AnimationHeader D_06009890; -extern AnimationHeader D_0600A280; -extern AnimationHeader D_0600AD98; -extern FlexSkeletonHeader D_06011B60; - -[...] - -void func_80C1019C(EnRecepgirl* this, PlayState* play) { - if (SkelAnime_Update(&this->skelAnime) != 0) { - if (&D_0600A280 == this->skelAnime.animation) { - Animation_MorphToPlayOnce(&this->skelAnime, &D_0600AD98, 5.0f); - } else { - Animation_ChangeTransitionRepeat(&this->skelAnime, &D_06009890, -4.0f); - } - } - if (Actor_ProcessTalkRequest(&this->actor, &play->state) != 0) { - func_80C10290(this); - return; - } - if (Actor_IsFacingPlayer(&this->actor, 0x2000) != 0) { - Actor_OfferTalk(&this->actor, play, 60.0f); - if (Player_GetMask(play) == 2) { - this->actor.textId = 0x2367; - return; - } - if (Flags_GetSwitch(play, this->actor.params)) { - this->actor.textId = 0x2ADC; - return; - } - this->actor.textId = 0x2AD9; - // Duplicate return node #12. Try simplifying control flow for better match - } -} -``` - -If we look with diff.py, we find this matches. But we can replace some of the `return`s by `else`s: generally, we use elses unless - -- After an `Actor_Kill` -- Sometimes after setting an actionfunction -- There's no way to avoid an early return - -Here, it's debatable whether to keep the first, since `func_80C10290` is likely a setup function. The latter two should be changed to elses, though. For now, let's replace all of them. This leaves us with - -```C -void func_80C1019C(EnRecepgirl* this, PlayState* play) { - if (SkelAnime_Update(&this->skelAnime) != 0) { - if (this->skelAnime.animation == &D_0600A280) { - Animation_MorphToPlayOnce(&this->skelAnime, &D_0600AD98, 5.0f); - } else { - Animation_ChangeTransitionRepeat(&this->skelAnime, &D_06009890, -4.0f); - } - } - - if (Actor_ProcessTalkRequest(&this->actor, &play->state) != 0) { - func_80C10290(this); - } else if (Actor_IsFacingPlayer(&this->actor, 0x2000)) { - Actor_OfferTalk(&this->actor, play, 60.0f); - if (Player_GetMask(play) == 2) { - this->actor.textId = 0x2367; - } else if (Flags_GetSwitch(play, this->actor.params)) { - this->actor.textId = 0x2ADC; - } else { - this->actor.textId = 0x2AD9; - } - } -} -``` - -which still matches. Lastly, we have an enum for the output of `Player_GetMask` and other mask-related things: in `z64player.h` we find - -```C -typedef enum { - /* 0x00 */ PLAYER_MASK_NONE, - /* 0x01 */ PLAYER_MASK_MASK_OF_TRUTH, - /* 0x02 */ PLAYER_MASK_KAFEIS_MASK, -[...] - /* 0x19 */ PLAYER_MASK_MAX -} PlayerMask; -``` -and so we can write the last if as `Player_GetMask(play) == PLAYER_MASK_KAFEIS_MASK`. - -Again, we have no choice in what to do next. - -## `func_80C10290` - -Remaking the context and running mips2c gives - -```C -void func_80C102D4(EnRecepgirl*, PlayState*); // extern - -void func_80C10290(EnRecepgirl *this) { - Animation_MorphToPlayOnce(&this->skelAnime, &D_0600A280, -4.0f); - this->actionFunc = func_80C102D4; -} -``` - -so all we have to do is add the function prototype for the newest action function. Not surprisingly, this matches without changing anything. - -## `func_80C102D4` - -
- -Large code block, click to show - - -```C -extern AnimationHeader D_06000968; - -void func_80C102D4(EnRecepgirl* this, PlayState* play) { - SkelAnime *sp20; - AnimationHeader *temp_v0; - SkelAnime *temp_a0; - u16 temp_v0_3; - u16 temp_v0_4; - u8 temp_v0_2; - - temp_a0 = &this->skelAnime; - sp20 = temp_a0; - if (SkelAnime_Update(temp_a0) != 0) { - temp_v0 = this->skelAnime.animation; - if (&D_0600A280 == temp_v0) { - Animation_ChangeDefaultRepeat(sp20, &D_06001384); - } else if (&D_0600AD98 == temp_v0) { - if (this->actor.textId == 0x2ADA) { - Animation_MorphToPlayOnce(sp20, &D_06000968, 10.0f); - } else { - Animation_ChangeTransitionRepeat(sp20, &D_06009890, 10.0f); - } - } else if (this->actor.textId == 0x2ADA) { - Animation_ChangeTransitionRepeat(sp20, &D_06009890, 10.0f); - } else { - Animation_MorphToPlayOnce(sp20, &D_0600A280, -4.0f); - } - } - temp_v0_2 = Message_GetState(&play->msgCtx); - if (temp_v0_2 == 2) { - this->actor.textId = 0x2ADC; - func_80C10148(this); - return; - } - if (((temp_v0_2 & 0xFF) == 5) && (Message_ShouldAdvance(play) != 0)) { - temp_v0_3 = this->actor.textId; - if (temp_v0_3 == 0x2AD9) { - Flags_SetSwitch(play, (s32) this->actor.params); - Animation_MorphToPlayOnce(sp20, &D_0600AD98, 10.0f); - if ((*(&gSaveContext + 0xF37) & 0x80) != 0) { - this->actor.textId = 0x2ADF; - } else { - this->actor.textId = 0x2ADA; - } - } else if (temp_v0_3 == 0x2ADC) { - Animation_MorphToPlayOnce(sp20, &D_0600AD98, 10.0f); - this->actor.textId = 0x2ADD; - } else { - Animation_MorphToPlayOnce(sp20, &D_06000968, 10.0f); - temp_v0_4 = this->actor.textId; - if (temp_v0_4 == 0x2ADD) { - this->actor.textId = 0x2ADE; - } else if (temp_v0_4 == 0x2ADA) { - this->actor.textId = 0x2ADB; - } else { - this->actor.textId = 0x2AE0; - } - } - Message_ContinueTextbox(play, this->actor.textId); - } -} -``` - -
- -Well, this is a big one! We get one more extern, for `D_06000968`. A lot of the temps used in the conditionals look fake, with the exception of `temp_v0_2`: because the function is only called once but the temp is used twice, the temp must be real. Removing the others and switching the `animation` conditionals, - -```C -void func_80C102D4(EnRecepgirl* this, PlayState* play) { - u8 temp_v0_2; - - if (SkelAnime_Update(&this->skelAnime) != 0) { - if (this->skelAnime.animation == &D_0600A280) { - Animation_ChangeDefaultRepeat(&this->skelAnime, &D_06001384); - } else if (this->skelAnime.animation == &D_0600AD98) { - if (this->actor.textId == 0x2ADA) { - Animation_MorphToPlayOnce(&this->skelAnime, &D_06000968, 10.0f); - } else { - Animation_ChangeTransitionRepeat(&this->skelAnime, &D_06009890, 10.0f); - } - } else if (this->actor.textId == 0x2ADA) { - Animation_ChangeTransitionRepeat(&this->skelAnime, &D_06009890, 10.0f); - } else { - Animation_MorphToPlayOnce(&this->skelAnime, &D_0600A280, -4.0f); - } - } - - temp_v0_2 = Message_GetState(&play->msgCtx); - if (temp_v0_2 == 2) { - this->actor.textId = 0x2ADC; - func_80C10148(this); - return; - } - - if (((temp_v0_2 & 0xFF) == 5) && (Message_ShouldAdvance(play) != 0)) { - if (this->actor.textId == 0x2AD9) { - Flags_SetSwitch(play, this->actor.params); - Animation_MorphToPlayOnce(&this->skelAnime, &D_0600AD98, 10.0f); - if ((*(&gSaveContext + 0xF37) & 0x80) != 0) { - this->actor.textId = 0x2ADF; - } else { - this->actor.textId = 0x2ADA; - } - } else if (this->actor.textId == 0x2ADC) { - Animation_MorphToPlayOnce(&this->skelAnime, &D_0600AD98, 10.0f); - this->actor.textId = 0x2ADD; - } else { - Animation_MorphToPlayOnce(&this->skelAnime, &D_06000968, 10.0f); - if (this->actor.textId == 0x2ADD) { - this->actor.textId = 0x2ADE; - } else if (this->actor.textId == 0x2ADA) { - this->actor.textId = 0x2ADB; - } else { - this->actor.textId = 0x2AE0; - } - } - Message_ContinueTextbox(play, this->actor.textId); - } -} -``` - -There remains one thing we need to fix before trying to compile it, namely `*(&gSaveContext + 0xF37) & 0x80`. This is really a funny way of writing an array access, because mips2c will get confused about arrays in structs. Opening up `z64save.h`, we find in the `SaveContext` struct that - -```C - /* 0x0EF8 */ u8 weekEventReg[100]; // "week_event_reg" - /* 0x0F5C */ u32 regionsVisited; // "area_arrival" -``` - -so it's somewhere in `weekEventReg`. `0xF37 - 0xEF8 = 0x3F = 63`, and it's a byte array, so the access is actually `gSaveContext.save.saveInfo.weekEventReg[63] & 0x80`. Now it will compile. We also don't use `!= 0` for flag comparisons: just `if (gSaveContext.save.saveInfo.weekEventReg[63] & 0x80)` will do. - -Running `./diff.py -mwo3 func_80C102D4` and scrolling down, we discover that this doesn't match! - -![First run of diff.py on func_80C102D4](images/func_80C102D4_diff1.png) - -The yellow shows registers that don't match, the different colours on the registers help you to estimate where the problems are. Usually it's best to start at the top and work down if possible: any regalloc problems at the top tend to propagate most of the way down. In our case, the first problem is - -``` -3f0: andi t0,v0,0xff r 153 3f0: andi t1,v0,0xff -``` - -somehow we skipped over `t0`. Where is this in the code? The `153` in the middle is the line number in the C file (the `3f0`s are the offsets into the assembly file), we have `--source` if you want to see the code explicitly, or you can do it the old-fashioned way, and work it out from nearby function calls. In this case, `func_80C10148` is run straight after, and the only place that is called is - -```C - temp_v0_2 = Message_GetState(&play->msgCtx); - if (temp_v0_2 == 2) { - this->actor.textId = 0x2ADC; - func_80C10148(this); - return; - } - - if (((temp_v0_2 & 0xFF) == 5) && (Message_ShouldAdvance(play) != 0)) { -``` - -If you look at the conditionals and the declaration of `temp_v0_2`, you may notice something odd: `temp_v0_2` is a `u8`. Therefore the `& 0xFF` does nothing! It's surprisingly common for this to happen, be it leaving out a `& 0xFF` or adding an extraneous one. If we remove it, we get a match: - -![func_80C102D4 now matching](images/func_80C102D4_diff2.png) - -Notice that indeed the subsequent regalloc, which might have looked like a bigger problem than the initial part, was also fixed: skipping a register in one place will throw the registers off below too. - -And now we've run out of functions. Time for `Update`. - -## Update - -Update runs every frame and usually is responsible for the actor's common logic updates: for example, updating timers, blinking, updating collision, running the `actionFunc`, and so on, either directly or through other functions it calls. A lot of subsidiary functions that are not common to every state (e.g. updating position, or the text when talking, etc.) are carried out by one of the action functions we have already decomped. - -Remake the context and run mips2c: - -```C -? func_80C100DC(EnRecepgirl *); // extern - -void EnRecepgirl_Update(Actor* thisx, PlayState* play) { - EnRecepgirl* this = (EnRecepgirl *) thisx; - ? sp30; - - this->actionFunc(this, play); - Actor_TrackPlayer(play, (Actor *) this, this + 0x2AE, (Vec3s *) &sp30, (bitwise Vec3f) this->actor.focus.pos.x, this->actor.focus.pos.y, this->actor.focus.pos.z); - func_80C100DC(this); -} -``` - -If we search for `func_80C100DC`, we find that this is the only time it is used. Hence we can be almost certain that its prototype is `void func_80C100DC(EnRecepgirl* this);`. This function occurs above `Update`, so you can put the prototype next to the `GLOBAL_ASM` and remove it when we decompile that function. - -Change the function and the prototype back to `Actor* thisx`, and add the casting temp: - -```C -void func_80C100DC(EnRecepgirl *); -#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C100DC.s") - -[...] - -void EnRecepgirl_Update(Actor* thisx, PlayState* play) { - EnRecepgirl* this = THIS; - ? sp30; - - this->actionFunc(this, play); - Actor_TrackPlayer(play, &this->actor, this + 0x2AE, (Vec3s *) &sp30, (bitwise Vec3f) this->actor.focus.pos.x, this->actor.focus.pos.y, this->actor.focus.pos.z); - func_80C100DC(this); -} -``` - -Now, our problem is `Actor_TrackPlayer`. The arguments all look terrible! Indeed, if we look at the actual function in `src/code/code_800E8EA0.c` (found by searching), we find that it should be - -```C -s32 Actor_TrackPlayer(PlayState* play, Actor* actor, Vec3s* headRot, Vec3s* torsoRot, Vec3f focusPos) -``` - -So mips2c has made a bit of a mess here: - -- the third argument should be a `Vec3s`. Hence `this + 0x2AE` is a `Vec3s*`, and so `this->unk_2AE` is a `Vec3s` -- `&sp30` is a `Vec3s*`, so `sp30` is a `Vec3s` (it's clearly not used for anything, just used to "dump" a side-effect of the function) -- The last argument is supposed to be an actual `Vec3f` - -Fixing all of this, we end up with - -```C -void EnRecepgirl_Update(EnRecepgirl* this, PlayState* play) { - EnRecepgirl* this = THIS; - Vec3s sp30; - - this->actionFunc(this, play); - Actor_TrackPlayer(play, &this->actor, &this->unk_2AE, &sp30, this->actor.focus.pos); - func_80C100DC(this); -} -``` - -and can fill in the top end of the struct: - -```C -typedef struct EnRecepgirl { - /* 0x0000 */ Actor actor; - /* 0x0144 */ SkelAnime skelAnime; - /* 0x0188 */ Vec3s jointTable[24]; - /* 0x0218 */ Vec3s morphTable[24]; - /* 0x02A8 */ EnRecepgirlActionFunc actionFunc; - /* 0x02AC */ u8 unk_2AC; - /* 0x02AD */ char unk_2AD[0x1]; - /* 0x02AE */ Vec3s unk_2AE; -} EnRecepgirl; // size = 0x2B4 -``` - -It's entirely possible that `unk_2AD` is not real, and is just padding: see [Types, structs, and padding](types_structs_padding.md) for the details. We'll find out once we've finished all the functions. If we look at the diff, we find that one line is different: - -![EnRecepgirl_Update's stack difference](images/EnRecepgirl_stack_diff.png) - -So `sp30` is in the wrong place: it's `4` too high on the stack in ours. This is because the main four functions do not actually take `PlayState`: they really take `Gamestate` and recast it with a temp, just like `EnRecepgirl* this = THIS;`. We haven't implemented this in the repo yet, though, so for now, it suffices to put a pad on the stack where it would go instead: experience has shown when it matters, it goes above the actor recast, so we end up with -```C -void EnRecepgirl_Update(Actor* thisx, PlayState* play) { - s32 pad; - EnRecepgirl* this = THIS; - Vec3s sp30; - - this->actionFunc(this, play); - Actor_TrackPlayer(play, &this->actor, &this->unk_2AE, &sp30, this->actor.focus.pos); - func_80C100DC(this); -} -``` - -and this now matches. - -**N.B.** sometimes using an actual `PlayState* play` temp is required for matching: add it to your bag o' matching memes. - -### *Some remarks about the function stack - -(Feel free to skip this if you'd rather finish the actor first.) - -The (function) stack is used to store variables. It has rather more space and is somewhat less volatile than registers (it still can't be used outside a function, except by a called function accessing its arguments). The stack a function sets up for itself to use is called its *stack frame* or *function frame* (or just *function stack* or *the stack*, although strictly speaking the frame itself is not a stack, since not just the top variable is accessed), and the function frames themselves form an (genuine) stack called the *call stack*. In MIPS this stack grows downwards, and its size is always a multiple of 0x8 (in case you want to put a 64-bit value on it, although almost no N64 game functions do this). The compiler uses the stack in a single function frame in the following way: - -| user-defined variables | -| compiler-defined varibles | -| saved registers | -| argument registers/stack | - -where sp is at the very bottom of this table, and the function that called the current function would have its frame above this one. We have seen a couple of aspects of this stack behaviour already: saving the function arguments onto it in [`EnRecepgirl_Destroy`](#destroy), and here, requiring an extre user stack variable to be the correct size. - -Anyway, back to EnRecepgirl. 4 functions to go... - -## `func_80C100DC` - -This is the final non-draw function. You know what to do now: remake the context and run mips2c: - -```C -void func_80C100DC(EnRecepgirl *this) { - u8 temp_t6; - u8 temp_v0; - - temp_v0 = this->unk_2AC; - temp_t6 = temp_v0 + 1; - if (temp_v0 != 0) { - this->unk_2AC = temp_t6; - if ((temp_t6 & 0xFF) == 4) { - this->unk_2AC = 0; - return; - } - // Duplicate return node #5. Try simplifying control flow for better match - return; - } - if (Rand_ZeroOne() < 0.02f) { - this->unk_2AC += 1; - } -} -``` - -Well, hmm. It's pretty hard to tell what's going on here. Finally it's time to really use `diff.py`. this function is a bit more typical of what to expect: this actor has been very easy so far! - -![func_80C100DC, first diff](images/func_80C100DC_diff1.png) - -Well, it's still *pretty* close. But the registers are all wrong. Firstly, `temp_t6` is already `u8`, so the `& 0xFF` is again ineffective, so let's try removing it... - -![func_80C100DC, second diff](images/func_80C100DC_diff2.png) - -It's not obvious that did much: it even looks a bit worse. - -```C - temp_v0 = this->unk_2AC; - temp_t6 = temp_v0 + 1; - if (temp_v0 != 0) { - this->unk_2AC = temp_t6; -``` - -may remind you of that loop we decompiled, where mips2c unnecessarily made two temps. Let's walk through what this does. - -- First, it saves the value of `this->unk_2AC` into `v0` -- Then, it adds one to it and stores it in `t6`. -- It checks if the first saved value is zero -- If it is, it sets `this->unk_2AC` to the incremented value and carries on. - -Well, if we allow ourselves to bend the order of operations a little, there's a much simpler way to write this with no temps, namely - -```C - if (this->unk_2AC != 0) { - this->unk_2AC++; -``` - -So let's try removing both temps: - -```C -void func_80C100DC(EnRecepgirl *this) { - if (this->unk_2AC != 0) { - this->unk_2AC++; - if (this->unk_2AC == 4) { - this->unk_2AC = 0; - return; - } - return; - } - if (Rand_ZeroOne() < 0.02f) { - this->unk_2AC++; - } -} -``` - -![func_80C100DC, matching](images/func_80C100DC_diff3.png) - -There we go. - -Even though this matches, it is not quite according to our style: remember what was said earlier about early returns. Here, both of them can be removed and replaced by a single else without affecting matching: - -```C -void func_80C100DC(EnRecepgirl *this) { - if (this->unk_2AC != 0) { - this->unk_2AC++; - if (this->unk_2AC == 4) { - this->unk_2AC = 0; - } - } else if (Rand_ZeroOne() < 0.02f) { - this->unk_2AC++; - } -} -``` - -and this is how we prefer it to be written. - -With that, the last remaining function is `EnJj_Draw`. Draw functions have an extra layer of macroing that is required, so we shall cover them separately. - -Next: [Draw functions](draw_functions.md) diff --git a/mm/docs/tutorial/types_structs_padding.md b/mm/docs/tutorial/types_structs_padding.md deleted file mode 100644 index 93492d3e1..000000000 --- a/mm/docs/tutorial/types_structs_padding.md +++ /dev/null @@ -1,163 +0,0 @@ -# Types, structs, and padding - -Reminders: - -- In N64 MIPS, 1 word is 4 bytes (yes, the N64 is meant to be 64-bit, but it mostly isn't used like it in MM or OoT) -- A byte is 8 bits, or 2 hex digits - -## Types - -The following are the common data types used everywhere: - -| Name | Size | Comment | -| ---- | ----- | -------- | -| char | 1 byte | character | -| u8 | 1 byte | unsigned byte | -| s8 | 1 byte | signed byte | -| u16 | 2 bytes | unsigned short | -| s16 | 2 bytes | signed short | -| u32 | 4 bytes/1 word | unsigned int | -| s32 | 4 bytes/1 word | signed int | -| void* | 4 bytes/1 word | pointer | -| uintptr_t | 4 bytes/1 word | pointer^ | -| intptr_t | 4 bytes/1 word | pointer^ | - -A pointer is sometimes mistaken for an `s32`. The last two, marked with `^`, are special types allowing for arithmetic on generic pointers, and are to be used over `u32`. - -`s32` is the default thing to use in the absence of any other information about the data. - -Useful data for guessing types: - -- `u8` is about 7 times more common than `s8` -- `s16` is about 16 times more common than `u16` -- `s32` is about 8 times more common than `u32` - -Another useful thing to put here: the typedef for an action function is - -```C -typedef void (*ActorNameActionFunc)(struct ActorName*, PlayState*); -``` - -where you replace `ActorName` by the actual actor name as used elsewhere in the actor, e.g. `EnRecepgirl`. In MM these typedefs have been automatically generated, so you don't need to constantly copy from here or another actor any more. - -## Some Common Structs - -Here are the usual names and the sizes of some of the most common structs used in actors and their structs: -| Type | Usual name | Size | -| ----------------------- | --------------------- | --------------- | -| `Actor` | `actor` | 0x144 | -| `DynaPolyActor` | `dyna` | 0x15C | -| `Vec3f` | | 0xC | -| `Vec3s` | | 0x6 | -| `SkelAnime` | `skelAnime` | 0x44 | -| `Vec3s[limbCount]` | `jointTable` | 0x6 * limbCount | -| `Vec3s[limbCount]` | `morphTable` | 0x6 * limbCount | -| `ColliderCylinder` | `collider` | 0x4C | -| `ColliderQuad` | `collider` | 0x80 | -| `ColliderJntSph` | `collider` | 0x20 | -| `ColliderJntSphElement` | `colliderElements[n]` | 0x40 * n | -| `ColliderTris` | `collider` | 0x20 | -| `ColliderTrisElement` | `colliderElements[n]` | 0x5C * n | - -Note that `Actor` and `DynaPolyActor` have changed size from OoT. - -## Padding - -### Alignment - -A stored variable or piece of data does not always start immediately after the previous one: there may be padding in between: `0`s that are never written or referred to, and so ignored. This is to do with how the processor accesses memory: it reads 1 word at a time, so multibyte objects are aligned so they cross as few word boundaries as possible. - -The clearest example of this is that variables with types that are 1 word in size (`s32`s and pointers, for example) are automatically shifted so that they start at the beginning of the next word, i.e. at an offset ending with one of `0,4,8,C`: this is called 4-alignment. This will also happen to `s16`s, but with 2-alignment - -### Struct padding - -In actor structs, this manifests as some of the char arrays not being completely replaced by actual variables. - -```C -typedef struct EnRecepgirl { - /* 0x0000 */ Actor actor; - /* 0x0144 */ SkelAnime skelAnime; - /* 0x0188 */ Vec3s jointTable[24]; - /* 0x0218 */ Vec3s morphTable[24]; - /* 0x02A8 */ EnRecepgirlActionFunc actionFunc; - /* 0x02AC */ u8 unk_2AC; - /* 0x02AE */ Vec3s unk_2AE; -} EnRecepgirl; // size = 0x2B4 -``` - -Notice that even though `unk_2AC` is a `u8`, `unk_2AE` is at `this + 0x2AE`, rather than `0x2AD`: we removed the extra char of padding while working on this actor. - -How do structs themselves align? A struct has the same alignment properties as its longest constituent (that is not itself a struct). For example, a `Vec3f` has 4-alignment, while a `Vec3s` has 2-alignment. - -A struct may also pad at the end: it will pad to the size of its largest non-struct element. Notably, every actor struct has size a whole number of words as well, so this phenomenon also occurs at the ends of structs. For example, ObjTree has the following actor struct: - -```C -typedef struct ObjTree { - /* 0x0000 */ DynaPolyActor dyna; - /* 0x015C */ ColliderCylinder collider; - /* 0x01A8 */ ObjTreeActionFunc actionFunc; - /* 0x01AC */ f32 unk_1AC; - /* 0x01B0 */ s16 unk_1B0; - /* 0x01B2 */ s16 unk_1B2; - /* 0x01B4 */ s16 unk_1B4; -} ObjTree; // size = 0x1B8 -``` - -The struct pads to be `0x1B8` in size even though the last actual variable ends at `0x1B6`. - -For more information on this topic, there are plenty of guides elsewhere on the Internet, for example [The Lost Art of Structure Packing](http://www.catb.org/esr/structure-packing/). *The main thing to bear in mind for decomp purposes is that after finishing the functions, there may be some small parts of the actor struct that are just not used, because they were originally just struct padding.* - -### Padding at the end of sections - -In the ROM, each actor is layed out in the following order: - -- .text (Function instructions, separated into .s files, aka .text) -- .data (contents of the .data.s file) -- .rodata (read-only data, includes strings, floats, jumptables etc., almost entirely moved to the appropriate function files in the MM repo) -- .bss (varibles initialised to 0, not assigned a value when declared) -- .reloc (relocation information: you can ignore this) - -Each section is 0x10/16-aligned (qword aligned), i.e. each new section begins at an address with last digit `0`. This means that there can occur up to three words of padding at the end of each section. - -(The same occurs with any object divided into multiple .c files: each new file becomes 0x10 aligned.) - -#### Padding at the end of .text (function instructions) - -In function instructions, this manifests as a set of `nop`s at the end of the last function: for example, in EnRecepGirl, - -```mips -/* 0006B0 80C10680 27BD0038 */ addiu $sp, $sp, 0x38 -/* 0006B4 80C10684 03E00008 */ jr $ra -/* 0006B8 80C10688 00000000 */ nop -/* 0006BC 80C1068C 00000000 */ nop -``` - -the second `nop` is just extra `0`s of padding, as you can see in the machine code (third column in the comment) - -Once the rest of the functions match, this is automatic. So you never need to worry about these. - -#### Padding at the end of .data - -In data, the last entry may contain up to 3 words of 0s as padding. These can safely be removed when migrating data, but make sure that you don't remove something that actually is accessed by the function and happens to be 0! - -For example, in `ObjTree` we found that the last symbol in the data, - -```mips -glabel D_80B9A5BC -/* 00006C 80B9A5BC */ .word 0x08000000 -/* 000070 80B9A5C0 */ .word 0x00000000 -/* 000074 80B9A5C4 */ .word 0xFE000000 -/* 000078 80B9A5C8 */ .word 0x00000000 -/* 00007C 80B9A5CC */ .word 0x00000000 -``` - -had 2 words of padding: only the first 3 words are actually used in the `CollisionCheckInfoInit2`. - -### Padding within the .data section - -Every distinct symbol in data is 4-aligned (word-aligned). So in the data, even if you have two `u8`s, they will be stored in addresses starting successive words: - -```C -u8 byte1 = 1 // will go to address ending in 0 -u8 byte2 = 2 // Will go to address ending in 4 -``` diff --git a/mm/docs/tutorial/vscode.md b/mm/docs/tutorial/vscode.md deleted file mode 100644 index 288bf0e48..000000000 --- a/mm/docs/tutorial/vscode.md +++ /dev/null @@ -1,81 +0,0 @@ -# VSCode - -A lot of people on this project use VSCode as their coding environment. - -## Extensions - -There are a number of useful extensions available to make work more efficient: - -- C/C++ IntelliSense -- Clang-Format -- HexInspector (hover on numbers for float and other info) -- NumberMonger (convert hex to decimal and vice versa) -- ~~bracket pair colorizer 2~~ (now obsolete due to VSCode's built-in bracket colouring) -- Better MIPS Support - -## Useful stuff to know - -- Ctrl + Alt + Up/Down (on Windows, on Linux it's Ctrl + Shift + Up/Down or Shift + Alt + Up/Down) gives multicursors across consecutive lines. If you want several cursors in a more diverse arrangement, middle clicking works, at least on Windows. -- Alt + Up/Down moves lines up/down. -- Shift + Alt + Up/Down (Linux: Ctrl + Shift + Alt + Up/Down) copies lines up/down. -- Ctrl + P offers a box to use to search for and open files. -- Ctrl + Shift + P offers a box for commands like editing settings or reloading the window. - -- Make use of VSCode's search/search-and-replace features. - - Ctrl + Click goes to a definition. - - Ctrl + F for search in current file - - Ctrl + H for replace in current file - - Ctrl + Shift + F for search in all files - - Ctrl + Shift + H for replace in all files - - F2 for Rename symbol - -Many of VS Code's other shortcuts can be found on [its getting started page](https://code.visualstudio.com/docs/getstarted/keybindings), which also has links to OS-specific PDFs. - -## C/C++ configuration - -You can create a `.vscode/c_cpp_properties.json` file with `C/C++: Edit Configurations (JSON)` in the command box to customise how IntelliSense reads the repository (stuff like where to look for includes, flags, compiler defines, etc.) to make VSCode's IntelliSense plugin better able to understand the structure of the repository. This is a good default one to use for this project's repository: - -```jsonc -{ - "configurations": [ - { - "name": "Linux", - "compilerPath": "${default}", // Needs to not be "" for -m32 to work - "compilerArgs": [ - "-m32" // Removes integer truncation warnings with gbi macros - ], - "intelliSenseMode": "${default}", // Shouldn't matter - "includePath": [ // Matches makefile's includes - "${workspaceFolder}/**", - "src", - "assets", - "build", - "include" - ], - "defines": [ - "_LANGUAGE_C" // For gbi.h - ], - "cStandard": "gnu89", // C89 + some GNU extensions from C99 like C++ comments - "cppStandard": "${default}" // Only ZAPD uses C++, so doesn't really matter - } - ], - "version": 4 -} -``` - -## Settings - -Add the following to (or create) the `.vscode/settings.json` file for VSCode to search the gitignored asset and assembly files by default: - -```jsonc -{ - "search.useIgnoreFiles": false, - "search.exclude": { - "**/.git": true, - "baserom/**": true, - "build/**": true, - "expected/**": true, - "nonmatchings/**": true, - }, -} -``` diff --git a/mm/docs/useful_conversions.md b/mm/docs/useful_conversions.md deleted file mode 100644 index 102c20daa..000000000 --- a/mm/docs/useful_conversions.md +++ /dev/null @@ -1,275 +0,0 @@ -# Useful conversions - -This article contains some useful conversion tables. Beware that we will omit the `0x` prefix on hex numbers: it will be evident from context which base is intended. - -- [Degrees and hex/binary angles](#degrees-and-hex-binary-angles) - * [Small angles](#small-angles) - * [Larger angles](#larger-angles) -- [Round decimal numbers in hex](#round-decimal-numbers-in-hex) - * [Small](#small) - * [Medium](#medium) - * [Large](#large) -- [Extra large](#extra-large) -- [Shifts/powers of 2 in dec and hex](#shifts-powers-of-2-in-dec-and-hex) - -## Degrees and hex/binary angles - -Conversion of degrees to binary angles in the two common ways, that give different answers. Table is produced using this script: - -```bash -$ printf "%s\t%s\t%s\n" "d" "d * 2^16/360" "2^16/360 * d" ; for i in {0..360..5} ; do printf "%d\t%X\t\t%X\n" "$i" $(( "$i" * 0x10000 / 360 )) $(( 0x10000 / 360 * "$i" )) ; done -``` - -### Small angles - -| `d` | `d * 2^16/360` | `2^16/360 * d` | -| ----: | -------------: | -------------: | -| 0 | 0 | 0 | -| 1 | B6 | B6 | -| 2 | 16C | 16C | -| 3 | 222 | 222 | -| 4 | 2D8 | 2D8 | -| 5 | 38E | 38E | -| 6 | 444 | 444 | -| 7 | 4FA | 4FA | -| 8 | 5B0 | 5B0 | -| 9 | 666 | 666 | -| 10 | 71C | 71C | -| 11 | 7D2 | 7D2 | -| 12 | 888 | 888 | -| 13 | 93E | 93E | -| 14 | 9F4 | 9F4 | -| 15 | AAA | AAA | -| 16 | B60 | B60 | -| 17 | C16 | C16 | -| 18 | CCC | CCC | -| 19 | D82 | D82 | -| 20 | E38 | E38 | -| 21 | EEE | EEE | -| 22 | FA4 | FA4 | -| 23 | 105B | 105A | -| 24 | 1111 | 1110 | -| 25 | 11C7 | 11C6 | -| 26 | 127D | 127C | -| 27 | 1333 | 1332 | -| 28 | 13E9 | 13E8 | -| 29 | 149F | 149E | -| 30 | 1555 | 1554 | - -### Larger angles - -| `d` | `d * 2^16/360` | `2^16/360 * d` | -| -----: | -------------: | -------------: | -| 0 | 0 | 0 | -| 5 | 38E | 38E | -| 10 | 71C | 71C | -| 15 | AAA | AAA | -| 20 | E38 | E38 | -| 25 | 11C7 | 11C6 | -| 30 | 1555 | 1554 | -| 35 | 18E3 | 18E2 | -| 40 | 1C71 | 1C70 | -| 45 | 2000 | 1FFE | -| 50 | 238E | 238C | -| 55 | 271C | 271A | -| 60 | 2AAA | 2AA8 | -| 65 | 2E38 | 2E36 | -| 70 | 31C7 | 31C4 | -| 75 | 3555 | 3552 | -| 80 | 38E3 | 38E0 | -| 85 | 3C71 | 3C6E | -| 90 | 4000 | 3FFC | -| 95 | 438E | 438A | -| 100 | 471C | 4718 | -| 105 | 4AAA | 4AA6 | -| 110 | 4E38 | 4E34 | -| 115 | 51C7 | 51C2 | -| 120 | 5555 | 5550 | -| 125 | 58E3 | 58DE | -| 130 | 5C71 | 5C6C | -| 135 | 6000 | 5FFA | -| 140 | 638E | 6388 | -| 145 | 671C | 6716 | -| 150 | 6AAA | 6AA4 | -| 155 | 6E38 | 6E32 | -| 160 | 71C7 | 71C0 | -| 165 | 7555 | 754E | -| 170 | 78E3 | 78DC | -| 175 | 7C71 | 7C6A | -| 180 | 8000 | 7FF8 | -| 185 | 838E | 8386 | -| 190 | 871C | 8714 | -| 195 | 8AAA | 8AA2 | -| 200 | 8E38 | 8E30 | -| 205 | 91C7 | 91BE | -| 210 | 9555 | 954C | -| 215 | 98E3 | 98DA | -| 220 | 9C71 | 9C68 | -| 225 | A000 | 9FF6 | -| 230 | A38E | A384 | -| 235 | A71C | A712 | -| 240 | AAAA | AAA0 | -| 245 | AE38 | AE2E | -| 250 | B1C7 | B1BC | -| 255 | B555 | B54A | -| 260 | B8E3 | B8D8 | -| 265 | BC71 | BC66 | -| 270 | C000 | BFF4 | -| 275 | C38E | C382 | -| 280 | C71C | C710 | -| 285 | CAAA | CA9E | -| 290 | CE38 | CE2C | -| 295 | D1C7 | D1BA | -| 300 | D555 | D548 | -| 305 | D8E3 | D8D6 | -| 310 | DC71 | DC64 | -| 315 | E000 | DFF2 | -| 320 | E38E | E380 | -| 325 | E71C | E70E | -| 330 | EAAA | EA9C | -| 335 | EE38 | EE2A | -| 340 | F1C7 | F1B8 | -| 345 | F555 | F546 | -| 350 | F8E3 | F8D4 | -| 355 | FC71 | FC62 | -| 360 | 10000 | FFF0 | - -Similarly for small angles with a smaller increment: - - - -## Round decimal numbers in hex - -```bash -printf "%s\t%s\n" "dec" "hex" ; for i in {0..100..5} ; do printf "%d\t%X\n" "$i" "$i" ; done -``` - -### Small - -| dec | hex | -| -----: | --: | -| 0 | 0 | -| 5 | 5 | -| 10 | A | -| 15 | F | -| 20 | 14 | -| 25 | 19 | -| 30 | 1E | -| 35 | 23 | -| 40 | 28 | -| 45 | 2D | -| 50 | 32 | -| 55 | 37 | -| 60 | 3C | -| 65 | 41 | -| 70 | 46 | -| 75 | 4B | -| 80 | 50 | -| 85 | 55 | -| 90 | 5A | -| 95 | 5F | -| 100 | 64 | - - -### Medium - -| dec | hex | -| -----: | ---: | -| 100 | 64 | -| 150 | 96 | -| 200 | C8 | -| 250 | FA | -| 300 | 12C | -| 350 | 15E | -| 400 | 190 | -| 450 | 1C2 | -| 500 | 1F4 | -| 550 | 226 | -| 600 | 258 | -| 650 | 28A | -| 700 | 2BC | -| 750 | 2EE | -| 800 | 320 | -| 850 | 352 | -| 900 | 384 | -| 950 | 3B6 | -| 1000 | 3E8 | - - -### Large - -| dec | hex | -| -----: | ----: | -| 1000 | 3E8 | -| 1500 | 5DC | -| 2000 | 7D0 | -| 2500 | 9C4 | -| 3000 | BB8 | -| 3500 | DAC | -| 4000 | FA0 | -| 4500 | 1194 | -| 5000 | 1388 | -| 5500 | 157C | -| 6000 | 1770 | -| 6500 | 1964 | -| 7000 | 1B58 | -| 7500 | 1D4C | -| 8000 | 1F40 | -| 8500 | 2134 | -| 9000 | 2328 | -| 9500 | 251C | -| 10000 | 2710 | - - -## Extra large -| dec | hex | -| -----: | ----: | -| 10000 | 2710 | -| 11000 | 2AF8 | -| 12000 | 2EE0 | -| 13000 | 32C8 | -| 14000 | 36B0 | -| 15000 | 3A98 | -| 16000 | 3E80 | -| 17000 | 4268 | -| 18000 | 4650 | -| 19000 | 4A38 | -| 20000 | 4E20 | -| 21000 | 5208 | -| 22000 | 55F0 | -| 23000 | 59D8 | -| 24000 | 5DC0 | -| 25000 | 61A8 | -| 26000 | 6590 | -| 27000 | 6978 | -| 28000 | 6D60 | -| 29000 | 7148 | -| 30000 | 7530 | - -## Shifts/powers of 2 in dec and hex - -```bash -$ printf "%s\t%s\t%s\n" "n" "1 << n (hex)" "1 << n (dec)" ; for i in {0..15..1} ; do printf "%d\t%X\t\t%d\n" "$i" $(( 1 << "$i" )) $(( 1 << "$i" )) ; done -``` -`1 << n` is the same as `2^n`. - -| `n` | `1 << n` (hex) | `1 << n` (dec) | -| -----: | -------------: | -------------: | -| 0 | 1 | 1 | -| 1 | 2 | 2 | -| 2 | 4 | 4 | -| 3 | 8 | 8 | -| 4 | 10 | 16 | -| 5 | 20 | 32 | -| 6 | 40 | 64 | -| 7 | 80 | 128 | -| 8 | 100 | 256 | -| 9 | 200 | 512 | -| 10 | 400 | 1024 | -| 11 | 800 | 2048 | -| 12 | 1000 | 4096 | -| 13 | 2000 | 8192 | -| 14 | 4000 | 16384 | -| 15 | 8000 | 32768 | - -