Game-Decompilation/mm
1
0
Fork 0
mirror of https://github.com/zeldaret/mm.git synced 2024-11-23 12:59:44 +00:00
Code Issues Actions Packages Projects Releases Wiki Activity

Contributing docs refresh (#793)

Browse Source 
* Contributing docs refresh

* Apply suggestions from code review

Co-authored-by: LtPeriwinkle <62761190+LtPeriwinkle@users.noreply.github.com>

* Link MM tutorial

* Add link to XML spec

* Review

Co-authored-by: LtPeriwinkle <62761190+LtPeriwinkle@users.noreply.github.com>
This commit is contained in:
EllipticEllipsis 2022-05-26 03:06:21 +01:00 committed by GitHub
parent c2afdf6eb0
commit 0582c636b8
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
7 changed files with 362 additions and 163 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

9
.github/pull_request_template.md vendored
View File

@ -1,9 +0,0 @@
Before opening this PR, ensure the following:
- `./format.sh` was run to apply standard formatting.
- `make` successfully builds a matching ROM.
- 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.
---
<!-- Leave the text above intact. Add additional comments below. -->

1
.gitignore vendored
View File

@ -46,6 +46,7 @@ tools/mips_to_c/
# Docs
!docs/**/*.png
docs/doxygen/
!.vscode/extensions.json
# Per-user configuration

133
CONTRIBUTING.md
View File

@ -1,5 +1,5 @@
Contributing to the Majora's Mask Decompilation Project
=======================================================
# 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.
@ -10,21 +10,19 @@ For general information about the project, see [our readme](https://github.com/z
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
------------
- [Discord](https://discord.zelda64.dev/) - Primary discussion platform.
- [Google Sheets reservation board](https://docs.google.com/spreadsheets/d/1X83YCPRa532v-Zo0WgUsJ2kB1X9RxBta5_p9aWA8uro) - We use this to track decompilation progress, not GitHub Issues.
## Useful Links
- [Installation guide](https://github.com/zeldaret/mm/blob/master/README.md#installation) - Instructions for getting this repository set up and built on your machine.
- [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.
- [Style Guide](docs/STYLE.md) - Description of the project style that we ask contributors to adhere to.
- [Code Review Guidelines](docs/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/) - Our homepage, with links to other resources.
- [Introduction to OOT decomp](https://github.com/zeldaret/oot/blob/master/docs/tutorial/contents.md) - A very detailed tutorial on how to get started with decomp. For OOT, but largely applicable to MM as well.
- The `#resources` channel on the Discord contains many more links
- [Zelda 64 Reverse Engineering Website](https://zelda64.dev/mm) - Our homepage, with FAQ and progress graph :chart_with_upwards_trend:.
- [MM decomp tutorial](docs/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/master/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
---------------
## Getting Started
### What should I know to take part?
@ -32,11 +30,14 @@ Basic knowledge of C, particularly arrays and pointers, is extremely useful. Kno
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 [OOT Practice Rom](http://practicerom.com/) (aka GZ) or the [MM Practice Rom](https://kz.zeldacodes.org/) (aka KZ) 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.
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*.
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.
**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
@ -46,53 +47,28 @@ 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.
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.
You should [join the Discord](https://discord.zelda64.dev/) to say hello and get suggestions on where to start on the `#mm-decomp` channel.
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 the [Google Sheets reservation board](https://docs.google.com/spreadsheets/d/1X83YCPRa532v-Zo0WgUsJ2kB1X9RxBta5_p9aWA8uro).
After joining the Discord, open the Google Sheets reservation board so you can claim your code file and avoid duplicate work.
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 work flow is: Reserve a file, decompile it, submit a PR, and then repeat while addressing review comments. The expectation is that one reservation goes to one file which ends up in a one file PR.
The workflow is:
- Reserve a file,
- decompile it,
- submit a PR,
- repeat while addressing review comments.
Please note that unless it is communicated beforehand you will be expected to fully complete the file if you reserve it on Google Sheets reservation board. Exceptions are always easy to approve if it's communicated to the team. Real life circumstances can prevent someone from finishing. In these cases they should link their repo/branch in the Google Sheets reservation board and unreserve immediately. Communicate any issues with your reservations as early as possible.
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.
Style Guide & Conventions
-------------------------
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.
Most of the C formatting style is enforced by the `format.sh` script which is based on `clang-format`.
Running `./format.sh` will apply our standard style to all `.c` files in the repository.
There are some conventions that cannot be automatically enforced.
## Style Guide & Conventions
### Naming Scheme
See the [Style Guide](docs/STYLE.md).
The following overlays are good examples of our naming conventions:
- [`ovl_Dm_Ravine`](src/overlays/actors/ovl_Dm_Ravine/z_dm_ravine.c)
- [`ovl_En_Jc_Mato`](src/overlays/actors/ovl_En_Jc_Mato/z_en_jc_mato.c)
These files demonstrate the following:
- Word order in names are from least-to-most specific (`DM_RAVINE_STATE_ACTIVE`, not `DM_RAVINE_ACTIVE_STATE`)
- Functions, structs, unions, enums, and typedefs are `TitleCase` (`DmRavine`)
- "Methods" for objects separate the object from the verb 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`)
- Public structs, enums, and constants should be defined in the header file in the following cases:
- The primary `Actor` struct (`DmRavine`)
- The actor's `InitVars`, as an `extern` symbol (`Dm_Ravine_InitVars`)
- Types used in other public declarations, like `actionFunc` typedefs (`DmRavineActionFunc`)
- Macros and enums for accessing & setting actor `params`
- The struct/enum/define is needed by other files
- Trailing commas in array and struct definitions (see `EnJcMatoDamageTable`)
- Constants converted to whichever looks best in context: hexadecimal, decimal, or float
- Rotation angles should always be in hexadecimal
- Define macros for bitwise access to `actor->params`
### `NON_MATCHING` & `NON_EQUIVALENT`
## `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:
@ -102,20 +78,23 @@ void CollisionCheck_SpawnWaterDroplets(GlobalContext* globalCtx, Vec3f* v) {
// ...
}
#else
void CollisionCheck_SpawnWaterDroplets(GlobalContext* globalCtx, Vec3f* v);
#pragma GLOBAL_ASM("asm/non_matchings/code/z_collision_check/CollisionCheck_SpawnWaterDroplets.s")
#endif
```
Before using `NON_MATCHING`, first try to use the [decomp-permuter](tools/decomp-permuter) tool to find a closer match.
Before PRing with a `NON_MATCHING`, you can try
- using the [decomp-permuter](tools/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 vs. Documenting
## 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.
So, beyond producing matching C code, the next steps are *documenting* the code.
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:
@ -123,22 +102,19 @@ Documenting is more than just adding comments. Documenting also includes:
- 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 `code/` and `boot/` should be documented. When documentation on a file has been started it should be as complete as possible.
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.
For right now, object segment symbols should not be documented/renamed.
These will be given names when object reconstruction is ready.
However, it can be useful to add comments with name suggestions.
See the [Style Guide](docs/STYLE.md) for more details on documentation style.
Pull Requests (PRs)
-------------------
## 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.
- `./format.sh` was run to apply standard formatting.
- `make` successfully builds a matching ROM.
- `./format.sh` 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.
@ -148,15 +124,28 @@ Feel free to reach out on the Discord if you have any questions about these step
### Pull Request Process
After opening a PR, the Jenkins server will verify your changes.
If there is an error, double-check that you can successfully `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`.
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 one reviewer and the project lead.
Each PR needs a review from two reviewers, at least one a project lead, and final approval from Kenix.
The PR author marks the comments as resolved: the commenter may not have permissions to do so.
Once all comments are addressed, it is courteous to ping the reviewer on either Discord or GitHub via re-requesting a review.
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.
After all the comments are addressed and at least one contributor has approved the review, the project lead can then review and merge the code.
The project lead is also responsible for ensuring that all of these procedures are followed.
Once all comments is addressed and all reviewers have approved, the PR will be merged.
Throughout the PR process, you (the author) should update the row on [Google Sheets reservation board](https://docs.google.com/spreadsheets/d/1X83YCPRa532v-Zo0WgUsJ2kB1X9RxBta5_p9aWA8uro) with the appropriate information as the decompilation process progresses.
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 master: it is always useful to have a clean master branch around if you need to fix something.
- When a PR is merged into master, 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 master 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.

24
README.md
View File

@ -17,15 +17,15 @@
```diff
- WARNING! -
The ROM this repository builds while has a matching checksum cannot be 'shifted' due
to hardcoded pointers which have yet to be dumped. Thus this repository is currently
in an experimental and research phase and cannot currently be used traditionally as a
source code base for general changes.
This repository is a work in progress, and while it can be used to make certain changes, it's
still constantly evolving. If you wish to use it for modding purposes in its current state,
please be aware that the codebase could drastically change at any time. Also note that some
parts of the ROM may not be 'shiftable' yet, so modifying them could currently be difficult.
```
This is a WIP **decompilation** of ***The Legend of Zelda: Majora's Mask***. The purpose of the project is to recreate a source code base for the game from scratch, using information found inside the game along with static and/or dynamic analysis. **It is not producing a PC port.** For more information you can get in touch with the team on our [Discord server](https://discord.zelda64.dev).
This is a WIP **decompilation** of ***The Legend of Zelda: Majora's Mask***. The purpose of the project is to recreate a source code base for the game from scratch, using information found inside the game along with static and/or dynamic analysis. **It is not, and will not, produce a PC port.** For frequently asked questions, you can visit [our website](https://zelda64.dev/mm), and for more information you can get in touch with the team on our [Discord server](https://discord.zelda64.dev).
The only build currently supported is N64 US, but other versions are planned to be supported.
The only version currently supported is N64 US, but we intend to eventually support every retail version of the original game (i.e. not versions of MM3D, which is a totally different game).
It currently builds the following ROM:
* mm.us.rev1.rom.z64 `md5: 2a0a8acb61538235bc1094d297fb6556`
@ -137,16 +137,10 @@ The disadvantage that the ordering of the terminal output is scrambled, so for d
## Contributing
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.
Some work also doesn't require much knowledge to get started.
Please note that is is our strict policy that *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.*
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.
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 or ZeldaRET's other decompilation projects.
For more information on getting started, see our [Contributing Guide](CONTRIBUTING.md) and our [Code Review Guidelines](REVIEWING.md) to see what code quality guidelines we follow.
## FAQ
### Q: Why does MM use transient assembly?
A: It is the view of the MM project leads that transient asm is safer than storing the disassembly in the repo. We feel like the C code is more transformative than a straight disassembly.
For more information on getting started, see our [Contributing Guide](CONTRIBUTING.md), [Style Guide](docs/STYLE.md) and our [Code Review Guidelines](docs/REVIEWING.md) to see what code quality guidelines we follow.

67
REVIEWING.md
View File

@ -1,67 +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* for the N64!
We invite all contributors to participate in our code review program. 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/master/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
------------
- [Discord](https://discord.zelda64.dev/) - Primary discussion platform.
- [Google Sheets reservation board](https://docs.google.com/spreadsheets/d/1X83YCPRa532v-Zo0WgUsJ2kB1X9RxBta5_p9aWA8uro) - We use this to track decompilation progress, not GitHub Issues.
- [Contributing guide](https://github.com/zeldaret/mm/blob/master/CONTRIBUTING.md) - Instructions for contributors.
- [Installation guide](https://github.com/zeldaret/mm/blob/master/README.md#installation) - Instructions for getting this repository set up and built on your machine.
- [Zelda 64 Reverse Engineering Website](https://zelda64.dev/) - Our homepage, with links to other resources.
- [Introduction to OOT decomp](https://github.com/zeldaret/oot/blob/master/docs/tutorial/contents.md) - A very detailed tutorial on how to get started with decomp. For OOT, but largely applicable to MM as well.
- The `#resources` channel on the Discord contains many more links
Getting Started
---------------
### What should I know to take part in the review process?
You should first get yourself familiar with our [Contributing guide](https://github.com/zeldaret/mm/blob/master/CONTRIBUTING.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 check for all of the items in the checklist. It is meant as a guide.
- Once the PR author has addressed all of your comments, you should add a comment 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. The project lead will have final say in these situations. All decisions will generally be guided by a consensus of contributors.
### Reviewer Checklist
- [ ] Jenkins build is successful.
- [ ] `make` builds a matching ROM.
- [ ] Any new compiler warnings that were added are required for matching. Ensure there is good reason if the warnings files have changed. `./tools/warnings_count/warnings_build_current.txt` and `./tools/warnings_count/warnings_setup_current.txt`
- [ ] Files with NON_MATCHING functions have equivalent behaviour. (This will only be reviewed once we have shiftability since equivalence testing is easiest in game)
- [ ] `code` and `boot` segment files should be documented as much as possible. Overlays with documentation should be complete.
- [ ] Overlays with documentation should have macros to define access to parameters if the parameter uses bitwise access. The params should have an enum when it makes sense.
- [ ] `format.sh` was run.
- [ ] 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`)
- [ ] "Methods" for objects separate the system from the verb 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 (see `EnJcMatoDamageTable`)

59
docs/REVIEWING.md Normal file
View File

@ -0,0 +1,59 @@
# 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/master/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](docs/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.sh` 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.

232
docs/STYLE.md Normal file
View File

@ -0,0 +1,232 @@
# 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_MarkForDeath` 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_4 | ACTOR_FLAG_8`) 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.
## GlobalCtx2
In some particular instances, IDO requires the function argument `globalCtx` to be cast to a second variable of the same type to match. In these particular instances, the function argument should be renamed to `globalCtx2` and than this `globalCtx2` just assigned to a stack variable called `globalCtx`. This cast should occur before the actor `THIS` cast is made. For example in `z_en_firefly.c`
```c
void EnFirefly_Update(Actor* thisx, GlobalContext* globalCtx2) {
GlobalContext* globalCtx = globalCtx2;
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, GlobalContext* globalCtx) {
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.