🎮 Support Amiga — Autostart, multi-disques et intégration vAmigaWeb

[aciderix]

🎮 Support Amiga — Autostart, multi-disques et intégration vAmigaWeb

Contexte

Le repo dispose déjà d'un packer Amiga dédié (packers/amiga/) basé sur vAmigaWeb (émulateur WASM natif), distinct du packer universel (EmulatorJS). Ce packer fonctionne mais utilise des scripts per-game (ex: Jimmy Willburne). L'objectif est de rendre le support Amiga générique et automatisé.

État actuel

Packer Amiga existant (packers/amiga/)

Fichier	Rôle
amiga-packer.md	Documentation
pack_jimmy.py	Script de packing spécifique à Jimmy Willburne
template_amiga_1disk.html	Template HTML pour jeux 1 disque
template_amiga_2disks.html	Template HTML pour jeux 2 disques
vAmiga.js / vAmiga.wasm	Émulateur vAmigaWeb compilé

Pourquoi vAmigaWeb et pas EmulatorJS/puae ?

Aspect	EmulatorJS (puae)	vAmigaWeb
Multi-disques	❌ Cassé — TypeError dans emulator.min.js, M3U non supporté	✅ DF0-DF3 pré-chargés
Kickstart	Problème de distribution (copyright)	Embarqué dans le HTML
Autostart	Pas de core_option fiable	✅ Boot automatique depuis DF0
Taille HTML	~1-2 MB	~5-10 MB (WASM complet)
Qualité émulation	Correcte (libretro)	Très bonne (cycle-exact)

Conclusion : vAmigaWeb est le bon choix pour l'Amiga dans ce projet.

---

Investigation : mécanisme d'autostart

Analyse des disquettes Jimmy Willburne

Analyse réalisée sur les 3 ADF originaux du jeu Jimmy Willburne :

Disk 1 — Original (jimmy_disk1.adf)

Fichiers à la racine:
  Jimmy                    FILE (386708 bytes)  ← exécutable du jeu
  Jimmy.info               FILE (7231 bytes)    ← icône Workbench
  Info_Jimmy               FILE (6537 bytes)
  Data1                    FILE (375341 bytes)  ← données
  Sauvegarde.JW            FILE (3680 bytes)
  + C/, Devs/, Fonts/, Libs/, S/

S/startup-sequence (14 bytes):
  Loadwb
  endcli

→ Charge le Workbench (bureau Amiga). L'utilisateur doit manuellement double-cliquer sur Jimmy.info.

Disk 3 — Intro (jimmy_disk3.adf)

Fichiers à la racine:
  Intro_Jimmy              FILE (22268 bytes)
  SetChipRev               FILE (8344 bytes)
  Data3                    FILE (329262 bytes)

s/startup-sequence (12 bytes):
  intro_jimmy

→ Lance l'intro directement (autostart natif).

Disk 2 — Données (jimmy_disk2.adf)

• Disque de données pur, label "Jimmy_Disk_222"
• Pas de startup-sequence

La modification pour l'autostart

Le fichier jimmy_disk1_mod.adf dans le repo est une version modifiée du disk 1 où la S/startup-sequence a été changée de :

Loadwb
endcli

en :

Jimmy

→ Le jeu se lance directement au boot sans passer par le Workbench.

Mécanisme multi-disques

Le packer vAmigaWeb charge les disques dans DF0 + DF1 avant le boot :

floppy_drive_count = 2
DF0 ← disk1 (boot)
DF1 ← disk2 (données)

Les deux disques sont insérés avant le boot → pas de swap nécessaire. L'Amiga voit les 2 drives directement. Extensible à DF0-DF3 pour ≤4 disques.

---

Problématique : automatiser l'autostart

Chaque jeu Amiga a un exécutable différent (Jimmy, Turrican, Xenon2, etc.). Comment détecter automatiquement quel programme lancer ?

Catégories de jeux Amiga

Catégorie	Autostart	Patchable ?	% estimé
Trackloaders	✅ Boot direct (bootblock custom, pas de filesystem)	Non nécessaire	~30%
AmigaDOS — startup lance le jeu	✅ Déjà autostart	Non nécessaire	~15%
AmigaDOS — Loadwb/endcli	❌ Charge Workbench	✅ Oui — patcher startup-sequence	~35%
WHDLoad	⚠️ Nécessite slave + assigns	🔶 Complexe	~15%
Multi-exe (intro + jeu)	⚠️ Choix nécessaire	🔶 Moyen	~5%

Stratégie de détection automatique

Utilisateur charge un .adf
    ↓
Parser le filesystem AmigaDOS
    ↓
├── Pas de filesystem (trackloader)
│   → Pas de patch, boot direct (fonctionne tout seul)
│
├── Startup-sequence lance déjà le jeu
│   → Pas besoin de patcher, on garde tel quel
│
├── Startup-sequence = Loadwb/endcli (ou vide)
│   → Détection heuristique de l'exécutable :
│   │
│   ├── 1. Chercher le plus gros fichier à la racine
│   │    (exclure C/, Libs/, Devs/, Fonts/, S/, *.info, *.font)
│   │
│   ├── 2. Chercher les .info à la racine → nom sans .info = exécutable
│   │
│   ├── 3. Si trouvé → proposer "Lancer [NomExe] au boot ?"
│   │
│   └── 4. Si pas trouvé → champ manuel

Heuristiques détaillées

1. Lire la startup-sequence existante — si elle lance déjà quelque chose (pas Loadwb/endcli/echo), on la garde
2. Plus gros fichier exécutable à la racine — exclure les répertoires système (C/, Libs/, Devs/, Fonts/, S/) et les fichiers non-exe (.info, .font, données < 10KB)
3. Fichiers .info à la racine — un .info correspond souvent à un exécutable du même nom
4. Fallback — champ texte pour que l'utilisateur spécifie manuellement

Exemple avec Jimmy Willburne :

• Jimmy = 386 KB (plus gros fichier racine) ✅
• Jimmy.info existe → confirme que Jimmy est l'exécutable ✅
• Détection automatique réussie

---

Proposition d'implémentation

Phase 1 — Packer Amiga générique (single-disk)

• Créer pack_amiga.py générique (remplacer pack_jimmy.py)
• Parser les ADF en Python (filesystem AmigaDOS)
• Détection automatique de l'exécutable principal
• Patcher la S/startup-sequence dans l'ADF si nécessaire
• Champ optionnel "Exécutable Amiga" si la détection échoue
• Embarquer le Kickstart 1.3 (A500) par défaut
• Template HTML single-disk existant

Phase 2 — Multi-disques

• Support 2-4 disques (DF0-DF3)
• Interface pour uploader plusieurs ADF
• Sélection du disque de boot
• Template HTML multi-disk existant

Phase 3 — Intégration packer web (optionnel)

• Ajouter l'option Amiga dans pack_game_fr.html / pack_game_en.html
• Ou garder le packer Amiga séparé (la taille WASM ~5MB rend l'intégration lourde)

Phase 4 — Cas avancés

• Support WHDLoad (.lha) — nécessite AROS ou vrai Kickstart
• Détection du modèle Amiga requis (A500/A1200) via les données du jeu
• Gestion des Assign nécessaires

---

Kickstart / BIOS

Kickstart	Modèle	Usage
kick13.A500 (256 KB)	Amiga 500	~80% des jeux (la majorité)
kick20.A500	Amiga 500+	Quelques jeux
kick31.A1200	Amiga 1200	Jeux AGA (graphismes avancés)

Note légale : Les Kickstart ROM sont sous copyright Cloanto/Amiga Inc. Ils ne peuvent pas être distribués librement. Options :

1. L'utilisateur fournit son propre Kickstart (via --bios ou upload dans le packer web)
2. Le Kickstart est embarqué dans le HTML par l'utilisateur au moment du packing (pas distribué dans le repo)
3. Fallback AROS (open-source) — compatibilité ~60%

Le packer actuel (packers/amiga/) embarque déjà kick13.A500 dans les templates.

---

Fichiers de référence

• Packer actuel : packers/amiga/pack_jimmy.py
• Templates : packers/amiga/template_amiga_1disk.html, template_amiga_2disks.html
• vAmigaWeb : packers/amiga/vAmiga.js, vAmiga.wasm
• Packer universel : packers/universal/pack_game.py (Amiga = core puae, mais pas recommandé)
• ROMs test : jimmy_disk1.adf, jimmy_disk1_mod.adf, jimmy_disk2.adf, jimmy_disk3.adf

Liens utiles

• vAmigaWeb — Émulateur Amiga WASM
• libretro PUAE docs — Documentation du core puae (pour référence)
• EmulatorJS issue multi-disk — Bug multi-disk EmulatorJS
• Format ADF — Spécification du format AmigaDOS

[aciderix]

🔍 Auto-détection de la version Kickstart

Ce qu'on peut détecter 🟢

Indice	Méthode	Fiabilité
Appels OpenLibrary(lib, version)	Parser les hunks Amiga de l'exécutable principal → le numéro de version minimum demandé indique l'OS requis (v34=1.3, v37=2.0, v40=3.1)	🟡 Moyen
Présence de SetChipRev	Utilitaire de sélection OCS/ECS/AGA → indique un jeu multi-chipset	🟢 Bon indice
Taille du disque ADF	DD = 880 KB (standard A500) / HD = 1.76 MB → souvent A1200/AGA	🟡 Approximatif
Bootblock expansion.library	Référence dans le bootblock → indice d'un jeu nécessitant plus qu'un A500 de base	🟡 Faible

Ce qui n'est PAS détectable 🔴

• Trackloaders : bypassent complètement AmigaDOS, aucun indice dans le filesystem. Ils accèdent directement aux pistes du disque.
• Pas de vérification explicite : beaucoup de jeux ne vérifient pas la version Kickstart — ils marchent ou crashent silencieusement
• Jeux qui EXIGENT le 1.3 : certains utilisent des bugs/features spécifiques au Kickstart 1.3 et cassent sur 2.0 ou 3.1 (registres hardware accédés directement)
• Jeux AGA : pas toujours identifiables sans exécuter le code (les modes graphiques AGA ne sont activés qu'au runtime)

Stratégie proposée

Défaut : Kickstart 1.3 (couvre ~80% des jeux classiques)
    │
    ├── Heuristique 1 : Taille ADF
    │   └── HD (1.76 MB) → suggérer Kickstart 3.1 (AGA probable)
    │
    ├── Heuristique 2 : Parser les hunks de l'exécutable
    │   ├── OpenLibrary version ≥ 40 → Kickstart 3.1
    │   ├── OpenLibrary version ≥ 37 → Kickstart 2.0
    │   └── Version < 37 ou non détectable → rester sur 1.3
    │
    ├── Heuristique 3 : Présence de SetChipRev / expansion.library
    │   └── Indice complémentaire, pas décisif seul
    │
    └── Override utilisateur : menu déroulant [1.3 ▼ | 2.0 | 3.1]
        → Toujours disponible, prioritaire sur la détection

Kickstarts et modèles correspondants

Version	Fichier	Modèle	exec.library	% des jeux
1.3	kick13.A500 (256 KB)	Amiga 500	v34	~70%
2.0	kick20.A500 (256 KB)	Amiga 500+ / 600	v37	~10%
3.1	kick31.A1200 (512 KB)	Amiga 1200	v40	~20%

Conclusion

L'auto-détection est un bonus qui améliorera l'expérience dans ~30% des cas (jeux AmigaDOS avec hunks parsables + disques HD). Pour les 70% restants (trackloaders + jeux sans vérification explicite), le défaut Kickstart 1.3 est le bon choix. L'override utilisateur reste indispensable.

[aciderix]

🏗️ Architecture : intégration dans le packer universel

Décision : intégrer, pas paralléliser

Plutôt que maintenir deux outils séparés (pack_game.py + pack_jimmy.py), on intègre vAmigaWeb dans le packer universel via un nouveau concept : engine.

Nouveau champ engine dans SYSTEMS

SYSTEMS = {
    # Systèmes EmulatorJS (inchangés)
    'nes':   { 'engine': 'emulatorjs', 'core': 'fceumm', ... },
    'snes':  { 'engine': 'emulatorjs', 'core': 'snes9x', ... },
    'c64':   { 'engine': 'emulatorjs', 'core': 'vice_x64sc', 'core_options': {...}, ... },
    'coleco':{ 'engine': 'emulatorjs', 'core': 'gearcoleco', 'bios': 'colecovision.rom', ... },
    
    # Amiga — nouveau moteur
    'amiga': {
        'engine': 'vamigaweb',
        'template': 'template_amiga',
        'bios': 'kick13.A500',
        'multi_disk': True,
        'patch_startup': True,
        'extensions': ['.adf'],
    }
}

Logique du packer

python3 pack_game.py game.adf --system amiga
    │
    ├── engine == 'emulatorjs' → flux actuel (inchangé)
    │   └── Template EmulatorJS, EJS_core, EJS_gameUrl, EJS_biosUrl
    │
    └── engine == 'vamigaweb' → nouveau flux
        ├── 1. Parser le filesystem AmigaDOS de l'ADF
        ├── 2. Détecter l'exécutable principal (heuristiques)
        ├── 3. Patcher S/startup-sequence si nécessaire
        ├── 4. Détecter la version Kickstart (heuristiques)
        ├── 5. Auto-search BIOS Kickstart (mêmes chemins que les autres BIOS)
        ├── 6. Gérer multi-disques si --disk2/--disk3 fournis
        └── 7. Générer HTML avec template vAmigaWeb

Ce qui est réutilisé (code commun)

Composant	Réutilisable ?
CLI (--system, --bios, --output)	✅ Tel quel
Auto-search BIOS (4 chemins dont docs/data/bios/)	✅ Tel quel
Embedding base64 dans le HTML	✅ Tel quel
Nom du jeu / métadonnées	✅ Tel quel
Structure du projet / README	✅ Tel quel

Ce qui est nouveau (code Amiga spécifique)

Composant	Description
parse_adf()	Parser le filesystem AmigaDOS (root block, hash table, file headers)
detect_executable()	Heuristiques : plus gros fichier racine, .info, startup-sequence existante
patch_startup_sequence()	Réécrire S/startup-sequence dans l'ADF en mémoire
detect_kickstart_version()	Heuristiques : taille ADF, hunks, expansion.library
--disk2, --disk3, --disk4	Nouveaux paramètres CLI pour multi-disques
--exe	Override manuel de l'exécutable à lancer
--kickstart	Override de la version Kickstart (1.3/2.0/3.1)
Template vAmigaWeb	HTML avec vAmiga.js/wasm, chargement DF0-DF3

Nouvelles options CLI

python3 pack_game.py game.adf --system amiga [options]

Options Amiga spécifiques :
  --disk2 FILE      Deuxième disquette (DF1)
  --disk3 FILE      Troisième disquette (DF2)
  --disk4 FILE      Quatrième disquette (DF3)
  --exe NAME        Exécutable à lancer (override la détection auto)
  --kickstart VER   Version Kickstart : 1.3 (défaut), 2.0, 3.1
  --no-patch        Ne pas modifier la startup-sequence

Packers web (FR/EN)

L'intégration dans les packers web est plus complexe mais faisable :

1. Sélection "Amiga" dans le dropdown → affiche les options spécifiques (multi-disques, exe override, kickstart)
2. Chargement vAmiga.js/wasm depuis GitHub Pages (data/amiga/vAmiga.js, data/amiga/vAmiga.wasm) ou CDN
3. Parsing ADF côté client en JavaScript (même logique que Python)
4. Upload multi-fichiers pour les disquettes supplémentaires
5. Génération HTML avec le template vAmigaWeb

Avantages de cette approche

• 🎯 Un seul outil pour tous les systèmes (CLI + web)
• 📖 Une seule documentation (README)
• 🔧 Extensible — le concept engine permet d'ajouter d'autres émulateurs à l'avenir
• 🧹 Remplace packers/amiga/pack_jimmy.py (scripts per-game → packer générique)
• ♻️ Réutilise tout le code commun (BIOS, base64, CLI, etc.)