Back to Details

pokemon-player

Compare original and translation side by side

🇺🇸

Original

English
🇨🇳

Translation

Chinese

Pokemon Player

Pokemon游玩助手

Play Pokemon games via headless emulation using the 
pokemon-agent
package.
使用
pokemon-agent
包通过无头模拟来玩Pokemon游戏。

When to Use

适用场景

  • User says "play pokemon", "start pokemon", "pokemon game"
  • User asks about Pokemon Red, Blue, Yellow, FireRed, etc.
  • User wants to watch an AI play Pokemon
  • User references a ROM file (.gb, .gbc, .gba)
  • 用户说“玩pokemon”、“启动pokemon”、“pokemon游戏”
  • 用户询问Pokemon红、蓝、黄、火红等版本
  • 用户想要观看AI玩Pokemon
  • 用户提到ROM文件（.gb、.gbc、.gba格式）

Startup Procedure

启动流程

1. First-time setup (clone, venv, install)

1. 首次设置（克隆仓库、创建虚拟环境、安装依赖）

The repo is NousResearch/pokemon-agent on GitHub. Clone it, then set up a Python 3.10+ virtual environment. Use uv (preferred for speed) to create the venv and install the package in editable mode with the pyboy extra. If uv is not available, fall back to python3 -m venv + pip.
On this machine it is already set up at /home/teknium/pokemon-agent with a venv ready — just cd there and source .venv/bin/activate.
You also need a ROM file. Ask the user for theirs. On this machine one exists at roms/pokemon_red.gb inside that directory. NEVER download or provide ROM files — always ask the user.
仓库为GitHub上的NousResearch/pokemon-agent。克隆后，设置Python 3.10+的虚拟环境。优先使用uv（速度更快）创建虚拟环境，并以可编辑模式安装包含pyboy扩展的包。如果没有uv，退而求其次使用python3 -m venv + pip。
本机已在/home/teknium/pokemon-agent路径下完成设置，虚拟环境已准备就绪——只需进入该目录并执行source .venv/bin/activate激活。
你还需要一个ROM文件。请向用户索要。本机在该目录的roms/pokemon_red.gb路径下有一个ROM文件。 绝对不要下载或提供ROM文件——务必向用户索要。

2. Start the game server

2. 启动游戏服务器

From inside the pokemon-agent directory with the venv activated, run pokemon-agent serve with --rom pointing to the ROM and --port 9876. Run it in the background with &. To resume from a saved game, add --load-state with the save name. Wait 4 seconds for startup, then verify with GET /health.
进入pokemon-agent目录并激活虚拟环境后，运行pokemon-agent serve命令，通过--rom指定ROM路径，--port设为9876。使用&让其在后台运行。 如需从存档恢复游戏，添加--load-state参数并指定存档名称。 等待4秒启动完成，然后通过GET /health接口验证状态。

3. Set up live dashboard for user to watch

3. 为用户设置实时仪表盘以便观看

Use an SSH reverse tunnel via localhost.run so the user can view the dashboard in their browser. Connect with ssh, forwarding local port 9876 to remote port 80 on nokey@localhost.run. Redirect output to a log file, wait 10 seconds, then grep the log for the .lhr.life URL. Give the user the URL with /dashboard/ appended. The tunnel URL changes each time — give the user the new one if restarted.
通过localhost.run建立SSH反向隧道，让用户可在浏览器中查看仪表盘。执行ssh命令，将本地9876端口转发至nokey@localhost.run的远程80端口。将输出重定向至日志文件，等待10秒后，从日志中提取.lhr.life格式的URL。向用户提供该URL并加上/dashboard/后缀。 隧道URL每次重启都会变化——若重启需向用户提供新的URL。

Save and Load

存档与读档

When to save

存档时机

  • Every 15-20 turns of gameplay
  • ALWAYS before gym battles, rival encounters, or risky fights
  • Before entering a new town or dungeon
  • Before any action you are unsure about
  • 每进行15-20回合游戏后
  • 务必在道馆战、劲敌对战或高风险战斗前
  • 进入新城镇或地牢前
  • 执行不确定的操作前

How to save

存档方法

POST /save with a descriptive name. Good examples: before_brock, route1_start, mt_moon_entrance, got_cut
发送POST /save请求并附上描述性名称。示例：before_brock、route1_start、mt_moon_entrance、got_cut

How to load

读档方法

POST /load with the save name.
发送POST /load请求并指定存档名称。

List available saves

查看可用存档

GET /saves returns all saved states.
发送GET /saves请求可返回所有存档状态。

Loading on server startup

服务器启动时读档

Use --load-state flag when starting the server to auto-load a save. This is faster than loading via the API after startup.
启动服务器时使用--load-state参数可自动加载存档，这比启动后通过API加载更快。

The Gameplay Loop

游戏循环

Step 1: OBSERVE — check state AND take a screenshot

步骤1：观察——检查状态并截图

GET /state for position, HP, battle, dialog. GET /screenshot and save to /tmp/pokemon.png, then use vision_analyze. Always do BOTH — RAM state gives numbers, vision gives spatial awareness.
发送GET /state获取位置、HP、战斗、对话信息。 发送GET /screenshot并保存至/tmp/pokemon.png，然后使用vision_analyze分析。 务必同时执行这两项操作——RAM状态提供数值信息，视觉分析提供空间感知。

Step 2: ORIENT

步骤2：定位

  • Dialog/text on screen → advance it
  • In battle → fight or run
  • Party hurt → head to Pokemon Center
  • Near objective → navigate carefully
  • 屏幕显示对话/文本 → 推进对话
  • 处于战斗中 → 战斗或逃跑
  • 队伍受伤 → 前往宝可梦中心
  • 接近目标 → 谨慎导航

Step 3: DECIDE

步骤3：决策

Priority: dialog > battle > heal > story objective > training > explore
优先级：对话 > 战斗 > 回血 > 剧情目标 > 练级 > 探索

Step 4: ACT — move 2-4 steps max, then re-check

步骤4：行动——最多移动2-4步，然后重新检查

POST /action with a SHORT action list (2-4 actions, not 10-15).
发送POST /action请求，附带简短的操作列表（2-4个动作，而非10-15个）。

Step 5: VERIFY — screenshot after every move sequence

步骤5：验证——每次移动序列后截图

Take a screenshot and use vision_analyze to confirm you moved where intended. This is the MOST IMPORTANT step. Without vision you WILL get lost.
截图并使用vision_analyze确认移动到了预期位置。这是最重要的步骤，没有视觉分析你肯定会迷路。

Step 6: RECORD progress to memory with PKM: prefix

步骤6：以PKM:为前缀记录进度至内存

Step 7: SAVE periodically

步骤7：定期存档

Action Reference

操作参考

  • press_a — confirm, talk, select
  • press_b — cancel, close menu
  • press_start — open game menu
  • walk_up/down/left/right — move one tile
  • hold_b_N — hold B for N frames (use for speeding through text)
  • wait_60 — wait about 1 second (60 frames)
  • a_until_dialog_end — press A repeatedly until dialog clears
  • press_a — 确认、对话、选择
  • press_b — 取消、关闭菜单
  • press_start — 打开游戏菜单
  • walk_up/down/left/right — 移动一格
  • hold_b_N — 按住B键N帧（用于快速跳过文本）
  • wait_60 — 等待约1秒（60帧）
  • a_until_dialog_end — 重复按A键直到对话结束

Critical Tips from Experience

经验总结的关键技巧

USE VISION CONSTANTLY

持续使用视觉分析

  • Take a screenshot every 2-4 movement steps
  • The RAM state tells you position and HP but NOT what is around you
  • Ledges, fences, signs, building doors, NPCs — only visible via screenshot
  • Ask the vision model specific questions: "what is one tile north of me?"
  • When stuck, always screenshot before trying random directions
  • 每移动2-4步就截图一次
  • RAM状态仅能告知你位置和HP，无法显示周围环境
  • 悬崖、栅栏、标识、建筑门、NPC——只有通过截图才能看到
  • 向视觉模型提出具体问题：“我北边一格是什么？”
  • 卡关时，尝试随机方向前务必先截图

Warp Transitions Need Extra Wait Time

地图切换需额外等待时间

When walking through a door or stairs, the screen fades to black during the map transition. You MUST wait for it to complete. Add 2-3 wait_60 actions after any door/stair warp. Without waiting, the position reads as stale and you will think you are still in the old map.
穿过门或楼梯时，屏幕会黑屏进行地图切换。必须等待切换完成，在门/楼梯切换后添加2-3个wait_60动作。若不等待，位置信息会显示为旧数据，你会误以为仍在原地图。

Building Exit Trap

建筑出口陷阱

When you exit a building, you appear directly IN FRONT of the door. If you walk north, you go right back inside. ALWAYS sidestep first by walking left or right 2 tiles, then proceed in your intended direction.
离开建筑时，你会直接出现在门前。如果向北走，会直接回到建筑内。务必先向左右移动2格，再朝目标方向前进。

Dialog Handling

对话处理

Gen 1 text scrolls slowly letter-by-letter. To speed through dialog, hold B for 120 frames then press A. Repeat as needed. Holding B makes text display at max speed. Then press A to advance to the next line. The a_until_dialog_end action checks the RAM dialog flag, but this flag does not catch ALL text states. If dialog seems stuck, use the manual hold_b + press_a pattern instead and verify via screenshot.
初代文本逐字滚动速度缓慢。要快速跳过对话，按住B键120帧后按A键，重复此操作即可。按住B键可让文本以最快速度显示，然后按A键进入下一行。 a_until_dialog_end动作会检查RAM中的对话标记，但该标记无法覆盖所有文本状态。若对话看似卡住，改用手动的hold_b + press_a组合操作，并通过截图验证。

Ledges Are One-Way

悬崖是单向的

Ledges (small cliff edges) can only be jumped DOWN (south), never climbed UP (north). If blocked by a ledge going north, you must go left or right to find the gap around it. Use vision to identify which direction the gap is. Ask the vision model explicitly.
悬崖（小峭壁）只能向下跳（向南），无法向上爬（向北）。若向北被悬崖阻挡，需向左或向右绕行寻找缺口。使用视觉分析确定缺口方向，明确询问视觉模型。

Navigation Strategy

导航策略

  • Move 2-4 steps at a time, then screenshot to check position
  • When entering a new area, screenshot immediately to orient
  • Ask the vision model "which direction to [destination]?"
  • If stuck for 3+ attempts, screenshot and re-evaluate completely
  • Do not spam 10-15 movements — you will overshoot or get stuck
  • 每次移动2-4步，然后截图确认位置
  • 进入新区域后立即截图定位
  • 向视觉模型询问“前往[目的地]该走哪个方向？”
  • 若尝试3次以上仍卡关，截图并重整思路
  • 不要连续发送10-15个移动指令——你会走过头或卡关

Running from Wild Battles

野生战斗逃跑

On the battle menu, RUN is bottom-right. To reach it from the default cursor position (FIGHT, top-left): press down then right to move cursor to RUN, then press A. Wrap with hold_b to speed through text/animations.
战斗菜单中，“逃跑”选项在右下角。从默认光标位置（“战斗”，左上角）出发：按向下键再按右键将光标移至“逃跑”，然后按A键。搭配hold_b操作可快速跳过文本/动画。

Battling (FIGHT)

战斗（攻击）

On the battle menu FIGHT is top-left (default cursor position). Press A to enter move selection, A again to use the first move. Then hold B to speed through attack animations and text.
战斗菜单中“攻击”选项在左上角（默认光标位置）。按A键进入技能选择，再按A键使用第一个技能。然后按住B键快速跳过攻击动画和文本。

Battle Strategy

战斗策略

Decision Tree

决策树

  1. Want to catch? → Weaken then throw Poke Ball
  2. Wild you don't need? → RUN
  3. Type advantage? → Use super-effective move
  4. No advantage? → Use strongest STAB move
  5. Low HP? → Switch or use Potion
  1. 想要捕获？ → 削弱后扔精灵球
  2. 不需要的野生宝可梦？ → 逃跑
  3. 属性克制？ → 使用克制技能
  4. 无属性优势？ → 使用最强本系技能
  5. HP过低？ → 换宠或使用药水

Gen 1 Type Chart (key matchups)

初代属性表（关键克制关系）

  • Water beats Fire, Ground, Rock
  • Fire beats Grass, Bug, Ice
  • Grass beats Water, Ground, Rock
  • Electric beats Water, Flying
  • Ground beats Fire, Electric, Rock, Poison
  • Psychic beats Fighting, Poison (dominant in Gen 1!)
  • 水克制火、地面、岩石
  • 火克制草、虫、冰
  • 草克制水、地面、岩石
  • 电克制水、飞行
  • 地面克制火、电、岩石、毒
  • 超能力克制格斗、毒（初代超能力系极强！）

Gen 1 Quirks

初代特性

  • Special stat = both offense AND defense for special moves
  • Psychic type is overpowered (Ghost moves bugged)
  • Critical hits based on Speed stat
  • Wrap/Bind prevent opponent from acting
  • Focus Energy bug: REDUCES crit rate instead of raising it
  • 特攻属性同时影响特殊技能的进攻和防御
  • 超能力系过于强势（幽灵系技能存在bug）
  • 暴击率基于速度属性
  • 缠绕/束缚技能可阻止对手行动
  • 聚气技能bug：反而降低暴击率

Memory Conventions

内存记录规范

PrefixPurposeExample
PKM:OBJECTIVECurrent goalGet Parcel from Viridian Mart
PKM:MAPNavigation knowledgeViridian: mart is northeast
PKM:STRATEGYBattle/team plansNeed Grass type before Misty
PKM:PROGRESSMilestone trackerBeat rival, heading to Viridian
PKM:STUCKStuck situationsLedge at y=28 go right to bypass
PKM:TEAMTeam notesSquirtle Lv6, Tackle + Tail Whip
前缀用途示例
PKM:OBJECTIVE当前目标从常青市商店领取包裹
PKM:MAP导航知识常青市：商店在东北方向
PKM:STRATEGY战斗/队伍规划挑战小霞前需要草系宝可梦
PKM:PROGRESS进度追踪击败劲敌，前往常青市
PKM:STUCK卡关情况y=28处的悬崖，需向右绕行
PKM:TEAM队伍记录杰尼龟6级，技能：撞击+摇尾巴

Progression Milestones

进度里程碑

  • Choose starter
  • Deliver Parcel from Viridian Mart, receive Pokedex
  • Boulder Badge — Brock (Rock) → use Water/Grass
  • Cascade Badge — Misty (Water) → use Grass/Electric
  • Thunder Badge — Lt. Surge (Electric) → use Ground
  • Rainbow Badge — Erika (Grass) → use Fire/Ice/Flying
  • Soul Badge — Koga (Poison) → use Ground/Psychic
  • Marsh Badge — Sabrina (Psychic) → hardest gym
  • Volcano Badge — Blaine (Fire) → use Water/Ground
  • Earth Badge — Giovanni (Ground) → use Water/Grass/Ice
  • Elite Four → Champion!
  • 选择初始宝可梦
  • 从常青市商店交付包裹，获得宝可梦图鉴
  • 岩石徽章——小刚（岩石系）→ 使用水系/草系宝可梦
  • 水系徽章——小霞（水系）→ 使用草系/电系宝可梦
  • 雷电徽章——马志士（电系）→ 使用地面系宝可梦
  • 彩虹徽章——莉佳（草系）→ 使用火系/冰系/飞行系宝可梦
  • 灵魂徽章——阿桔（毒系）→ 使用地面系/超能力系宝可梦
  • 沼泽徽章——娜姿（超能力系）→ 最难的道馆
  • 火山徽章——夏伯（火系）→ 使用水系/地面系宝可梦
  • 大地徽章——坂木（地面系）→ 使用水系/草系/冰系宝可梦
  • 四天王 → 冠军！

Stopping Play

停止游玩

  1. Save the game with a descriptive name via POST /save
  2. Update memory with PKM:PROGRESS
  3. Tell user: "Game saved as [name]! Say 'play pokemon' to resume."
  4. Kill the server and tunnel background processes
  1. 通过POST /save请求保存游戏，使用描述性名称
  2. 以PKM:PROGRESS为前缀更新内存记录
  3. 告知用户：“游戏已保存为[名称]！说‘play pokemon’即可继续。”
  4. 终止服务器和隧道的后台进程

Pitfalls

注意事项

  • NEVER download or provide ROM files
  • Do NOT send more than 4-5 actions without checking vision
  • Always sidestep after exiting buildings before going north
  • Always add wait_60 x2-3 after door/stair warps
  • Dialog detection via RAM is unreliable — verify with screenshots
  • Save BEFORE risky encounters
  • The tunnel URL changes each time you restart it
  • 绝对不要下载或提供ROM文件
  • 未进行视觉检查前，不要发送超过4-5个动作指令
  • 离开建筑后务必先向左右移动，再向北前进
  • 穿过门/楼梯后务必添加2-3个wait_60动作
  • 通过RAM检测对话不可靠——需用截图验证
  • 高风险对战前务必存档
  • 每次重启隧道，URL都会变化