Skip to content

Dolphin toolkit for The SpongeBob SquarePants Movie, including watch files for Dolphin Memory Engine, and Lua scripts for TAS creators and speedrun practice.

Notifications You must be signed in to change notification settings

ItsPepperpot/TSSM-Dolphin-Toolkit

Repository files navigation

TSSM-Dolphin-Toolkit

A preview of the Dolphin Memory Engine watch file, next to a screenshot of the game with the Patty Wagon overlay.

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
BitButton Press
15Unsure (controller disconnected?)
14Unsure (unused?)
13Unsure (unused?)
12START
11Y
10X
9B
8A
7Unsure (controller connected?)
6L
5R
4Z
3Up
2Down
1Right
0Left
Main Stick X X position of the main analog stick.
0255, 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
SIMPs0.37.53.9
Asphalt/Water/Bridges12513
Grass0.8521.2511.05
Sand0.717.59.1
Mud0.4105.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
BitCostume
4Caveman costume (SpongeBob)
3Ripped Shorts costume (SpongeBob)
2Caveman costume (Patrick)
1Goofy 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
BitCheat Code
15Unlock all tasks
14Upgrade all moves
(Sets all the ability statuses to 2.)
10Double manliness points
(Sets the manliness multiplier to 2.)
9Unlock all moves (Sets all the ability statuses that are 0 to 1.)
0Unlock 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.
AreaValue of CurrentArea
BB02Milestone Test Level
BB03Desert 1
BB01Thug Tug 1
DE01Trench 1
DE02Junk 1
TT01Goofy Goober 1
TT02Shell City 1
B101Planktopolis 1
JK01Frog Fish Boss
B201Dennis Boss 1
GG02Neptune 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:
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

About

Dolphin toolkit for The SpongeBob SquarePants Movie, including watch files for Dolphin Memory Engine, and Lua scripts for TAS creators and speedrun practice.

Topics

Resources

Stars

Watchers

Forks

Languages