🦅 Amiibo Behavior Visualizer

Interpretable AI for Fighting Games: Recreating and expanding upon Firoiu et al.'s "Beating the World's Best at Super Smash Bros. Melee with Deep Reinforcement Learning" (2017) using Bayesian methods and causal inference instead of black-box neural networks.

Real-time personality tracking and optimization system for Super Smash Bros. Ultimate Amiibo training on Ryujinx emulator.

🎯 Features

• Real-time Dashboard - Live web visualization of Amiibo personality changes
• Training Validation - Before/after comparison to verify training effectiveness
• 32+ Parameters - Track all behavioral parameters across 8 personality dimensions
• Auto-Monitoring - Detect and analyze changes as they happen
• Bayesian Optimization - Advanced parameter optimization framework (planned)

🚀 Quick Start

Prerequisites

• Python 3.7+
• Ryujinx emulator with SSBU
• Amiibo save data in Ryujinx

Installation

git clone https://github.com/PaulLunis/Amiibot.git
cd Amiibot

No dependencies to install - uses Python standard library only!

Usage

Complete Training Session:

python start_training_session.py

Dashboard Only:

python dashboard_server.py
# Open: http://localhost:8000/dashboard.html

Validation:

python training_validation_workflow.py

📊 What It Tracks

8 Personality Dimensions

• Defense - Shielding, defensive play
• Agility - Movement speed, aerial combat
• Offense - Aggression, attack frequency
• Risk-taking - Off-stage play, risky moves
• General Style - Overall combat approach
• Engagement - Pursuit behavior
• Caution - Conservative decisions
• Dynamism - Playstyle variety

32+ Behavioral Parameters

Including: offensive, defensive, shield_master, meteor_master, feint_master, air_offensive, item_collector, and many more.

🎨 Dashboard

Beautiful web-based visualization with:

• 🎭 Radar chart (8-dimensional personality profile)
• 📊 Bar chart (comparative metrics)
• ⚙️ Parameter grid (all 32+ values, color-coded)
• Auto-refresh every 2 seconds

---

🎓 Research Context

Inspired by Deep RL, Enhanced with Interpretability

In 2017, Firoiu et al. (MIT/NYU) trained deep reinforcement learning agents that defeated top professional Super Smash Bros. Melee players using Actor-Critic networks and weeks of self-play. While groundbreaking, their approach had key limitations:

• Black-box neural networks - no insight into learned strategies
• Weeks of training - computationally expensive
• No opponent modeling - implicit adaptation only
• Uninterpretable - couldn't explain why agents made decisions

This project provides an interpretable alternative by analyzing and optimizing existing Amiibo AI using principled statistical methods from computational cognitive science.

📊 Approach Comparison

Aspect	Deep RL (Firoiu 2017)	This Project
Method	Actor-Critic neural networks	Bayesian parameter optimization
Training Time	1-2 weeks self-play	Hours with Bayesian optimization
Interpretability	Black-box (hidden layers)	32 interpretable parameters
Sample Efficiency	Thousands of episodes	50-100 evaluations (GP-UCB)
Opponent Modeling	Implicit in network weights	Explicit Bayesian Theory-of-Mind
Causality	Correlational only	Causal structure learning
Uncertainty	None	Full posterior distributions
Explainability	Post-hoc analysis	Built-in interpretability

🔬 Research Contributions

This project bridges three research areas:

1. Game AI Research - Interpretable alternative to deep RL for fighting games
2. Bayesian Optimization - Sample-efficient parameter search in expensive evaluation settings
3. Computational Cognitive Science - Theory-of-Mind opponent modeling and causal inference

Potential Publications:

• "Bayesian Optimization of Interpretable Fighting Game AI"
• "Causal Structure Learning in Game AI Parameters"
• "Theory-of-Mind for Adaptive Amiibo Behavior"
• "Sample-Efficient Alternatives to Deep RL for Fighting Games"

---

📁 Project Structure

amiibot_behavior_visualizer/
├── start_training_session.py    # All-in-one workflow
├── dashboard_server.py           # Web dashboard server
├── dashboard.html                # Visualization UI
├── training_validation_workflow.py  # Before/after validation
├── export_personality.py         # State exporter
├── parse_amiibo_bin.py          # Core personality decoder
│
├── docs/                         # Documentation
│   ├── README.md                 # Full documentation
│   ├── QUICK_REFERENCE.txt       # Command reference
│   ├── COMPLETE_WORKFLOW_GUIDE.md
│   ├── BAYESIAN_OPTIMIZATION_ROADMAP.md
│   └── PPL_INTEGRATION_NOTES.md
│
└── src/                          # Future: Skyline plugin
    └── lib.rs

🔬 Advanced Features

Phase 4: Parameter Writer ⭐ NEW - READY TO TEST ⭐

Direct parameter editing with safety features:

• Write individual parameters or full personality profiles
• Automatic backup before each write
• Verification system ensures writes succeeded
• Reset to blank slate for from-scratch training
• Between-match editing capability

Try it now:

python test_parameter_writer.py  # Run test suite
python write_amiibo_parameters.py  # Interactive demo

See PHASE4_IMPLEMENTATION_PLAN.md for testing guide.

Phase 5: Bayesian Optimization (Next)

• Gaussian Process optimization (GP-UCB)
• Thompson sampling
• Sample-efficient parameter search

Phase 6: Strategy Templates

• Pre-designed optimal builds
• UCB-based template comparison
• Profile save/load system

Phase 7-8: Statistical Inference

• Hierarchical Bayesian models (PyMC)
• Causal inference
• Uncertainty quantification

Phase 9: Probabilistic Programming

• Gen.jl integration for custom inference
• Active learning with Expected Information Gain
• Opponent modeling (Theory-of-Mind)

📚 Documentation

• Quick Reference - Command cheat sheet
• Complete Guide - Detailed workflows
• Bayesian Optimization - Advanced methods
• PPL Integration - Gen.jl/PyMC guide
• Save Locations - Technical reference

🎓 Background & Methodology

Why Interpretable AI Matters

While deep RL achieved superhuman performance in fighting games (Firoiu et al. 2017), understanding and controlling AI behavior requires interpretability. This project demonstrates that:

1. Existing AI can be analyzed - Amiibo already have trained behaviors
2. Parameters are interpretable - 32 dimensions with clear meanings
3. Optimization is sample-efficient - Bayesian methods need far fewer evaluations
4. Causality can be identified - Which parameters actually matter for performance

Computational Methods

This project applies cutting-edge computational cognitive science:

Phase 1-3 (Complete): Data Infrastructure

• Real-time parameter tracking and visualization
• Training validation with before/after snapshots
• Statistical analysis of behavior changes

Phase 4-6 (Planned): Optimization

• Bayesian Optimization - GP-UCB for sample-efficient parameter search
• Multi-armed Bandits - UCB1 for discrete strategy selection
• Thompson Sampling - Probability matching for exploration

Phase 7-8 (Planned): Inference & Causality

• Hierarchical Bayesian Models (PyMC) - Multi-level parameter relationships
• Causal Structure Learning (DoWhy) - Identify which parameters cause wins
• Uncertainty Quantification - Posterior distributions over parameters

Phase 9 (Planned): Probabilistic Programming

• Gen.jl - Custom inference strategies and active learning
• Theory-of-Mind - Bayesian opponent modeling (inspired by LABTOM)
• Expected Information Gain - Optimal experiment design

Perfect for Researchers In:

• Game AI - Interpretable alternatives to deep RL
• Bayesian Optimization - High-dimensional, expensive evaluation settings
• Causal Inference - Learning parameter-performance relationships
• Cognitive Science - Theory-of-Mind and opponent modeling
• Active Learning - Sample-efficient experiment design
• Inverse RL - Inferring reward functions from behavior

🤝 Contributing

Contributions welcome! Areas of interest:

• Parameter writer implementation
• Bayesian optimizer
• Strategy templates
• Documentation improvements
• Testing on different Amiibo characters

📝 License

MIT License - see LICENSE file for details

🙏 Acknowledgments

Research Inspiration:

• Firoiu et al. (2017) - "Beating the World's Best at Super Smash Bros. Melee with Deep Reinforcement Learning"
• LABTOM Project - Bayesian Theory-of-Mind framework for agent reasoning

Technical Foundation:

• Amiibo bin file format documentation from the community
• Skyline framework for Switch modding
• Ryujinx emulator team

Computational Methods:

• Gen.jl probabilistic programming language
• PyMC Bayesian inference framework
• DoWhy causal inference library

📧 Contact

Questions? Open an issue or contact @PaulLunis

---

Status: Phases 1-3 complete (Validation + Dashboard), Phases 4-9 planned

Current Version: 1.0.0-beta

Last Updated: October 2025