Skip to main content

Plugin Development

Plugins extend BeatBax with additional sound chip backends, export targets, and integration points. Start here when a feature should be usable across the CLI, web app, and desktop app instead of living in one UI.

Common Plugin Areas​

  • Sound chip backends — e.g. @beatbax/plugin-chip-sms, @beatbax/plugin-chip-spectrum-128
  • Export targets — e.g. @beatbax/plugin-exporter-vgm, @beatbax/plugin-exporter-arkos, @beatbax/plugin-exporter-famitracker
  • Import sources — resolve shared instruments or song assets from new locations
  • Tool integrations — expose engine functionality to external workflows

Registration​

Register chip plugins and exporter plugins explicitly with the engine/host registries. Chip plugins may declare related exporters via exporterPlugins, or the host/CLI may import and register exporter packages at startup. Do not rely on async chip-exporter auto-resolution.

Exporters should prefer payload-first returns (ExportPayload / bytes / string) when outputPath is omitted so desktop and browser hosts can download results.

Optional chip hooks: configureForSong(ChipSongContext), validateSong(), getMeterDisplayGain(), preloadForPCM(insts, options?), wizard metadata (NewSongWizardMetadata, status).

Implement preloadForPCM when the chip loads samples asynchronously (for example NES DMC). Load failures should not throw: report each one through the optional options.onWarn({ component, message }) callback (types ChipPreloadOptions and ChipWarning), and fall back to console.warn when no callback is passed. The engine Player exposes the same warnings as player.onWarn, and Desktop shows them in the Output panel.

Development Flow​

npm run engine:build
npm run cli:build
npm test

For new chip support, validate both rendered audio behavior and exporter behavior where applicable. For new export targets, include small .bax fixtures that cover timing, instruments, metadata, and edge cases.

Useful upstream guides:

Chip instrumentEditor schemas may set per-type preview behaviour for Desktop: melodic piano octave, oneshot Trigger (noise/DMC), or Game Boy noise uge_note strip. Hosts also treat Spectrum/AY tone_mix=true as oneshot preview. See Instrument Editor.