Fully document PlayEffectAnimationEntity + misc.

.github/workflows/release.yml

@@ -40,7 +40,7 @@ jobs:
       - check-headers
       - check-symbol-header-sync
     env:
-      RELEASE_VERSION: '0.10.5'
+      RELEASE_VERSION: '0.10.6'
       OUTPUT_DIR: out
       RELEASE_INSTALL_DIR: release-install
       RELEASE_ASSETS_DIR: release-assets

headers/functions/arm9.h

@@ -531,6 +531,10 @@ void LoadAnimationFrameAndIncrementInAnimationControl(struct animation_control*
                                                       struct wan_animation_frame* anim_frame);
 void DisplayAnimationControlCurrentFrame(struct animation_control* anim_ctrl);
 void DisplayAndSwitchAnimationControlCurrentFrame(struct animation_control* anim_ctrl);
+void GetPixelOffsetFromSprite(struct vec2_16* pixel_offset, struct animation_control* sprite,
+                              enum wan_offset_type wan_offset);
+void FillPixelOffsetArrayFromSprite(struct vec2_16* pixel_offsets, uint8_t array_len,
+                                    struct animation_control* sprite);
 void FillOamAdjustmentInfo(struct animation_control* dst, uint16_t* src);
 uint32_t AnimationControlGetAllocForMaxFrame(struct animation_control* anim_ctrl);
 void SetAnimationControlPausedFlag(struct animation_control* anim_ctrl, bool new_val);

headers/functions/overlay10.h

@@ -14,10 +14,10 @@ void UpdateInventoryMenu(struct window* window);
 bool IsInventoryMenuState3(int window_id);
 void CreateInventoryMenuOuter(int n_items, int param_2, int param_3, uint8_t* param_4,
                               undefined* param_5, undefined* param_6, uint32_t param_7);
-void LoadPaletteBase(uint8_t sprite_index, bool is_4bpp);
-int GetEffectAnimationField0x19(int anim_id);
+void LoadPaletteBase(uint8_t sprite_index, bool is_4bpp, uint8_t start_4bpp);
+enum wan_offset_type GetEffectAnimationWanOffset(int anim_id);
 bool ScreenEffectActive(enum screen screen);
-bool AnimationHasMoreFrames(int param_1);
+bool BlockingAnimationInProgress(int unique_id);
 struct effect_animation* GetEffectAnimation(int anim_id);
 struct move_animation* GetMoveAnimation(enum move_id move_id);
 struct special_monster_move_animation* GetSpecialMonsterMoveAnimation(int ent_id);

headers/functions/overlay29.h

@@ -58,12 +58,13 @@ bool ItemIsActive(struct entity* entity, enum item_id item_id);
 int GetVisibilityRange(void);
 void RevealWholeFloor(struct entity* entity);
 bool DungeonScreenEffectActive(void);
-int PlayEffectAnimationEntity(struct entity* entity, int effect_id, bool play_now, int param_4,
-                              int param_5, undefined param_6, enum direction_id effect_dir,
+int PlayEffectAnimationEntity(struct entity* entity, int effect_id, bool blocking,
+                              enum wan_offset_type wan_offset, uint8_t finish_cur_effects_first,
+                              bool play_if_two_turn_invisible, enum direction_id effect_dir,
                               uint16_t* custom_oam_adjustment_info);
-int PlayEffectAnimationPos(struct position* pos, int effect_id, bool play_now);
-int PlayEffectAnimationPixelPos(struct pixel_position* pixel_pos, int effect_id, bool play_now);
-void AnimationDelayOrSomething(undefined param_1);
+int PlayEffectAnimationPos(struct position* pos, int effect_id, bool blocking);
+int PlayEffectAnimationPixelPos(struct pixel_position* pixel_pos, int effect_id, bool blocking);
+void FinishPlayingEffectAnimations(bool wait_for_non_blocking);
 void CopyStatusIconFlags(struct status_icon_flags* dst, struct entity* src);
 void UpdateStatusIconFlags(struct entity* entity);
 void PlayQuestionMarkEffect(struct entity* entity);
@@ -315,7 +316,8 @@ bool DefenderAbilityIsActive(struct entity* attacker, struct entity* defender,
 bool IsMonster(struct entity* entity);
 void TryActivateConversion2(struct entity* attacker, struct entity* defender, struct move* move);
 void TryActivateTruant(struct entity* entity);
-void TryPointCameraToMonster(struct entity* entity, undefined param_2, undefined param_3);
+void TryPointCameraToFarOffTeammate(struct entity* entity);
+void TryPointCameraToMonster(struct entity* entity, undefined param_2, bool discover_minimap);
 void ReevaluateSnatchMonster(void);
 struct entity* GetRandomExplorerMazeMonster(void);
 void RestorePpAllMovesSetFlags(struct entity* entity);
@@ -504,6 +506,7 @@ void EndMagnetRiseStatus(struct entity* user, struct entity* target);
 bool TransferNegativeBlinkerClassStatus(struct entity* user, struct entity* target);
 bool TryEndPetrifiedOrSleepStatus(struct entity* user, struct entity* target);
 void EndFrozenStatus(struct entity* user, struct entity* target);
+void ResetTypeChanges(struct entity* user);
 void EndProtectStatus(struct entity* user, struct entity* target);
 void TryRestoreRoostTyping(struct entity* user, struct entity* target);
 void TryTriggerMonsterHouse(struct entity* entity, bool outside_enemies);
@@ -662,7 +665,7 @@ void RevealStairs(struct entity* user, struct entity* target);
 void RevealEnemies(struct entity* user, struct entity* target);
 bool TryInflictLeechSeedStatus(struct entity* user, struct entity* target, bool log_failure,
                                bool check_only);
-void EndLeechSeedStatusForAllTargets(struct entity* user);
+void EndLeechSeedClassStatusForAllTargets(struct entity* user);
 void TryInflictDestinyBondStatus(struct entity* user, struct entity* target);
 void TryInflictSureShotStatus(struct entity* user, struct entity* target, uint8_t turns);
 void TryInflictWhifferStatus(struct entity* user, struct entity* target, uint8_t turns,

headers/types/common/common.h

@@ -1669,4 +1669,21 @@ struct alarm_callback_info {
 };
 ASSERT_SIZE(struct alarm_callback_info, 12);
 
+struct effect_animation {
+    enum effect_file_type file_type; // 0x0
+    int file_index;                  // 0x4: File index in pack 3 (effect.bin)
+    int palette_num;                 // 0x8
+    // 0xC: Some sort of index into the file. Related animations are grouped together into the same
+    // file and indexed with this. Is used as the animation_key parameter in
+    // SetAnimationForAnimationControl.
+    int animation_index;
+    int se_id;                // 0x10: Sound effect id, passed to PlaySeByIdVolume
+    int field_0x14;           // 0x14: Seemingly always 0
+    uint8_t is_screen_effect; // 0x18: Seems to always be 1 for screen effects, unused otherwise
+    struct wan_offset_type_8 wan_offset; // 0x19
+    uint8_t is_non_blocking;             // 0x1A
+    uint8_t repeat; // 0x1B: If non-zero, makes the animation repeat a bunch of times
+};
+ASSERT_SIZE(struct effect_animation, 28);
+
 #endif

headers/types/common/enums.h

@@ -4391,4 +4391,26 @@ enum mission_reward_frame_update_case {
     // There are more, seems like it goes up to case 21
 };
 
+enum wan_offset_type {
+    WAN_OFFSET_HEAD = 0,
+    WAN_OFFSET_HAND_LEFT = 1,
+    WAN_OFFSET_HAND_RIGHT = 2,
+    WAN_OFFSET_CENTER = 3,
+};
+
+// This is sometimes stored as an 8-bit integer
+#pragma pack(push, 1)
+ENUM_8_BIT(wan_offset_type);
+#pragma pack(pop)
+
+enum effect_file_type {
+    EFFECT_FILE_INVALID = 0,
+    EFFECT_FILE_WAN_FILE_0 = 1,
+    EFFECT_FILE_WAN_FILE_1 = 2,
+    EFFECT_FILE_WAN = 3,
+    EFFECT_FILE_WAT = 4,
+    EFFECT_FILE_SCREEN = 5,
+    EFFECT_FILE_WBA = 6,
+};
+
 #endif

headers/types/dungeon_mode/dungeon_mode.h

@@ -1260,26 +1260,6 @@ struct trap_animation {
 };
 ASSERT_SIZE(struct trap_animation, 2);
 
-// Unverified, ported from Irdkwia's notes
-struct effect_animation {
-    int field_0x0;
-    int file_index; // 0x4: File index in pack 3 (effect.bin)
-    int field_0x8;
-    // 0xC: Some sort of index into the file. Related animations are grouped together into the same
-    // file and indexed with this. Is used as the animation_key parameter in
-    // SetAnimationForAnimationControl.
-    int animation_index;
-    int se_id; // 0x10: Sound effect id, passed to PlaySeByIdVolume
-    int field_0x14;
-    uint8_t field_0x18;
-    int8_t field_0x19;
-    // 0x1A: Is non-zero if the animation is non-blocking. In this case, the animation will be
-    // delayed until the next time AnimationDelayOrSomething is called.
-    uint8_t is_non_blocking;
-    uint8_t unk_repeat; // 0x1B: If non-zero, makes the animation repeat a bunch of times
-};
-ASSERT_SIZE(struct effect_animation, 28);
-
 // Contains data about a monster that spawns in a dungeon
 struct monster_spawn_entry {
     uint16_t level_mult_512; // 0x0: Spawn level << 9
@@ -2558,8 +2538,8 @@ struct message_log_info {
     undefined field_0x1;
     undefined field_0x2;
     undefined field_0x3;
-    struct alert_box_info* alert_box_info;
-    // 0x4: If this does not match the current user, a new group will always start
+    struct alert_box_info* alert_box_info; // 0x4
+    // 0x8: If this does not match the current user, a new group will always start
     struct entity* last_user;
 };
 ASSERT_SIZE(struct message_log_info, 12);

symbols/arm9.yml

@@ -5039,6 +5039,24 @@ arm9:
         Displays the current frame of the animation_control struct and switches it afterwards if applicable.
 
         r0: animation_control
+    - name: GetPixelOffsetFromSprite
+      address:
+        EU: 0x201D02C
+      description: |-
+        Converts a WAN offset on a sprite into a pixel offset.
+
+        r0: [output] pixel offset (99 in a field means there is no offset)
+        r1: animation_control of sprite
+        r2: WAN offset type
+    - name: FillPixelOffsetArrayFromSprite
+      address:
+        EU: 0x201D0D0
+      description: |-
+        Converts the first array_len WAN offsets on a sprite into an array of pixel offsets.
+
+        r0: [output] array of pixel offsets of size array_len (99 in a field means there is no offset)
+        r1: array_len
+        r2: animation_control of sprite
     - name: FillOamAdjustmentInfo
       aliases:
         - FillOamAttributeInfo

symbols/overlay10.yml

@@ -160,16 +160,17 @@ overlay10:
 
         r0: sprite index in wan_table to load from
         r1: 0 for 8bpp, 1 for 4bpp
-    - name: GetEffectAnimationField0x19
+        r2: starting palette number for 4bpp
+    - name: GetEffectAnimationWanOffset
       address:
         EU: 0x22BE7F4
         NA: 0x22BDEB4
         JP: 0x22BF658
       description: |-
-        Calls GetEffectAnimation and returns field 0x19.
+        Calls GetEffectAnimation and returns its wan_offset field.
 
         r0: anim_id
-        return: GetEffectAnimation(anim_id)->field_0x19.
+        return: GetEffectAnimation(anim_id)->wan_offset
     - name: ScreenEffectActive
       address:
         EU: 0x22C0228
@@ -179,17 +180,18 @@ overlay10:
         Returns true if a screen effect (like Leaf Storm's or cutscene rain) is currently active on the given screen.
 
         r0: screen
-    - name: AnimationHasMoreFrames
+    - name: BlockingAnimationInProgress
+      aliases:
+        - AnimationHasMoreFrames
       address:
         EU: 0x22C0244
         NA: 0x22BF904
         JP: 0x22C10A8
       description: |-
-        Just a guess. This is called in a loop in PlayEffectAnimation, and the output controls whether or not AdvanceFrame continues to be called.
-        If the current effect animation's is_non_blocking field is set, the function will return false the very first time it is called.
+        Checks if there is an effect animation with the given unique id in progress and if so, whether its is_non_blocking field is 0.
 
-        r0: ?
-        return: whether or not the animation still has more frames left?
+        r0: unique id of animation
+        return: bool
     - name: GetEffectAnimation
       address:
         EU: 0x22C07E0

symbols/overlay29.yml

@@ -782,17 +782,17 @@ overlay29:
         NA: 0x22E35E4
         JP: 0x22E4C54
       description: |-
-        Just a guess. This appears to be paired often with GetEffectAnimationField0x19, and also has calls AnimationHasMoreFrames in a loop alongside AdvanceFrame(66) calls.
-
-        The third parameter skips the loop entirely. It seems like in this case the function might just preload some animation frames for later use??
+        Plays an effect animation on an entity.
 
         r0: entity pointer
         r1: Effect ID
-        r2: appears to be a flag for actually running the animation now? If this is 0, the AdvanceFrame loop is skipped entirely.
+        r2: whether the effect is blocking or not (i.e. whether the function should wait until it is finished or 100 frames have passed to return)
+        r3: WAN offset on entity sprite to use
+        stack[0]: if 2, waits until any in-progress effects are finished before playing the given one; if 1, waits only for blocking effects
+        stack[1]: whether to still play the effect even if the entity is using a non-flying two-turn move like Dig or Shadow Force
         stack[2]: direction of effect
         stack[3]: custom oam_adjustment_info array for the animation_control struct (length 6, or null if should use default values)
-        others: ?
-        return: status code, or maybe the number of frames or something? Either way, -1 seems to indicate the animation being finished or something?
+        return: -1 if the animation is finished / exceeded 100 frames, or a unique id for the playing effect otherwise
     - name: PlayEffectAnimationPos
       address:
         EU: 0x22E418C
@@ -803,8 +803,8 @@ overlay29:
 
         r0: Position where the effect should be played
         r1: Effect ID
-        r2: Unknown flag (same as the one in PlayEffectAnimationEntity)
-        return: Result of call to PlayEffectAnimationPixelPos
+        r2: whether the effect is blocking or not (i.e. whether the function should wait until it is finished or 100 frames have passed to return)
+        return: -1 if the animation is finished / exceeded 100 frames, or a unique id for the playing effect otherwise
     - name: PlayEffectAnimationPixelPos
       address:
         EU: 0x22E41D0
@@ -815,19 +815,19 @@ overlay29:
 
         r0: Pixel position where the effect should be played
         r1: Effect ID
-        r2: Unknown flag (same as the one in PlayEffectAnimationEntity)
-        return: Same as PlayEffectAnimationEntity
-    - name: AnimationDelayOrSomething
+        r2: whether the effect is blocking or not (i.e. whether the function should wait until it is finished or 100 frames have passed to return)
+        return: -1 if the animation is finished / exceeded 100 frames, or a unique id for the playing effect otherwise
+    - name: FinishPlayingEffectAnimations
+      aliases:
+        - AnimationDelayOrSomething
       address:
         EU: 0x22E4290
         NA: 0x22E38E0
         JP: 0x22E4F50
       description: |-
-        Called whenever most (all?) animations are played. Does not return until the animation is over.
-
-        Might wait until the animation is done? Contains several loops that call AdvanceFrame.
+        Waits until currently playing effect animations are finished, and returns only when they are done. Might have some other effects too.
 
-        r0: ?
+        r0: if 0, will only wait until effects with an is_non_blocking field equal to 0 finish; if 1, waits for all effects to finish
     - name: CopyStatusIconFlags
       address:
         EU: 0x22E43F0
@@ -3281,6 +3281,15 @@ overlay29:
         Checks if an entity has the ability Truant, and if so tries to apply the pause status to it.
 
         r0: pointer to entity
+    - name: TryPointCameraToFarOffTeammate
+      address:
+        EU: 0x22FA24C
+      description: |-
+        Attempts to place the camera on top of the specified teammate.
+
+        If the monster is already onscreen or the far-off pals option is disabled, the function does nothing.
+
+        r0: entity pointer
     - name: TryPointCameraToMonster
       address:
         EU: 0x22FA2C0
@@ -3293,7 +3302,7 @@ overlay29:
 
         r0: Entity pointer. Must be a monster, otherwise the function does nothing.
         r1: ?
-        r2: ?
+        r2: whether to fill the minimap at the monster's position
     - name: ReevaluateSnatchMonster
       address:
         EU: 0x22FA37C
@@ -5228,6 +5237,13 @@ overlay29:
 
         r0: user entity pointer
         r1: target entity pointer
+    - name: ResetTypeChanges
+      address:
+        EU: 0x230870C
+      description: |-
+        Resets any type changes that the given monster has undergone.
+
+        r0: entity pointer
     - name: EndProtectStatus
       address:
         EU: 0x2308744
@@ -6499,13 +6515,15 @@ overlay29:
         r2: flag to log a message on failure
         r3: flag to only perform the check for inflicting without actually inflicting
         return: Whether or not the status could be inflicted
-    - name: EndLeechSeedStatusForAllTargets
+    - name: EndLeechSeedClassStatusForAllTargets
+      aliases:
+        - EndLeechSeedStatusForAllTargets
       address:
         EU: 0x2316434
         NA: 0x23159D4
         JP: 0x2316EAC
       description: |-
-        Ends the Leech Seed status for all monsters that the given monster gave the status to.
+        Ends the Leech Seed and Destiny Bond status for all monsters that the given monster gave the status to.
 
         r0: user entity pointer
     - name: TryInflictDestinyBondStatus