{"id":27742452,"url":"https://github.com/ericflo/emuvlm","last_synced_at":"2025-07-05T01:39:17.969Z","repository":{"id":280203926,"uuid":"939848579","full_name":"ericflo/emuvlm","owner":"ericflo","description":null,"archived":false,"fork":false,"pushed_at":"2025-03-02T00:22:20.000Z","size":408,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-03-02T00:23:31.516Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ericflo.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2025-02-27T07:55:20.000Z","updated_at":"2025-03-02T00:22:24.000Z","dependencies_parsed_at":"2025-03-02T00:23:43.879Z","dependency_job_id":"1a69e4f0-7e38-48cc-891e-15b514608015","html_url":"https://github.com/ericflo/emuvlm","commit_stats":null,"previous_names":["ericflo/emuvlm"],"tags_count":0,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericflo%2Femuvlm","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericflo%2Femuvlm/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericflo%2Femuvlm/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ericflo%2Femuvlm/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ericflo","download_url":"https://codeload.github.com/ericflo/emuvlm/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":251347600,"owners_count":21575113,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-04-28T16:41:14.941Z","updated_at":"2025-04-28T16:41:15.754Z","avatar_url":"https://github.com/ericflo.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# EmuVLM\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n[![Python 3.8+](https://img.shields.io/badge/python-3.8+-blue.svg)](https://www.python.org/downloads/)\n[![GitHub issues](https://img.shields.io/github/issues/ericflo/emuvlm)](https://github.com/ericflo/emuvlm/issues)\n[![GitHub stars](https://img.shields.io/github/stars/ericflo/emuvlm)](https://github.com/ericflo/emuvlm/stargazers)\n[![GitHub forks](https://img.shields.io/github/forks/ericflo/emuvlm)](https://github.com/ericflo/emuvlm/network)\n[![GitHub contributors](https://img.shields.io/github/contributors/ericflo/emuvlm)](https://github.com/ericflo/emuvlm/graphs/contributors)\n[![Last Commit](https://img.shields.io/github/last-commit/ericflo/emuvlm)](https://github.com/ericflo/emuvlm/commits/main)\n\nEmuVLM lets AI play retro games by \"seeing\" the game screen and choosing actions. It connects emulators with vision language models (VLMs) that can understand images.\n\n\u003c!--![EmuVLM Demo](https://github.com/ericflo/emuvlm/raw/main/docs/images/demo.gif)--\u003e\n\n## What it does\n\n- 🎮 AI plays Game Boy, Game Boy Color, and other retro games\n- 👁️ Uses vision models to analyze game screens and make decisions\n- 🧠 Works with multiple AI models (LLaVA, Qwen, MiniCPM)\n- 💾 Supports saving/loading game sessions\n- 🖥️ Works on macOS, Linux, and Windows (via WSL)\n\n## Quick Start\n\n### Prerequisites\n\n- Python 3.8+ (3.10 recommended)\n- Game Boy/GBC ROMs (legally obtained)\n- macOS, Linux, or Windows with WSL2\n\n### Installation\n\n```bash\n# Create a virtual environment\npython -m venv venv\nsource venv/bin/activate  # On Windows: venv\\Scripts\\activate\n\n# Install EmuVLM\ngit clone https://github.com/ericflo/emuvlm.git\ncd emuvlm\npip install -e .\n\n# Install emulator dependencies\n./install_emulators.sh\n\n# Download a model (LLaVA is the default)\nemuvlm-download-model\n```\n\n### Play Games\n\n1. Start the model server:\n   ```bash\n   emuvlm-llama-server\n   ```\n\n2. Run the built-in demo (no ROM needed):\n   ```bash\n   emuvlm-demo\n   ```\n\n3. Or play with your own ROM:\n   ```bash\n   emuvlm --game /path/to/pokemon.gb\n   ```\n\n## Supported Games\n\nEmuVLM works best with turn-based games:\n\n- **Fully Supported:** Game Boy/GBC games (especially Pokémon, Zelda)\n- **Beta Support:** Game Boy Advance, NES, SNES, Genesis, N64, PlayStation\n\n## Configuration\n\nConfigure your setup in `config.yaml`:\n\n```yaml\nmodel:\n  # Use LLaVA (default), Qwen, or MiniCPM\n  model_type: \"llava\"\n  # Adjust temperature (0.0-1.0)\n  temperature: 0.2\n\ngames:\n  pokemon_blue:\n    rom: \"/path/to/PokemonBlue.gb\"\n    emulator: \"pyboy\"\n```\n\n## Command Reference\n\n| Command | Description |\n|---------|-------------|\n| `emuvlm --game pokemon_blue` | Play a configured game |\n| `emuvlm-demo` | Run the built-in demo game |\n| `emuvlm-llama-server` | Start the model server |\n| `emuvlm-download-model` | Download the default model |\n| `emuvlm-download-model --model-type qwen` | Download the Qwen model |\n| `emuvlm-monitor --game pokemon_blue` | Watch and intervene in gameplay |\n| `emuvlm-download-rom --game pokemon` | Create a placeholder ROM |\n\n## Advanced Options\n\n- **Select different model types:**\n  ```bash\n  emuvlm-download-model --model-type qwen\n  emuvlm-llama-server --model-type qwen\n  ```\n\n- **Enable game state summarization:**\n  ```bash\n  emuvlm --game zelda --summary on\n  ```\n\n- **Resume a saved session:**\n  ```bash\n  emuvlm --game pokemon_blue --session path/to/session.session\n  ```\n\n## Troubleshooting\n\n- **Model server not starting:** \n  - Check you have enough disk space for the model (~5GB)\n  - Make sure you've downloaded the model with `emuvlm-download-model`\n\n- **Game not responding correctly:**\n  - Try adjusting timing in config.yaml (action_delay)\n  - Make sure your ROM is compatible\n\n- **Installation problems:**\n  - Use the install script: `./install_emulators.sh`\n  - Check error messages for missing dependencies\n\n- **Platform-specific issues:**\n  - For macOS: See [MAC_COMPATIBILITY.md](MAC_COMPATIBILITY.md)\n  - For Windows WSL: See [WSL_COMPATIBILITY.md](WSL_COMPATIBILITY.md)\n\n## Project Structure\n\n- `emuvlm/` - Main package\n  - `emulators/` - Emulator integrations\n  - `model/` - AI model code\n  - `cli.py` - Command-line interface\n  - `config.yaml` - Default configuration\n\n## Contributing\n\nContributions welcome! Please feel free to submit a Pull Request.\n\n1. Fork the repository\n2. Create your feature branch: `git checkout -b feature/amazing-feature`\n3. Commit your changes: `git commit -m 'Add some amazing feature'`\n4. Push to the branch: `git push origin feature/amazing-feature`\n5. Open a Pull Request\n\nPlease make sure to update tests as appropriate.\n\n## License\n\nThis project is licensed under the MIT License - see the [LICENSE](LICENSE) file for details.\n\n## Acknowledgments\n\n- [PyBoy](https://github.com/Baekalfen/PyBoy), [mGBA](https://mgba.io/), and other emulator projects\n- [LLaVA](https://github.com/haotian-liu/LLaVA), [Qwen](https://github.com/QwenLM/Qwen-VL), and [MiniCPM](https://github.com/OpenBMB/MiniCPM) model creators\n- [llama.cpp](https://github.com/ggerganov/llama.cpp) for local model inference\n\nFor more details on implementation, see [PLAN.md](PLAN.md).\nFor platform-specific compatibility details, see:\n- [MAC_COMPATIBILITY.md](MAC_COMPATIBILITY.md) for macOS\n- [WSL_COMPATIBILITY.md](WSL_COMPATIBILITY.md) for Windows WSL","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericflo%2Femuvlm","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fericflo%2Femuvlm","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fericflo%2Femuvlm/lists"}