[{"data":1,"prerenderedAt":-1},["ShallowReactive",2],{"project-96054":3},{"id":4,"name":5,"fullName":6,"owner":7,"repo":5,"description":8,"homepage":9,"htmlUrl":9,"language":10,"languages":9,"totalLinesOfCode":9,"stars":11,"forks":12,"watchers":13,"openIssues":14,"contributorsCount":14,"subscribersCount":14,"size":14,"stars1d":14,"stars7d":14,"stars30d":15,"stars90d":14,"forks30d":14,"starsTrendScore":14,"compositeScore":16,"rankGlobal":9,"rankLanguage":9,"license":17,"archived":18,"fork":18,"defaultBranch":19,"hasWiki":20,"hasPages":18,"topics":21,"createdAt":9,"pushedAt":9,"updatedAt":22,"readmeContent":23,"aiSummary":24,"trendingCount":14,"starSnapshotCount":14,"syncStatus":25,"lastSyncTime":26,"discoverSource":27},96054,"SuperAstra","ScottStevenson\u002FSuperAstra","ScottStevenson","Change SNES games with AI while you play them.",null,"Python",252,27,141,0,68,51.14,"MIT License",false,"main",true,[],"2026-09-20 04:01:32","# SUPERASTRA\n\n**Change the game.**\n\nA SNES-themed desktop companion that lets Astra investigate and alter a running\ngame through natural-language prompts. Built for BizHawk, with an RPG-style\ninterface and live memory tools.\n\n![SUPERASTRA desktop interface](docs\u002Fqa\u002Fdesktop.png)\n\nThe agent can inspect the actual game, find memory structures, write new memory\nroutines or cartridge patches, test the result, and keep what it learns for that\nexact cartridge version. The same investigation tools are available for an\nunrecognized game and a previously unseen request.\n\nThis **v0.3.2 prototype** has passed real Snes9x game-behavior tests and automated\nLua\u002Fprotocol checks. The Windows Lua bridge connection has also been confirmed manually.\nSee [validation notes](docs\u002FVALIDATION.md) for the scope of these checks.\n\n## Start playing\n\nYou need **Windows or Linux**, **Python 3.10 or newer with Tkinter**, a current\n[BizHawk release](https:\u002F\u002Fgithub.com\u002FTASEmulators\u002FBizHawk\u002Freleases), your ROM, and\nan OpenAI API key whose project can use `gpt-6-astra`.\n\n1. Extract this entire folder somewhere writable. Keep its files together.\n2. Double-click `Start-Windows.cmd`, or run `python3 run.py` on Linux.\n3. In BizHawk, open the ROM. Use its **BSNES** SNES core. Open\n   **Tools → Lua Console**, then open `LOAD-IN-BIZHAWK.lua` from this folder.\n4. Keep emulation running. The companion will show the cartridge name.\n5. Open **Settings**, enter your API key, and leave the model as\n   `gpt-6-astra`. Type what you want and click **Cast prompt**.\n\nThis runs alongside the desktop emulator. It is not an iPhone emulator extension\nand is not a hosted website. The app requires no Python packages beyond the\nstandard library. Linux distributions sometimes package Tkinter separately as\n`python3-tk`.\n\n### Does it work while I play?\n\nThat is the intended workflow. The companion reads the running game, and Lua\napplies changes between frames. Emulation continues while Astra thinks or\nresearches. A request is not instantaneous: it can require several API calls\nand observations. Generated ongoing effects execute locally each frame without\nan API call for each update.\n\nControlled experiments temporarily run an earlier checkpoint and return to the\nplayer's pre-experiment state. They can visibly interrupt play for up to 300\nemulated frames per trial. This prototype uses the same emulator for those\ntrials; it does not run a separate invisible emulator in the background.\n\nThe live engine behavior has been tested through Snes9x. Native BizHawk and a\nlive Astra request still require an end-to-end desktop test.\n\n## Prompts and unfamiliar games\n\nTry the original examples in Super Mario World:\n\n- “Drop a star.”\n- “Put 5 Chucks on the screen.”\n- “Make a new effect that gives me a cape whenever I collect a coin.”\n\nFor another game, ask directly for the alteration. Examples of investigation\nrequests include “Find my health and keep it full while I'm playing” or “Figure\nout how this game stores enemies so we can spawn another one.” These are requests\nfor Astra to investigate, not claims that those behaviors have been tested in\nevery game.\n\nThe agent receives:\n\n| Context | What it can do with it |\n| --- | --- |\n| Live screenshot | Identify characters, objects, menus and visible results |\n| Cartridge hash, headers and vectors | Identify the exact version and investigate its mapping |\n| Local cartridge index | Read or search actual code and data without uploading the whole ROM |\n| CPU registers and disassembly | Follow implementation details where the emulator core supports them |\n| WRAM reads and scans | Find values, object tables and state flags |\n| Hardware-domain reads | Inspect exposed VRAM, OAM, CGRAM, audio RAM and cartridge RAM |\n| Frame observations and controller probes | Compare values with what happens during play |\n| Named checkpoints and experiments | Test a hypothesis against the same starting state, capture results, then restore the player state |\n| CPU bus write watch | See which registers\u002Fcode are associated with a write, on supporting cores |\n| Persistent game notebook | Reuse a working plan, hypotheses, evidence, previous routines and automatically recorded tool results |\n| Optional web research | Find disassemblies and memory documentation, then check against the ROM |\n| Searchable source collection | Import full text\u002Fsource files using **Add context**, then retrieve relevant symbols and numbered lines |\n\nThe general path works without a recognized game profile. Astra can create a new\none-shot routine, an effect that runs each frame, or a guarded patch to code\u002Fdata\nin the loaded cartridge. The built-in Mario actions provide optional shortcuts.\n\n**“Any game, any prompt” describes the interface and investigation goal, not a\nguarantee of success.** The model still has to discover the right structures and\nverify its reasoning. An unfamiliar game can take multiple requests or need\nuser observations, source notes or additional reverse engineering. Some requests\nneed new assets, more cartridge space, a coprocessor debugger or a larger game\nengine rewrite. This version can edit existing loaded cartridge bytes; it cannot\nexpand the ROM, create an exportable ROM patch, synthesize new artwork, or debug\nevery special chip. Astra must identify a missing capability or unknown mechanic\nand report it honestly. No implementation can guarantee every imaginable prompt.\n\n### How an unfamiliar game gains context\n\n1. Read the screen, ROM identity\u002Fheader candidates, registers and available domains.\n2. Retrieve relevant saved knowledge, imported sources or primary web documentation.\n3. Build a working model of the required mechanics: game mode, state fields,\n   object lifecycle, initialization code and graphics dependencies as applicable.\n4. Create a checkpoint. Compare a control run with one changed input or candidate\n   alteration. Results include sampled values, WRAM differences and a branch screen.\n5. Apply a successful candidate to the live game, verify it, and retain evidence.\n\nTool evidence is recorded automatically; hypotheses are kept separate from\nverified findings. **Resume** resumes saved work, including after\nrestarting the companion. It refreshes live context and never automatically\nreplays an old mutation. The latest bounded tool transcript and a compact working\nplan are retained; older tool evidence is searchable. The default is 32 API steps\nper request, adjustable to 1–256 in settings or with `--steps`.\n\n**Add context** accepts multiple UTF-8 source\u002Ftext files, up to 8 MiB each,\n32 files and 32 MiB total per ROM. Astra searches them locally and requests\nrelevant excerpts. Lexical search uses keywords, addresses and symbols. It does\nnot upload an entire imported source collection automatically. **Game knowledge** displays the retained plan, recent evidence and available sources.\n\n## Undo and ongoing effects\n\nEach committed memory mutation gets a full emulator checkpoint. **Undo** restores\nthe entire game to just before the last mutation, including gameplay since that\nmoment, with the loaded-cartridge byte journal restored as well. Up to eight\nUndo states and four independent named experiment checkpoints are retained in memory.\n\n**Stop effects** removes active routines, memory freezes and loaded-cartridge\npatches. It leaves current WRAM values as they are. **Stop thinking** prevents the next AI tool\noperation; it does not undo previous actions. Undo and Stop effects can also be\nused while Astra is waiting for the API. An in-progress temporary experiment\nis restored when cancelled. External state\u002FROM loads supersede the experiment.\n\nOpening another ROM, loading a state externally, or restarting the Lua bridge\nclears effects and checkpoints. Undo can restore earlier routines and cartridge\npatches. Your original ROM file is never patched by this app. Cartridge changes\nare limited to 4096 bytes per operation and 64 KiB of distinct journaled offsets\nper bridge session; a core must expose writable ROM for these operations.\n\n## What gets created on your computer\n\n- `ipc\u002F`: the connection token, short-lived requests\u002Fresponses, the latest\n  screenshot and a local cartridge copy for indexing. Start the app before\n  loading the Lua script. Do not run two companion apps against the same folder.\n- `knowledge\u002F\u003CROM-SHA1>.json`: working context, findings, tool evidence, source\n  metadata and generated routines. Up to 1000 findings and 500 tool events are\n  retained, with bounded excerpts of large tool results.\n- `knowledge\u002F\u003CROM-SHA1>.investigation.json`: the latest bounded investigation\n  transcript and status, including encrypted API reasoning items for continuation.\n  Screenshots are omitted from the persisted transcript; a fresh one is requested.\n- `knowledge\u002Fsources\u002F\u003CROM-SHA1>\u002F`: locally indexed imported text. Retained context\n  is never executed merely because it exists. Astra decides what to reuse.\n- `profiles\u002F`: optional exact-hash field maps. No manual profile is needed to\n  use the general agent tools.\n\nAPI keys entered in settings are kept in memory, not written to these files. You\ncan instead set `OPENAI_API_KEY`; `OPENAI_MODEL` optionally overrides the model.\nPrompts, screenshots, requested memory\u002Fcode windows, notes and selected findings\nare sent to OpenAI. Full cartridge and RAM dumps are processed locally. Enabling\nweb research also lets Astra send game-related search queries. API usage is\nbilled to the configured OpenAI project; the app shows token counts after a turn.\n\n## Terminal use\n\nRun these from the extracted folder:\n\n```bash\npython run.py --doctor\npython run.py --status\npython run.py --prompt \"Drop a star\"\npython run.py --prompt \"Find the code that updates my health\" --no-web\npython run.py --prompt \"Continue\" --steps 64\n```\n\nThe explicit **Local Mario shortcuts** mode needs no API key. It understands a\nfew phrases, including the two original examples, and is useful for checking the\nemulator connection:\n\n```bash\npython run.py --local --prompt \"Drop a star\"\npython run.py --local --prompt \"Put 5 chucks on the screen\"\npython run.py --local --prompt \"Undo\"\n```\n\nThe supplied shortcuts accept the unmodified USA SMW SHA-1 and the exact Ice\nFlower build used for game testing. Other revisions still have the general agent\ntools. Vanilla sprite slots and level graphics limits still apply: a request for\nfive enemies needs five free slots, and Chucks may have missing or wrong tiles in\nlevels that do not load their graphics.\n\nWhen loaded-cartridge patches are active, the verified-layout Mario shortcuts\nare disabled; the general tools remain available to reassess the modified game.\n\n## Updating\n\nStop the Lua bridge and companion, then replace their source files together with\nthis version. Preserve your existing `knowledge\u002F` directory to keep discoveries;\nthe older notebook format is read automatically. Restart both components. Do not\nmix files from different releases. Checkpoints exist only in the emulator session.\n\n## If the connection does not respond\n\n- If the Lua Console says `Open LOAD-IN-BIZHAWK.lua by its full path`, replace\n  that launcher with the file from this release. Earlier versions incorrectly assumed\n  BizHawk would expose the script filename through Lua debug information.\n- Confirm the app and Lua script came from the same extracted folder.\n- Keep BizHawk unpaused, including its background emulation setting when the\n  companion window has focus.\n- Check the Lua Console error output. If WRAM is unavailable, select the BSNES\n  core and reopen the ROM and script.\n- After a crash, close the crashed companion and remove `ipc\u002Fclient.lock` if it\n  remains. Do not remove another running app's lock.\n- A timed-out mutation is never automatically repeated: it might have executed\n  before its acknowledgement was lost. Inspect the game or use Undo.\n- If Astra's API request is rejected, check the key's project, billing and access\n  to the configured model. There is no automatic substitution of another model.\n\n## Development\n\nSee [CONTRIBUTING.md](CONTRIBUTING.md) for development and release instructions,\n[architecture](docs\u002FARCHITECTURE.md) for extension points, and\n[validation](docs\u002FVALIDATION.md) for exactly what was tested.\n\nUnit\u002Fintegration tests require the optional Lua test runtime:\n\n```bash\npython -m pip install -r requirements-dev.txt\npython -m unittest discover -s tests -v\n```\n\nNo emulator binary or commercial ROM is included. The small `json.lua` dependency\nis included under its MIT license in `emulator\u002Fjson-LICENSE.txt`. This project's\noriginal source is MIT-licensed; see [LICENSE](LICENSE). The Spellbook logo is\na separate brand asset; see [asset credits](assets\u002FREADME.md).\n\n## Primary references\n\n- [BizHawk Lua API](https:\u002F\u002Ftasvideos.org\u002FBizhawk\u002FLuaFunctions)\n- [BizHawk source and releases](https:\u002F\u002Fgithub.com\u002FTASEmulators\u002FBizHawk)\n- [SMW Disassembly X](https:\u002F\u002Fgithub.com\u002FIsoFrieze\u002FSMWDisX)\n- [GPT-6 Astra model](https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fmodels\u002Fgpt-6-astra)\n- [Responses function calling](https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Ffunction-calling)\n- [Responses web search](https:\u002F\u002Fdevelopers.openai.com\u002Fapi\u002Fdocs\u002Fguides\u002Ftools-web-search)\n","SuperAstra 是一个面向 SNES 游戏的实时 AI 辅助修改工具，运行于 BizHawk 桌面模拟器环境，通过自然语言指令动态读取、分析并修改正在运行的游戏内存与行为。其核心功能包括自动识别游戏内存结构、生成并注入 Lua 补丁、执行可控实验性变更（如添加道具、修改角色能力），且支持跨会话记忆特定卡带版本的修改逻辑。技术上依赖 BizHawk 的 Lua API 和外部大模型（gpt-6-astra）协同推理，所有变更在本地帧间执行，无需持续调用 API。适用于 ROM 研究、游戏玩法实验、辅助开发测试及个性化游戏改造等场景。",2,"2026-09-09 02:30:05","CREATED_QUERY"]