decomp: name unknown fields from evidence and define more data in C

config/us/undefined_syms.txt

@@ -85,3 +85,13 @@ D_001A26C0 = 0x001A26C0;
 D_001A28C8 = 0x001A28C8;
 D_001A2A08 = 0x001A2A08;
 D_001A2AF8 = 0x001A2AF8;
+D_00141680 = 0x00141680;
+D_00141720 = 0x00141720;
+D_0015ED8C = 0x0015ED8C;
+D_0015ED90 = 0x0015ED90;
+D_0015ED94 = 0x0015ED94;
+D_0015ED9C = 0x0015ED9C;
+D_0015EE28 = 0x0015EE28;
+D_0015EE2C = 0x0015EE2C;
+D_0015EEA8 = 0x0015EEA8;
+D_0015EEAC = 0x0015EEAC;

configure.py

@@ -317,10 +317,10 @@
     "l05/mobys/skid_mcmarx.c",
     "l05/mobys/taxi.c",
     "l05/mobys/television.c",
-    "l05/mobys/triggered_motion.c",
-    "l05/mobys/triggered_slide.c",
-    "l05/mobys/triggered_moby_yaw.c",
-    "l05/mobys/triggered_spray_emitter.c",
+    "l05/mobys/moby_893.c",
+    "l05/mobys/moby_843.c",
+    "l05/mobys/moby_895.c",
+    "l05/mobys/moby_855.c",
     "l05/mobys/water.c",
     "l06/hero/hero_set_state.c",
     "l06/hero/update_hero_state_machine.c",
@@ -379,7 +379,7 @@
     "l08/mobys/blarg_bombthrower.c",
     "l08/mobys/bolt_pickup.c",
     "l08/mobys/bolt_thief.c",
-    "l08/mobys/bomb.c",
+    "l08/mobys/blarg_bombthrower_bomb.c",
     "l08/mobys/bomber_tank.c",
     "l08/mobys/bomber_tank_bomb.c",
     "l08/mobys/commando.c",
@@ -675,7 +675,7 @@
     "l18/mobys/hidden_deplanetizer_gun.c",
     "l18/mobys/inert_moby.c",
     "l18/mobys/lift.c",
-    "l18/mobys/mine.c",
+    "l18/mobys/drek_boss_mine.c",
     "l18/mobys/rocket.c",
     "l18/mobys/rocket_tank.c",
     "l18/mobys/rocket_tank_rocket.c",
@@ -940,6 +940,15 @@
 # link fails when the section is not SIZE bytes.  Both the assembly-backed and
 # the promoted (normalized) unit names resolve to the same retail bytes.
 RODATA_OVERLAYS = {
+    "game/startlevel": (0x1E76C0, 0xE8640, 23),
+    "rendering/frame/initialize_level_render_state": (0x1E76D8, 0xE8658, 80),
+    "rendering/lights/detach_point_light": (0x1E7B50, 0xE8AD0, 105),
+    "mobys/create_moby": (0x1E83C0, 0xE9340, 57),
+    "rendering/mobys/draw_mobys": (0x1E8400, 0xE9380, 35),
+    "rendering/texture/dma_shrub_textures": (0x1E88D0, 0xE9850, 24),
+    "rendering/texture/dma_tfrag_textures": (0x1E89B0, 0xE9930, 24),
+    "rendering/texture/dma_tie_textures": (0x1E8A50, 0xE99D0, 22),
+    "ui/text/copy_text_to_shared_buffer": (0x1E7AA8, 0xE8A28, 19),  # "(Message too long)"
     "_dtoa_r": (0x152310, 0x53290, 88),  # Infinity/NaN/0 strings, f64 literals, switch table
     # _getpic's switch emits a 5-entry jump table (0x14 bytes) that retail
     # stored at 0x153AA0 inside core_rdata; the expected object references it
@@ -973,7 +982,7 @@
     "ui/help/draw_help": (0x1E7A70, 0xE89F0, 28),  # switch table (migrated)
     "ui/help/dismiss_help": (0x1E7A20, 0xE89A0, 32),  # switch table (migrated)
     "_sceFs_Rcv_Intr": (0x1528E0, 0x53860, 100),  # retail switch table (jtbl_001528E0)
-    "ui/menus/system/process_menu_entry": (0x1E86A0, 0xE9620, 24),  # retail switch table (jtbl_001E86A0)
+    "ui/menus/system/process_menu_entry": (0x1E8680, 0xE9600, 56),  # thousands separators, switch table (jtbl_001E86A0)
     "draw_sky_shells": (0x1E8910, 0xE9890, 24),  # switch table
     "ui/menus/system/update_timed_menu_sequence": (0x1E8810, 0xE9790, 80),  # switch table
     "mobys/animation/update_resident_dialogue_animation_state": (0x1E8A90, 0xE9A10, 52),  # switch table
@@ -1133,13 +1142,15 @@
     "game/startlevel": (0x15EF5C, 0x5FEDC, 4),  # boot image buffer
     "mobys/update_visible_mobys": (0x15FF24, 0x60EA4, 4),  # visible moby list
     "world/select_world_object_resource_tables": (0x15FF44, 0x60EC4, 8),  # resource tag and count
+    "world/update_world_object_animation": (0x160488, 0x61408, 12),  # cutscene moby class per content variant
     "ui/hud/init_hud": (0x15F6D8, 0x60658, 8),  # allocation tag
     "ui/menus/widgets/format_scaled_display_value": (0x161078, 0x61FF8, 11),  # display value formats
 }
 
 # The same for a unit's `.data`: data only that unit reads, defined in it.
 # `scripts/data-refs.py --emit` writes the definition and prints the entry.
 DATA_OVERLAYS = {
+    "ui/menus/system/setup_menu_display_text": (0x1E0888, 0xE1808, 76),  # gold bolts per level
     "sdk/kernel/supplement_crt0": (0x130320, 0x312A0, 8),
     "sdk/graph/sce_gs_get_gparam": (0x132D40, 0x33CC0, 16),
     "sdk/input/sce_pad2_init": (0x132DD0, 0x33D50, 4),  # pad2_initialized
@@ -1160,7 +1171,7 @@
     "rendering/effects/render_level_effects_and_screen_sprites": (0x1CE2C0, 0xCF240, 56),
     "weapons/load_hand_gadget": (0x1D52E8, 0xD6268, 1776),
     "ui/menus/item_preview/update_preview_animation_and_attachments": (0x1D6080, 0xD7000, 56),
-    "rendering/shrubs/register_shrub_render_class": (0x1D7F30, 0xD8EB0, 384),
+    "rendering/shrubs/register_shrub_render_class": (0x1D7F30, 0xD8EB0, 1408),
     "rendering/effects/build_variant_effect_quads": (0x1D9890, 0xDA810, 384),
     "rendering/effects/build_resident_indexed_texture_warp_meshes": (0x1D9A10, 0xDA990, 56),
     "rendering/effects/draw_light_flare": (0x1D97B0, 0xDA730, 224),
@@ -1176,6 +1187,7 @@
     "rendering/texture/initialize_alpha_lookup_table": (0x18E740, 0x8F6C0, 1024),
     "mobys/resolve_moby_hit_response": (0x1CC080, 0xCD000, 200),
     "ui/map/copy_level_object_positions": (0x1E03B8, 0xE1338, 80),
+    "ui/menus/item_preview/update_item_preview_binding": (0x1E0408, 0xE1388, 1152),
     "rendering/debug/print_debug_text_centered": (0x189DC0, 0x8AD40, 384),
     "rendering/effects/draw_light_quads": (0x18CAA0, 0x8DA20, 64),
     "runtime/callbacks/add_draw_callback": (0x18DB40, 0x8EAC0, 512),
@@ -1221,6 +1233,7 @@
     "ui/map/world_to_map_coords": (0x19E970, 0x9F8F0, 304),
     "ui/text/copy_text_to_shared_buffer": (0x19A440, 0x9B3C0, 80),
     "ui/menus/save_data/run_state_handler": (0x1A0438, 0xA13B8, 100),
+    "save/memcard_restore_game": (0x1A04C0, 0xA1440, 960),  # the save block lists mc_gamedata, mc_leveldata
     "mobys/find_or_allocate_moby_render_slot": (0x1B2BC0, 0xB3B40, 64),
     "mobys/stash_moby_class_dists": (0x1B2E80, 0xB3E00, 896),
     "ui/menus/pause/assign_heli_pack_label_text_table": (0x1D06D0, 0xD1650, 112),
@@ -1239,8 +1252,13 @@
     "rendering/vu1/vu1_gs_regs_alt": (0x1DE3F0, 0xDF370, 48),  # its GS register packet
     "rendering/vu1/vu1_tex_flush": (0x1DEE00, 0xDFD80, 48),  # its GS register packet
     "ui/map/draw_map_overlay": (0x1E8068, 0xE8FE8, 17),  # no map text
-    "ui/map/update_map_icons": (0x1A2BC0, 0xA3B40, 76),  # icon list of each level
+    "ui/map/update_map_icons": (0x1A08C0, 0xA1840, 9036),  # mission and map icon lists of each level
     "ui/menus/item_preview/draw_menu_preview_objects": (0x1D5020, 0xD5FA0, 96),  # slot draw flags
+    "ui/menus/item_preview/clear_preview_resource_bindings": (0x1D59D8, 0xD6958, 136),
+    "ui/menus/system/emit_selected_graphics_dma_packets": (0x1D7D90, 0xD8D10, 192),
+    "ui/text/font/font_print": (0x1DF050, 0xDFFD0, 2784),  # glyph records of the three fonts
+    "ui/vendor/render_vendor_buy_label_pass": (0x1DFFB0, 0xE0F30, 1032),  # vendor prices by item
+    "ui/map/draw_map_screen_layers": (0x1DDF68, 0xDEEE8, 76),  # map inset per level
 }
 
 # Uninitialised variables a unit defines.  `.sbss` (small ones) sits in the

docs/contributing/code-cleanup.md

@@ -96,6 +96,11 @@ register that nothing set on that path (to keep it live) as
 - **Locals and fields:** name them by what they hold (`count`, `next`), not by
   register or offset (`v1`, `unk_70`). Keep `unkXXX` only until the meaning is
   clear.
+- **Where names come from:** what the code does with the value first. SDK
+  code takes the names of the PS2 SDK headers (`sceSifServeData`,
+  `sceIpuDmaEnv`, `sceCdCLOCK`) or of newlib (`FILE`, `_reent`). A file-local
+  copy of a shared struct (a moby, a moby class) uses the names of its header
+  (`rnc/mobys/moby.h`), even when it keeps its own layout.
 
 ## Structs and data
 

include/rnc/audio/music/music_stream_state.h

@@ -16,13 +16,13 @@
 
 /* One music channel record (0x1C bytes). */
 struct MusicStreamChannel {
-    s32 handle;            /* 0x00: stream handle from the start callback; -1 while starting */
-    s16 track;             /* 0x04 */
-    s16 volume;            /* 0x06 */
-    s16 flags;             /* 0x08 */
-    s16 state;             /* 0x0A: set 1 on start, 1 -> 2 in the start callback */
-    s16 fade_flags;        /* 0x0C: -0x8000 on music_pause, 4 on music_unpause */
-    s16 unkE;              /* 0x0E: cleared by music_pause */
+    s32 handle;      /* 0x00: stream handle from the start callback; -1 while starting */
+    s16 track;       /* 0x04 */
+    s16 volume;      /* 0x06 */
+    s16 flags;       /* 0x08 */
+    s16 state;       /* 0x0A: set 1 on start, 1 -> 2 in the start callback */
+    s16 pause_flags; /* 0x0C: bit 0x8000 pauses the stream (music_pause), 4 resumes it (music_unpause) */
+    s16 pause_timer; /* 0x0E: frames until a timed pause ends; 0 from music_pause pauses until music_unpause */
     s16 crossfade_enabled; /* 0x10: remaining-time callback starts the crossfade */
     u8  pad_12[0x2];
     s32 poll_interval;  /* 0x14 */

include/rnc/audio/voice_pool.h

@@ -69,7 +69,7 @@ typedef struct {
     s32         group_3_volume;
     s32         group_4_volume;
     s32         group_5_volume;
-    s32         unk60;
+    s32         reverb_owner; /* 0x060: owner of the reverb request */
     s32         reverb_depth; /* 0x064 */
     u8          reverb_type;
     u8          reverb_delay;

include/rnc/camera/camera_globals.h

@@ -23,10 +23,10 @@ struct CameraBlend {
 /* advance_alternate_camera_transition's orbit around the focus, from
    orbit_angles toward the angles compute_camera_angles gives. */
 struct CameraOrbit {
-    f32 angles[3];   /* 0x00: yaw, pitch, distance (compute_camera_angles) */
-    s32 frames;      /* 0x0C */
-    f32 frame_step;  /* 0x10: 1 / frames */
-    s32 start_count; /* 0x14: counted up on each start */
+    f32 angles[3];  /* 0x00: yaw, pitch, distance (compute_camera_angles) */
+    s32 frames;     /* 0x0C */
+    f32 frame_step; /* 0x10: 1 / frames */
+    s32 duration_frames; /* 0x14: orbit duration set by the camera; start_camera_blend adds one and scales it into frames */
     u8  pad_18[0x8];
     f32 forward[4];        /* 0x20 */
     f32 up[4];             /* 0x30 */

include/rnc/camera/follow_cam.h

@@ -10,19 +10,20 @@
  * follow_camera_transition reads `follow` for its spring constants, and
  * fast_dec_timer counts `blend_timer` down. The follow_camera_set_* setters
  * (FUN_L00_002e8450..002e8680) each write one field and do nothing while the
- * record's unk86 is set. The shot cameras (volume_camera_swing, volume_camera_aim)
+ * record's camera_class is set. The shot cameras (volume_camera_swing, volume_camera_aim)
  * snap every vector at once when a shot starts.
  */
 typedef struct {
     f32 focus[4];    /* 0x40: point the camera looks at, moved by velocity each frame */
     f32 velocity[4]; /* 0x50: focus displacement for this frame */
     u8  pad60[0x20];
-    f32 look_target[4];  /* 0x80: focus offset blended towards the hero */
-    f32 eye[4];          /* 0x90: resulting camera position */
-    f32 offset[4];       /* 0xA0: eased offset, split into a lateral and an up part */
-    f32 lateral_ease[4]; /* 0xB0: cam_interp_values state of the lateral part */
-    f32 up_ease[4];      /* 0xC0: cam_interp_values state of the up part */
-    f32 unkD0[4];        /* 0xD0: set to look_target when a shot camera snaps */
+    f32 look_target[4]; /* 0x80: focus offset blended towards the hero */
+    f32 pivot
+        [4]; /* 0x90: point pivot_height above the hero; the camera sits at pivot + eye_offset */
+    f32 offset[4];           /* 0xA0: eased offset, split into a lateral and an up part */
+    f32 lateral_ease[4];     /* 0xB0: cam_interp_values state of the lateral part */
+    f32 up_ease[4];          /* 0xC0: cam_interp_values state of the up part */
+    f32 snap_look_target[4]; /* 0xD0: set to look_target when a shot camera snaps */
     u8  padE0[0x10];
     f32 look_height; /* 0xF0: height of look_target above the hero */
     u8  padF4[0x22];
@@ -39,58 +40,58 @@ typedef struct {
 
 /* 0x1A8: FUN_L00_002e8680 and the shot cameras reach `flags` through it. */
 typedef struct {
-    u8  pad1A8[8];
-    f32 unk1B0; /* 0x1B0: aim cameras start only while it is (nearly) 0 */
+    u8 pad1A8[8];
+    f32 pitch_input; /* 0x1B0: normalised stick pitch; aim cameras start only while it is (nearly) 0 */
     u8  pad1B4[4];
     s32 flags; /* 0x1B8: bits 0 and 1 set by the shot cameras and FUN_L00_002e8680 */
 } FollowCamFlags;
 
 /* 0x1D0: written when a shot camera snaps. */
 typedef struct {
     u8  pad1D0[0x20];
-    f32 unk1F0[4]; /* 0x1F0: set to the record's position */
-    f32 unk200;    /* 0x200: unk15C minus the length of unk130 */
-    u8  pad204[8];
+    f32 shot_pos[4];        /* 0x1F0: set to the record's position */
+    f32 distance_reduction; /* 0x200: distance minus the length of eye_offset (walls pull the camera in) */
+    u8 pad204[8];
 } FollowCamSnap;
 
 typedef struct {
-    f32            unk130[4]; /* 0x130: eye offset; its length is the eye distance */
-    f32            unk140[4]; /* 0x140: copy of unk130 */
-    u8             pad150[0xC];
-    f32            unk15C;   /* 0x15C: eye distance, set with unk130 by the shot cameras */
-    f32            distance; /* 0x160: distance of the eye behind the hero */
-    f32            unk164;   /* 0x164: aim cameras start only while it is (nearly) 0 */
-    u8             pad168[0x40];
+    f32 eye_offset[4];       /* 0x130: camera offset from the pivot; its length is distance */
+    f32 saved_eye_offset[4]; /* 0x140: copy of eye_offset */
+    u8  pad150[0xC];
+    f32 distance; /* 0x15C: distance of the camera from the pivot (4.64), length of eye_offset */
+    f32 pivot_height; /* 0x160: height of the pivot above the hero (2.0) */
+    f32 yaw_step; /* 0x164: yaw step this frame; aim cameras start only while it is (nearly) 0 */
+    u8  pad168[0x40];
     FollowCamFlags ctl; /* 0x1A8 */
     u8             pad1BC[0x10];
-    f32            unk1CC;     /* 0x1CC: set by FUN_L00_002e8540 */
-    FollowCamSnap  snap;       /* 0x1D0 */
-    f32            zoom_scale; /* 0x20C */
-    f32            zoom;       /* 0x210: 1.0 is no zoom */
-    f32            zoom_range; /* 0x214 */
-    u8             pad218[0xE];
-    s16            unk226; /* 0x226: set to 1 by FUN_L00_002e8620 */
-    u8             pad228[4];
-    f32            unk22C; /* 0x22C: set by FUN_L00_002e8490 */
-    s32            mode;   /* 0x230: 0 normal; shot cameras of type 10 and 11 set 0x14D and 2 */
+    f32 script_pitch; /* 0x1CC: scripted pitch in radians, set by set_follow_camera_script_pitch */
+    FollowCamSnap snap;       /* 0x1D0 */
+    f32           zoom_scale; /* 0x20C */
+    f32           zoom;       /* 0x210: 1.0 is no zoom */
+    f32           zoom_range; /* 0x214 */
+    u8            pad218[0xE];
+    s16 run_toward_lock; /* 0x226: 1 (lock_follow_camera_run_toward) keeps the camera from pulling back while the hero runs toward it */
+    u8 pad228[4];
+    f32 pull_back_max; /* 0x22C: farthest pull-back while the hero runs toward the camera (6.0), set by set_follow_camera_pull_back_max */
+    s32 mode;          /* 0x230: 0 normal; shot cameras of type 10 and 11 set 0x14D and 2 */
 } FollowCamTail;
 
 /* 0x20..0x3B: eased values reset when a shot camera snaps. */
 typedef struct {
     u8  pad20[2];
-    s16 unk22;       /* 0x22 */
-    f32 look_height; /* 0x24: copy of follow.look_height */
-    f32 distance;    /* 0x28: copy of tail.distance */
-    f32 unk2C;       /* 0x2C */
-    f32 unk30;       /* 0x30 */
-    f32 unk34;       /* 0x34 */
-    f32 unk38;       /* 0x38 */
+    s16 unk22;            /* 0x22 */
+    f32 look_height;      /* 0x24: copy of follow.look_height */
+    f32 pivot_height;     /* 0x28: eased copy of tail.pivot_height */
+    f32 look_height_vel;  /* 0x2C: cam_interp_values step of look_height */
+    f32 pivot_height_vel; /* 0x30: cam_interp_values step of pivot_height */
+    f32 pitch_bias;       /* 0x34: springed pitch bias while the camera is low */
+    f32 pitch_bias_vel;   /* 0x38 */
     u8  pad3C[4];
 } FollowCamReset;
 
 typedef struct FollowCamState {
-    f32            position[4]; /* 0x00: the record's position when a shot camera snaps */
-    s16            unk10;       /* 0x10: set by set_follow_camera_orbit_clamp_mode */
+    f32 position[4]; /* 0x00: the record's position when a shot camera snaps */
+    s16 leash; /* 0x10: nonzero lets the camera trail the hero on a leash; set by set_follow_camera_orbit_clamp_mode */
     u8             pad12[0xE];
     FollowCamReset reset;  /* 0x20 */
     FollowCamBlock follow; /* 0x40 */

include/rnc/camera/update_cam.h

@@ -11,11 +11,12 @@
    D_00187410[48]; D_001870C0[0] and [1] point at the current and previous
    one. Size 0xA0 (backup_current_cam copies 0xA0 bytes). */
 struct UpdateCam {
-    u128  m0;
-    u128  m1;
-    u128  m2;
+    u128  forward; /* 0x00: camera basis rows (grindrail camera) */
+    u128  right;   /* 0x10: cross(forward, the level up) */
+    u128  up;      /* 0x20: cross(right, forward) */
     Vec4f pos;
-    u8    pad40[0x24];
+    u128  prev_forward; /* 0x40: copy of forward the pitch rotation starts from */
+    u8    pad50[0x14];
     Vec3  prev_pos;
     void *saved_state;
     u8    state; /* activation rule, see camera_activation_check_priority */
@@ -26,11 +27,11 @@ struct UpdateCam {
     s16   transition_state;
     u8    pad80[4];
     s16   descriptor_index;
-    s16   unk86; /* 0 lets the hero collision moby spawn; 6 disables shake */
-    u8    pad88[4];
-    s16   type; /* index into camera_types (D_001E8C00) */
-    s16   activation_blocked;
-    u8    pad90[0x10];
+    s16 camera_class; /* 0x86: 0 the follow camera (lets the hero collision moby spawn), 6 disables shake, 7 Swingshot */
+    u8  pad88[4];
+    s16 type; /* index into camera_types (D_001E8C00) */
+    s16 activation_blocked;
+    u8  pad90[0x10];
 };
 
 /* Per camera type callbacks, indexed by UpdateCam.type. */