TSSM-Dolphin-Toolkit

A toolset of useful Dolphin utilities for The SpongeBob SquarePants Movie, aimed to be used by speedrunners and TAS creators. It contains .dmw files that label notable memory addresses, useful for debugging and speedrunning strat hunting/practice.

Also included are various Lua scripts for Dolphin Lua Core, allowing TAS creators to create their runs easier and practice scripts for speedrunners.

Example use cases:

• Practising two-frame token warps by reading the Token Count (token counter increments when the loading screen appears after warping)

• Practising one-frame damage boosts by locking Patrick/SpongeBob's health in the memory engine.

How to Use

Dolphin Memory Engine

1. Download Dolphin Memory Engine.

2. Clone/download this repository.

3. In Dolphin Memory Engine, go to File > Open and open the correct .dmw for your game ID.

   If you don't know your game ID:

   • NTSC (English): GGVE78
   • PAL (English): GGVP78
   • PAL (Deutsch): GGVD78
   • PAL (Français/Nederlands): GGVX78

4. Open the game in Dolphin.

Dolphin Lua Core

1. Download Dolphin Lua Core. Add a blank text file called example.txt if you would like it to ignore your Dolphin settings (useful if you have other Dolphin installations).
2. Clone/download this repository.
3. Drag the contents of dolphin-lua-core into the folder where Dolphin Lua Core is located.
4. To enable a script, first open the game in Dolphin. Go to Tools > Execute Script and select the script you would like to use. If you would like a script to run automatically, add an underscore to the beginning of the script filename.

Script Descriptions

• TSSM_Core: Contains the core functions that retrieve and write data to memory, used by the other scripts. No need to run this automatically.
• TSSM_Oneframe_Practice: Allows the user to practice "one-frame" jumps for both SpongeBob and Patrick, showing them how many frame early/late that the jump button is pressed. Currently only works on NTSC in 60fps levels.
• TSSM_Pattywagon: Contains some useful Patty Wagon info, such as nitro count, X, Y and Z velocities, total speed, and time remaining in the current nitro. Useful for testing speeds on different surfaces for TAS runs, for example.

Memory Address Descriptions

⚠ This is subject to change and will be updated with new information as it is available.

Label	Description
Game ID	Game's ID. G - System Code (GameCube) GV - Title Code (The SpongeBob SquarePants Movie) E/P/D/X - Region Code (Varies) 78 - Publisher Code (THQ)
Controller Input
Buttons pressed (Bit field)	A two-byte bit field containing the state of the buttons pressed on the controller. Bit 15 → Bit 0 00000000 00000000 Bit Button Press 15 Unsure (controller disconnected?) 14 Unsure (unused?) 13 Unsure (unused?) 12 START 11 Y 10 X 9 B 8 A 7 Unsure (controller connected?) 6 L 5 R 4 Z 3 Up 2 Down 1 Right 0 Left
Main Stick X	X position of the main analog stick. 0–255, center is 128 (applies to all analog stick axes).
Main Stick Y	Y position of the main analog stick.
C Stick X	X position of the C stick.
C Stick Y	Y position of the C stick.
Left Shoulder Button	How pressed the left shoulder button is. 0 (unpressed)–255 (fully pressed) (applies to both shoulder buttons.)
Right Shoulder Button	How pressed the right shoulder button is.
Abilities/Upgrades
Karate Spin	Unlock/upgrade status of Karate Spin. 0 = locked, 1 = unlocked, 2 = upgraded (applies to all moves below). If not set in SB04, a move will default to 0, including karate/star spin. Can be set in SB04.ini with G.KarateSpin.
Bash	Unlock/upgrade status of Bash. Can be set in SB04.ini with G.Bash.
Spongebowl	Unlock/upgrade status of Spongebowl. Can be set in SB04.ini with G.MachoBowl.
Sonic Wave	Unlock/upgrade status of Sonic Wave. Can be set in SB04.ini with G.WaveGuitar.
Star Spin	Unlock/upgrade status of Star Spin. Can be set in SB04.ini with G.BellyBump.
Cartwheel	Unlock/upgrade status of Cartwheel. Can be set in SB04.ini with G.Cartwheel.
Smash	Unlock/upgrade status of Smash. Can be set in SB04.ini with G.BellyFlop.
Throw	Unlock/upgrade status of Throw. Can be set in SB04.ini with G.Throw.
SpongeBob Health Upgrades	The number of health upgrades SpongeBob has. Can be set in SB04.ini with G.HealthSB. While usually capped at 3 in-game, you can set this value higher to give SpongeBob more health (though the UI will only display a max of 6 Krabby Patties).
Patrick Health Upgrades	The number of health upgrades Patrick has. Can be set in SB04.ini with G.HealthPat.
Manliness Point Values
Purple Manliness Value	The value of a purple manliness point. Default is 50, can be set in SB04.ini with G.ShinyValuePurple.
Blue Manliness Value	The value of a blue manliness point. Default is 10, can be set in SB04.ini with G.ShinyValueBlue.
Green Manliness Value	The value of a green manliness point. Default is 5, can be set in SB04.ini with G.ShinyValueGreen.
Yellow Manliness Value	The value of a yellow manliness point. Default is 2, can be set in SB04.ini with G.ShinyValueYellow.
Red Manliness Value	The value of a red manliness point. Default is 1, can be set in SB04.ini with G.ShinyValueRed.
Upgrade Manliness Requirements
The manliness points required to gain the next upgrade point. The values in memory are cumulative (250, 1500, 3000, ..., 35000) whereas the values set in SB04.ini are incremental (250, 1250, 1500, ..., 4000).
Upgrades 1-14	Watch Name Normal Value SB04.ini Upgrade 1 250 Upgrade1 = 250 Upgrade 2 1500 Upgrade2 = 1250 Upgrade 3 3000 Upgrade3 = 1500 Upgrade 4 5000 Upgrade4 = 2000 Upgrade 5 7000 Upgrade5 = 2000 Upgrade 6 9000 Upgrade6 = 2000 Upgrade 7 11000 Upgrade7 = 2000 Upgrade 8 14000 Upgrade8 = 3000 Upgrade 9 17000 Upgrade9 = 3000 Upgrade 10 20000 Upgrade10 = 3000 Upgrade 11 23000 Upgrade11 = 3000 Upgrade 12 27000 Upgrade12 = 4000 Upgrade 13 31000 Upgrade13 = 4000 Upgrade 14 35000 Upgrade14 = 4000
Health
SpongeBob Health	The health SpongeBob has remaining.
SpongeBob Max Health	SpongeBob's maximum health. Calculated from 3 + the number of health upgrades. Updates after SpongeBob dies.
Patrick Health	The health Patrick has remaining.
Patrick Max Health	Patrick's maximum health. Calculated from 3 + the number of health upgrades. Updates after Patrick dies.
Sliding/Driving Health	The health remaining when sliding or driving.
Sliding/Driving Max Health	The maximum health when sliding or driving. Setting this to values above 3 will update the UI, but you won't gain extra lives as the game is hardcoded to three lives in these levels.
Player States
Player is Jumping	Whether the player is performing a single-jump. It is possible for this value to be 0 when double jumping, if the player jumps after falling off a ledge after the game's ~30 frames coyote time.
Player is Double Jumping	Whether the player is double jumping.
Player is Spinning	Whether the player is using the star spin/karate spin.
Player is Bashing (SB)	Whether the player is using the bash attack.
Player is Bowling (SB)	Whether the player is using the sponge bowl.
Player Is In Source Box (Box State)	Whether the player is standing in a warp box prior to being teleported. This byte is responsible for "box state glitch", wherein you cannot take damage from enemies or goo, and you are unable to use certain abilities. You can activate the glitch by warping in a source box while the target box is unopened, or by locking this value to 1.
Player is Bouncing Off Goo	Whether the player is bouncing off goo. If goo is touched while this is 1, the player will drown.
Movement
Gravity	The gravity for all players. Default is 30, can be set in SB04.ini with G.Gravity.
SB Min Walk Speed	SpongeBob's minimum walk speed. Normally 0.6.
SB Max Walk Speed	SpongeBob's maximum walk speed. Normally 4 as set in SB04.ini. If not set in SB04, defaults to 3.
SB Max Run Speed	SpongeBob's max running speed, i.e. top theoretical speed when the analog stick is fully deflected. Normally 5 as set in SB04.ini. If not set in SB04, defaults to 7.
SB Jump Gravity	Affects the height of SpongeBob's jumps. Normally 5, as set in SB04.ini with SB.JumpGravity. If not set in SB04, defaults to 7.
Sliding Friction (Ice Physics Glitch)	Appears to affect friction when sliding, default is 0. Also responsible for Ice Physics Glitch (IPG). IPG refers to the decreased friction on certain surfaces caused by this value being 0. This value is set to 0.01 if the player touches a flinger's goo, or 0.2 when walking on freezy fruit ice. Losing IPG is generally undesirable as the player will lose all their speed when landing on some icy surfaces (e.g. SCDA Floating Block ice blocks or the I'm Ready... Depression freezer room). The value is not normally reset to 0, even when exiting to main menu, so the console/game must be reset or the reduced ice speed persists.
Last Grounded Position
When the player falls off a ledge into a damage source (e.g. goo or spikes), the player will typically be bounced back to their last grounded position within a certain range. This value is constantly updated with the player's current position, however, if the player jumps very quickly within landing (TODO: add frame window?) or jumps on the very edge of a platform, this position won't be updated, allowing the player to bounce back to a position of their choice. Speedrunners can abuse this fact to skip token animations by dying and bouncing into a token simultaneously.
Last Grounded X Position	The player's last grounded X coordinate.
Last Grounded Y Position	The player's last grounded Y coordinate.
Last Grounded Z Position	The player's last grounded Z coordinate.
Player Position Duplicate (Read-Only)
The following contains memory addresses that are continuously updated with the player's position. They do not contain the actual internal position of the player, and writing to these addresses will not change the player's position. The actual player position's addresses are dynamic and change each level, but these are useful for the sake of reference.
X Position	The player's current X coordinate.
Y Position	The player's current Y coordinate.
Z Position	The player's current Z coordinate.
Patty Wagon
Patty Wagon X Velocity	The patty wagon's velocity along the X axis.
Patty Wagon Y Velocity	The patty wagon's velocity along the Y axis.
Patty Wagon Z Velocity	The patty wagon's velocity along the Z axis.
Nitro Count	The number of nitros the patty wagon has remaining (0-255).
Max Speed	The patty wagon's maximum speed when driving forwards normally on an ideal surface. Normally 25. The actual maximum speed is dependent on the surface along which it is driving, see Surface Speed Multipliers
Max Reverse Speed	The patty wagon's maximum speed when reversing normally on an ideal surface. Normally 13.
Max Speed Using Nitro	The patty wagon's maximum speed when using a nitro. Normally 29.
Nitro Duration	How long the nitro lasts for, in seconds. Normally 2.5.
Nitro Time Remaining	The time remaining for the nitro currently being used. When a nitro is used, this value is set to Nitro Duration and counts down to 0.
Surface Speed Multipliers	Affects the maximum drive and reverse speeds depending on what the patty wagon is driving on. Surface Speed Multiplier Max Drive Speed Max Reverse Speed SIMPs 0.3 7.5 3.9 Asphalt/Water/Bridges 1 25 13 Grass 0.85 21.25 11.05 Sand 0.7 17.5 9.1 Mud 0.4 10 5.2
Collectibles
Manliness Points	The manliness points collected. The in-game UI lags behind the true count—after collecting manlies, the UI element will count up towards the actual value.
Token Count	The number of tokens currently collected.
Extras Count	The number of extras currently collected.
Upgrade Points	The number of upgrade points remaining. Values above 30 are displayed as "0" in the upgrade menu.
Camera
Camera Pitch Scale	The scale for pitching the camera up/down. Default is 0.77, can be set in SB04.ini with zcam_pad_pitch_scale.
Camera Yaw Scale	The scale for yawing the camera around the player. Default is 0.18, higher values move the camera faster. Can be set in SB04.ini with zcam_pad_pyaw_scale.
Camera is Zoomed In	Whether the camera is in the zoomed in state.
Camera X Position	The camera's X coordinate.
Camera Y Position	The camera's Y coordinate.
Camera Z Position	The camera's Z coordinate.
Camera Roll	The camera's roll. TODO: Add units
Damage
Player Can Take Damage	Whether the player can take damage. Can be set in SB04.ini with G.TakeDamage.
Damage Delay Timer	The number of seconds after being hit before able to take damage. Can be set in SB04.ini with G.DamageTimeHit.
Options
The values set in the options menu. All are 0 by default until the options menu is opened for the first time.
Rumble Feature	Whether the user has set the rumble feature to be enabled. Note that this is not the value that determines if rumble is active (see Vibration Enabled)
Music Volume	The setting for music volume.
Sound Effects Volume	The setting for sound effects volume.
Cheat Codes
Costume Cheats (Bit Field)	A one-byte bit field storing the costumes enabled through cheat codes. Four different costumes are enabled through using cheat codes. Costumes are applied when warping to a new area. Bit 7 → Bit 0 00000000 Bit Costume 4 Caveman costume (SpongeBob) 3 Ripped Shorts costume (SpongeBob) 2 Caveman costume (Patrick) 1 Goofy Goober costume (Patrick) Caveman costumes appear to take priority for both characters if more than one costume is enabled.
Cheat Codes (Bit Field)	A two-byte bit field storing cheats enabled through cheats codes (non-costume cheats). Note that changing these bits do not seem to instantly apply the effects of the cheat codes as other memory locations are usually changed once a valid cheat code is entered. Bit 15 → Bit 0 00000000 00000000 Bit Cheat Code 15 Unlock all tasks 14 Upgrade all moves (Sets all the ability statuses to 2.) 10 Double manliness points (Sets the manliness multiplier to 2.) 9 Unlock all moves (Sets all the ability statuses that are 0 to 1.) 0 Unlock all 6 health slots (Sets the health upgrades for Patrick and SpongeBob to 3).
Num of Inputs Entered	The number of inputs entered when entering a cheat code. Resets to 0 if more than 33 inputs are entered.
Manliness Points Multiplier	The multiplier for collected manliness points. Default is 1, set to 2 when the "Double manliness points" cheat code is used.
Watermark
The watermark is an in-game text overlay. While usually empty, it can be added by adding Watermark = [Your text here...] to SB04.ini or by setting the Watermark Text in Dolphin Memory Engine.
Watermark Text	The watermark text. Variables can also be shown in the watermark, with the syntax {var:VariableName}.
Watermark Alpha	The watermark alpha (opacity). Between 0 and 255, default is 48. Can be set in SB04.ini with WatermarkAlpha.
Watermark Size	The watermark's size. Default is 40. Can be set in SB04.ini with WatermarkSize.
TEXT Variables
Strings that can be used in TEXT assets. Can be used with {var:VariableName}. Many are used by UI elements in-game. Note that, in memory, these strings are all empty by default and only update when queried. TODO: Add screenshots
ActivePad	Unsure (Controller slot?)
BadCard	Erroneous memory card, used for warning messages on game boot (e.g. if the memory card is corrupt, has no space remaining etc.)
BadCardAvailable
BadCardNeeded	Space required to save a game file (used when displaying the warning message on boot when the memory card is erroneous).
CurrentArea	Possibly deprecated, leftover from previous games? Maybe used early on in development. Area Value of CurrentArea BB02 Milestone Test Level BB03 Desert 1 BB01 Thug Tug 1 DE01 Trench 1 DE02 Junk 1 TT01 Goofy Goober 1 TT02 Shell City 1 B101 Planktopolis 1 JK01 Frog Fish Boss B201 Dennis Boss 1 GG02 Neptune Boss All other areas ????
CurrentDate	The current date, e.g. "Sunday April 4, 2021"
CurrentLevel	The name of the current level, e.g. "No Cheese!"
CurrentScene	The name of the current level's HIP file, e.g. "BB03".
CurrentTime	The current time, e.g. "1:18:03 P.M."
GameSlot0	Status of game save file slot 0. Contains game completion %, date saved, save file size in blocks and last level, e.g. : "0% 04/04/21 (9 Blocks) I'm Ready... Depression" Will be "Empty" if nothing in the save slot.
GameSlot1	Status of game save file slot 1.
GameSlot2	Status of game save file slot 2.
GameSlot3	Status of game save file slot 3.
GameSlot4	Status of game save file slot 4.
GameSlot5	Status of game save file slot 5.
GameSlot6	Status of game save file slot 6.
GameSlot7	Status of game save file slot 7.
SpaceNeeded	Space required to save game?
MCAccessType
MCAutoSaveCard
MCMaxSpace
MCMinSpace
MCName
MCSelectedCard
MCSelectedGame
NumChestsNeeded	The number of treasure chests required to unlock the next extra. Updates when opening the Extras menu.
NumChestsCurrentLevel	Number of treasure chests collected in the currently selected level. Updates while scrolling through levels in pause menu.
NumChestsTotalCurrentLevel	Total number of treasure chests in the currently selected level. Updates while scrolling through levels in pause menu.
PlayerPosition	The player's position in the format x, y, z with the decimal part removed (i.e. coordinates are floored).
PS2PadName	Unsure (PlayStation 2 variable?)
SelectedArea	Unsure (Appears to always be "????")
SoundFXVolume	Sound effects volume, 0-10.
SoundMusicVolume	Music volume, 0-10.
SpaceAvailable	Space available on the memory card (TODO: which memory card?)
SpaceAvailableString	Unsure (Same as above?)
SpaceNeeded	Space required to save game?
Miscellaneous
Boot HIP File	The first area to load when starting a new game. Must be set in SB04.ini using BOOT, default is BB02 (No Cheese!). If not set, the game will crash attempting to load the first level.
Vibration Enabled	Whether the vibration setting is enabled. Default is 1, though can be changed in SB04.ini with option_vibration. Toggling the Rumble Feature in options will override this value.
Music Disabled	Whether the music is disabled. Default is 0. Can be set in SB04.ini with NoMusic.
Cutscenes Disabled	Whether the in-engine cutscenes are disabled. Default is 0. Can be set in SB04.ini with NoCutscenes.
Pad Check Disabled	Unsure (maybe disables checking if a gamepad is plugged in?) Default is 0. Can be set in SB04.ini with NoPadCheck.
Asynchronous Loading Screen	Controls whether the loading screen is synchronous. Default is 1. Can be set in SB04.ini with AsyncLoadingScreen. Setting to 0 will prevent loading screens appearing while a level is loading.
Attract Mode During Gameplay	Whether the game will show the attract mode promo during gameplay. If enabled, the game will exit to the title screen after 45 seconds of no controller inputs. Default is 0. Can be set in SB04.ini with G.AttractModeDuringGameplay.
Attract Mode Gameplay Timer	If Attract Mode During Gameplay is 1, this timer will decrease from 45 to 0 upon which the game will reset to the title screen.
Attract Mode Title Screen Timer	The "attract mode" promo timer for the title screen. Decreases from 45 to 0 upon which the game will play the movie "SBAttr.bik". View promo videos: English Versions (GGVE78, GGVP78) Non-English Versions (GGVD78, GGVX78)
Attract Mode Timer Length	The length of the timer (in seconds) for both the gameplay and title screen attract mode timers. Default is 45.
Movies Disabled	Whether the movies are disabled. Movies include .bik files in the folder FMV (e.g. story cutscenes, ability upgrade and studio logos videos). Default is 0. Can be set in SB04.ini with NoMovies.
Force Mono	Whether the audio is in mono (i.e. one audio channel instead of stereo left/right channels). Default is 0. Can be set in SB04.ini with ForceMono.
Initial Manliness Points	Number of initial manliness points the player has. Default is 0. Can be set in SB04.ini with G.InitialShinyCount.
Initial Token Count	Number of initial Goofy Goober tokens the player has. Default is 0. Can be set in SB04.ini with G.InitialSpatulaCount.
Initial Unused Upgrade Points	Number of initial upgrade points the player has. Default is 0. Can be set in SB04.ini with G.UnusedSkillPoints.
Sonic Wave Time Remaining	The number of seconds remaining the Sonic Wave guitar has. Reset to 6 when using Sonic Wave.
Flythrough Minimum Skip Time	The minimum number of seconds before the player can skip a flythrough. Default is 1.0, can be set in SB04.ini with gSkipTimeFlythrough.
Cutscene Minimum Skip Time	The minimum number of seconds before the player can skip a cutscene. Default is 1.0, can be set in SB04.ini with gSkipTimeCutscene.
Cutscene Letterbox Alpha	The alpha (opacity) of the letterboxes shown during in-engine cutscenes. Default is 255 (fully opaque), can be set in SB04.ini with ScrFxLetterBoxAlpha.
Framerate Limiter	Limits the framerate. Value is a divisor for the max framerate. In most levels it is 1, though it is 2 in Bubble Blowing Baby Hunt, Google-Eyes and Smelly Knick Knacks, and all the driving levels. Exiting to the main menu will not reset the value so if you leave one of these levels, the main menu will remain in 25/30fps.
Shortbread Cookie Jar	Unsure (perhaps used for debugging?) Default is 2.0, can be set in SB04.ini with ShortbreadCookieJar.
Bowl Electricity Effect Active	Whether the electricity effect is active during the upgraded sponge bowl's explode animation.
Bowl Aura Effect Active	Whether the aura sphere is active during the upgraded sponge bowl's explode animation. Locking this to 1 will show the location of the last ball explosion. Appears to always be reset to 0 after warping. If enabled after warping, the aura location will be at the map's origin (0,0,0).
Bowl Warping Effect Active	Whether the warping effect is active during the upgraded sponge bowl's explode animation. While normally 1 during explosion, it can be 0 if the ball explodes behind the camera or in a place where the ball isn't visible.
Bowl Praxis X Position	The X coordinate of the praxis effect that appears during upgrade bowl's explode animation.
Bowl Praxis Y Position	The Y coordinate of the praxis effect that appears during upgrade bowl's explode animation.
Bowl Praxis Z Position	The Z coordinate of the praxis effect that appears during upgrade bowl's explode animation.

TODO

• Find player x,y,z location (not static addresses), part of PLYR asset?
• Boss healths