aminet-emulator

name	aminet-emulator
description	FS-UAE emulator configuration and launch: hardware profiles, ROM management, WHDLoad integration, config generation, and state snapshots. Use when configuring emulation, managing ROMs, or launching Amiga software.
metadata	{"extensions":{"gsd-skill-creator":{"triggers":{"intents":["aminet.*run|aminet.*launch","fs-uae|fsuae","emulat.*config","whdload","rom.*manage"],"files":["src/aminet/emulator-config.ts","src/aminet/hardware-profiles.ts","src/aminet/rom-manager.ts","src/aminet/whdload.ts","src/aminet/emulator-launch.ts","src/aminet/emulator-state.ts"],"contexts":["amiga emulation","emulator configuration","fs-uae setup"],"threshold":0.7},"token_budget":"1.0%","version":1,"enabled":true,"plan_origin":"242-aminet-integration","phase_origin":"242"}}}

Aminet Emulator

Purpose

Manages FS-UAE emulator configuration, hardware profiles, ROM provisioning, WHDLoad integration, launch orchestration, and emulator state snapshots. Enables launching Amiga software with the correct hardware configuration, Kickstart ROM, and WHDLoad settings derived from package metadata.

Capabilities

• FS-UAE config generation with buildFsUaeConfig/generateFsUaeConfig
• Path normalization and sorted key output for deterministic configs
• Boolean 1/0 serialization matching FS-UAE format
• 5 hardware profiles: A500, A1200, A1200+030, A4000, WHDLoad
• Embedded TS constants with deep-frozen structuredClone copies
• getProfile/getAllProfiles/getProfileForModel accessors
• ROM manager with CRC32 IEEE polynomial (no external deps)
• 12 known ROM entries with checksums (no ROM data distributed)
• scanRomDirectory with Cloanto XOR decryption and overdump handling
• selectRomForProfile with WHDLoad-to-A1200 fallback mapping
• DI-based crc32Fn for testability
• selectProfileFromReadme with priority-based matching (WHDLoad > 040 > 030 > AGA > 020 > OS3.x > A500 default)
• writeFsUaeConfig with recursive mkdir
• launchEmulator orchestrating config gen + write + execFile
• Structured error types: NO_HARD_DRIVES, INVALID_PROFILE, FSUAE_MISSING, LAUNCH_FAILED
• WHDLoad .Slave detection (case-insensitive recursive scan)
• WHDLOAD_KICKSTART_MAP for 8 Kickstart revisions
• Per-game CPU/chipset/RAM/NTSC/clock overrides via buildWhdloadConfig
• save_states=0 forced for safety; PRELOAD hint at 4MB+
• 9-slot snapshot metadata (save/list/delete)
• shouldDisableSaveStates for directory hard drive safety
• buildMissingRomGuidance with CRC32 hex and legal source references

Key Modules

Module	Purpose
src/aminet/emulator-config.ts	FS-UAE config generation with path normalization and sorted keys
src/aminet/hardware-profiles.ts	5 hardware profiles (A500/A1200/A1200+030/A4000/WHDLoad)
src/aminet/rom-manager.ts	CRC32 ROM identification, Cloanto decryption, directory scanning
src/aminet/whdload.ts	WHDLoad .Slave detection, kickstart mapping, per-game overrides
src/aminet/emulator-launch.ts	Launch orchestration with profile selection and structured errors
src/aminet/emulator-state.ts	9-slot snapshots, save state safety checks, ROM guidance

Usage Examples

Generate FS-UAE config:

import { buildFsUaeConfig, generateFsUaeConfig } from './emulator-config.js';

const config = buildFsUaeConfig({
  profile: a1200Profile,
  romPath: '/roms/kick31.rom',
  hardDrives: ['/games/Lemmings'],
});
const configText = generateFsUaeConfig(config);
// Sorted key=value pairs ready for FS-UAE

Select profile from readme:

import { selectProfileFromReadme } from './emulator-launch.js';

const profile = selectProfileFromReadme(readmeText);
// Matches WHDLoad > 040 > 030 > AGA > 020 > OS3.x > A500 default

Scan and select ROM:

import { scanRomDirectory, selectRomForProfile } from './rom-manager.js';

const roms = await scanRomDirectory('/roms');
const rom = selectRomForProfile(roms, 'a1200');
// Handles Cloanto encrypted ROMs and overdumps

Configure WHDLoad:

import { detectSlaveFiles, buildWhdloadConfig } from './whdload.js';

const slaves = await detectSlaveFiles('/games/Lemmings');
const config = buildWhdloadConfig(slaves[0], {
  cpu: '68020',
  chipRam: 2048,
  ntsc: false,
});

Launch emulator:

import { launchEmulator } from './emulator-launch.js';

const result = await launchEmulator({
  packageDir: '/games/Lemmings',
  romDir: '/roms',
  readmeText,
});
// Orchestrates: profile selection -> ROM match -> config gen -> launch

Dependencies

• FS-UAE emulator installed on host system
• User-provided Kickstart ROMs (not distributed; CRC32 verification only)
• Node.js node:child_process for FS-UAE launch
• Node.js node:fs for config writing and ROM scanning
• Node.js node:crypto not used (CRC32 implemented inline, IEEE polynomial)

Token Budget Rationale

1.0% budget reflects the 6 modules covering config generation, hardware profiles, ROM management, WHDLoad integration, launch orchestration, and state snapshots. Despite the module count, the patterns are well-structured with clear separation of concerns, requiring moderate context for correct configuration and launch sequences.