From d5b71bd0f531986d2a6a63f0a90d8e1233e01a7f Mon Sep 17 00:00:00 2001
From: EllipticEllipsis <73679967+EllipticEllipsis@users.noreply.github.com>
Date: Thu, 16 Dec 2021 23:47:18 +0000
Subject: [PATCH] Tutorial (#362)
* ObjTree OK, data imported
* EnMs OK, data imported
* And the spec
* OK
* Some minor edits
* A lot of preliminary stuff
* Mostly complete beginning
* First draft of other functions doc
* Whoops, forgot the GlobalContext pad
* Draw functions (minus colour), create Data
* Data
* gitignore, some progress on documenting
* Review comments, continue documenting
* spec
* Finish off documentation
* undefined_syms
* Add a couple of todos
* One more
* At least add tools for object decomp
* Start conversion table stuff
* Document ObjTree
* Document EnMs
* Add more tables to conversions
* Maide's review
* Review
* Review
* Typos and incomplete thoughts
* Update vscode.md
* Correct function/variable names
* Review suggestions
* Format
* Missed one
* Rename functions and format
* Fix ObjTree
* Update actorfixer.py, fix some variable names
* Some review
* Review suggestions
* More review
* Hopefully fix all the thisx references
* Missed one
---
.gitignore | 1 +
docs/tutorial/advanced_control_flow.md | 747 ++++++++++++++++++
docs/tutorial/beginning_decomp.md | 675 ++++++++++++++++
docs/tutorial/contents.md | 56 ++
docs/tutorial/data.md | 171 ++++
docs/tutorial/diff_and_permuter.md | 145 ++++
docs/tutorial/disassembly_quirks.md | 36 +
docs/tutorial/documenting.md | 601 ++++++++++++++
docs/tutorial/draw_functions.md | 303 +++++++
.../images/EnRecepgirl_Init_diff_matching.png | Bin 0 -> 115482 bytes
.../images/EnRecepgirl_stack_diff.png | Bin 0 -> 14017 bytes
docs/tutorial/images/En_Recepgirl.gv.png | Bin 0 -> 64180 bytes
docs/tutorial/images/fresh_actor_data.png | Bin 0 -> 43984 bytes
docs/tutorial/images/func_80C100DC_diff1.png | Bin 0 -> 48501 bytes
docs/tutorial/images/func_80C100DC_diff2.png | Bin 0 -> 52908 bytes
docs/tutorial/images/func_80C100DC_diff3.png | Bin 0 -> 54359 bytes
docs/tutorial/images/func_80C102D4_diff1.png | Bin 0 -> 100966 bytes
docs/tutorial/images/func_80C102D4_diff2.png | Bin 0 -> 112959 bytes
docs/tutorial/images/z64utils_main.png | Bin 0 -> 31423 bytes
.../images/z64utils_object_analyzed.png | Bin 0 -> 70998 bytes
.../images/z64utils_object_analyzer.png | Bin 0 -> 11211 bytes
.../images/z64utils_skeleton_error.png | Bin 0 -> 18512 bytes
.../images/z64utils_skeleton_head.png | Bin 0 -> 95083 bytes
docs/tutorial/introduction.md | 87 ++
docs/tutorial/merging.md | 97 +++
docs/tutorial/object_decomp.md | 14 +
docs/tutorial/other_functions.md | 605 ++++++++++++++
docs/tutorial/types_structs_padding.md | 159 ++++
docs/tutorial/vscode.md | 84 ++
docs/useful_conversions.md | 275 +++++++
include/z64item.h | 13 +-
include/z64object.h | 2 +-
include/z64player.h | 8 +-
spec | 9 +-
src/code/code_8012EC80.c | 14 +-
src/code/z_face_reaction.c | 2 +-
.../actors/ovl_En_Bji_01/z_en_bji_01.c | 2 +-
src/overlays/actors/ovl_En_Daiku/z_en_daiku.c | 2 +-
src/overlays/actors/ovl_En_Fsn/z_en_fsn.c | 2 +-
.../actors/ovl_En_Ma_Yto/z_en_ma_yto.c | 4 +-
src/overlays/actors/ovl_En_Ms/z_en_ms.c | 162 +++-
src/overlays/actors/ovl_En_Ms/z_en_ms.h | 10 +-
src/overlays/actors/ovl_En_Muto/z_en_muto.c | 2 +-
src/overlays/actors/ovl_En_Pm/z_en_pm.c | 2 +-
.../actors/ovl_En_Recepgirl/z_en_recepgirl.c | 197 ++++-
.../actors/ovl_En_Recepgirl/z_en_recepgirl.h | 11 +-
src/overlays/actors/ovl_En_Sob1/z_en_sob1.c | 2 +-
src/overlays/actors/ovl_Obj_Tree/z_obj_tree.c | 148 +++-
src/overlays/actors/ovl_Obj_Tree/z_obj_tree.h | 13 +-
tools/actorfixer.py | 162 ++++
tools/disasm/functions.txt | 32 +-
tools/disasm/variables.txt | 6 +-
tools/sizes/code_functions.csv | 284 +++----
undefined_syms.txt | 3 +
54 files changed, 4878 insertions(+), 270 deletions(-)
create mode 100644 docs/tutorial/advanced_control_flow.md
create mode 100644 docs/tutorial/beginning_decomp.md
create mode 100644 docs/tutorial/contents.md
create mode 100644 docs/tutorial/data.md
create mode 100644 docs/tutorial/diff_and_permuter.md
create mode 100644 docs/tutorial/disassembly_quirks.md
create mode 100644 docs/tutorial/documenting.md
create mode 100644 docs/tutorial/draw_functions.md
create mode 100644 docs/tutorial/images/EnRecepgirl_Init_diff_matching.png
create mode 100644 docs/tutorial/images/EnRecepgirl_stack_diff.png
create mode 100644 docs/tutorial/images/En_Recepgirl.gv.png
create mode 100644 docs/tutorial/images/fresh_actor_data.png
create mode 100644 docs/tutorial/images/func_80C100DC_diff1.png
create mode 100644 docs/tutorial/images/func_80C100DC_diff2.png
create mode 100644 docs/tutorial/images/func_80C100DC_diff3.png
create mode 100644 docs/tutorial/images/func_80C102D4_diff1.png
create mode 100644 docs/tutorial/images/func_80C102D4_diff2.png
create mode 100644 docs/tutorial/images/z64utils_main.png
create mode 100644 docs/tutorial/images/z64utils_object_analyzed.png
create mode 100644 docs/tutorial/images/z64utils_object_analyzer.png
create mode 100644 docs/tutorial/images/z64utils_skeleton_error.png
create mode 100644 docs/tutorial/images/z64utils_skeleton_head.png
create mode 100644 docs/tutorial/introduction.md
create mode 100644 docs/tutorial/merging.md
create mode 100644 docs/tutorial/object_decomp.md
create mode 100644 docs/tutorial/other_functions.md
create mode 100644 docs/tutorial/types_structs_padding.md
create mode 100644 docs/tutorial/vscode.md
create mode 100644 docs/useful_conversions.md
diff --git a/.gitignore b/.gitignore
index b09a0acd3f..a6d3f3b8f5 100644
--- a/.gitignore
+++ b/.gitignore
@@ -44,6 +44,7 @@ tools/mips_to_c/
# Docs
!docs/**/*.png
+!.vscode/extensions.json
# Per-user configuration
.python-version
diff --git a/docs/tutorial/advanced_control_flow.md b/docs/tutorial/advanced_control_flow.md
new file mode 100644
index 0000000000..953e3e44d7
--- /dev/null
+++ b/docs/tutorial/advanced_control_flow.md
@@ -0,0 +1,747 @@
+# 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, GlobalContext* globalCtx);
+void EnMs_Destroy(Actor* thisx, GlobalContext* globalCtx);
+void EnMs_Update(Actor* thisx, GlobalContext* globalCtx);
+void EnMs_Draw(Actor* thisx, GlobalContext* globalCtx);
+
+void func_80952734(EnMs* this, GlobalContext* globalCtx);
+void func_809527F8(EnMs* this, GlobalContext* globalCtx);
+void func_809529AC(EnMs* this, GlobalContext* globalCtx);
+void func_80952A1C(EnMs *this, GlobalContext *globalCtx);
+
+const ActorInit En_Ms_InitVars = {
+ ACTOR_EN_MS,
+ ACTORCAT_NPC,
+ FLAGS,
+ OBJECT_MS,
+ sizeof(EnMs),
+ (ActorFunc)EnMs_Init,
+ (ActorFunc)EnMs_Destroy,
+ (ActorFunc)EnMs_Update,
+ (ActorFunc)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, GlobalContext* globalCtx) {
+ EnMs* this = THIS;
+
+ Actor_ProcessInitChain(thisx, D_80952BCC);
+ SkelAnime_InitFlex(globalCtx, &this->skelAnime, &D_06003DC0, &D_060005EC, this->jointTable, this->morphTable, 9);
+ Collider_InitCylinder(globalCtx, &this->collider);
+ Collider_SetCylinderType1(globalCtx, &this->collider, &this->actor, &D_80952BA0);
+ ActorShape_Init(&this->actor.shape, 0.0f, func_800B3FC0, 35.0f);
+ Actor_SetScale(&this->actor, 0.015f);
+ this->actor.colChkInfo.mass = 0xFF;
+ this->actionFunc = func_80952734;
+ this->actor.speedXZ = 0.0f;
+ this->actor.velocity.y = 0.0f;
+ this->actor.gravity = -1.0f;
+}
+
+void EnMs_Destroy(Actor* thisx, GlobalContext* globalCtx) {
+ EnMs* this = THIS;
+
+ Collider_DestroyCylinder(globalCtx, &this->collider);
+}
+
+void func_80952734(EnMs* this, GlobalContext* globalCtx) {
+ s16 temp_v1 = this->actor.yawTowardsPlayer - this->actor.shape.rot.y;
+
+ if (gSaveContext.inventory.items[10] == ITEM_NONE) {
+ this->actor.textId = 0x92E;
+ } else {
+ this->actor.textId = 0x932;
+ }
+
+ if (func_800B84D0(&this->actor, globalCtx) != 0) {
+ this->actionFunc = func_809527F8;
+ return;
+ }
+
+ if (this->actor.xzDistToPlayer < 90.0f) {
+ if (ABS_ALT(temp_v1) < 0x2000) {
+ func_800B8614(&this->actor, globalCtx, 90.0f);
+ }
+ }
+}
+
+#pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Ms/func_809527F8.s")
+
+void func_809529AC(EnMs *this, GlobalContext *globalCtx) {
+ if (Actor_HasParent(&this->actor, globalCtx)) {
+ this->actor.textId = 0;
+ func_800B8500(&this->actor, globalCtx, this->actor.xzDistToPlayer, this->actor.playerHeightRel, 0);
+ this->actionFunc = func_80952A1C;
+ } else {
+ func_800B8A1C(&this->actor, globalCtx, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel);
+ }
+}
+
+void func_80952A1C(EnMs *this, GlobalContext *globalCtx) {
+ if (func_800B84D0(&this->actor, globalCtx)) {
+ func_80151938(globalCtx, 0x936U);
+ this->actionFunc = func_809527F8;
+ } else {
+ func_800B8500(&this->actor, globalCtx, this->actor.xzDistToPlayer, this->actor.playerHeightRel, -1);
+ }
+}
+
+void EnMs_Update(Actor* thisx, GlobalContext* globalCtx) {
+ s32 pad;
+ EnMs* this = THIS;
+
+ Actor_SetHeight(&this->actor, 20.0f);
+ this->actor.targetArrowOffset = 500.0f;
+ Actor_SetScale(&this->actor, 0.015f);
+ SkelAnime_Update(&this->skelAnime);
+ this->actionFunc(this, globalCtx);
+ Collider_UpdateCylinder(&this->actor, &this->collider);
+ CollisionCheck_SetOC(globalCtx, &globalCtx->colChkCtx, &this->collider.base);
+}
+
+void EnMs_Draw(Actor* thisx, GlobalContext* globalCtx) {
+ EnMs* this = THIS;
+
+ func_8012C28C(globalCtx->state.gfxCtx);
+ SkelAnime_DrawFlexOpa(globalCtx, 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, GlobalContext *globalCtx) {
+ u8 temp_v0;
+ u8 temp_v0_2;
+
+ temp_v0 = func_80152498(&globalCtx->msgCtx);
+ if (temp_v0 != 4) {
+ if (temp_v0 != 5) {
+ if ((temp_v0 == 6) && (func_80147624(globalCtx) != 0)) {
+ this->actionFunc = func_80952734;
+ return;
+ }
+ // Duplicate return node #17. Try simplifying control flow for better match
+ return;
+ }
+ if (func_80147624(globalCtx) != 0) {
+ func_801477B4(globalCtx);
+ func_800B8A1C((Actor *) this, globalCtx, 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 (func_80147624(globalCtx) != 0) {
+ temp_v0_2 = globalCtx->msgCtx.choiceIndex;
+ if (temp_v0_2 != 0) {
+ if (temp_v0_2 != 1) {
+
+ }
+ func_8019F230();
+ func_80151938(globalCtx, 0x934U);
+ // Duplicate return node #17. Try simplifying control flow for better match
+ return;
+ }
+ func_801477B4(globalCtx);
+ if ((s32) gSaveContext.rupees < 0xA) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x935U);
+ return;
+ }
+ if ((s32) gSaveContext.inventory.ammo[gItemSlots[0xA]] >= 0x14) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x937U);
+ return;
+ }
+ func_8019F208();
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, 90.0f, 10.0f);
+ func_801159EC(-0xA);
+ this->actionFunc = func_809529AC;
+ }
+}
+```
+
+which is long, messy, and contains some rather nasty-looking control flow, including horrors like
+
+```C
+ temp_v0 = func_80152498(&globalCtx->msgCtx);
+ if (temp_v0 != 4) {
+ if (temp_v0 != 5) {
+ if ((temp_v0 == 6) && (func_80147624(globalCtx) != 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, GlobalContext *globalCtx) {
+ u8 temp_v0;
+ u8 temp_v0_2;
+
+ temp_v0 = func_80152498(&globalCtx->msgCtx);
+ if (temp_v0 == 4) {
+ goto block_7;
+ }
+ if (temp_v0 == 5) {
+ goto block_5;
+ }
+ if (temp_v0 != 6) {
+ goto block_17;
+ }
+ if (func_80147624(globalCtx) == 0) {
+ goto block_17;
+ }
+ this->actionFunc = func_80952734;
+ return;
+block_5:
+ if (func_80147624(globalCtx) == 0) {
+ goto block_17;
+ }
+ func_801477B4(globalCtx);
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel);
+ this->actionFunc = func_809529AC;
+ return;
+block_7:
+ if (func_80147624(globalCtx) == 0) {
+ goto block_17;
+ }
+ temp_v0_2 = globalCtx->msgCtx.choiceIndex;
+ if (temp_v0_2 == 0) {
+ goto block_11;
+ }
+ if (temp_v0_2 == 1) {
+ goto block_16;
+ }
+ goto block_16;
+block_11:
+ func_801477B4(globalCtx);
+ if ((s32) gSaveContext.rupees >= 0xA) {
+ goto block_13;
+ }
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x935U);
+ return;
+block_13:
+ if ((s32) gSaveContext.inventory.ammo[gItemSlots[0xA]] < 0x14) {
+ goto block_15;
+ }
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x937U);
+ return;
+block_15:
+ func_8019F208();
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, 90.0f, 10.0f);
+ func_801159EC(-0xA);
+ this->actionFunc = func_809529AC;
+ return;
+block_16:
+ func_8019F230();
+ func_80151938(globalCtx, 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.rupees >= 0xA) {
+ goto block_13;
+ }
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x935U);
+ return;
+block_13:
+```
+
+Currently, this says to jump over the code block `play_sound...` 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.rupees < 0xA) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 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, GlobalContext *globalCtx) {
+ u8 temp_v0;
+ u8 temp_v0_2;
+
+ temp_v0 = func_80152498(&globalCtx->msgCtx);
+ if (temp_v0 == 4) {
+ goto block_7;
+ }
+ if (temp_v0 == 5) {
+ goto block_5;
+ }
+ if (temp_v0 != 6) {
+ goto block_17;
+ }
+ if (func_80147624(globalCtx) == 0) {
+ goto block_17;
+ }
+ this->actionFunc = func_80952734;
+ return;
+block_5:
+ if (func_80147624(globalCtx) == 0) {
+ goto block_17;
+ }
+ func_801477B4(globalCtx);
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel);
+ this->actionFunc = func_809529AC;
+ return;
+block_7:
+ if (func_80147624(globalCtx) == 0) {
+ goto block_17;
+ }
+ temp_v0_2 = globalCtx->msgCtx.choiceIndex;
+ if (temp_v0_2 == 0) {
+ goto block_11;
+ }
+ if (temp_v0_2 == 1) {
+ goto block_16;
+ }
+ goto block_16;
+block_11:
+ func_801477B4(globalCtx);
+
+ if (gSaveContext.rupees < 0xA) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x935U);
+ return;
+ }
+ if (gSaveContext.inventory.ammo[gItemSlots[0xA]] >= 0x14) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x937U);
+ return;
+ }
+
+ func_8019F208();
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, 90.0f, 10.0f);
+ func_801159EC(-0xA);
+ this->actionFunc = func_809529AC;
+ return;
+block_16:
+ func_8019F230();
+ func_80151938(globalCtx, 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, GlobalContext *globalCtx) {
+ u8 temp_v0;
+ u8 temp_v0_2;
+
+ temp_v0 = func_80152498(&globalCtx->msgCtx);
+ if (temp_v0 == 4) {
+ goto block_7;
+ }
+ if (temp_v0 == 5) {
+ goto block_5;
+ }
+ if (temp_v0 != 6) {
+ return;
+ }
+ if (func_80147624(globalCtx) == 0) {
+ return;
+ }
+ this->actionFunc = func_80952734;
+ return;
+block_5:
+ if (func_80147624(globalCtx) == 0) {
+ return;
+ }
+ func_801477B4(globalCtx);
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel);
+ this->actionFunc = func_809529AC;
+ return;
+block_7:
+ if (func_80147624(globalCtx) == 0) {
+ return;
+ }
+ temp_v0_2 = globalCtx->msgCtx.choiceIndex;
+ if (temp_v0_2 == 0) {
+ goto block_11;
+ }
+ if (temp_v0_2 == 1) {
+ goto block_16;
+ }
+ goto block_16;
+block_11:
+ func_801477B4(globalCtx);
+
+ if (gSaveContext.rupees < 0xA) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x935U);
+ return;
+ }
+ if (gSaveContext.inventory.ammo[gItemSlots[0xA]] >= 0x14) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x937U);
+ return;
+ }
+
+ func_8019F208();
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, 90.0f, 10.0f);
+ func_801159EC(-0xA);
+ this->actionFunc = func_809529AC;
+ return;
+block_16:
+ func_8019F230();
+ func_80151938(globalCtx, 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 = globalCtx->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 (globalCtx->msgCtx.choiceIndex) {
+ case 0:
+ func_801477B4(globalCtx);
+
+ if (gSaveContext.rupees < 0xA) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x935U);
+ return;
+ }
+ if (gSaveContext.inventory.ammo[gItemSlots[0xA]] >= 0x14) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x937U);
+ return;
+ }
+
+ func_8019F208();
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, 90.0f, 10.0f);
+ func_801159EC(-0xA);
+ this->actionFunc = func_809529AC;
+ return;
+ break;
+
+ case 1:
+ default:
+ func_8019F230();
+ func_80151938(globalCtx, 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 (globalCtx->msgCtx.choiceIndex) {
+ case 0:
+ func_801477B4(globalCtx);
+
+ if (gSaveContext.rupees < 0xA) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x935U);
+ } else if (gSaveContext.inventory.ammo[gItemSlots[0xA]] >= 0x14) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x937U);
+ } else {
+ func_8019F208();
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, 90.0f, 10.0f);
+ func_801159EC(-0xA);
+ this->actionFunc = func_809529AC;
+ }
+ break;
+
+ case 1:
+ default:
+ func_8019F230();
+ func_80151938(globalCtx, 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 (func_80147624(globalCtx) == 0) {
+ return;
+ }
+```
+
+can be swapped round and made to wrap the switch. This leaves us with
+
+```C
+void func_809527F8(EnMs *this, GlobalContext *globalCtx) {
+ u8 temp_v0;
+
+ temp_v0 = func_80152498(&globalCtx->msgCtx);
+ if (temp_v0 == 4) {
+ goto block_7;
+ }
+ if (temp_v0 == 5) {
+ goto block_5;
+ }
+ if (temp_v0 != 6) {
+ return;
+ }
+ if (func_80147624(globalCtx) == 0) {
+ return;
+ }
+ this->actionFunc = func_80952734;
+ return;
+block_5:
+ if (func_80147624(globalCtx) == 0) {
+ return;
+ }
+ func_801477B4(globalCtx);
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel);
+ this->actionFunc = func_809529AC;
+ return;
+block_7:
+ if (func_80147624(globalCtx) != 0) {
+ switch (globalCtx->msgCtx.choiceIndex) {
+ case 0:
+ func_801477B4(globalCtx);
+
+ if (gSaveContext.rupees < 0xA) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x935U);
+ } else if (gSaveContext.inventory.ammo[gItemSlots[0xA]] >= 0x14) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x937U);
+ } else {
+ func_8019F208();
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, 90.0f, 10.0f);
+ func_801159EC(-0xA);
+ this->actionFunc = func_809529AC;
+ }
+ break;
+
+ case 1:
+ default:
+ func_8019F230();
+ func_80151938(globalCtx, 0x934U);
+ break;
+ }
+ }
+}
+```
+
+Now, the top of the function also looks like a switch:
+```C
+ temp_v0 = func_80152498(&globalCtx->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, GlobalContext *globalCtx) {
+ switch (func_80152498(&globalCtx->msgCtx)) {
+ case 6:
+ this->actionFunc = func_80952734;
+ break;
+
+ case 5:
+ if (func_80147624(globalCtx) == 0) {
+ return;
+ }
+ func_801477B4(globalCtx);
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel);
+ this->actionFunc = func_809529AC;
+ break;
+
+ case 4:
+ if (func_80147624(globalCtx) != 0) {
+ switch (globalCtx->msgCtx.choiceIndex) {
+ case 0:
+ func_801477B4(globalCtx);
+
+ if (gSaveContext.rupees < 0xA) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x935U);
+ } else if (gSaveContext.inventory.ammo[gItemSlots[0xA]] >= 0x14) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x937U);
+ } else {
+ func_8019F208();
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, 90.0f, 10.0f);
+ func_801159EC(-0xA);
+ this->actionFunc = func_809529AC;
+ }
+ break;
+
+ case 1:
+ default:
+ func_8019F230();
+ func_80151938(globalCtx, 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, GlobalContext *globalCtx) {
+ switch (func_80152498(&globalCtx->msgCtx)) {
+ case 6:
+ this->actionFunc = func_80952734;
+ break;
+
+ case 5:
+ if (func_80147624(globalCtx) != 0) {
+ func_801477B4(globalCtx);
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, this->actor.xzDistToPlayer, this->actor.playerHeightRel);
+ this->actionFunc = func_809529AC;
+ }
+ break;
+
+ case 4:
+ if (func_80147624(globalCtx) != 0) {
+ switch (globalCtx->msgCtx.choiceIndex) {
+ case 0:
+ func_801477B4(globalCtx);
+
+ if (gSaveContext.rupees < 0xA) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x935U);
+ } else if (gSaveContext.inventory.ammo[gItemSlots[0xA]] >= 0x14) {
+ play_sound(0x4806U);
+ func_80151938(globalCtx, 0x937U);
+ } else {
+ func_8019F208();
+ func_800B8A1C((Actor *) this, globalCtx, 0x35, 90.0f, 10.0f);
+ func_801159EC(-0xA);
+ this->actionFunc = func_809529AC;
+ }
+ break;
+
+ case 1:
+ default:
+ func_8019F230();
+ func_80151938(globalCtx, 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/docs/tutorial/beginning_decomp.md b/docs/tutorial/beginning_decomp.md
new file mode 100644
index 0000000000..01cc21cf3b
--- /dev/null
+++ b/docs/tutorial/beginning_decomp.md
@@ -0,0 +1,675 @@
+# 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, GlobalContext* globalCtx);
+void EnRecepgirl_Destroy(Actor* thisx, GlobalContext* globalCtx);
+void EnRecepgirl_Update(Actor* thisx, GlobalContext* globalCtx);
+void EnRecepgirl_Draw(Actor* thisx, GlobalContext* globalCtx);
+
+// --------------- 4 ---------------
+#if 0
+const ActorInit En_Recepgirl_InitVars = {
+ ACTOR_EN_RECEPGIRL,
+ ACTORCAT_NPC,
+ FLAGS,
+ OBJECT_BG,
+ sizeof(EnRecepgirl),
+ (ActorFunc)EnRecepgirl_Init,
+ (ActorFunc)EnRecepgirl_Destroy,
+ (ActorFunc)EnRecepgirl_Update,
+ (ActorFunc)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.
+
+5. `if`'d-out section containing the `InitVars` and a few other common pieces of data. This can be ignored until we import the data.
+
+4. 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). Once the corresponding object files have been decompiled, these will simply be replaced by including the object file (see [Object Decompilation](object_decomp.md) for how this process works). These symbols have been automatically extracted from the MIPS code. There may turn out to be some that were not caught by the script, in which case they need to be placed in the file called `undefined_syms.txt` in the root directory of the project. Ask in Discord for how to do this: it is simple, but rare enough to not be worth covering here.
+
+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*, GlobalContext*);
+
+typedef struct EnRecepgirl {
+ /* 0x0000 */ Actor actor;
+ /* 0x0144 */ char unk_144[0x164];
+ /* 0x02A8 */ EnRecepgirlActionFunc actionFunc;
+ /* 0x02AC */ char unk_2AC[0x8];
+} EnRecepgirl; // size = 0x2B4
+
+extern const ActorInit En_Recepgirl_InitVars;
+
+#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, GlobalContext* globalCtx);
+```
+
+- 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
+
+
+
+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/master/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, GlobalContext *globalCtx) {
+ 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(globalCtx, (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(globalCtx, (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, GlobalContext *globalCtx) {
+ 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(globalCtx, (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(globalCtx, (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, GlobalContext *globalCtx) {
+ 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(globalCtx, (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(globalCtx, (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
+const ActorInit En_Recepgirl_InitVars = {
+ ACTOR_EN_RECEPGIRL,
+ ACTORCAT_NPC,
+ FLAGS,
+ OBJECT_BG,
+ sizeof(EnRecepgirl),
+ (ActorFunc)EnRecepgirl_Init,
+ (ActorFunc)EnRecepgirl_Destroy,
+ (ActorFunc)EnRecepgirl_Update,
+ (ActorFunc)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(globalCtx, (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(GlobalContext* globalCtx, SkelAnime* skelAnime, FlexSkeletonHeader* skeletonHeaderSeg,
+ AnimationHeader* animationSeg, 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(globalCtx, &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, GlobalContext *globalCtx) {
+ 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(globalCtx, &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(globalCtx, (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(globalCtx, (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*, GlobalContext*)`.
+
+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, GlobalContext* globalCtx);
+void EnRecepgirl_Destroy(Actor* thisx, GlobalContext* globalCtx);
+void EnRecepgirl_Update(Actor* thisx, GlobalContext* globalCtx);
+void EnRecepgirl_Draw(Actor* thisx, GlobalContext* globalCtx);
+
+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.
+
+0. `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.
+
+1. 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];
+```
+
+2.
+```C
+ temp_s0 = &D_80C106B0[3];
+ D_80C106B0[2] = Lib_SegmentedToVirtual(D_80C106B0[2]);
+ phi_s0 = &D_80C106B0[3];
+```
+
+3.
+```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, GlobalContext *globalCtx) {
+ EnRecepgirl* this = THIS;
+
+ Actor_ProcessInitChain(&this->actor, D_80C106C0);
+ ActorShape_Init(&this->actor.shape, -60.0f, NULL, 0.0f);
+ SkelAnime_InitFlex(globalCtx, &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(globalCtx, 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 master 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.)
+
+
+
+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/docs/tutorial/contents.md b/docs/tutorial/contents.md
new file mode 100644
index 0000000000..227f4fc7d4
--- /dev/null
+++ b/docs/tutorial/contents.md
@@ -0,0 +1,56 @@
+# Getting started
+
+## [Introduction to decomp](introduction.md)
+- What we are doing
+- Structure of the code
+
+## Pre-decompilation
+- 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
+
+## [Object Decompilation](object_decomp.md) (TODO)
+- 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/docs/tutorial/data.md b/docs/tutorial/data.md
new file mode 100644
index 0000000000..ae856123e9
--- /dev/null
+++ b/docs/tutorial/data.md
@@ -0,0 +1,171 @@
+# Data
+
+Up: [Contents](contents.md)
+Previous: [Draw functions](draw_functions.md)
+
+## Table of Contents
+
+- [Data first](#data-first)
+- [Extern and data last](#extern-and-data-last)
+- [Segmented pointers](#segmented-pointers)
+- [Fake symbols](#fake-symbols)
+- [Inlining](#inlining)
+
+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/master/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
+const ActorInit En_Recepgirl_InitVars = {
+ ACTOR_EN_RECEPGIRL,
+ ACTORCAT_NPC,
+ FLAGS,
+ OBJECT_BG,
+ sizeof(EnRecepgirl),
+ (ActorFunc)EnRecepgirl_Init,
+ (ActorFunc)EnRecepgirl_Destroy,
+ (ActorFunc)EnRecepgirl_Update,
+ (ActorFunc)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
+const ActorInit En_Recepgirl_InitVars = {
+ ACTOR_EN_RECEPGIRL,
+ ACTORCAT_NPC,
+ FLAGS,
+ OBJECT_BG,
+ sizeof(EnRecepgirl),
+ (ActorFunc)EnRecepgirl_Init,
+ (ActorFunc)EnRecepgirl_Destroy,
+ (ActorFunc)EnRecepgirl_Update,
+ (ActorFunc)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
+
+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.)
+
+This is mitigated by use of the file `undefined_syms.txt`, which feeds the linker the raw addresses to use as the symbol definitions. If you find a segmented address that is not in already externed, `extern` it at the top of the file and add it to the actor's section in undefined_syms:
+```C
+extern void* D_0600F8F0;
+extern void* D_0600FCF0;
+extern void* D_060100F0;
+extern void* D_0600FCF0;
+
+static void* D_80C106B0[4] = { &D_0600F8F0, &D_0600FCF0, &D_060100F0, &D_0600FCF0 };
+```
+and in undefined_syms.txt:
+```
+// ovl_En_Recepgirl
+D_06000968 = 0x06000968;
+D_06001384 = 0x06001384;
+D_06009890 = 0x06009890;
+D_0600A280 = 0x0600A280;
+D_0600AD98 = 0x0600AD98;
+D_0600F8F0 = 0x0600F8F0;
+D_0600FCF0 = 0x0600FCF0;
+D_060100F0 = 0x060100F0;
+D_06011B60 = 0x06011B60;
+```
+
+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/docs/tutorial/diff_and_permuter.md b/docs/tutorial/diff_and_permuter.md
new file mode 100644
index 0000000000..aa72999d15
--- /dev/null
+++ b/docs/tutorial/diff_and_permuter.md
@@ -0,0 +1,145 @@
+# `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/master/docs/tutorial/beginning_decomp.md#diff) and [here for the permuter](https://github.com/zeldaret/oot/blob/master/docs/tutorial/other_functions.md#the-permuter).
+
+
+
+
diff --git a/docs/tutorial/disassembly_quirks.md b/docs/tutorial/disassembly_quirks.md
new file mode 100644
index 0000000000..dacfb78d81
--- /dev/null
+++ b/docs/tutorial/disassembly_quirks.md
@@ -0,0 +1,36 @@
+# 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/docs/tutorial/documenting.md b/docs/tutorial/documenting.md
new file mode 100644
index 0000000000..9b2c8e177e
--- /dev/null
+++ b/docs/tutorial/documenting.md
@@ -0,0 +1,601 @@
+# 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, GlobalContext* globalCtx);
+void EnRecepgirl_Destroy(Actor* thisx, GlobalContext* globalCtx);
+void EnRecepgirl_Update(Actor* thisx, GlobalContext* globalCtx);
+void EnRecepgirl_Draw(Actor* thisx, GlobalContext* globalCtx);
+
+void func_80C10148(EnRecepgirl* this);
+void func_80C1019C(EnRecepgirl* this, GlobalContext* globalCtx);
+void func_80C10290(EnRecepgirl* this);
+void func_80C102D4(EnRecepgirl * this, GlobalContext * globalCtx);
+
+const ActorInit En_Recepgirl_InitVars = {
+ ACTOR_EN_RECEPGIRL,
+ ACTORCAT_NPC,
+ FLAGS,
+ OBJECT_BG,
+ sizeof(EnRecepgirl),
+ (ActorFunc)EnRecepgirl_Init,
+ (ActorFunc)EnRecepgirl_Destroy,
+ (ActorFunc)EnRecepgirl_Update,
+ (ActorFunc)EnRecepgirl_Draw,
+};
+
+extern void* D_0600F8F0;
+extern void* D_0600FCF0;
+extern void* D_060100F0;
+
+static void* D_80C106B0[4] = { &D_0600F8F0, &D_0600FCF0, &D_060100F0, &D_0600FCF0 };
+
+// static InitChainEntry sInitChain[] = {
+static InitChainEntry D_80C106C0[] = {
+ ICHAIN_U8(targetMode, 6, ICHAIN_CONTINUE),
+ ICHAIN_F32(targetArrowOffset, 1000, ICHAIN_STOP),
+};
+
+static s32 D_80C106C8 = 0;
+
+extern AnimationHeader D_06000968;
+extern AnimationHeader D_06001384;
+extern AnimationHeader D_06009890;
+extern AnimationHeader D_0600A280;
+extern AnimationHeader D_0600AD98;
+extern FlexSkeletonHeader D_06011B60;
+
+
+// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Init.s")
+void EnRecepgirl_Init(Actor* thisx, GlobalContext* globalCtx) {
+ EnRecepgirl* this = THIS;
+ s32 i;
+
+ Actor_ProcessInitChain(&this->actor, D_80C106C0);
+ ActorShape_Init(&this->actor.shape, -60.0f, NULL, 0.0f);
+ SkelAnime_InitFlex(globalCtx, &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(globalCtx, 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, GlobalContext* globalCtx) {
+}
+
+// #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 == &D_06001384) {
+ Animation_MorphToPlayOnce(&this->skelAnime, &D_0600AD98, 5.0f);
+ }
+ this->actionFunc = func_80C1019C;
+}
+
+// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C1019C.s")
+void func_80C1019C(EnRecepgirl* this, GlobalContext* globalCtx) {
+ 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 (func_800B84D0(&this->actor, globalCtx) != 0) {
+ func_80C10290(this);
+ } else if (Actor_IsActorFacingLink(&this->actor, 0x2000)) {
+ func_800B8614(&this->actor, globalCtx, 60.0f);
+ if (Player_GetMask(globalCtx) == 2) {
+ this->actor.textId = 0x2367;
+ } else if (Flags_GetSwitch(globalCtx, 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, &D_0600A280, -4.0f);
+ this->actionFunc = func_80C102D4;
+}
+
+// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/func_80C102D4.s")
+void func_80C102D4(EnRecepgirl *this, GlobalContext *globalCtx) {
+ 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 = func_80152498(&globalCtx->msgCtx);
+ if (temp_v0_2 == 2) {
+ this->actor.textId = 0x2ADC;
+ func_80C10148(this);
+ return;
+ }
+
+ if ((temp_v0_2 == 5) && (func_80147624(globalCtx) != 0)) {
+ if (this->actor.textId == 0x2AD9) {
+ Actor_SetSwitchFlag(globalCtx, this->actor.params);
+ Animation_MorphToPlayOnce(&this->skelAnime, &D_0600AD98, 10.0f);
+ if ((gSaveContext.weekEventReg[63] & 0x80)) {
+ 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;
+ }
+ }
+ func_80151938(globalCtx, this->actor.textId);
+ }
+}
+
+// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Update.s")
+void EnRecepgirl_Update(Actor *thisx, GlobalContext *globalCtx) {
+ s32 pad;
+ EnRecepgirl* this = THIS;
+ Vec3s sp30;
+
+ this->actionFunc(this, globalCtx);
+ func_800E9250(globalCtx, &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(GlobalContext *globalCtx, 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(GlobalContext *globalCtx, s32 limbIndex, Actor *thisx) {
+ EnRecepgirl* this = THIS;
+
+ if (limbIndex == 5) {
+ Matrix_RotateY(0x400 - this->unk_2AE.x, MTXMODE_APPLY);
+ Matrix_GetStateTranslationAndScaledX(500.0f, &this->actor.focus.pos);
+ }
+}
+
+// #pragma GLOBAL_ASM("asm/non_matchings/overlays/ovl_En_Recepgirl/EnRecepgirl_Draw.s")
+void EnRecepgirl_Draw(Actor *thisx, GlobalContext *globalCtx) {
+ EnRecepgirl* this = THIS;
+
+ OPEN_DISPS(globalCtx->state.gfxCtx);
+
+ func_8012C28C(globalCtx->state.gfxCtx);
+
+ gSPSegment(POLY_OPA_DISP++, 0x08, D_80C106B0[this->unk_2AC]);
+
+ func_801343C0(globalCtx, this->skelAnime.skeleton, this->skelAnime.jointTable, this->skelAnime.dListCount, func_80C10558, NULL, func_80C10590, &this->actor);
+
+ CLOSE_DISPS(globalCtx->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_UnkLimbDraw`. 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 `func_800E9250` 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 `func_800E9250` 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
+const 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/Random06457/Z64Utils/releases]. To use it with MM, you also need a json file to fill in the file names: the latest version can be obtained from [https://github.com/Random06457/Z64Utils-Config]. 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:
+
+
+
+Search for the object file, right-click 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 okay. This will open this window:
+
+
+
+Go to "Analysis -> Find Dlists" and press OK (the defaults are usually fine). This will automatically search for displaylists in the object, which are a sufficiently distinctive format to be easy to find. We want to see the other stuff in the object too, so also do "Analysis -> Analyze Dlists". This will populate the window with even more stuff:
+
+
+
+We will talk about what all these types of data are next time, but for now, all we want to know is what
+```C
+extern void* D_0600F8F0;
+extern void* D_0600FCF0;
+extern void* D_060100F0;
+```
+actually are. We know they are set on segment 8, so we need to find where the skeleton uses them. We know from `extern FlexSkeletonHeader D_06011B60;` that this is at `0x06011B60`, so scroll down to it, 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 `extern AnimationHeader D_06000968;`, and you will get this error:
+
+
+
+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
+extern void* D_0600F8F0;
+extern void* D_0600FCF0;
+extern void* D_060100F0;
+
+static TexturePtr sEyeTextures[] = { &D_0600F8F0, &D_0600FCF0, &D_060100F0, &D_0600FCF0 };
+```
+
+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 `texturesDesegmented`, 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(GlobalContext* globalCtx, 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(GlobalContext* globalCtx, s32 limbIndex, Actor* thisx) {
+ EnRecepgirl* this = THIS;
+
+ if (limbIndex == 5) {
+ Matrix_RotateY(0x400 - this->unk_2AE.x, MTXMODE_APPLY);
+ Matrix_GetStateTranslationAndScaledX(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 : 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:
+
+
+
+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 == &D_06001384) {
+ Animation_MorphToPlayOnce(&this->skelAnime, &D_0600AD98, 5.0f);
+ }
+ this->actionFunc = func_80C1019C;
+}
+
+void func_80C1019C(EnRecepgirl* this, GlobalContext* globalCtx) {
+ 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 (func_800B84D0(&this->actor, globalCtx) != 0) {
+ func_80C10290(this);
+ } else if (Actor_IsActorFacingLink(&this->actor, 0x2000)) {
+ func_800B8614(&this->actor, globalCtx, 60.0f);
+ if (Player_GetMask(globalCtx) == PLAYER_MASK_KAFEIS_MASK) {
+ this->actor.textId = 0x2367; // "... doesn't Kafei want to break off his engagement ... ?"
+ } else if (Flags_GetSwitch(globalCtx, 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, &D_0600A280, -4.0f);
+ this->actionFunc = func_80C102D4;
+}
+
+void func_80C102D4(EnRecepgirl* this, GlobalContext* globalCtx) {
+ u8 temp_v0_2;
+
+ if (SkelAnime_Update(&this->skelAnime)) {
+ if (this->skelAnime.animation == &D_0600A280) {
+ Animation_ChangeDefaultRepeat(&this->skelAnime, &D_06001384);
+ } else if (this->skelAnime.animation == &D_0600AD98) {
+ if (this->actor.textId == 0x2ADA) { // Mayor's office is on the left (meeting ongoing)
+ Animation_MorphToPlayOnce(&this->skelAnime, &D_06000968, 10.0f);
+ } else {
+ Animation_ChangeTransitionRepeat(&this->skelAnime, &D_06009890, 10.0f);
+ }
+ } else if (this->actor.textId == 0x2ADA) { // Mayor's office is on the left (meeting ongoing)
+ Animation_ChangeTransitionRepeat(&this->skelAnime, &D_06009890, 10.0f);
+ } else {
+ Animation_MorphToPlayOnce(&this->skelAnime, &D_0600A280, -4.0f);
+ }
+ }
+
+ temp_v0_2 = func_80152498(&globalCtx->msgCtx);
+ if (temp_v0_2 == 2) {
+ this->actor.textId = 0x2ADC; // hear directions again?
+ func_80C10148(this);
+ } else if ((temp_v0_2 == 5) && (func_80147624(globalCtx) != 0)) {
+ if (this->actor.textId == 0x2AD9) { // "Welcome..."
+ Actor_SetSwitchFlag(globalCtx, this->actor.params);
+ Animation_MorphToPlayOnce(&this->skelAnime, &D_0600AD98, 10.0f);
+ if (gSaveContext.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, &D_0600AD98, 10.0f);
+ this->actor.textId = 0x2ADD; // "So..."
+ } else {
+ Animation_MorphToPlayOnce(&this->skelAnime, &D_06000968, 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
+ }
+ }
+ func_80151938(globalCtx, 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 `func_800B84D0(&this->actor, globalCtx) != 0`. This is something to do with talking. The other function handles the rest of the conversation, and hands back to the first if `func_80152498(&globalCtx->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
+
+
+
+
+## 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(&D_06001B2C, &colHeader);
+ this->dyna.bgId = DynaPoly_SetBgActor(globalCtx, &globalCtx->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(&D_06001B2C, &colHeader);
+ this->dyna.bgId = DynaPoly_SetBgActor(globalCtx, &globalCtx->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/docs/tutorial/draw_functions.md b/docs/tutorial/draw_functions.md
new file mode 100644
index 0000000000..319d5efbb0
--- /dev/null
+++ b/docs/tutorial/draw_functions.md
@@ -0,0 +1,303 @@
+# 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, GlobalContext* globalCtx);
+```
+
+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(GlobalContext *globalCtx, s32 limbIndex, Gfx **dList, Vec3f *pos, Vec3s *rot, Actor *actor); // extern
+void func_80C10590(GlobalContext *globalCtx, s32 limbIndex, Actor *actor); // extern
+void *D_80C106B0[4] = {(void *)0x600F8F0, (void *)0x600FCF0, (void *)0x60100F0, (void *)0x600FCF0};
+
+void EnRecepgirl_Draw(Actor *thisx, GlobalContext *globalCtx) {
+ EnRecepgirl* this = (EnRecepgirl *) thisx;
+ GraphicsContext *sp30;
+ Gfx *temp_v1;
+ GraphicsContext *temp_a0;
+
+ temp_a0 = globalCtx->state.gfxCtx;
+ sp30 = temp_a0;
+ func_8012C28C(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];
+ func_801343C0(globalCtx, 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(GlobalContext *globalCtx, 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(GlobalContext *globalCtx, 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, GlobalContext *globalCtx) {
+ EnRecepgirl* this = THIS;
+
+ OPEN_DISPS(globalCtx->state.gfxCtx);
+
+ func_8012C28C(globalCtx->state.gfxCtx);
+
+ gSPSegment(POLY_OPA_DISP++, 0x08, D_80C106B0[this->unk_2AC]);
+
+ func_801343C0(globalCtx, this->skelAnime.skeleton, this->skelAnime.jointTable, this->skelAnime.dListCount, func_80C10558, NULL, func_80C10590, &this->actor);
+
+ CLOSE_DISPS(globalCtx->state.gfxCtx);
+}
+```
+
+And this matches.
+
+The last two functions in the actor are used as arguments in `func_801343C0`. 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 func_801343C0(GlobalContext* globalCtx, void** skeleton, Vec3s* jointTable, s32 dListCount,
+ OverrideLimbDraw overrideLimbDraw, PostLimbDraw postLimbDraw, UnkActorDraw unkDraw, Actor* actor)
+```
+The typedefs of the callbacks it uses are in `z64animation.h`:
+```C
+typedef s32 (*OverrideLimbDraw)(struct GlobalContext* globalCtx, s32 limbIndex, Gfx** dList, Vec3f* pos, Vec3s* rot,
+ struct Actor* actor);
+
+typedef void (*PostLimbDraw)(struct GlobalContext* globalCtx, s32 limbIndex, Gfx** dList, Vec3s* rot,
+ struct Actor* actor);
+
+[...]
+
+typedef void (*UnkActorDraw)(struct GlobalContext* globalCtx, s32 limbIndex, struct Actor* actor);
+```
+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, UnkActorDraw
+
+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(GlobalContext *globalCtx, 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(GlobalContext *globalCtx, 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 UnkActorDraw, it has a much simpler prototype. mips2c gives
+```C
+void func_80C10590(GlobalContext *globalCtx, s32 limbIndex, Actor *actor) {
+ if (limbIndex == 5) {
+ Matrix_RotateY((s16) (0x400 - actor->unk2AE), 1);
+ Matrix_GetStateTranslationAndScaledX(500.0f, (Vec3f *) &actor->focus);
+ }
+}
+```
+There is only minor cleanup needed here:
+- recasting the last argument,
+- replacing the last argument of `Matrix_RotateY` 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(GlobalContext *globalCtx, s32 limbIndex, Actor *thisx) {
+ EnRecepgirl* this = THIS;
+
+ if (limbIndex == 5) {
+ Matrix_RotateY(0x400 - this->unk_2AE.x, MTXMODE_APPLY);
+ Matrix_GetStateTranslationAndScaledX(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, GlobalContext *globalCtx) {
+ 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 = globalCtx->state.gfxCtx;
+ temp_s0 = temp_a0;
+ func_8012C28C(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(globalCtx->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_InsertRotation(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(globalCtx->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(globalCtx->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(globalCtx->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(globalCtx->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, GlobalContext* globalCtx) {
+ s16 sp36 = (f32) thisx->shape.rot.x;
+ s16 sp34 = (f32) thisx->shape.rot.z;
+
+ OPEN_DISPS(globalCtx->state.gfxCtx);
+
+ func_8012C28C(globalCtx->state.gfxCtx);
+ gSPMatrix(POLY_OPA_DISP++, Matrix_NewMtx(globalCtx->state.gfxCtx), G_MTX_NOPUSH | G_MTX_LOAD | G_MTX_MODELVIEW);
+ gSPDisplayList(POLY_OPA_DISP++, D_06000680);
+
+ Matrix_InsertRotation(sp36, 0, sp34, MTXMODE_APPLY);
+ gSPMatrix(POLY_OPA_DISP++, Matrix_NewMtx(globalCtx->state.gfxCtx), G_MTX_NOPUSH | G_MTX_LOAD | G_MTX_MODELVIEW);
+ gSPDisplayList(POLY_OPA_DISP++, D_060007C8);
+
+ CLOSE_DISPS(globalCtx->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/master/docs/tutorial/draw_functions.md)
+
+Next: [Data](data.md)
diff --git a/docs/tutorial/images/EnRecepgirl_Init_diff_matching.png b/docs/tutorial/images/EnRecepgirl_Init_diff_matching.png
new file mode 100644
index 0000000000000000000000000000000000000000..9fc473019221e4a0b4a4cde94efefe8982ed6bab
GIT binary patch
literal 115482
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