Puddles that splash when you walk - pret/pokecrystal GitHub Wiki

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.)

Contents

  1. Define a collision type for puddles
  2. Design a splashing sound effect
  3. Design a graphical emote for splashing
  4. Define a map object for splashing
  5. Load puddle splash graphics when outdoors
  6. Show splash graphics and play sound for puddle tiles
  7. Add puddles to a map

1. Define a collision type for puddles

Edit constants/collision_constants.asm:

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

And edit data/collision/collision_permissions.asm:

 CollisionPermissionTable::
 ; entries correspond to COLL_* constants
 	table_width 1, CollisionPermissionTable
 	db LAND_TILE         ; COLL_FLOOR
 	db LAND_TILE         ; COLL_01
-	db LAND_TILE         ; 02
+	db LAND_TILE         ; COLL_PUDDLE
 	db LAND_TILE         ; COLL_03
 	db LAND_TILE         ; COLL_04
 	db LAND_TILE         ; 05
 	db LAND_TILE         ; 06
 	db WALL_TILE         ; COLL_WALL
 	...

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

2. Design a splashing sound effect

Edit constants/sfx_constants.asm:

 ; SFX indexes (see audio/sfx_pointers.asm)
 	const_def
 	const SFX_DEX_FANFARE_50_79           ; 00
 	const SFX_ITEM      
 	...
 	const SFX_4_NOTE_DITTY                ; cd
 	const SFX_TWINKLE                     ; ce
+	const SFX_PUDDLE
 DEF NUM_SFX EQU const_value

Edit audio/sfx_pointers.asm:

 SFX:
 ; entries correspond to SFX_* constants
 	table_width 3, SFX
 	dba Sfx_DexFanfare5079
 	dba Sfx_Item
 	...
 	dba Sfx_4NoteDitty
 	dba Sfx_Twinkle
+	dba Sfx_Puddle
 	assert_table_length NUM_SFX

And edit audio/sfx_crystal.asm, at the end:

+Sfx_Puddle:
+	channel_count 1
+	channel 5, Sfx_Puddle_Ch5
+
+Sfx_Puddle_Ch5:
+	duty_cycle $1
+	pitch_sweep 9, 7
+	square_note 15, 9, 8, 1792
+	pitch_sweep 0, 8
+	sound_ret

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

This is supposed to look like water droplets.

Edit gfx/emotes.asm:

 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:

 ; showemote arguments
 ; Emotes indexes (see data/sprites/emotes.asm)
 	const_def
 	const EMOTE_SHOCK
 	const EMOTE_QUESTION
 	const EMOTE_HAPPY
 	const EMOTE_SAD
 	const EMOTE_HEART
 	const EMOTE_BOLT
 	const EMOTE_SLEEP
 	const EMOTE_FISH
 	const EMOTE_SHADOW
 	const EMOTE_ROD
 	const EMOTE_BOULDER_DUST
 	const EMOTE_GRASS_RUSTLE
+	const EMOTE_PUDDLE_SPLASH
 DEF NUM_EMOTES EQU const_value
 DEF EMOTE_FROM_MEM EQU -1
 DEF EMOTE_LENGTH EQU 6

And edit data/sprites/emotes.asm:

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

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:

 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:

 ; 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
 DEF NUM_SPRITEMOVEDATA EQU const_value

 ; StepFunction_FromMovement.Pointers indexes (see engine/overworld/map_objects.asm)
 	const_def
 	const SPRITEMOVEFN_00                    ; 00
 	...
 	const SPRITEMOVEFN_GRASS                 ; 1b
+	const SPRITEMOVEFN_PUDDLE
 DEF NUM_SPRITEMOVEFN EQU const_value

 ...

 ; 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
 DEF NUM_OBJECT_ACTIONS EQU const_value

 ; 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
 DEF NUM_FACINGS EQU const_value

Edit data/sprites/map_objects.asm:

 ; 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

+; 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
 
 	assert_table_length NUM_SPRITEMOVEDATA

-; unused
-	db SPRITEMOVEFN_00 ; movement function
-	db DOWN ; facing
-	db OBJECT_ACTION_STAND ; action
-	db 0 ; flags1
-	db 0 ; flags2
-	db 0 ; palette flags

Edit engine/overworld/map_objects.asm:

 StepFunction_FromMovement:
 	...
 
 .Pointers:
 ; entries correspond to SPRITEMOVEFN_* constants (see constants/map_object_constants.asm)
 	dw MovementFunction_Null                 ; 00
 	...
 	dw MovementFunction_ShakingGrass         ; 1b
+	dw MovementFunction_SplashingPuddle
	assert_table_length NUM_SPRITEMOVEFN
 
 ...

 MovementFunction_ShakingGrass:
 	call EndSpriteMovement
 	call InitMovementField1dField1e
 	ld hl, OBJECT_ACTION
 	add hl, bc
 	ld [hl], OBJECT_ACTION_GRASS_SHAKE
+ContinueMovement_Grass_Puddle:
 	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
+
+MovementFunction_SplashingPuddle:
+	call EndSpriteMovement
+	call InitMovementField1dField1e
+	ld hl, OBJECT_ACTION
+	add hl, bc
+	ld [hl], OBJECT_ACTION_PUDDLE_SPLASH
+	jr ContinueMovement_Grass_Puddle

Edit engine/overworld/map_object_action.asm:

 ObjectActionPairPointers:
 ; entries correspond to OBJECT_ACTION_* constants (see constants/map_object_constants.asm)
	table_width 2 + 2, ObjectActionPairPointers
	;  normal action,                  frozen action
 	dw SetFacingStanding,              SetFacingStanding
 	...
 	dw SetFacingGrassShake,            SetFacingStanding
 	dw SetFacingSkyfall,               SetFacingCurrent
+	dw SetFacingPuddleSplash,          SetFacingStanding
	assert_table_length NUM_OBJECT_ACTIONS

...

 SetFacingGrassShake:
 	ld hl, OBJECT_STEP_FRAME
 	add hl, bc
 	inc [hl]
 	ld a, [hl]
 	ld hl, OBJECT_FACING
 	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
+	add hl, bc
+	and 4
+	ld a, FACING_SPLASH_1
+	jr z, .ok
+	inc a ; FACING_SPLASH_2
+	assert FACING_SPLASH_1 + 1 == FACING_SPLASH_2
+.ok
+	ld [hl], a
+	ret

Finally, edit data/sprites/facings.asm:

 Facings:
 ; entries correspond to FACING_* constants (see constants/map_object_constants.asm)
	table_width 2, Facings
 	dw FacingStepDown0
 	...
 	dw FacingGrass1
 	dw FacingGrass2
+	dw FacingSplash1
+	dw FacingSplash2
 	assert_table_length NUM_FACINGS
 	dw 0 ; end

 ...

 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:

 LoadMiscTiles:
 	ld a, [wSpriteFlags]
 	bit 6, a
 	ret nz
 
 	ld c, EMOTE_SHADOW
 	farcall LoadEmote
 	call GetMapEnvironment
 	call CheckOutdoorMap
-	ld c, EMOTE_GRASS_RUSTLE
 	jr z, .outdoor
 	ld c, EMOTE_BOULDER_DUST
+	jr .load_emote
+
 .outdoor
+	ld c, EMOTE_GRASS_RUSTLE
+	farcall LoadEmote
+	ld c, EMOTE_PUDDLE_SPLASH
.load_emote
 	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 engine/overworld/movement.asm:

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

 	ld hl, OBJECT_TILE_COLLISION
 	add hl, bc
 	ld a, [hl]
 	call CheckSuperTallGrassTile
 	jr z, .shake_grass
+	cp COLL_PUDDLE
+	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, [hMapObjectIndex]
 	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 again:

 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
+	jp PlaySFX
+
+.PuddleObject
+	; vtile, palette, movement
+	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.

…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

Let's say you want to copy HG/SS and add puddles to Route 34. Since 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 (you can replace some unused PokéCom Center tiles, or expand the tilesets)
  2. Assign the WATER color to those tiles in gfx/tilesets/johto_modern_palette_map.asm
  3. Design a puddle block in data/tilesets/johto_modern_metatiles.bin
  4. Assign the PUDDLE collision type to that block in data/tilesets/johto_modern_collision.asm
  5. Redesign maps/Route34.blk to use the puddle block

You can use Polished Map to edit maps and tilesets; refer to the new map and new tileset tutorials for more information.

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

Screenshot