Slippi-AI (Phillip II)

Use scripts/eval_two.py to play against a trained model. By default, the script assumes the human player uses a Wii-U controller adapter.

Key Options:

• --p1.type <type>: Set to human to play as Player 1.
• --p2.ai.path <path>: Path to the trained model file.
• --p2.character <character>: Specify the character for the AI (e.g., fox, falco, marth).
• --dolphin.copy_home_directory: Use your own Dolphin configuration and controller settings instead of the default Wii-U setup.
• --dolphin.iso <path>: Manually specify the Melee ISO if auto-detection fails.
• --dolphin.path <path>: Manually specify the Slippi Dolphin executable path if auto-detection fails.

Example Command:

python scripts/eval_two.py --p1.type human --p2.ai.path <path/to/trained/model> --p2.character fox

python scripts/eval_two.py --p1.type human --p2.ai.path <path/to/trained/model> [--dolphin.copy_home_directory]

This notebook demonstrates how to extract, calculate, and visualize character-specific evaluation losses from W&B runs.

Key steps include:

1. Retrieve Runs: Use wandb.Api().runs(path, filters=...) to fetch runs, potentially filtered by a group (e.g., 'imitation').
2. Identify Characters: Extract the list of allowed characters from the run configuration using the dataset.allowed_characters key.
3. Extract Metrics: Access character-specific metrics using the following key patterns:
   • Losses: eval_characters.losses.<char>
   • Counts: eval_characters.counts.<char>
4. Calculate Mean Loss: Since W&B stores cumulative values, calculate the mean loss per character as: eval_characters.losses.<char> / eval_characters.counts.<char>.
5. Visualize: Use plotnine (ggplot style) to plot eval_loss against step for multiple characters.

# Example: Calculating mean loss for characters
_losses_key = lambda char: 'eval_characters.losses.' + char
_counts_key = lambda char: 'eval_characters.counts.' + char

# Assuming 'df' is a pandas DataFrame from run.history()
for char in chars:
    df[f'{char}.mean'] = df[_losses_key(char)] / df[_counts_key(char)]

# Plotting with plotnine
(gg.ggplot(to_plot)
 + gg.aes(x="step", y="eval_loss", group="char", color="char")
 + gg.geom_line())

To analyze a dataset of parsed replays, load the pickled data into memory and convert it into a pandas DataFrame. This allows for filtering by validity, training suitability, and player attributes.

Common analysis tasks include:

• Filtering valid training data: Use df['valid'] and df['is_training'] to isolate high-quality samples.
• Checking for winners: Use df['winner'].notnull() to ensure a match outcome is recorded.
• Grouping by source: Use a mapping function to create a compact_raw column to group replays by their original dataset/folder (e.g., 'Zain', 'Phillip').

import pandas as pd
import pickle
import os

# Load parsed data
root = '/path/to/replays/'
parsed_path = os.path.join(root, 'parsed.pkl')

with open(parsed_path, 'rb') as f:
    data_bytes = f.read()

data = pickle.loads(data_bytes)
df = pd.DataFrame(data)

# Filter for valid training data
training = df[df['valid'] & (df['is_training'] == True)]

The project uses a pickled database (parsed.pkl) containing replay information. You can load this into a pandas DataFrame to inspect the validity of replays and identify specific error reasons.

Common workflow:

1. Load the pickle file using pickle.load().
2. Convert the database object into a pd.DataFrame.
3. Filter for invalid replays using the valid column.
4. Analyze the reason column to find specific issues (e.g., replays where a specific function was 'called').

import pickle
import os
import pandas as pd

root = '/path/to/replays/'
with open(os.path.join(root, 'parsed.pkl'), 'rb') as f:
    db = pickle.load(f)

df = pd.DataFrame(db)

# Filter for invalid replays
invalid = df[df['valid'] == False]

# Count occurrences of error reasons
print(invalid['reason'].value_counts())

# Filter for specific reasons starting with 'called'
called = invalid[invalid['reason'].map(lambda s: s.startswith('called'))]

This notebook demonstrates how to process a collection of Super Smash Bros. Melee replays to create a specialized dataset of matches played against 'Phillip' (the Slippi-AI bot).

Key steps include:

1. Loading a pre-parsed pickle file containing replay metadata.
2. Normalizing player names using slippi_ai.nametags.
3. Converting character IDs to human-readable strings using melee.Character.
4. Filtering for valid training replays using check_replay from slippi_db.scripts.make_local_dataset.
5. Grouping matches by matchup (character vs opponent character) to select a representative sample (e.g., the last 5 matches per matchup).
6. Compiling and renaming the selected files into a structured ZIP archive for training.

import pandas as pd
from slippi_ai import nametags
from slippi_db import utils
from slippi_db.scripts.make_local_dataset import check_replay

# Example logic for filtering and preparing a matchup dataset
# 1. Load data
df = pd.DataFrame(data)

# 2. Filter for Phillip matches
phillip_df = df[df['compact_raw'] == 'Phillip']

# 3. Filter for valid training data
training_phil_df = vs_phil_df[vs_phil_df['not_training_reason'].isnull()].copy()

# 4. Select sample matchups
matchup_df = training_phil_df.groupby(['char', 'opponent_char']).tail(5).reset_index()