Dusk Ball

3 files changed, 62 insertions, 6 deletions

diff --git a/Add-different-kinds-of-new-items.md b/Add-different-kinds-of-new-items.md
index d1377e0..c906af6 100644
--- a/Add-different-kinds-of-new-items.md
+++ b/Add-different-kinds-of-new-items.md
@@ -146,7 +146,7 @@ Anyway, that's all you need to add a basic item:
 
 A Sweet Heart, from Gen 5, restores 20 HP, just like RageCandyBar. It can be used on the field or during battle, and enemy trainer AI should know how to use one too.
 
-First, add the essential data. Replace `ITEM_2D` with `SWEET_HEART`; give it a name, description, and attributes (`item_attribute 100, HELD_NONE, 0, CANT_SELECT, ITEM, ITEMMENU_PARTY, ITEMMENU_PARTY`); give it the `RestoreHPEffect`; and remove `ITEM_2D` from `TimeCapsule_CatchRateItems`.
+First, add the essential data. Replace `ITEM_2D` with `SWEET_HEART`; give it a name, description, and attributes (`100, HELD_NONE, 0, CANT_SELECT, ITEM, ITEMMENU_PARTY, ITEMMENU_PARTY`); give it the `RestoreHPEffect`; and remove `ITEM_2D` from `TimeCapsule_CatchRateItems`.
 
 Then it's time to implement the specific HP healing amount for Sweet Heart. Notice how most healing items—Potion, Fresh Water, etc—have an `item_attribute` parameter value equal to how much they heal? Those aren't actually used anywhere. Instead, the healing amounts for items used by the player, by the enemy trainer, and (when possible) by the Pokémon holding it are all handled separately.
 
@@ -214,11 +214,9 @@ Now if a trainer has a Sweet Heart (as defined in [data/trainers/attributes.asm]
 
 A Lava Cookie, from Gen 3, heals any status condition, just like Full Heal. It can be used on the field or during battle, and enemy trainer AI should know how to use one too.
 
-First, add the essential data. Replace `ITEM_32` with `LAVA_COOKIE`; give it a name, description, and attributes (`item_attribute 200, HELD_NONE, 0, CANT_SELECT, ITEM, ITEMMENU_PARTY, ITEMMENU_PARTY`); give it the `StatusHealingEffect`; and remove `ITEM_32` from `TimeCapsule_CatchRateItems`.
+First, add the essential data. Replace `ITEM_32` with `LAVA_COOKIE`; give it a name, description, and attributes (`200, HELD_NONE, 0, CANT_SELECT, ITEM, ITEMMENU_PARTY, ITEMMENU_PARTY`); give it the `StatusHealingEffect`; and remove `ITEM_32` from `TimeCapsule_CatchRateItems`.
 
-Then it's time to implement the specific status-healing effect.
-
-Edit [data/items/heal_status.asm](../blob/master/data/items/heal_status.asm):
+Then it's time to implement the specific status-healing effect. Edit [data/items/heal_status.asm](../blob/master/data/items/heal_status.asm):
 
 ```diff
  StatusHealingActions: ; f071
@@ -281,7 +279,65 @@ Now if a trainer has a Lava Cookie (as defined in [data/trainers/attributes.asm]
 
 ### `PokeBallEffect`: Dusk Ball
 
-TODO
+A Dusk Ball, from Gen 4, has a 3× catch rate if used in caves or at night.
+
+First, add the essential data. Replace `ITEM_5A` with `DUSK_BALL`; give it a name, description, and attributes (`1000, HELD_NONE, 0, CANT_SELECT, BALL, ITEMMENU_NOUSE, ITEMMENU_CLOSE`); give it the `PokeBallEffect`; and remove `ITEM_5A` from `TimeCapsule_CatchRateItems`.
+
+A piece of data specific to Poké Balls is what color they are when thrown in battle. Edit [data/battle_anims/ball_colors.asm](../blob/master/data/battle_anims/ball_colors.asm):
+
+```diff
+ BallColors: ; cd26c (33:526c)
+ 	db MASTER_BALL, PAL_BATTLE_OB_GREEN
+ 	...
+ 	db LOVE_BALL,   PAL_BATTLE_OB_RED
++	db DUSK_BALL,   PAL_BATTLE_OB_GREEN
+ 	db -1,          PAL_BATTLE_OB_GRAY
+ ; cd284
+```
+
+Then it's time to implement the specific Pokémon-catching effect. Edit [engine/items/item_effects.asm](../blob/master/engine/items/item_effects.asm) again:
+
+```diff
+ BallMultiplierFunctionTable:
+ ; table of routines that increase or decrease the catch rate based on
+ ; which ball is used in a certain situation.
+ 	dbw ULTRA_BALL,  UltraBallMultiplier
+ 	...
+ 	dbw PARK_BALL,   ParkBallMultiplier
++	dbw DUSK_BALL,   DuskBallMultiplier
+ 	db -1 ; end
+
++DuskBallMultiplier:
++; is it night?
++	ld a, [wTimeOfDay]
++	cp NITE
++	jr z, .night_or_cave
++; or are we in a cave?
++	ld a, [wEnvironment]
++	cp CAVE
++	jr z, .night_or_cave
++; neither night nor cave
++	ret
++
++.night_or_cave
++; b is the catch rate
++; a == b / 2 + b + b + b == b × 3.5
++	ld a, b
++	srl a
++rept 3
++	add b
++	jr c, .max
++endr
++	ret
++
++.max
++	ld b, $ff
++	ret
+```
+
+`DuskBallMultiplier`, like all the Ball multiplier routines, just has to modify `b` according to the relevant factors. If it's nighttime or we're in a cave, it multiplies `b` by 3.5; otherwise it doesn't modify `b`.
+
+![Screenshot](screenshots/dusk-ball.png)
 
 
 ### `EvoStoneEffect`: Mist Stone
diff --git a/screenshots/big-nugget.png b/screenshots/big-nugget.png
index b2e1ab1..f8d18fc 100644
--- a/screenshots/big-nugget.png
+++ b/screenshots/big-nugget.png
diff --git a/screenshots/dusk-ball.png b/screenshots/dusk-ball.png
new file mode 100644
index 0000000..ef18a99
--- /dev/null
+++ b/screenshots/dusk-ball.png