The libmelee library provides a Python 3 API for creating custom AI for Super Smash Bros. Melee, compatible with Slippi Online. It allows developers to interact with the game's state and control characters programmatically, enabling the development of AI agents for training, research, or competitive play.

How It Works

libmelee interfaces with the Melee game through Slippi's online functionality and Dolphin emulator's input mechanism. It captures the game state frame-by-frame, providing detailed information on character positions, animations, and game events. The library then allows AI agents to send controller inputs back to the game, enabling real-time interaction and control. libmelee normalizes some of Melee's internal inconsistencies, such as animation frame indexing, to provide a more intuitive and consistent API for developers.

Quick Start & Requirements

• Installation: pip3 install melee
• Prerequisites:
  • Install and configure Slippi: https://slippi.gg
  • For Linux AppImage users: Extract the AppImage using ./Slippi_Online-x86_64.AppImage --appimage-extract.
  • Optional: GameCube Adapter or HitBox adapter for interactive play.
  • Install custom Slippi Gecko Codes by replacing GALE01r2.ini with the one found at https://github.com/altf4/slippi-ssbm-asm/blob/libmelee/Output/Netplay/GALE01r2.ini. On Linux AppImage, this file is located at squashfs-root/usr/bin/Sys/GameSettings/GALE01r2.ini.
• Running: python3 example.py -e PATH_TO_SLIPPI_FOLDER (replace PATH_TO_SLIPPI_FOLDER with the Slippi folder, e.g., squashfs-root/usr/bin/ on Linux AppImage).
• Resources: A ~10-minute quickstart video is available, though some minor API aspects may have changed. Detailed API documentation is at https://libmelee.readthedocs.io/.

Highlighted Details

• Normalizes animation frame indexing to always start at frame 1 for consistent AI development.
• Handles Sheik and Zelda as a single transforming character, abstracting internal game representation.
• Exposes Melee's five distinct velocity values for accurate state representation, crucial for advanced techniques like tech chasing.
• Provides programmatic control over virtual controllers via Dolphin's named pipes, allowing button presses and analog stick tilts.

Maintenance & Community

The library is actively improved. Users are advised to stay updated via pip3 install --upgrade melee. Specific community links (Discord/Slack) or social handles are not mentioned in the README.

Licensing & Compatibility

The license is not specified in the provided README. Compatibility for commercial use or closed-source linking is not detailed.

Limitations & Caveats

Users are strictly warned against playing on Unranked matchmaking with AI bots until official bot account support is implemented, as violations may lead to account bans. Some game values are unintuitive but unavoidable due to Melee's internal workings, requiring developers to understand these nuances. The API has undergone changes, with older values slated for removal in version 1.0.0.