libmelee

This is a fork of libmelee geared toward machine learning.

Differences from upstream

Gamestates match raw values from slp files, allowing faster tools such as peppi to be used to process replays for imitation learning without risking mismatch between replay data and live data. Upstream on the other hand preprocesses some values to make them more legible, e.g. sets intangibility for ledge grabbing.
A separate process is used to keep the enet connection to dolphin alive. Otherwise, it will time out after one minute of inactivity.
Sets up gecko codes for exi-inputs/fast-forward mode, which allows the game to run much faster than normal. These codes internally disable melee's rendering in the same way that is used to fast-forward a replay during playback. A custom dolphin build is required for this (see below).
Fixes input stick and analog trigger values to match what the game outputs. This makes imitation-trained bots behave correctly. See this commit for details.
Various other miscellaneous improvements, such as being able to control dolphin's debug logging, interfacing with mainline slippi-dolphin, setting infinite time mode, and playing as Sheik.

Installing Libmelee

This fork is now the source for the melee package on pypi, starting with version 0.45.0, and so can be installed with

pip install melee

To upgrade, run

pip install -U melee

Setup Instructions

Linux / OSX / Windows

You can install and configure Slippi just like you would for rollback netplay -- see https://slippi.gg for instructions. If you want to use fast-forward mode, you will need to use my fork of slippi-Ishiiruka. A prebuilt Linux AppImage is available here, which can be used like a regular executable. This build is also headless, meaning it has no graphical elements at all. There is also a Linux mainline build that can run either headless or with graphics (but not in fast-forward mode).
If you want to play interactively with or against your AI, you'll probably want a GameCube Adapter, available on Amazon. Alternatively the HitBox adapter works well too.
Run the example script:

./example.py -e PATH_TO_SLIPPI_FOLDER_OR_EXE

Fast-Forward Mode

To use fast-forward mode, set these arguments in the Console constructor:

console = melee.Console(
  path="PATH_TO_CUSTOM_DOLPHIN",
  gfx_backend="Null",
  disable_audio=True,
  use_exi_inputs=True,
  enable_ffw=True,
)

Known Issues

On MacOS, mainline slippi dolphin crashes (segfaults) for unknown reasons. You should use Ishiiruka instead, or you can try building a "nogui" executable (this is what I use).

Playing Online

Do not play on Unranked There is no libmelee option for it, but don't try. Eventually we'll have a way to register an account as a "bot account" that others will have the ability to opt in or out of playing against. But we don't have it yet. Until then, do not play any bots on Unranked. If you do, we'll know about it, ban your account, overcook all of your food, and seed you against a campy Luigi every tournament. Don't do it.

Quickstart Video

Here's a ~10 minute video that will show you how easy it can be to write a Melee AI from scratch.

Some of the minor aspects of the API have changed since this video was made, but it's still a good resource.

The API

This readme will give you a very high level overview of the API. For a more detailed view into specific functions and their params, check out the ReadTheDocs page here: https://libmelee.readthedocs.io/

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.

Note About Consistency and Binary Compatibility

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 Climbers: 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 Values are Unintuitive but Unavoidable

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)

Controller

Libmelee lets you programatically press buttons on a virtual controller via Dolphin's named pipes input mechanism. The interface for this is pretty simple, after setting up a controller and connecting it, you can:

controller.press_button(melee.enums.BUTTON_A)

controller.release_button(melee.enums.BUTTON_A)

Or tilt one of the analog sticks by:

controller.tilt_analog(melee.enums.BUTTON_MAIN, X, Y)

(X and Y are numbers between 0->1. Where 0 is left/down and 1 is right/up. 0.5 is neutral)

Note on Controller Input

Dolphin will accept whatever your last button input was each frame. So if you press A, and then release A on the same frame, only the last action will matter and A will never be seen as pressed to the game.

Also, if you don't press a button, Dolphin will just use whatever you pressed last frame. So for example, if on frame 1 you press A, and on frame 2 you press Y, both A and Y will be pressed. The controller does not release buttons for you between frames. Though there is a helper function:

controller.release_all()

which will release all buttons and set all sticks / shoulders to neutral.

API Changes

Each of these old values will be removed in version 1.0.0. So update your programs!

gamestate.player has been changed to gamestate.players (plural) to be more Pythonic.
gamestate.x and gamestate.y have been combined into a named tuple: gamestate.position. So you can now access it via gamestate.position.x.
projectile.x and projectile.y have been combined into a named tuple: projectile.position. So you can now access it via projectile.position.x.
projectile.x_speed and projectile.y_speed have been combined into a named tuple: projectile.speed. So you can now access it via projectile.speed.x
gamestate.stage_select_cursor_x and gamestate.stage_select_cursor_x have both been combined into the PlayerState cursor. It makes the API cleaner to just have cursor be separate for each player, even though it's a shared cursor there.
playerstate.character_selected has been combined into playerstate.charcter. Just use the menu to know the context.
playerstate.ecb_left and the rest have been combined into named tuples like: playerstate.ecb.left.x for each of left, right, top, bottom. And x, y coords.
hitlag boolean has been changed to hitlag_left int
ProjectileSubtype has been renamed to ProjectileType to refer to its primary type enum. There is a new subtype int that refers to a subtype.

OpenAI Gym

libmelee is inspired by, but not exactly conforming to, the OpenAI Gym API.

Metadata

Release files for melee 0.47.5

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for melee 0.47.5
File	Size	Uploaded
melee-0.47.5.tar.gz	589.0 kB	Oct 10, 2026	Details

Built distribution (wheel)

Table of built distributions (wheels) for melee 0.47.5
File	Interpreter	ABI	Platform	Reset
melee-0.47.5-py3-none-any.whl 630.5 kB Oct 10, 2026	Python 3	none	any	Details

Total release size: 1.2 MB

Release files / melee-0.47.5.tar.gz

Download URL	melee-0.47.5.tar.gz
Size	589.0 kB
Tags	Source
SHA-256 checksum How to use checksums	`8a517fb267129720fcbfe53176522f03e1bdb5d5011d78f50ebe11ea3131b669`
BLAKE2b-256 checksum How to use checksums	`791cf84d430eace53b21649d6ddc7bc129d106cb79e83e183488e7c3f02459b9`
Upload date	Oct 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/vladfi1/libmelee
Publishing commit: github.com/vladfi1/libmelee/tree/25255fb1532a723b19c339f581c09b192b3a2fb2

Workflow

Publishing configuration: github.com/vladfi1/libmelee/blob/25255fb1532a723b19c339f581c09b192b3a2fb2/.github/workflows/publish.yml
Publishing logs: github.com/vladfi1/libmelee/actions/runs/38008208348/attempts/1

Artifact

Subject: melee-0.47.5.tar.gz
SHA-256 checksum: 8a517fb267129720fcbfe53176522f03e1bdb5d5011d78f50ebe11ea3131b669 Verifying attestations

Release files / melee-0.47.5-py3-none-any.whl

Download URL	melee-0.47.5-py3-none-any.whl
Size	630.5 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`28951be33bfa19a9da0c0cfd7476197095fabbe323637768e123e74a2dcd9046`
BLAKE2b-256 checksum How to use checksums	`ebd9d310adb2554c43a6a65b484e705642d04e12af610793356e352a8e952881`
Upload date	Oct 10, 2026
Uploaded using Trusted Publishing? What is trusted publishing?	Yes
Uploaded via	`twine/7.0.0 CPython/3.13.14`

Provenance

Identity

Publishing platform: GitHub Actions
Publishing repository: github.com/vladfi1/libmelee
Publishing commit: github.com/vladfi1/libmelee/tree/25255fb1532a723b19c339f581c09b192b3a2fb2

Workflow

Publishing configuration: github.com/vladfi1/libmelee/blob/25255fb1532a723b19c339f581c09b192b3a2fb2/.github/workflows/publish.yml
Publishing logs: github.com/vladfi1/libmelee/actions/runs/38008208348/attempts/1

Artifact

Subject: melee-0.47.5-py3-none-any.whl
SHA-256 checksum: 28951be33bfa19a9da0c0cfd7476197095fabbe323637768e123e74a2dcd9046 Verifying attestations