Document Probability Distribution of Calls to rand_int (#1063)

* document probability of the majority of conditional calls to rand_int

* update positions of else/elseif comments

* remove unneeded documentation

include/common_structs.h

@@ -915,7 +915,7 @@ typedef struct BattleStatus {
     /* 0x09F */ char unk_9F;
     /* 0x0A0 */ struct EffectInstance* waterBlockEffect;
     /* 0x0A4 */ s8 cloudNineTurnsLeft;
-    /* 0x0A5 */ s8 cloudNineDodgeChance; /* = 50% */
+    /* 0x0A5 */ s8 cloudNineDodgeChance; /* = 50/101 ≈ 49.5% */
     /* 0x0A6 */ char unk_A6[2];
     /* 0x0A8 */ struct EffectInstance* cloudNineEffect;
     /* 0x0AC */ s8 merleeAttackBoost;

src/16F740.c

@@ -47,29 +47,30 @@ void btl_merlee_on_start_turn(void) {
 
                 if (currentEncounter->currentEnemy != NULL) {
                     if (currentEncounter->currentEnemy->flags & ACTOR_FLAG_NO_HEALTH_BAR) {
+                        // 46/101 ≈ 45.5%
                         if (temp <= 45) {
                             playerData->merleeSpellType = MERLEE_SPELL_1;
-                        } else if (temp <= 90) {
+                        } else if (temp <= 90) { // 45/101 ≈ 44.6%
                             playerData->merleeSpellType = MERLEE_SPELL_2;
-                        } else {
+                        } else { // 10/101 ≈ 9.9%
                             playerData->merleeSpellType = MERLEE_SPELL_EXP_BOOST;
                         }
-                    } else if (temp <= 30) {
+                    } else if (temp <= 30) { // 31/101 ≈ 30.7%
                         playerData->merleeSpellType = MERLEE_SPELL_1;
-                    } else if (temp <= 60) {
+                    } else if (temp <= 60) { // 30/101 ≈ 29.7%
                         playerData->merleeSpellType = MERLEE_SPELL_2;
-                    } else if (temp <= 80) {
+                    } else if (temp <= 80) { // 20/101 ≈ 19.8%
                         playerData->merleeSpellType = MERLEE_SPELL_EXP_BOOST;
-                    } else {
+                    } else { // 20/101 ≈ 19.8%
                         playerData->merleeSpellType = MERLEE_SPELL_COIN_BOOST;
                     }
-                } else if (temp <= 30) {
+                } else if (temp <= 30) { // 31/101 ≈ 30.7%
                     playerData->merleeSpellType = MERLEE_SPELL_1;
-                } else if (temp <= 60) {
+                } else if (temp <= 60) { // 30/101 ≈ 29.7%
                     playerData->merleeSpellType = MERLEE_SPELL_2;
-                } else if (temp <= 80) {
+                } else if (temp <= 80) { // 20/101 ≈ 19.8%
                     playerData->merleeSpellType = MERLEE_SPELL_EXP_BOOST;
-                } else {
+                } else { // 20/101 ≈ 19.8%
                     playerData->merleeSpellType = MERLEE_SPELL_COIN_BOOST;
                 }
 
@@ -104,29 +105,30 @@ void btl_merlee_on_first_strike(void) {
 
                 if (currentEncounter->currentEnemy != NULL) {
                     if (currentEncounter->currentEnemy->flags & ACTOR_FLAG_NO_HEALTH_BAR) {
+                        // 46/101 ≈ 45.5%
                         if (temp <= 45) {
                             playerData->merleeSpellType = MERLEE_SPELL_1;
-                        } else if (temp <= 90) {
+                        } else if (temp <= 90) { // 45/101 ≈ 44.6%
                             playerData->merleeSpellType = MERLEE_SPELL_2;
-                        } else {
+                        } else { // 10/101 ≈ 9.9%
                             playerData->merleeSpellType = MERLEE_SPELL_EXP_BOOST;
                         }
-                    } else if (temp <= 30) {
+                    } else if (temp <= 30) { // 31/101 ≈ 30.7%
                         playerData->merleeSpellType = MERLEE_SPELL_1;
-                    } else if (temp <= 60) {
+                    } else if (temp <= 60) { // 30/101 ≈ 29.7%
                         playerData->merleeSpellType = MERLEE_SPELL_2;
-                    } else if (temp <= 80) {
+                    } else if (temp <= 80) { // 20/101 ≈ 19.8%
                         playerData->merleeSpellType = MERLEE_SPELL_EXP_BOOST;
-                    } else {
+                    } else { // 20/101 ≈ 19.8%
                         playerData->merleeSpellType = MERLEE_SPELL_COIN_BOOST;
                     }
-                } else if (temp <= 30) {
+                } else if (temp <= 30) { // 31/101 ≈ 30.7%
                     playerData->merleeSpellType = MERLEE_SPELL_1;
-                } else if (temp <= 60) {
+                } else if (temp <= 60) { // 30/101 ≈ 29.7%
                     playerData->merleeSpellType = MERLEE_SPELL_2;
-                } else if (temp <= 80) {
+                } else if (temp <= 80) { // 20/101 ≈ 19.8%
                     playerData->merleeSpellType = MERLEE_SPELL_EXP_BOOST;
-                } else {
+                } else { // 20/101 ≈ 19.8%
                     playerData->merleeSpellType = MERLEE_SPELL_COIN_BOOST;
                 }
 

src/182B30.c

@@ -10,9 +10,9 @@ enum StandardPalettes {
     STANDARD_PAL_STATIC     = 3,
 };
 
-#define UNPACK_PAL_R(color) (((color) >> 11) & 0x1F) 
+#define UNPACK_PAL_R(color) (((color) >> 11) & 0x1F)
-#define UNPACK_PAL_G(color) (((color) >> 6) & 0x1F) 
+#define UNPACK_PAL_G(color) (((color) >> 6) & 0x1F)
-#define UNPACK_PAL_B(color) (((color) >> 1) & 0x1F) 
+#define UNPACK_PAL_B(color) (((color) >> 1) & 0x1F)
 #define UNPACK_PAL_A(color) ((color) & 1)
 
 #define PACK_PAL_RGBA(r, g, b, a) (((r) << 11) | ((g) << 6) | ((b) << 1) | (a));
@@ -2293,7 +2293,7 @@ void render_with_static_palettes(b32 isNpcSprite, ActorPart* part, s32 yaw, Matr
         decorationTable->resetPalAdjust = FALSE;
         decorationTable->nextPalTime = 0;
     }
-    
+
     if (!skipAnimation) {
         if (decorationTable->nextPalTime == 0) {
             decorationTable->palAnimState += 2;
@@ -2414,7 +2414,7 @@ void render_with_fear_palettes(b32 isNpcSprite, ActorPart* part, s32 yaw, Matrix
                 r /= 2;
                 g /= 2;
                 b /= 2;
-                
+
                 *palOut++ = PACK_PAL_RGBA(r, g, b, a);
             }
         }
@@ -2424,6 +2424,7 @@ void render_with_fear_palettes(b32 isNpcSprite, ActorPart* part, s32 yaw, Matrix
         part->palAnimPosOffset[0] = FearPaletteAnimXOffsets[abs(decorationTable->nextPalTime)];
         if (part->palAnimPosOffset[0] == PAL_ANIM_END) {
             part->palAnimPosOffset[0] = 0;
+            // 30-90
             decorationTable->nextPalTime = rand_int(60) + 30;
         }
     }
@@ -2563,6 +2564,7 @@ void render_with_paralyze_palettes(b32 isNpcSprite, ActorPart* part, s32 yaw, Ma
                 part->palAnimPosOffset[1] = ParalyzePaletteAnimXOffsets[abs(decorationTable->nextPalTime)];
                 if (part->palAnimPosOffset[1] == PAL_ANIM_END) {
                     part->palAnimPosOffset[1] = 0;
+                    // 30-90
                     decorationTable->nextPalTime = rand_int(60) + 30;
                 }
             }

src/1AC760.c

@@ -766,7 +766,7 @@ HitResult calc_partner_damage_enemy(void) {
         if (battleStatus->lastAttackDamage > 0) {
             sfx_play_sound_at_position(SOUND_231, SOUND_SPACE_MODE_0, state->goalPos.x, state->goalPos.y, state->goalPos.z);
         }
-        
+
         if (battleStatus->lastAttackDamage > 0 || (battleStatus->currentAttackElement & DAMAGE_TYPE_STATUS_ALWAYS_HITS && tempBinary)) {
             if (gBattleStatus.flags1 & BS_FLAGS1_40) {
                 show_action_rating(ACTION_RATING_NICE, target, state->goalPos.x, state->goalPos.y, state->goalPos.z);

src/C50A0.c

@@ -2300,7 +2300,7 @@ void update_item_entity_collectable(ItemEntity* item) {
                 }
             }
 
-            // if the item has non-zero lateral velocity, try moving it laterally 
+            // if the item has non-zero lateral velocity, try moving it laterally
             if (!(item->flags & (ITEM_ENTITY_FLAG_DONE_FALLING | ITEM_ENTITY_FLAG_NO_MOTION))
                 && item->spawnType != ITEM_SPAWN_MODE_ITEM_BLOCK_SPAWN_ALWAYS
                 && item->spawnType != ITEM_SPAWN_MODE_TOSS_FADE1

src/battle/battle.h

@@ -386,7 +386,7 @@ typedef struct Stage {
     /* 0x18 */ s32* foregroundModelList;
     /* 0x1C */ s32 stageEnemyCount;         // number of enemies in the stageFormation
     /* 0x20 */ Formation* stageFormation;   // extra enemies native to this stage
-    /* 0x24 */ s32 stageEnemyChance;        // chance for stageFormation enemies to spawn: N = 0 means always, N > 0 is 1/N chance
+    /* 0x24 */ s32 stageEnemyChance;        // 1/(N+1) chance for stageFormation enemies to spawn
 } Stage; // size = 0x28
 
 /// Zero-terminated.

src/battle/move/item/shooting_star.c

@@ -10,8 +10,8 @@
 
 API_CALLABLE(N(func_802A123C_71D9AC)) {
     s32 t1 = 200;
-    s32 r1 = rand_int(t1) + 100; // 100-299
+    s32 r1 = rand_int(t1) + 100; // 100-300
-    s32 r2 = rand_int(40); // 0-39
+    s32 r2 = rand_int(40); // 0-40
     f32 var_f22;
 
     if ((script->varTable[0] % 4) != 0) {

src/main_loop.c

@@ -152,6 +152,7 @@ void step_game_loop(void) {
         gOverrideFlags &= ~GLOBAL_OVERRIDES_8000;
     }
 
+    // Unused rand_int used to advance the global random seed each visual frame
     rand_int(1);
 }