ModRetro Chromatic Plugin

View saved version →

---
name: chromatic-deployment
description: Find or set up a physical ModRetro Chromatic, capture its USB video feed, stream a live ROM demo to it, or flash a homebrew cartridge.
---

# ModRetro Chromatic deployment

The plugin bundles its vendor backend; no separate CLI is needed. Use the public
`device`, `device_capture`, `setup`, `play`, and `flash` tools. See the [device guide](../../docs/chromatic-device-testing.md)
for platform details and manual checks.

If the plugin itself needs preparation, use the [setup skill](../modretro-chromatic-setup/SKILL.md).
Device tools with an existing ROM need only the runtime component. The public
`setup` tool below handles hardware, not plugin dependencies.
For a tool error, follow [recover the failed step](../../docs/agent-guide.md#recover-the-failed-step):
missing project context, denied access, and an uncertain device action need different responses.

## Browser previews

Open every `web_preview` or `device_capture` URL, including screenshot Open links, only in **Codex's built-in browser**. If it is unavailable or blocked, retain the URL and report the concrete limitation. Never launch or fall back to an external browser.

Reuse the active preview URL or emulator/capture session for the same task. When temporary testing is complete, close only the session this task owns with `web_preview_close`, `emulator_close`, or `device_capture {"action":"close"}`. Preserve user play (including paused games), ongoing recordings, and unresolved saves or commands; inspect status and retain recovery evidence before closing. Never scan processes, kill by name, claim an unfamiliar port, or clean up another task's session. An unknown action is not safe to replay.

## Choose the device and ROM

`device {"command":"status"}` reports requirements without probing USB or proving
driver health. When discovery is in scope, use
`device {"command":"list_devices","requestId":"<unique discovery ID>"}` so a lost
reply can be recovered. Read the returned operation and select the intended `deviceToken`, never player 1
by default. Tokens identify the current enumeration, expire after five minutes,
and are consumed by accepted cartridge detection, live play, or flash. After one
of those actions settles, rediscover and reselect before another. Reconnection,
changed enumeration, or ambiguity also requires a fresh choice.

Players 1–8 are supported. Report discovery `diagnostics` even when another
device is selectable. `conflicts` contains duplicate player numbers without
tokens: have the user assign distinct numbers on the devices, reconnect them,
then discover again. `unmatched` preserves incomplete USB associations; check
the reported connection/access issue without claiming a driver diagnosis.

For live play or flash, use `rom_inspect` on the intended file within the
authorized project or workspace. Pass its exact path, `sizeBytes`, and SHA-256;
never substitute a different ROM, digest, or device. If no project or workspace
is authorized, follow [project selection](../../docs/agent-guide.md#start-and-select-the-intended-project).

## Prepare a first write on a new computer

Developer Mode activation is handled by the official [ModRetro Updater](https://support.modretro.com/en_us/articles/chromatic-firmware-updater-ryhoYnzCx),
not this plugin. For a known never-activated computer or an explicit
`feature.developer_mode_required` result, direct the user to that updater.
Do not request, accept, submit, store, or inspect activation codes through chat,
plugin tools, a plugin browser form, or a terminal. The plugin has no activation or
activation-status workflow. Code correction also belongs in the updater.

A new plugin installation, missing local record, or successful device discovery
does not establish whether activation is needed. A generic write failure does
not establish an invalid code, a seat limit, or a USB cause. Preserve the original
write result and any uncertain cartridge outcome; do not automatically retry it.

After the user completes the updater workflow, return to the plugin for fresh
device discovery, selection, and the normal flash confirmation. Reuse existing
explicit erase/write consent only when it covers this intended device and action.
Updater completion is not permission to write a cartridge and does not verify
that the game was installed. Build and emulator work can continue independently.

## Choose the requested action

- **Drivers:** `setup` with `command:"install_drivers"` uses the current session
  ID. Explain Linux's all-user udev access or Windows's elevated unsigned driver
  installer before acting; macOS reports `not_required` without launching one.
  See [driver setup](../../docs/chromatic-device-testing.md#driver-setup-depends-on-the-platform)
  for platform prerequisites.
- **Cartridge detection:** `setup` with `command:"detect_cartridge"` uses the
  selected token and may reconfigure the FPGA. Do not reset, activate, reinstall,
  or invoke a privileged shell as automatic recovery.
- **Live play:** `play` streams host-emulated video/audio without writing the
  cartridge. See [live-demo options](../../docs/chromatic-device-testing.md#stream-a-live-demo)
  for duration and saves; use the local emulator for automated input or profiling.
- **Physical video:** `device_capture {"action":"open"}` returns a local page.
  On macOS, open Connection settings with `open_settings`; the user explicitly
  enables capture and grants normal OS access. Tools cannot enable it silently.
  Linux x64/ARM64 uses Connect without an Enable or macOS permission step and is
  video-only. Windows device capture is unavailable; other supported device
  actions remain separate. The browser is display-only. Use `permission_status`
  and `list_devices` to inspect access and exact Chromatic choices, then connect
  that selection. Linux listing briefly opens matching nodes for capabilities
  without streaming. Optional macOS audio requires the same player’s USB input,
  never another camera or microphone. For “watch me play,” `start_recording` returns an accepted
  capture ID immediately: 3 minutes default, 10 minutes maximum. Poll `status` with
  that ID; the deadline stops the camera. Inspect fresh `live_frame` images during
  recording, save `screenshot` PNGs, and use `read_capture` for the last two frame
  IDs or completed video downloads/paths. `stop_recording` ends early; `close`
  releases the session. Partial/unknown outcomes are not duration success.
  Open the returned URL in Codex's built-in browser for the physical live view.
  Emulator buttons, stepping, memory and profiling do not control this feed.
  Screenshots return a real
  physical-feed image; videos stay download-only. Keep emulator images and
  host-to-device live demos distinct from this feed. Native labels do not prove
  which ROM is installed. Do not replay a timed-out command; inspect its status
  and preserve recovery downloads. See [physical capture](../../docs/chromatic-device-testing.md#capture-the-physical-device).
- **Flash:** Apply the eligibility and consent rules below. Tell the user the ROM
  path, size, digest, and device. For a flash-only request, report the original
  write result; label gameplay unverified unless it was observed and offer the
  [manual checks](../../docs/chromatic-device-testing.md#check-the-game-manually).
  If gameplay verification was also requested, continue with available evidence
  and ask only for missing observations the tools cannot make.

Set `confirm:true` only when the user has explicitly requested the specific setup,
live-play, or write action. Give each approved attempt a unique `requestId`.

## Check the ROM and get first-flash consent

Treat the exact ROM you compiled from game project source as homebrew; no extra
provenance check is needed unless it is a known third-party commercial game.
Refuse clearly third-party commercial games even if the user owns or modifies a
copy. A game the user or their team made is eligible even if sold. For other
supplied ROMs of unknown origin, try to boot the exact inspected file in the
[local emulator](../../docs/agent-guide.md#playtest-real-roms) and use any credible
evidence already available that identifies that file. If eligibility remains
unclear, do not flash; ask only for the missing evidence. See the [flash guide](../../docs/chromatic-device-testing.md#flash-the-exact-inspected-rom)
for evidence examples and refusal wording.

Before the first flash on a device, explain that it **will erase the selected
cartridge’s existing game data, saves may be lost, and no backup is made**. Get
explicit acknowledgement and permission to write; a bare flash request is not
enough. A request that already acknowledges the loss and approves this write
satisfies it. Use that consent for later user-requested writes on the same device
without asking again; a fresh discovery token alone does not reset it.
Ask only if consent is unavailable or narrower, or device identity has changed or
is uncertain.

## Use the reported recovery guidance

After the original operation settles, use its recognized failure and
`error.details.recovery` guidance. A successful cartridge detection can also
return `result.recovery` when its flash chip is explicitly unidentified.
Keep unknown causes unknown and preserve original command evidence.

`device.program_failed` alone does not identify an activation, USB, or cartridge
cause. Read the original `device` `operation_status` by its `operationId` and
inspect `error.message`, `error.details.vendorCode`, and any reported recovery.
For a copied preview error, use `operationId`: its displayed `requestId` is
preview-scoped, not the service request ID. Start with **Copy error** and the
public error summary. Optional `failureDetails` records only supported structured
evidence; an observed token does not establish a cause. If original diagnostics
are unavailable, report that limit once and keep the cause unknown. Raw command
evidence may contain sensitive text. A closed process still leaves
`cartridgeWrite: "outcome-unverified"`; do not retry automatically.

USB/HID failures call for the indicated platform access checks, not automatic
driver installation. Cartridge contact guidance does not establish that a
non-ModRetro cartridge is supported. Developer Mode errors direct the user to the
official ModRetro Updater. Unknown capacity stays unknown; do not request a code
or automatically retry the write. See the
[recovery guide](../../docs/chromatic-device-testing.md#use-the-original-failure-to-choose-recovery).

## Recover an interrupted action

Poll `device {"command":"operation_status","operationId":"<returned ID>"}` until
the original attempt settles. If a direct MCP discovery, setup, play, or flash
reply was lost, use its original caller-supplied `requestId` instead of
`operationId`. A preview's request ID is not interchangeable; use its copied
operation ID, or call `web_preview` action `install_status` with
`installationRequestId` set to the original preview UUID. A supplied ID never
falls back to the latest request; omission inspects the latest request and must
not substitute for original-attempt recovery. Match the returned request ID and
known generation before adopting its result. `requestedOperationUnknown: true`
leaves the original outcome unconfirmed. If exact public lookup is unavailable,
that same dialog's **Check status** sends its saved request ID. These reads
never retry an attempt or renew an expired device token. Activation and its
status are managed outside the plugin by the official ModRetro Updater.
Progress, cancellation, timeout, or a vendor `retryable` flag is not
proof of process closure or permission to repeat the action. Do not delete an
unresolved reservation, infer closure from a PID, or bypass it with a new request.
Preserve error causes, process-close evidence, captured output, and any unverified
hardware outcome. The journal survives server restarts but cannot supervise a
child after host termination. See [interruption and completion](../../docs/chromatic-device-testing.md#keep-interruption-and-completion-distinct).

## First-run recovery

Keep preview readiness and USB device readiness separate. A refused localhost
preview does not justify installing a driver. When device diagnostics actually
require Windows driver setup, explain the normal administrator prompt once,
use the existing `setup` driver action within the user's authorization, then
rediscover devices. Installer exit success alone is not a connection check.
Continue with fresh device selection and the existing write confirmation; never
replay an uncertain write. Missing activation goes to ModRetro Updater, never
to code collection.

Referenced files: 1

View saved version →

---
name: modretro-chromatic-authoring
description: Create or edit native game projects, scenes, events, and gameplay for Game Boy or Game Boy Color.
---

# ModRetro Chromatic authoring

Work in the creator's genuine `.gbsproj` / `.gbsres` project so the result stays editable in the game editor and builds to a real cartridge.

If the plugin needs setup or its tools cannot start, use the [setup skill](../modretro-chromatic-setup/SKILL.md) first. Creating or iterating a playable game needs `runtime,build`, including its browser preview. Use runtime alone only for source inspection or edits that do not require a build; add `emulator` for local stepped play. Carry necessary authorized setup through installation and callable tools, then return to the requested game. Do not stop at a passive doctor report or ask the user to install Node/npm manually.

## Browser previews

Open every `web_preview` or `device_capture` URL, including screenshot Open links, only in **Codex's built-in browser**. If it is unavailable or blocked, retain the URL and report the concrete limitation. Never launch or fall back to an external browser.

A missing, locked or unreachable browser does not block gameplay checks. Retain
its state and continue with public PyBoy `emulator_run`, `emulator_step` and
`emulator_observe` on the intended exact ROM. Follow the [headless fallback](../../docs/stepped-playtesting.md#when-browser-play-is-unavailable)
for setup, retained evidence and the separate browser/physical acceptance limits.

For new or iterated projects, use `web_preview` to show a successful playable
build early. Keep the appropriate owned preview tab visible and open while
working so the user can follow. Update it after meaningful successful builds
at a safe point: do not interrupt human play, saves or recordings, and resolve
unknown outcomes first. Do not arbitrarily reload or autoplay.

## Select the intended project

`session_status {}` reports the current selection without granting access. Confirm it is the project the user intends; if none is selected or a different one is active, use `project_select` with the intended absolute `.gbsproj` path before reading or editing project resources. To start a game, use `project_create` with an absolute unused destination under an existing canonical parent and `select:true` when continuing in it. `starter` is included. `wrecklight` creates an editable adventure copy; compact installations require its matching local `templateSourcePath`. Never edit the source template. Discovery grants no access and neither creation nor selection expands an existing authorization boundary. See [project selection](../../docs/agent-guide.md#start-and-select-the-intended-project) for configured workspaces and sibling projects, or the [Wrecklight remix guide](../../docs/wrecklight-remix.md) for that template.

## Author native resources

- Start with `project_inspect {}` and narrow `project_inventory` or focused scene/script reads to the part being changed. `scene_apply` uses the project `revision`; script edits use the exact target's `script_inspect.revision`, and `trigger_create` uses `scene_inspect.sceneRevision`. Restart after `STALE_CURSOR`. For concurrent editor changes or a destructive global reverse-reference decision, see [revisions and the world index](../../docs/agent-guide.md#inspect-efficiently-and-manage-revisions); the latter needs `project_refresh {"mode":"strong"}`.
- Prefer semantic tools such as `scene_apply`, `script_edit`, `script_transition`, and `collision_edit`. Preserve unknown fields, stable resource/event IDs, script branches, collision bytes, plugins, and format versions. If a tool cannot express the change, inspect neighboring resources and make the smallest compatible native edit. A distributed `scene_apply` has best-effort rollback, not cross-file atomicity.
- Use the project's actual `mono`, `mixed`, or `color` mode. Actor coordinates are normally gameplay tiles; scene `x`/`y` are editor-canvas positions. Keep assets inside the selected project, preserve authored PNGs/sidecars and the reserved UI palette, and keep generated outputs separate from authored resources and existing tracked cartridges.
- Preserve native `EVENT_TEXT` wording and page boundaries by default; request wrapping or pagination only when the user wants a rewrite. Guard `dialogue_update` with the same owner's `script_inspect.revision`; use `validation:"reject"` when overflow must block the write. Unknown custom events remain opaque. See [dialogue and resource examples](references/project-authoring.md#dialogue-representation).

For example, to make a door go to another room: find both scene IDs, inspect the trigger and destination collision, insert a typed `script_transition` using a valid landing tile, then build and directly check that entering and leaving the door works if gameplay verification is in scope.

## Choose the relevant detail

- [Native resource layout and tool examples](references/project-authoring.md): scenes, actors, events, variables, collision, palettes, settings, and focused edits.
- [Native tilemaps](../../docs/tilemaps.md): fixed-size rooms built from named 8 × 8 tiles. Capture exact existing patterns or deliberately fill; mutations need the current revision. Ordinary edits preserve protected cells; exclusive replacement operations require inspected preimages. Decoration must not infer or clear collisions.
- [Extensions and builds](references/extensions-and-build.md): custom events, scene modes, project-local plugins, official CLI and GBDK. Use existing visual events and scene modes when they express the mechanic; engine ejection needs authorization.
- [Packaged setup](../../docs/setup.md) and [Windows setup](../../docs/windows-setup.md): dependency details. `toolchain_doctor` metadata readiness is not executable health; the setup skill preserves the user's authorized scope.
- [Pixel art](../modretro-chromatic-pixel-art/SKILL.md) for image/palette work; [ROM debugging](../modretro-chromatic-rom-debugging/SKILL.md) and [stepped playtesting](../../docs/stepped-playtesting.md) for compilation, input-driven bugs, and real framebuffer evidence.

Verify the change at the level the request needs: reread the native resources, build the actual project when compilation matters, and inspect genuine emulator frames when behavior matters. A static preview or compiler probe does not show that the game was built or played; state any missing evidence.

Referenced files: 3

View saved version →

---
name: modretro-chromatic-pixel-art
description: Create, edit, or check native game sprites, backgrounds, tiles, and palettes. Use for Image Generation or native pixel work, tile budgets, and in-game readability.
---

# ModRetro Chromatic pixel art

Choose the workflow from the request and the existing artwork. Read the matching
reference; load other details when the task needs them.

If the plugin tools are unavailable, follow the [setup skill](../modretro-chromatic-setup/SKILL.md).
Native asset work needs the runtime; a compiler or emulator is needed only for
requested build or gameplay checks.

## Browser previews

Open every `web_preview` or `device_capture` URL, including screenshot Open links, only in **Codex's built-in browser**. If it is unavailable or blocked, retain the URL and report the concrete limitation. Never launch or fall back to an external browser.

## Choose a workflow

| Need | Route |
| --- | --- |
| **A new static sprite** | Start with the [two-step Image Generation workflow](references/prompting-recoverable-grids.md): generate a deliberately coarse design, then reconstruct it as whole filled grid cells. Use the requested or existing project size; otherwise start at 32 × 32. |
| **A background, tileset, or reusable room** | Use [native artwork and tile tools](references/native-pixel-tools.md#new-native-artwork), with [hardware and import guidance](references/hardware-and-imports.md) for palette and tile budgets. Use [native tilemaps](../../docs/tilemaps.md) for rooms built from authored tiles. |
| **Exact pixel edits, manual art, palettes, or tile composition** | Use [native pixel authoring and plugin tools](references/native-pixel-tools.md). Author PNG/cel pixels directly; use the plugin for supported palette, tilemap, and sprite-metadata edits. Prefer this route when existing pixels must stay exact. |
| **Animation from an approved still** | Use [native animation guidance](references/prompting-grid-animation.md): optional generated motion reference, deliberately authored native frames, then timed review. Preserve the approved still and working motions. |
| **Editor files, existing raster art, or import/conversion** | Use [authoring and interchange](references/authoring-and-interchange.md). Preserve editable sources and check the available conversion/import tools. |

Honor a requested method. When the user is choosing, explain the relevant
tradeoff: Image Generation explores designs; native authoring provides exact
pixel control. A generated grid still requires cell and visual review.

## Work in the right context

Source-art exploration can stay in the workspace. Before changing a game,
select the intended `.gbsproj` and inspect the actual asset, style, and
compatibility mode. Follow the [project operating guide](../../docs/agent-guide.md#start-and-select-the-intended-project)
for selection and revision safeguards; keep original and editable artwork.

- For source colors, dimensions, import profiles, and budgets, read
  [hardware and imports](references/hardware-and-imports.md).
- For silhouette, genre, and scene readability, read
  [art direction](references/genre-art-direction.md).
- For recipe-backed rooms, protected cells, and exact collision edits, read
  [native tilemaps](../../docs/tilemaps.md).

Inspect the result at native size. Review animation in motion and keep user
feedback authoritative; passing pixel checks does not establish visual quality.
When integrating into a game, use [stepped playtesting](../../docs/stepped-playtesting.md)
for actual scene behavior. Distinguish source previews from verified gameplay.

Referenced files: 9

View saved version →

---
name: modretro-chromatic-rom-debugging
description: Build, inspect, and debug Game Boy or Game Boy Color ROMs. Use for native project or GBDK build failures, browser previews, direct emulator playtesting, and source or cartridge diagnostics.
---

# ModRetro Chromatic ROM debugging

Work from the user's actual cartridge and project. Select the intended project
explicitly; an unconfigured `project_select` needs its absolute `.gbsproj` path,
and `project_create` leaves it unselected unless called with `select:true`.
Never fall back to the bundled starter. See the [project selection rules](../../docs/agent-guide.md#start-and-select-the-intended-project)
when no authorized project or workspace is selected. If compiler or optional
PyBoy availability is uncertain, use `toolchain_doctor`; report unavailable
checks rather than substituting a sample ROM or silently installing a runtime.
Use authorized ROMs and output roots; preserve existing user saves and evidence.

If MCP cannot start or dependencies are missing, use the [setup skill](../modretro-chromatic-setup/SKILL.md).
Select build and/or emulator components for the requested checks; ROM inspection
alone needs only the runtime.

## Browser previews

Open every `web_preview` or `device_capture` URL, including screenshot Open links, only in **Codex's built-in browser**. If it is unavailable or blocked, retain the URL and report the concrete limitation. Never launch or fall back to an external browser.

If the browser is unavailable, locked or unreachable, retain its state and
continue gameplay with the public PyBoy loop below on the intended exact ROM;
browser access is not a prerequisite. Use the setup skill's `emulator` component
if needed. Keep browser UI/annotation and physical-device/capture checks
separate. See [headless fallback](../../docs/stepped-playtesting.md#when-browser-play-is-unavailable)
for retained evidence and scoped failures.

Reuse the active preview URL or emulator/capture session for the same task. When temporary testing is complete, close only the session this task owns with `web_preview_close`, `emulator_close`, or `device_capture {"action":"close"}`. Preserve user play (including paused games), ongoing recordings, and unresolved saves or commands; inspect status and retain recovery evidence before closing. Never scan processes, kill by name, claim an unfamiliar port, or clean up another task's session. An unknown action is not safe to replay.

### A preview URL refuses the connection

Preview URLs belong to the MCP process that opened them. A plugin update,
restart, or fresh chat can leave an old browser tab pointing at a closed server.
On every platform, including Windows, inspect `web_preview {"action":"status"}`
in the owning session before reusing a URL. A connection-refused page alone is
not evidence of browser policy, a missing emulator, or a device-driver problem.

If there is no live preview in the current session, select the user's original
project and call `web_preview {"action":"recover"}` to reopen its verified export without compiling. If no unchanged export exists, use `web_preview {}` to build and open it, then open the
newly returned URL. Do not invent the port, reuse a historical URL, or rebuild
with `force:true` just to reopen a server. Preserve any unresolved recording or
save from the old owner; opening a new preview does not recover unsaved state.
If a live listener is reported but the browser still fails, retain the exact
error and inspect the current owner; do not reset security settings or loop on
reload. An explicit access refusal must not be bypassed through another caller.

## Build and choose the right evidence

- Build the selected project with `rom_build` and inspect its returned cartridge
  with `rom_inspect`. Preserve compiler stderr and exit status on failures. A
  classified official-CLI `DEP0190` is a known deprecation; a failed process,
  missing/invalid ROM, or mismatched artifact is not a successful build. A GBDK
  `sourcePath` probe proves only its C source compiled.
- For direct model playtesting, use the optional PyBoy `emulator_*` tools. The
  model making the change should choose each bounded input, inspect the actual
  returned frames, and decide what to do next; the emulator stays paused between
  calls.
- For interactive human play or annotation, `web_preview {}` opens or reuses the
  selected project's official Binjgb browser export. [Browser playback](references/emulation-and-regression.md#official-browser-play),
  [saved progress](../../docs/agent-guide.md#saved-progress), and
  [frame annotation](../../docs/agent-guide.md#annotate-a-game-preview) cover
  those modes. A browser export, a native `rom_build`, PyBoy, and physical
  hardware each establish different facts. For physical Chromatic play or
  flashing, use [Chromatic deployment](../chromatic-deployment/SKILL.md).

## Direct play and regression checks

Example: hold right, add A for two frames, then release every button:

```text
emulator_run {"romPath":"<absolute ROM outputPath returned by the build>","restart":true,"initialFrames":120}
emulator_observe {}
emulator_step {"buttons":["right"],"frames":12,"sampleCount":4}
emulator_step {"buttons":["right","a"],"frames":2,"sampleCount":2}
emulator_step {"buttons":[],"frames":1,"sampleCount":1}
```

Every step supplies the **complete held-button set** and advances 1–3,600
frames. The set persists: repeated buttons stay held without a new press; `[]`
releases all buttons but still advances frames. `emulator_observe {}` is inert:
it reads the genuine 160 × 144 framebuffer without advancing frames, delivering
input, or changing a recording. Use short steps near uncertain timings and
consecutive samples for flicker; a sampled frame proves nothing about gaps.

If images fail, check `execution` separately from `imageDelivery`. The input may
have advanced even if no image arrived or transport left execution unknown. Do
not repeat it to recover evidence; use inert observation or `emulator_review`
of a retained interval. See [stepped playtesting](../../docs/stepped-playtesting.md)
for execution status, contact sheets, cancellation, and cleanup.

Preserve the first failure and its inputs. After a source fix, build the new
cartridge and repeat the relevant button sets and frame counts from comparable
starting conditions; inspect behavior separately from animation/hash changes.
An unchanged ROM reuses its session; use `restart:true` for an intentional fresh
boot and `emulator_close {}` before selecting another project. Enable
`recording:{}` on a fresh boot when the input history matters. For branching an
existing attempt, see [recordings and checkpoints](../../docs/recorded-playtesting.md):
first send a neutral frame, and restore only into the identical ROM and runtime,
including the worker hash. A checkpoint from before a rebuild cannot be used for
the regression run.

## Diagnose and report

For named variables, the current scene, or authored collision/event references,
build with `captureDebugArtifacts:true`, start that exact ROM with
`debugMode:"source"`, and call `emulator_debug` while paused. It requires
authenticated same-build artifacts and unchanged source; unsupported or
optimized-out data stays unavailable. For bounded OAM/VRAM/WRAM/HRAM inspection,
use `emulator_inspect`. See [hardware and source diagnostics](references/emulation-and-regression.md#bounded-hardware-and-source-diagnostics)
or [cartridge headers, hardware limits, and common failures](references/hardware-and-cartridge.md).

Distinguish authored source, typechecks or generated imagery, static dialogue or
art previews, a compiled native cartridge, and actual observed runtime frames.
Neither sampled images nor host-side throughput prove audio, saves, physical
hardware behavior, or cartridge CPU-cycle performance. Report what ran, what
the frames showed, and what remains unverified. For host-specific setup, see
[Windows setup](../../docs/windows-setup.md); Windows x64 is experimental and
other-platform results do not validate it.

Referenced files: 3

View saved version →

---
name: modretro-chromatic-setup
description: Prepare missing game compiler or emulator dependencies for an installed ModRetro Chromatic plugin, or diagnose tools that cannot start.
---

# Prepare game dependencies

Follow the shared [agent guide](../../docs/agent-guide.md).

Codex manages plugin installation and updates. A working plugin must not be
recreated, registered in another marketplace, or reinstalled to obtain a compiler.
Never edit installed manifests, MCP configuration, receipts or plugin-cache files.
Do not invoke Plugin Creator, register-personal-plugin, prepare-plugin-payload,
or `codex plugin add` during game dependency setup.

## Diagnose the failed step

Call `toolchain_doctor` when available. Authoring/device tools, compiler dependencies,
emulator dependencies, project selection and Developer Mode are separate.
For PROJECT_SELECTION_REQUIRED select the intended project; do not reinstall.
For missing compiler/emulator dependencies use the packaged commands below.
If MCP cannot start, report the concrete launcher error; do not manufacture a
replacement plugin. Codex must supply the initial Node executable.

## Install only missing dependencies

Prefer `toolchain_prepare {"components":["build"]}` for missing compiler tools,
or `["emulator"]` for local play, or both. It plans and prepares dependencies
without replacing the plugin. Show one concise progress update, then continue
the original build/preview after success. Inspect incomplete results before any
retry; a refusal is not permission to switch callers.

If this tool is unavailable, use the exact Node executable and setup command returned by `toolchain_doctor`.
The installed self-contained package retains its own runtime. Even legacy
`--components runtime,build` requests skip runtime replacement in this package.

- Build or preview a game: `--components build`.
- Play an existing ROM: `--components emulator`.
- Build and playtest: `--components build,emulator`.
- Add `desktop` only when the visual editor is requested.
- Source editing or flashing an existing ROM needs no compiler setup.

Run `node <installed-plugin>/scripts/setup.mjs plan --components build --json`,
then `apply --components build --yes --json`, then
`doctor --components build --probes cli-version,gbdk-version --json`.
Substitute the exact executable/path and requested components; quote paths with
spaces. On PowerShell prefix the quoted executable with `&`.
A request to build/play includes necessary dependency setup; do not create an
extra approval step. Preserve real access refusals and unresolved installer locks.

Use the same stable dependency root for all commands. By default this is
`~/Library/Application Support/modretro-chromatic` on macOS,
`%LOCALAPPDATA%/modretro-chromatic` on Windows, and
`${XDG_DATA_HOME:-~/.local/share}/modretro-chromatic` on Linux.
The launcher reads its `toolchain` subdirectory independently of plugin version.
An explicit GB_STUDIO_SETUP_ROOT selects another root; preserve configured roots.
Do not silently repoint or overwrite an independently configured toolchain.
Reuse setup-owned components; never take over an unowned nonempty directory.

After setup, continue the actual requested build in the same installed plugin.
Do not follow legacy docs into local-payload generation or marketplace registration.
Verify a real project build; metadata readiness alone is not completion.

## Device activation and playtesting

Activation is external: link to the official
[ModRetro Updater](https://support.modretro.com/en_us/articles/chromatic-firmware-updater-ryhoYnzCx).
Never collect activation codes or infer code validity from a generic write failure.
Use the deployment skill for installation confirmation and unknown-write recovery.

Use the built-in browser for previews unless the user explicitly selects another
browser. When browser play is unavailable, use the exact ROM with the supported
local emulator; see [stepped playtesting](../../docs/stepped-playtesting.md).