GameState¶
The GameState represents the current state of the game as a snapshot in time. It’s your primary way to view what’s happening in the game, holding all the information about the game that you probably care about including things like:
- Current frame count
- Current stage
Also a list of PlayerState objects that represent the state of the 4 players:
- Character X,Y coordinates
- Animation of each character
- Which frame of the animation the character is in
The GameState object should be treated as immutable. Changing it won’t have any effect on the game, and you’ll receive a new copy each frame anyway.
Design Note¶
Libmelee tries to create a sensible and intuitive API for Melee. So it may break with some low-level binary structures that the game creates. Some examples:
- Melee is wildly inconsistent with whether animations start at 0 or 1. For some animations, the first frame is 0, for others the first frame is 1. This is very annoying when trying to program a bot. So libmelee re-indexes all animations to start at 1. This way the math is always simple and consistent. IE: If grab comes out on “frame 7”, you can reliably check
character.animation_frame == 7
. - Libmelee treats Sheik and Zelda as one character that transforms back and forth. This is actually not how the game stores the characters internally, though. Internally to Melee, Sheik and Zelda are the same as Ice Clibmers: there’s always two of them. One just happens to be invisible and intangible at a time. But dealing with that would be a pain.
Some Oddities¶
Other values in Melee are unintuitive, but are a core aspect of how the game works so we can’t abstract it away.
- Melee doesn’t have just two velocity values (X, Y) it has five! In particular, the game tracks separately your speed “due to being hit” versus “self-induced” speed. This is why after an Amsah tech, you can still go flying off stage. Because your “attack based speed” was high despite not moving anywhere for a while. Libmelee could produce a single X,Y speed pair but this would not accurately represent the game state. (For example, SmashBot fails at tech chasing without these 5 speed values)
- Melee tracks whether or not you’re “on ground” separately from your character’s Y position. It’s entirely possible to be “in the air” but be below the stage, and also possible to be “on ground” but have a positive Y value. This is just how the game works and we can’t easily abstract this away.
- Your character model can be in a position very different from the X, Y coordinates. A great example of this is Marth’s Forward Smash. Marth leans WAAAAY forward when doing this attack, but his X position never actually changes. This is why Marth can smash off the stage and be “standing” on empty air in the middle of it. (Because the game never actually moves Marth’s position forward)
Gamestate is a single snapshot in time of the game that represents all necessary information to make gameplay decisions
-
class
melee.gamestate.
GameState
¶ Represents the state of a running game of Melee at a given moment in time
-
consoleNick
¶ The name of the console the replay was created on. Might be blank.
Type: (string)
-
custom
¶ Custom fields to be added by the user
Type: (dict)
-
distance
¶ Euclidian distance between the two players. (or just Popo for climbers)
Type: (float)
-
frame
¶ The current frame number. Monotonically increases. Can be negative.
Type: int
The index of the selected menu item for when in menus.
Type: (int)
The current menu scene, such as IN_GAME, or STAGE_SELECT
Type: enums.MenuState
-
playedOn
¶ Platform the game was played on (values include dolphin, console, and network). Might be blank.
Type: (string)
-
player
¶ Deprecated. Will be removed in version 1.0.0. Use players instead Dict of PlayerState objects. Key is controller port
Type: (dict of int - gamestate.PlayerState) Type: WARNING
-
players
¶ Dict of PlayerState objects. Key is controller port
Type: (dict of int - gamestate.PlayerState)
-
projectiles
¶ All projectiles (items) currently existing
Type: (list of Projectile)
-
ready_to_start
¶ Is the ‘ready to start’ banner showing at the character select screen?
Type: (bool)
-
stage
¶ The current stage being played on
Type: enums.Stage
-
stage_select_cursor_x
¶ DEPRECATED. Use players[X].cursor instead. Will be removed in 1.0.0. Stage select cursor’s X coordinate. Ranges from -27 to 27
Type: (float)
-
stage_select_cursor_y
¶ DEPRECATED. Use players[X].cursor instead. Will be removed in 1.0.0. Stage select cursor’s Y coordinate. Ranges from -19 to 19
Type: (float)
-
startAt
¶ 52:59Z’
Type: (string) Type: Timestamp string of when the game started. Such as ‘2018-06-22T07
The current sub-menu
Type: (enums.SubMenu)
-
-
class
melee.gamestate.
PlayerState
¶ Represents the state of a single player
-
action
¶ The current action (or animation) the character is in
Type: (enum.Action)
-
action_frame
¶ What frame of the Action is the character in? Indexed from 1.
Type: (int)
-
character
¶ The player’s current character
Type: (enum.Character)
-
character_selected
¶
-
coin_down
¶ Is the player’s character selection coin placed down? (Does not work in Slippi selection screen)
Type: (bool)
-
connectCode
¶ The rollback connect code for the player. Might be blank.
Type: (string)
-
controller_state
¶ What buttons were pressed for this character
Type: (controller.ControllerState)
-
controller_status
¶ Status of the player’s controller.
Type: (enums.ControllerStatus)
-
costume
¶ Index for which costume the player is wearing
Type: (int)
-
cpu_level
¶ CPU level of player. 0 for a libmelee-controller bot or human player.
Type: (bool)
-
cursor
¶ x, y cursor position
Type: (namedtuple Type: float, float)
-
cursor_x
¶ DEPRECATED. Use cursor instead. Will be removed in 1.0.0. Cursor X value
Type: (float)
-
cursor_y
¶ DEPRECATED. Use position instead. Will be removed in 1.0.0. Cursor Y value
Type: (float)
-
ecb
¶
-
ecb_bottom
¶ Bottom edge of the ECB. (x, y) offset from player’s center.
Type: (float, float)
-
ecb_left
¶ Left edge of the ECB. (x, y) offset from player’s center.
Type: (float, float)
-
ecb_right
¶ Right edge of the ECB. (x, y) offset from player’s center.
Type: (float, float)
-
ecb_top
¶ Top edge of the ECB. (x, y) offset from player’s center.
Type: (float, float)
-
facing
¶ Is the character facing right? (left is False). Characters in Melee must always be facing left or right
Type: (bool)
-
hitlag_left
¶ Is the player currently in hitstun?
Type: (bool)
-
hitstun_frames_left
¶ How many more frames of hitstun there is
Type: (int)
-
iasa
¶
-
invulnerability_left
¶ How many frames of invulnerability are left.
Type: (int)
-
invulnerable
¶ Is the player invulnerable?
Type: (bool)
-
is_holding_cpu_slider
¶ Is the player holding the CPU slider in the character select screen?
Type: (bool)
-
jumps_left
¶ Number of jumps available. Including ground jump. Will be 2 for most characters on ground.
Type: (int)
-
moonwalkwarning
¶ Helper variable to tell you that if you dash back right now, it’ll moon walk
Type: (bool)
-
nana
¶ Additional player state for Nana, if applicable. If the character is not Ice Climbers, Nana will be None. Will also be None if this player state is Nana itself. Lastly, the secondary climber is called ‘Nana’ here, regardless of the costume used.
Type: (enums.PlayerState)
-
nickName
¶ The in-game nickname for the player. Might be blank.
Type: (string)
-
off_stage
¶ Helper variable to say if the character is ‘off stage’.
Type: (bool)
-
on_ground
¶ Is the character on the ground?
Type: (bool)
-
percent
¶ The player’s damage
Type: (int)
-
position
¶ x, y character position
Type: (namedtuple Type: float, float)
-
shield_strength
¶ The player’s shield strength (max 60). Shield breaks at 0
Type: (float)
-
speed_air_x_self
¶ Self-induced horizontal air speed
Type: (float)
-
speed_ground_x_self
¶ Self-induced horizontal ground speed
Type: (float)
-
speed_x_attack
¶ Attack-induced horizontal speed
Type: (float)
-
speed_y_attack
¶ Attack-induced vertical speed
Type: (float)
-
speed_y_self
¶ Self-induced vertical speed
Type: (float)
-
stock
¶ The player’s remaining stock count
Type: (int)
-
team_id
¶ The team ID of the player. This is different than costume, and only relevant during teams.
Type: (int)
-
x
¶ DEPRECATED. Use position instead. Will be removed in 1.0.0. The character’s X position
Type: (float)
-
y
¶ DEPRECATED. Use position instead. Will be removed in 1.0.0. The character’s Y position
Type: (float)
-
-
class
melee.gamestate.
Projectile
¶ Represents the state of a projectile (items, lasers, etc…)
-
frame
= None¶ How long the item has been out
Type: (int)
-
owner
= None¶ Player port of the projectile’s owner. -1 for no owner
Type: (int)
-
position
= None¶ x, y projectile position
Type: (namedtuple Type: float, float)
-
speed
= None¶ x, y projectile speed
Type: (namedtuple Type: float, float)
-
subtype
= None¶ The subtype of the item. Many projectiles have ‘subtypes’ that make them different. They’re all different, so it’s not an enum
Type: (int)
-
type
= None¶ Which actual projectile type this is
Type: (enums.ProjectileType)
-
x
= None¶ DEPRECATED. Use position instead. Will be removed in 1.0.0. Projectile’s X position
Type: (float)
-
x_speed
= None¶ DEPRECATED. Use speed instead. Will be removed in 1.0.0. Projectile’s horizontal speed
Type: (float)
-
y
= None¶ DEPRECATED. Use position instead. Will be removed in 1.0.0. Projectile’s Y position
Type: (float)
-
y_speed
= None¶ DEPRECATED. Use speed instead. Will be removed in 1.0.0. Projectile’s vertical speed
Type: (float)
-
-
melee.gamestate.
port_detector
(gamestate, character, costume)¶ Autodiscover what port the given character is on
Slippi Online assigns us a random port when playing online. Find out which we are
Returns: The given character belongs to the returned port 0: We don’t know.
Return type: [1-4]
Parameters: - gamestate – Current gamestate
- character – The character we know we picked
- costume – Costume index we picked