SFIII Gym

A Gymnasium environment for Street Fighter III: 3rd Strike using the MAME emulator. Train reinforcement learning agents to play one of the most iconic fighting games ever made.

Features

• Gymnasium-compatible — standard reset() / step() / render() API
• Rich observations — game frame (224×384 RGB), player healths, sides, opponent character, and current stage
• 15 discrete actions — movement (8 directions + idle) and attacks (6 punch/kick buttons)
• Configurable difficulty — 8 difficulty levels (1–8)
• Render modes — "human" for live playback, "rgb_array" for headless training

Prerequisites

• Python ≥ 3.12
• Linux (MAME emulator requirement)
• Street Fighter III: 3rd Strike ROM (sfiii3n.zip) — you must legally obtain this ROM and place it in a local directory (e.g. ./rom/)

Installation

pip install sfiii-gym

Or with uv:

uv add sfiii-gym

For development:

git clone https://github.com/alexpalms/sfiii-gym.git
cd sfiii-gym
uv sync

Getting Started

from sfiii_gym import Environment

# Create the environment
env = Environment("env1", "./rom", render_mode="human", throttle=False)
obs, info = env.reset()

cumulative_reward = 0
while True:
    env.render()
    action = env.action_space.sample()  # Replace with your agent's action
    obs, reward, terminated, truncated, info = env.step(action)
    cumulative_reward += reward

    if terminated or truncated:
        print(f"Episode finished — Cumulative Reward: {cumulative_reward}")
        obs, info = env.reset()
        cumulative_reward = 0

Observation Space

Action Space

Discrete(15) — 0: no-op, 1–8: movement directions, 9–14: attacks (jab, strong, fierce, short, forward, roundhouse).

Configuration

Repository Structure

sfiii-gym/
├── src/sfiii_gym/          # Main package
│   ├── __init__.py         # Package exports
│   ├── environment.py      # Gymnasium environment implementation
│   ├── actions.py          # Action definitions and mappings
│   ├── steps.py            # Step/observation processing logic
│   └── py.typed            # PEP 561 typing marker
├── tests/
│   ├── unit/               # Unit tests (actions, steps)
│   └── integration/        # Integration tests (env run, Gym API compliance)
├── stubs/MAMEToolkit/      # Type stubs for the MAME emulator toolkit
├── examples/
│   └── run_env.py          # Example script to run the environment
├── rom/                    # ROM directory (not distributed)
└── pyproject.toml          # Project metadata and dependencies

License

This project is licensed under the MIT License.