Sweet Heart

2 files changed, 121 insertions, 1 deletions

diff --git a/Add-different-kinds-of-new-items.md b/Add-different-kinds-of-new-items.md
index 8ae1c82..2b70ad6 100644
--- a/Add-different-kinds-of-new-items.md
+++ b/Add-different-kinds-of-new-items.md
@@ -144,7 +144,127 @@ Anyway, that's all you need to add a basic item:
 
 ### `RestoreHPEffect`: Sweet Heart
 
-TODO
+A Sweet Heart, from Gen 5, restores 20 HP. It can be used on the field or during battle, and enemy trainer AI should know how to use one too.
+
+Edit [constants/item_constants.asm](../blob/master/constants/item_constants.asm):
+
+```diff
+ 	const DIRE_HIT     ; 2c
+- 	const ITEM_2D      ; 2d
++ 	const SWEET_HEART  ; 2d
+ 	const FRESH_WATER  ; 2e
+```
+
+Edit [data/items/names.asm](../blob/master/data/items/names.asm):
+
+```diff
+ 	db "DIRE HIT@"
+-	db "TERU-SAMA@"
++	db "SWEET HEART@"
+ 	db "FRESH WATER@"
+```
+
+Edit [data/items/descriptions.asm](../blob/master/data/items/descriptions.asm):
+
+```diff
+ 	dw DireHitDesc
+-	dw TeruSama3Desc
++	dw SweetHeartDesc
+ 	dw FreshWaterDesc
+
+ 	...
+
+-TeruSama3Desc:
+-	db   "?@"
++SweetHeartDesc:
++	db   "Restores #MON"
++	next "HP by 20.@"
+```
+
+Edit [data/items/attributes.asm](../blob/master/data/items/attributes.asm):
+
+```diff
+-; ITEM_2D
+-	item_attribute $9999, HELD_NONE, 0, 0, ITEM, ITEMMENU_NOUSE, ITEMMENU_NOUSE
++; SWEET_HEART
++	item_attribute 100, HELD_NONE, 0, CANT_SELECT, ITEM, ITEMMENU_PARTY, ITEMMENU_PARTY
+```
+
+Edit [data/items/item_effects.asm](../blob/master/data/items/item_effects.asm):
+
+```diff
+ 	dw DireHitEffect       ; DIRE_HIT
+-	dw NoEffect            ; ITEM_2D
++	dw RestoreHPEffect     ; SWEET_HEART
+ 	dw RestoreHPEffect     ; FRESH_WATER
+```
+
+And edit [data/items/catch_rate_items.asm](../blob/master/data/items/catch_rate_items.asm):
+
+```diff
+-	db ITEM_2D, BITTER_BERRY
+```
+
+Now 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.
+
+Edit [data/items/heal_hp.asm](../blob/master/data/items/heal_hp.asm):
+
+```diff
+ HealingHPAmounts: ; f3af
+ 	dbw FRESH_WATER,   50
+ 	...
+ 	dbw BERRY_JUICE,   20
++	dbw SWEET_HEART,   20
+ 	dbw -1, 0 ; end
+; f3df
+```
+
+`HealingHPAmounts` is used by `GetHealingItemAmount`, which is called by `ItemRestoreHP`, which is called by `RestoreHPEffect`, which is the effect we already assigned to Sweet Heart; so now it will successfully heal 20 HP when used by the player.
+
+Edit [engine/battle/ai/items.asm](../blob/master/engine/battle/ai/items.asm):
+
+```diff
+ AI_Items: ; 39196
+ 	dbw FULL_RESTORE, .FullRestore
+ 	...
+ 	dbw X_SPECIAL,    .XSpecial
++	dbw SWEET_HEART,  .SweetHeart
+ 	db -1 ; end
+ ; 381be
+
+ ...
+
+ .Potion: ; 382a0
+ 	call .HealItem
+ 	jp c, .DontUse
+ 	ld b, 20
+ 	call EnemyUsedPotion
+ 	jp .Use
+ ; 382ae
+
++.SweetHeart:
++	call .HealItem
++	jp c, .DontUse
++	ld b, 20
++	call EnemyUsedSweetHeart
++	jp .Use
+
+ ...
+
+ EnemyUsedPotion: ; 383e8
+ 	ld a, POTION
+ 	ld b, 20
+ 	jr EnemyPotionContinue
+
++EnemyUsedSweetHeart:
++	ld a, SWEET_HEART
++	ld b, 20
++	jr EnemyPotionContinue
+```
+
+Now if a trainer has a Sweet Heart (as defined in [data/trainers/attributes.asm](../blob/master/data/trainers/attributes.asm)) they'll be able to use it. The `.HealItem` subroutine called by `.SweetHeart` determines whether the healing item will be used, with different random chances when the enemy has half or a quarter of their HP left; and the `EnemyPotionContinue` routine does the whole process of restoring HP, animating the HP bar, playing the sound effect, etc.
+
+![Screenshot](screenshots/sweet-heart.png)
 
 
 ### `StatusHealingEffect`: Lava Cookie
diff --git a/screenshots/sweet-heart.png b/screenshots/sweet-heart.png
new file mode 100644
index 0000000..d8a1c58
--- /dev/null
+++ b/screenshots/sweet-heart.png