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
menu_selection

The index of the selected menu item for when in menus.

Type:(int)
menu_state

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
submenu

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