Gen 3 introduced all kinds of overworld effects: footprints in sand, rain and lightning, reflections in water, splashing in puddles... Most of those are difficult or impossible with the GameBoy Color hardware, but we can achieve decent splashing puddles, including visible water droplets and a splashing noise. They'll be similar to the tall grass that rustles when you walk on it.

(The code for this feature was adapted from [Pokémon Polished Crystal](https://github.com/Rangi42/polishedcrystal/).)


## Contents

1. [Define a collision type for puddles](#1-define-a-collision-type-for-puddles)
2. [Design a splashing sound effect](#2-design-a-splashing-sound-effect)
3. [Design a graphical emote for splashing](#3-design-a-graphical-emote-for-splashing)
4. [Define a map object for splashing](#4-define-a-map-object-for-splashing)
5. [Load puddle splash graphics when outdoors](#5-load-puddle-splash-graphics-when-outdoors)
6. [Show splash graphics and play sound for puddle tiles](#6-show-splash-graphics-and-play-sound-for-puddle-tiles)
7. [Add puddles to a map](#7-add-puddles-to-a-map)


## 1. Define a collision type for puddles

Edit [constants/collision_constants.asm](../blob/master/constants/collision_constants.asm):

```diff
 ; collision data types (see data/tilesets/*_collision.asm)
 ; TileCollisionTable indexes (see data/collision_permissions.asm)
 COLL_FLOOR             EQU $00
 COLL_01                EQU $01 ; garbage
+COLL_PUDDLE            EQU $02
 COLL_03                EQU $03 ; garbage
 COLL_04                EQU $04 ; garbage
 COLL_WALL              EQU $07
 ...
```

And edit [data/collision_permissions.asm](../blob/master/data/collision_permissions.asm):

```diff
 TileCollisionTable::
 ; entries correspond to COLL_* constants
 	NONTALKABLE  LANDTILE ; COLL_FLOOR
 	NONTALKABLE  LANDTILE ; COLL_01
-	NONTALKABLE  LANDTILE ; 02
+	NONTALKABLE  LANDTILE ; COLL_PUDDLE
 	NONTALKABLE  LANDTILE ; COLL_03
 	NONTALKABLE  LANDTILE ; COLL_04
 	NONTALKABLE  LANDTILE ; 05
 	NONTALKABLE  LANDTILE ; 06
 	NONTALKABLE  WALLTILE ; COLL_WALL
 	...
```

Puddles don't do anything when "talked" to (unlike Cut trees or whirlpools, for instance), and can be walked on, so they need to be `NONTALKABLE LANDTILE`.


## 2. Design a splashing sound effect

Edit [constants/sfx_constants.asm](../blob/master/constants/sfx_constants.asm):

```diff
 	...
 	const SFX_4_NOTE_DITTY                ; cd
 	const SFX_TWINKLE                     ; ce
+	const SFX_PUDDLE
```

Edit [audio/sfx_pointers.asm](../blob/master/audio/sfx_pointers.asm):

```diff
 	...
 	dba Sfx_4NoteDitty
 	dba Sfx_Twinkle
+	dba Sfx_Puddle
```

And edit [audio/sfx_crystal.asm](../blob/master/audio/sfx_crystal.asm):

```diff
+Sfx_Puddle:
+	musicheader 1, 5, Sfx_Puddle_Ch5
+
+Sfx_Puddle_Ch5:
+	dutycycle $1
+	soundinput $97
+	sound __, 16, $98, $0700
+	soundinput $8
+	endchannel
```

This is based off of `Sfx_WaterGun_Ch5`.


## 3. Design a graphical emote for splashing

Create **gfx/overworld/puddle_splash.png**:

![gfx/overworld/puddle_splash.png](screenshots/gfx-overworld-puddle_splash.png)

This is supposed to look like water droplets.

Edit [gfx/emotes.asm](../blob/master/gfx/emotes.asm):

```diff
 ShockEmote:     INCBIN "gfx/emotes/shock.2bpp"
 QuestionEmote:  INCBIN "gfx/emotes/question.2bpp"
 HappyEmote:     INCBIN "gfx/emotes/happy.2bpp"
 SadEmote:       INCBIN "gfx/emotes/sad.2bpp"
 HeartEmote:     INCBIN "gfx/emotes/heart.2bpp"
 BoltEmote:      INCBIN "gfx/emotes/bolt.2bpp"
 SleepEmote:     INCBIN "gfx/emotes/sleep.2bpp"
 FishEmote:      INCBIN "gfx/emotes/fish.2bpp"
 JumpShadowGFX:  INCBIN "gfx/overworld/shadow.2bpp"
 FishingRodGFX:  INCBIN "gfx/overworld/fishing_rod.2bpp"
 BoulderDustGFX: INCBIN "gfx/overworld/boulder_dust.2bpp"
 GrassRustleGFX: INCBIN "gfx/overworld/grass_rustle.2bpp"
+PuddleSplashGFX: INCBIN "gfx/overworld/puddle_splash.2bpp"
```

Then edit [constants/script_constants.asm](../blob/master/constants/script_constants.asm):

```diff
 ; showemote arguments
 ; Emotes indexes (see data/sprites/emotes.asm)
 	const_def
 	const EMOTE_SHOCK ; 0
 	const EMOTE_QUESTION ; 1
 	const EMOTE_HAPPY ; 2
 	const EMOTE_SAD ; 3
 	const EMOTE_HEART ; 4
 	const EMOTE_BOLT ; 5
 	const EMOTE_SLEEP ; 6
 	const EMOTE_FISH ; 7
 	const EMOTE_SHADOW ; 8
 	const EMOTE_ROD ; 9
 	const EMOTE_BOULDER_DUST ; 10
 	const EMOTE_GRASS_RUSTLE ; 11
+	const EMOTE_PUDDLE_SPLASH
 EMOTE_MEM EQU -1
```

And edit [data/sprites/emotes.asm](../blob/master/data/sprites/emotes.asm):

```diff
 emote: MACRO
 ; graphics pointer, length, starting tile
 	dw \1
 	db \2 tiles, BANK(\1)
 	dw vTiles0 tile \3
 ENDM
 
 Emotes:
 ; entries correspond to EMOTE_* constants
 	emote ShockEmote,     4, $f8
 	...
 	emote GrassRustleGFX, 1, $fe
+	emote PuddleSplashGFX, 1, $ff
```

Be careful here! As of July 2018, pokecrystal mentions `vTiles0` in the `emote` macro, so the emotes' tile IDs range from $f8 to $ff. Older versions used `vTiles1` with tile IDs from $78 to $7f. If you have an older copy, then do this instead:

```diff
 emote: MACRO
 ; graphics pointer, length, starting tile
 	dw \1
 	db \2 tiles, BANK(\1)
 	dw vTiles1 tile \3
 ENDM

 Emotes:
 ; entries correspond to EMOTE_* constants
 	emote ShockEmote,     4, $78
 	...
 	emote GrassRustleGFX, 1, $7e
+	emote PuddleSplashGFX, 1, $7f
```


## 4. Define a map object for splashing

The puddle splash map object will be very similar to the rustling grass map object, so we can generally use it as a reference.

Edit [constants/map_object_constants.asm](../blob/master/constants/map_object_constants.asm):

```diff
 ; SpriteMovementData indexes (see data/sprites/map_objects.asm)
 	const_def
 	const SPRITEMOVEDATA_00                   ; 00
 	...
 	const SPRITEMOVEDATA_GRASS                ; 23
 	const SPRITEMOVEDATA_SWIM_WANDER          ; 24
+	const SPRITEMOVEDATA_PUDDLE
 NUM_SPRITEMOVEDATA EQU const_value

 ; MapObjectMovementPattern.Pointers indexes (see engine/overworld/map_objects.asm)
 	const_def
 	const SPRITEMOVEFN_00                    ; 00
 	...
 	const SPRITEMOVEFN_GRASS                 ; 1b
+	const SPRITEMOVEFN_PUDDLE

 ...

 ; ObjectActionPairPointers indexes (see engine/overworld/map_object_action.asm)
 	const_def
 	const OBJECT_ACTION_00            ; 00
 	...
 	const OBJECT_ACTION_GRASS_SHAKE   ; 0f
 	const OBJECT_ACTION_SKYFALL       ; 10
+	const OBJECT_ACTION_PUDDLE_SPLASH

 ; Facings indexes (see data/sprites/facings.asm)
 	const_def
 	const FACING_STEP_DOWN_0    ; 00
 	...
 	const FACING_GRASS_1        ; 1e
 	const FACING_GRASS_2        ; 1f
+	const FACING_SPLASH_1
+	const FACING_SPLASH_2
```

Edit [data/sprites/map_objects.asm](../blob/master/data/sprites/map_objects.asm):

```diff
 ; SPRITEMOVEDATA_GRASS
 	db SPRITEMOVEFN_GRASS ; movement function
 	db DOWN ; facing
 	db OBJECT_ACTION_GRASS_SHAKE ; action
 	db WONT_DELETE | FIXED_FACING | SLIDING | EMOTE_OBJECT ; flags1
 	db HIGH_PRIORITY ; flags2
 	db 0 ; palette flags

 ; SPRITEMOVEDATA_SWIM_WANDER
 	db SPRITEMOVEFN_RANDOM_WALK_XY ; movement function
 	db DOWN ; facing
 	db OBJECT_ACTION_STAND ; action
 	db 0 ; flags1
 	db 0 ; flags2
 	db SWIMMING ; palette flags

-; 25
-	db SPRITEMOVEFN_00 ; movement function
-	db DOWN ; facing
-	db OBJECT_ACTION_STAND ; action
-	db 0 ; flags1
-	db 0 ; flags2
-	db 0 ; palette flags
+; SPRITEMOVEDATA_PUDDLE
+	db SPRITEMOVEFN_PUDDLE ; movement function
+	db DOWN ; facing
+	db OBJECT_ACTION_PUDDLE_SPLASH ; action
+	db WONT_DELETE | FIXED_FACING | SLIDING | EMOTE_OBJECT ; flags1
+	db HIGH_PRIORITY ; flags2
+	db 0 ; palette flags
```

Edit [engine/overworld/map_objects.asm](../blob/master/engine/overworld/map_objects.asm):

```diff
 MapObjectMovementPattern:
 	...
 
 .Pointers:
 ; entries correspond to SPRITEMOVEFN_* constants
 	dw .Null_00 ; 00
 	...
 	dw .MovementShakingGrass ; 1b
+	dw .MovementSplashingPuddle
 
 ...

 .MovementShakingGrass:
 	call EndSpriteMovement
 	call ._MovementShadow_Grass_Emote_BoulderDust
 	ld hl, OBJECT_ACTION
 	add hl, bc
 	ld [hl], OBJECT_ACTION_GRASS_SHAKE
+._MovementGrass_Puddle_End:
 	ld hl, OBJECT_STEP_DURATION
 	add hl, de
 	ld a, [hl]
 	add -1
 	ld hl, OBJECT_STEP_DURATION
 	add hl, bc
 	ld [hl], a
 	ld hl, OBJECT_STEP_TYPE
 	add hl, bc
 	ld [hl], STEP_TYPE_TRACKING_OBJECT
 	ret
+
+.MovementSplashingPuddle:
+	call EndSpriteMovement
+	call ._MovementShadow_Grass_Emote_BoulderDust
+	ld hl, OBJECT_ACTION
+	add hl, bc
+	ld [hl], OBJECT_ACTION_PUDDLE_SPLASH
+	jr ._MovementGrass_Puddle_End
```

Edit [engine/overworld/map_object_action.asm](../blob/master/engine/overworld/map_object_action.asm):

```diff
 ObjectActionPairPointers:
 ; entries correspond to OBJECT_ACTION_* constants
 	dw SetFacingStanding,              SetFacingStanding
 	...
 	dw SetFacingGrassShake,            SetFacingStanding
 	dw SetFacingSkyfall,               SetFacingCurrent
+	dw SetFacingPuddleSplash,          SetFacingStanding

...

 SetFacingGrassShake:
 	ld hl, OBJECT_STEP_FRAME
 	add hl, bc
 	inc [hl]
 	ld a, [hl]
 	ld hl, OBJECT_FACING_STEP
 	add hl, bc
 	and 4
 	ld a, FACING_GRASS_1
 	jr z, .ok
 	inc a ; FACING_GRASS_2

 .ok
 	ld [hl], a
 	ret
+
+SetFacingPuddleSplash:
+	ld hl, OBJECT_STEP_FRAME
+	add hl, bc
+	inc [hl]
+	ld a, [hl]
+	ld hl, OBJECT_FACING_STEP
+	add hl, bc
+	and 4
+	ld a, FACING_SPLASH_1
+	jr z, .ok
+	inc a ; FACING_SPLASH_2
+
+.ok
+	ld [hl], a
+	ret
```

Finally, edit [data/sprites/facings.asm](../blob/master/data/sprites/facings.asm):

```diff
 Facings:
 ; entries correspond to FACING_* constants
 	dw FacingStepDown0
 	...
 	dw FacingGrass1
 	dw FacingGrass2
+	dw FacingSplash1
+	dw FacingSplash2
 .End
 	dw 0

 ...

 FacingGrass1:
 	db 2 ; #
 	db  8,  0, ABSOLUTE_TILE_ID, $fe
 	db  8,  8, ABSOLUTE_TILE_ID | X_FLIP, $fe

 FacingGrass2:
 	db 2 ; #
 	db  9, -1, ABSOLUTE_TILE_ID, $fe
 	db  9,  9, ABSOLUTE_TILE_ID | X_FLIP, $fe
+
+FacingSplash1:
+	db 2 ; #
+	db  8,  0, ABSOLUTE_TILE_ID, $ff
+	db  8,  8, ABSOLUTE_TILE_ID | X_FLIP, $ff
+
+FacingSplash2:
+	db 2 ; #
+	db  9, -1, ABSOLUTE_TILE_ID, $ff
+	db  9,  9, ABSOLUTE_TILE_ID | X_FLIP, $ff
```


## 5. Load puddle splash graphics when outdoors

Edit [engine/overworld/overworld.asm](../blob/master/engine/overworld/overworld.asm):

```diff
 LoadUsedSpritesGFX:
 	...

 	ld c, EMOTE_SHADOW
 	farcall LoadEmote
 	call GetMapEnvironment
 	call CheckOutdoorMap
-	ld c, EMOTE_GRASS_RUSTLE
 	jr z, .outdoor
 	ld c, EMOTE_BOULDER_DUST
+	farcall LoadEmote
+	ret
 .outdoor
+	ld c, EMOTE_GRASS_RUSTLE
+	farcall LoadEmote
+	ld c, EMOTE_PUDDLE_SPLASH
 	farcall LoadEmote
 	ret
```

Outdoor maps will load `EMOTE_GRASS_RUSTLE` into tile $fe and `EMOTE_PUDDLE_SPLASH` into tile $ff; each of them only takes up one tile, so that's okay. Indoor maps will load `EMOTE_BOULDER_DUST` for Strength boulders, which is two tiles long, so it takes up both $fe and $ff. There are no maps with tall grass *and* Strength boulders, so this was never an issue. Now you'll also need to avoid putting Strength boulders on a map with puddles.


## 6. Show splash graphics and play sound for puddle tiles

Edit [home/map_objects.asm](../blob/master/home/map_objects.asm):

```diff
 CheckSuperTallGrassTile::
 	cp COLL_LONG_GRASS
 	ret z
 	cp COLL_LONG_GRASS_1C
 	ret
+
+CheckPuddleTile::
+	cp COLL_PUDDLE
+	ret
```

Edit [engine/overworld/movement.asm](../blob/master/engine/overworld/movement.asm):

```diff
 NormalStep:
 	call InitStep
 	call UpdateTallGrassFlags
 	ld hl, OBJECT_ACTION
 	add hl, bc
 	ld [hl], OBJECT_ACTION_STEP

 	ld hl, OBJECT_NEXT_TILE
 	add hl, bc
 	ld a, [hl]
 	call CheckSuperTallGrassTile
 	jr z, .shake_grass
+	call CheckPuddleTile
+	jr z, .splash_puddle

 	call CheckGrassTile
 	jr c, .skip_grass

 .shake_grass
 	call ShakeGrass
+	jr .skip_grass
+
+.splash_puddle
+	call SplashPuddle
+	; fallthrough

 .skip_grass
 	ld hl, wCenteredObject
 	ldh a, [hMapObjectIndexBuffer]
 	cp [hl]
 	jr z, .player

 	ld hl, OBJECT_STEP_TYPE
 	add hl, bc
 	ld [hl], STEP_TYPE_NPC_WALK
 	ret

 .player
 	ld hl, OBJECT_STEP_TYPE
 	add hl, bc
 	ld [hl], STEP_TYPE_PLAYER_WALK
 	ret
```

Edit [engine/overworld/map_objects.asm](../blob/master/engine/overworld/map_objects.asm) again:

```diff
 ShakeGrass:
 	push bc
 	ld de, .GrassObject
 	call CopyTempObjectData
 	call InitTempObject
 	pop bc
 	ret

 .GrassObject
 	db $00, PAL_OW_TREE, SPRITEMOVEDATA_GRASS
+
+SplashPuddle:
+	push bc
+	ld de, .PuddleObject
+	call CopyTempObjectData
+	call InitTempObject
+	pop bc
+	ld de, SFX_PUDDLE
+	call PlaySFX
+	ret
+
+.PuddleObject
+	db $00, PAL_OW_BLUE, SPRITEMOVEDATA_PUDDLE
```

That's it! Now `COLL_PUDDLE` can be used like any other collision type—try assigning it to a block in [data/tilesets/\*_collision.asm](../tree/master/data/tilesets/).

…Although, there aren't any suitable tiles for puddles. So let's make some.


## 7. Add puddles to a map

Here are some puddle tiles devamped from Gen 3:

![Screenshot](screenshots/puddle-tiles.png)

Let's say you want to copy HG/SS and add puddles to Route 34. Since [maps/Route34.blk](../blob/master/maps/Route34.blk) uses the `johto_modern` tileset, here's what that would involve:

1. Add the puddle tiles to [gfx/tilesets/johto_modern.png](../blob/master/gfx/tilesets/johto_modern.png) (you can replace some unused PokéCom Center tiles, or [expand the tilesets](Expand-tilesets-from-192-to-255-tiles))
2. Assign the `WATER` color to those tiles in [gfx/tilesets/johto_modern_palette_map.asm](../blob/master/gfx/tilesets/johto_modern_palette_map.asm)
3. Design a puddle block in [data/tilesets/johto_modern_metatiles.bin](../blob/master/data/tilesets/johto_modern_metatiles.bin)
4. Assign the `PUDDLE` collision type to that block in [data/tilesets/johto_modern_collision.asm](../blob/master/data/tilesets/johto_modern_collision.asm)
5. Redesign [maps/Route34.blk](../blob/master/maps/Route34.blk) to use the puddle block

You can use [Polished Map](https://github.com/Rangi42/polished-map) to edit maps and tilesets; refer to the [new map](Add-a-new-map-and-landmark) and [new tileset](Add-a-new-tileset) tutorials for more information.

Now we can walk around Route 34, and see and hear puddles in action!

![Screenshot](screenshots/puddles.png)