How cicero225/llm_pokemon_scaffold works
Project type and purpose
• This is a specialized “agent harness” that lets large language models (LLMs) play Pokémon Red via a local Game Boy emulator (PyBoy).
• It wraps emulator control, memory‐reading, prompt construction, tool definitions, logging, and a multi‐stage LLM reasoning/navigation pipeline into one Python application.
File structure
• Top‐level:
• main.py – CLI entrypoint & orchestrator
• config.py – model & feature flags
• requirements.txt, LICENSE, README.md
• secret_api_keys.py (user‐supplied at runtime)
• ROM file (pokemon.gb) + save files (save.state, locations.pkl)
• agent/ directory (core modules):
• emulator.py – PyBoy wrapper, threads the emulator
• memory_reader.py – reads game state from emulator memory
• simple_agent.py – orchestrates the LLM loop: capture, prompt, call, parse, execute
• prompts.py – system & function‐calling templates (incl. meta-critique stage)
• tool_definitions.py – registers tools (map builder, pathfinder, checkpoint logger, navigator)
• utils.py – helper code (collision map management, token streams for Gemini, etc.)
Key README insights
• Multi‐stage reasoning: meta‐critique LLM, checkpoint logs
• Navigation aids: ASCII collision maps, automated pathfinder tool
• Separate emulator thread for continuous game ticking
• LLM interactions via openAI/Gemini/o3 endpoints – function calling paradigm