How kotlinds/ai-plays-pokemon works
ai-plays-pokemon is a live Pokémon HeartGold-playing application: a person selects a backend and mode, then either the built-in player or an external MCP agent observes game state and acts through the emulator. Its main stages are emulator-backed state/action handling, agent memory and orchestration, and decision backends; the UI also exposes configuration and run results. README-documented capabilities include Jev, Koog LLMs, Claude Code, MCP tools, and Pure/Assisted/Hybrid modes. Some subsystem links rely on README descriptions because their implementation was not sampled.
Main entry points: AppController.kt App controller · GameMcpServer.kt MCP game server · ConsoleHost.kt Console host · PokemonPlayer.kt Autonomous player
Components 25
App and control
- Application entry
src/main/kotlin/me/nathanfallet/aiplayspokemon/Main.kt - Desktop UI
src/main/kotlin/me/nathanfallet/aiplayspokemon/ui/App.kt - Control panel
src/main/kotlin/me/nathanfallet/aiplayspokemon/ui/ControlPanel.kt - App controller
src/main/kotlin/me/nathanfallet/aiplayspokemon/ui/AppController.kt - App configuration
src/main/kotlin/me/nathanfallet/aiplayspokemon/config/AppConfig.kt
Agent gameplay
- Player settings
src/main/kotlin/me/nathanfallet/aiplayspokemon/agent/PlayerSettings.kt - Autonomous player
src/main/kotlin/me/nathanfallet/aiplayspokemon/agent/PokemonPlayer.kt - Agent session
src/main/kotlin/me/nathanfallet/aiplayspokemon/agent/AgentSession.kt - Game state and actions
src/main/kotlin/me/nathanfallet/aiplayspokemon/agent/GameSession.kt - Agent memory
src/main/kotlin/me/nathanfallet/aiplayspokemon/agent/AgentMemory.kt - Run statistics
src/main/kotlin/me/nathanfallet/aiplayspokemon/agent/RunStats.kt
Decision backends
- Decision interface
src/main/kotlin/me/nathanfallet/aiplayspokemon/decision/DecisionModel.kt - Jev decision model
src/main/kotlin/me/nathanfallet/aiplayspokemon/decision/jev/JevDecisionModel.kt - Jev API client
src/main/kotlin/me/nathanfallet/aiplayspokemon/decision/jev/JevClient.kt - Koog LLM model
src/main/kotlin/me/nathanfallet/aiplayspokemon/decision/llm/LlmDecisionModel.kt - LLM providers
src/main/kotlin/me/nathanfallet/aiplayspokemon/decision/llm/LlmProvider.kt - Claude Code model
src/main/kotlin/me/nathanfallet/aiplayspokemon/decision/claudecode/ClaudeCodeDecisionModel.kt
Emulation
- Console host
src/main/kotlin/me/nathanfallet/aiplayspokemon/emulator/ConsoleHost.kt - Emulator adapter
src/main/kotlin/me/nathanfallet/aiplayspokemon/emulator/Emulator.kt - Emulator display
src/main/kotlin/me/nathanfallet/aiplayspokemon/ui/EmulatorScreen.kt
External agents
- MCP game server
src/main/kotlin/me/nathanfallet/aiplayspokemon/mcp/GameMcpServer.kt - Delivery tracking
src/main/kotlin/me/nathanfallet/aiplayspokemon/mcp/DeliveryTracker.kt
Other components
- Person
- External MCP agent
- Model service
Connections 30
- Person → Desktop UI: controls
README.md - Application entry → Desktop UI: starts
src/main/kotlin/me/nathanfallet/aiplayspokemon/Main.kt - Desktop UI → Control panel: renders
src/main/kotlin/me/nathanfallet/aiplayspokemon/ui/App.kt - Desktop UI → Emulator display: renders
src/main/kotlin/me/nathanfallet/aiplayspokemon/ui/App.kt - Control panel → App controller: configures
src/main/kotlin/me/nathanfallet/aiplayspokemon/ui/ControlPanel.kt - App controller → App configuration: reads and saves
src/main/kotlin/me/nathanfallet/aiplayspokemon/ui/AppController.kt - App controller → Player settings: sets
src/main/kotlin/me/nathanfallet/aiplayspokemon/ui/AppController.kt - App controller → Console host: controls
src/main/kotlin/me/nathanfallet/aiplayspokemon/ui/AppController.kt - App controller → Autonomous player: creates
src/main/kotlin/me/nathanfallet/aiplayspokemon/ui/AppController.kt - App controller → MCP game server: starts
src/main/kotlin/me/nathanfallet/aiplayspokemon/ui/AppController.kt - Autonomous player → Agent session: runs
src/main/kotlin/me/nathanfallet/aiplayspokemon/agent/PokemonPlayer.kt - Autonomous player → Decision interface: requests choices
src/main/kotlin/me/nathanfallet/aiplayspokemon/agent/PokemonPlayer.kt - Autonomous player → Run statistics: records runs
src/main/kotlin/me/nathanfallet/aiplayspokemon/agent/PokemonPlayer.kt - Agent session → Game state and actions: delegates state and actions
src/main/kotlin/me/nathanfallet/aiplayspokemon/agent/AgentSession.kt - Agent session → Agent memory: uses
src/main/kotlin/me/nathanfallet/aiplayspokemon/agent/AgentSession.kt - Game state and actions → Console host: observes console
src/main/kotlin/me/nathanfallet/aiplayspokemon/agent/GameSession.kt - Decision interface → Jev decision model: implemented by
src/main/kotlin/me/nathanfallet/aiplayspokemon/decision/jev/JevDecisionModel.kt - Decision interface → Koog LLM model: implemented by
src/main/kotlin/me/nathanfallet/aiplayspokemon/decision/llm/LlmDecisionModel.kt - Decision interface → Claude Code model: implemented by
src/main/kotlin/me/nathanfallet/aiplayspokemon/decision/claudecode/ClaudeCodeDecisionModel.kt - Jev decision model → Jev API client: sends requests
src/main/kotlin/me/nathanfallet/aiplayspokemon/decision/jev/JevDecisionModel.kt - Jev API client → Model service: calls Jev API
README.md - Koog LLM model → LLM providers: uses
src/main/kotlin/me/nathanfallet/aiplayspokemon/decision/llm/LlmDecisionModel.kt - LLM providers → Model service: calls model service
README.md - Claude Code model → Model service: invokes CLI
README.md - Console host → Emulator adapter: wraps
src/main/kotlin/me/nathanfallet/aiplayspokemon/emulator/ConsoleHost.kt - Console host → Emulator display: supplies display
README.md - External MCP agent → MCP game server: calls tools
README.md - MCP game server → Game state and actions: reads and acts
src/main/kotlin/me/nathanfallet/aiplayspokemon/mcp/GameMcpServer.kt - MCP game server → Console host: accesses emulator
src/main/kotlin/me/nathanfallet/aiplayspokemon/mcp/GameMcpServer.kt - MCP game server → Delivery tracking: tracks delivery
src/main/kotlin/me/nathanfallet/aiplayspokemon/mcp/GameMcpServer.kt