Player States
Note
This page is a work in progress. States are a very important and thus very complex part of player behavior. The descriptions are not comprehensive and can be improved.
At any point, the player is in exactly one state, which is handled by the player's StateMachine. The state determines a lot of the mechanics concerning movement, and most input processing is state-specific. There are 26 states in vanilla, but mods can and do add custom states.
The current state can be seen in the CelesteTAS info HUD. While internally represented as integers, all vanilla and some custom states have names, which generally begin with St.
The term "state" is often colloquially used to simply describe the player's entire current situation. However, most of those things aren't actually states, which notably means they can coexist with (in theory) any state. For example, the following things are not states:
- Crouching/ducking
- Carrying a holdable
- Being dead
- Having a delayed ultra stored
- "Sliding"
Each state can have the following callbacks: Update, Coroutine, Begin, End. These are called in the following situations:
- When the player state changes, the game instantly calls the old state's End callback followed by the new state's Begin callback.
- Every frame, when the Player's Update method calls
base.Update(), the StateMachine calls the current state's Update callback. That method's return value is an integer that determines the new state. The StateMachine sets the state to the new value if a different one than the current state was returned. Then, the now current state's coroutine is advanced.
StNormal is the regular state that the player spends most of the time in. This state allows, among other things, moving horizontally subject to friction, dashing, as well as grounded jumps, walljumps, and climbjumps.
StClimb is the state for holding onto a wall using grab. Entering StClimb resets horizontal speed to 0 and divides vertical speed by 5. In StClimb, the player can climb up or down the wall, dash, or climbjump. Dashing or climbjumping will end StClimb. Climbing to the top of a wall triggers a climbhop.
Note
A climbjump directly from StNormal will never enter StClimb (see the detailed page on climbjumps).
StDash is the state during a dash. If not cancelled early, it will typically last for 15 frames (including 3 freeze frames). In StDash, the player will move at a constant speed. The main available movement options in StDash are supers, hypers, wallbounces, and climbjumps, all of which will immediately cause a change to StNormal.
StSwim is the state for being mostly underwater. In StSwim, the player has access to full analog movement.
Note
Walking in one-tile-high water on top of a solid or jumping off the surface of water never causes the player to enter StSwim.
StBoost is the state that the player is in while waiting inside a booster (red or green bubble). The only available controls in StBoost are slightly shifting the player's position with analog movement (the position will be reset once the booster actually triggers) and pressing dash to fastbubble. Once the booster triggers (automatically or through fastbubbling), the player will enter StDash or StRedDash depending on the type of booster.
StRedDash is the state for travelling with a red booster. It causes the player to travel at a constant speed until hitting a solid or cancelling the state using a dash, super, hyper, wallbounce, walljump, or climbjump.
StHitSquash is entered when the player collides with a solid in StRedDash. In StHitSquash, the player slows down towards 0 speed with a friction of 13.33336 px/s/frame. The state automatically changes to StNormal after 6 frames, but can be cancelled early by performing a grounded/coyote jump, walljump, or climbjump, or by simply pressing jump even if no wall or floor is nearby (which will have no effect other than changing the state to StNormal).
StLaunch is the state used for various types of launches, including explosion-type launches (bumpers and puffers), badeline boss launches, and mid-room badeline boost launches. The only available controls during StLaunch are dashing (which will enter StDash) and picking up a holdable (which will enter StPickup). In StLaunch, the game will allow picking up holdables even if the player is already holding a holdable (including the same one). The state automatically changes to StNormal once the player's total speed goes below 220.
StPickup is entered when the player picks up a holdable. During StPickup, the player's speed will temporarily be set to 0 and inputs are ignored. The state changes to StNormal once the holdable has been moved to the holding position above the player. This takes 13 frames unless a skinmod changes the holding position.
StDreamDash is the state used for travelling through a dream block. Uniquely, in StDreamDash, the player can move through solids.
StSummitLaunch is the state used for the final launch of a badeline boost chain, which will generally carry the player into the next room. Upon screen transitioning, the state will change to StIntroJump.
StDummy is the generic NoControl/cutscene state. This state is used for most cutscenes and other cases where the player is not meant to have control, such as while using a bino. In StDummy, basic friction applies similar to StNormal. Gravity applies unless disabled by the cutscene. While most inputs are ignored, holding the jump button still has its usual effects on the jump timer and on half-gravity. StDummy does not prevent the player from moving past the screen bounds, but does not allow screen transitions to occur.
StIntroWalk is the state used for the WalkInRight and WalkInLeft intro types, used e.g. in Prologue, Chapter 3, Chapter 4, Epilogue, and Core.
StIntroJump is the state used for the Jump intro type, used e.g. in Chapter 1. It is also used for the landing after being thrown up into a screen by StSummitLaunch.
StIntroRespawn is the state used for respawning after a death, or for custom maps that use the Respawn intro type.
StIntroWakeUp is the state used for the WakeUp intro type, used e.g. in Chapter 2.
StBirdDashTutorial is the state used for the dash tutorial at the end of Prologue.
StFrozen is a cutscene state that does not have any state-specific behavior (unlike e.g. the friction and animation handling in StDummy). It is used when a cutscene wants to fully control the player object, such as in the gondola cutscene at the end of Chapter 4.
Note
This is distinct from both freeze frames (which fully skip the scene update loop) and from the level being frozen (which prevents all entities except specifically tagged ones from updating, and is used e.g. while the cassette collection UI is visible).
StReflectionFall is the state used for the fall during the Chapter 6 cutscene that leads to the Lake checkpoint, or for custom maps that use the Fall intro type.
StStarFly is the feather state. It allows full analog movement.
StTempleFall is the state used for the fall after the mirror in Chapter 5.
StCassetteFly is the state that carries the player to a specific location in a clear bubble after collecting a cassette, a key in the Power Source checkpoint of Chapter 9, or many berries in custom maps.
StAttract is the state that pulls the player towards a badeline boss when close to it.
StIntroMoonJump is the state used for the landing in the cutscene after being launched to space by Badeline at the start of Chapter 9.
StFlingBird is the state that the player is in while holding onto a fling bird. Once the actual fling happens, the state changes to StNormal.
StIntroThinkForABit is the state used for the ThinkForABit intro type, used e.g. in Chapter 9.
Celeste TAS