a2adv — des livres-jeu qui tournent sur des ordinateurs retro

Une note d'honnêteté. Ce projet est en partie écrit avec l'aide de l'IA. Ça remplace la bonne équipe de quinquagénaires passionnés qu'il aurait fallu pour le mener — mais si le sujet vous parle, n'hésitez surtout pas à vous manifester : les vrais passionnés restent très largement les bienvenus.

L'IA a permis de faire des outils de conversion en python et de verifier les timings, un retravaille pour factoriser et optimiser le code, tout en ajoutant des commentaires, pour le rendre plus lisible ... bref c'est criticable ou non, votre choix, c'est le miens en tout cas !

a2adv est une chaîne d'outils complète pour écrire des livres dont vous êtes le héros et les faire tourner sur de vrais ordinateurs rétro — pas sur un émulateur qui fait semblant, mais sur un support d'époque qu'une machine d'époque avale sans broncher.

Le projet est parti de l'Apple II de 1979 : une disquette ProDOS bootable, moteur écrit en C et assembleur 6502 — c'est la plateforme de référence, la plus aboutie et la seule vérifiée sur matériel réel. Il s'étend maintenant à d'autres machines de la même génération : un portage Atari ST (68000) est en cours dans player/atarist/, avec le même format d'aventure et le même compilateur.

Vous écrivez l'aventure dans un format texte lisible, sur un ordinateur moderne. Un compilateur la transforme en données binaires neutres vis-à-vis de la plateforme cible. Un moteur par machine — sa propre boucle de jeu, son propre affichage, son propre disque — les lit et joue l'histoire.

      aventure.adv           a2c (Python)        STORYnn.DAT        player (par plateforme)
   ┌────────────────┐     ┌───────────────┐     ┌────────────┐     ┌─────────────────────┐
   │  texte, choix  │ ──▶ │  compilateur  │ ──▶ │  binaire   │ ──▶ │  Apple II  (6502)   │
   │  conditions    │     │  + QA         │     │  neutre    │     │  Atari ST  (68000)  │
   └────────────────┘     └───────────────┘     └────────────┘     └─────────────────────┘

---

À quoi ça ressemble

Quatre captures de L'Homme en Costume Blanc sur Apple 2, prises sur la disquette produite par la chaîne d'outils.

Écran-titre. Image HIRES plein écran et menu. Aucun de ces libellés n'est dans le moteur : ils viennent tous de l'aventure.	Préface, en 80 colonnes. Les passages en vidéo inverse sont écrits *comme ça* dans le source.
Bandeau d'état et choix. Caractéristiques, score et mouvements en permanence ; les choix apparaissent selon leurs conditions.	Mode image + texte. Image HIRES en haut, narration et choix dans la fenêtre 40 colonnes du bas.

---

Pourquoi

Le livre-jeu et l'Apple II sont contemporains, et pourtant écrire l'un pour l'autre a toujours été pénible : on tapait du BASIC, on comptait les octets à la main, et changer une phrase voulait dire renuméroter des paragraphes.

a2adv part de l'idée inverse : l'auteur écrit du texte, la machine s'occupe des octets. Les contraintes de 1979 sont respectées à la lettre — mais elles sont absorbées par le compilateur, pas subies par l'auteur.

Les objectifs qui gouvernent le projet

Ces objectifs viennent du player historique, l'Apple II — le plus abouti et le seul vérifié sur matériel réel — mais ils gouvernent tout le projet : un nouveau player (Atari ST, ou une autre machine demain) doit s'y conformer lui aussi, avec ses propres contraintes matérielles.

Compatibilité maximale. La machine de destination, c'est l'Apple II : le moteur vise le 6502 et tient dans les 64 Ko de RAM principale — le plancher imposé par ProDOS lui-même, qui ne démarre pas en dessous. Un Apple II ou II+ à 64 Ko suffit donc, mais un //e est conseillé pour le confort : le 80 colonnes est plus agréable à lire sur de longs paragraphes — le 40 reste pleinement géré — et son générateur de caractères possède les minuscules (N'importe quel //e les a, y compris le modèle nu à 64 Ko : c'est une ROM, pas une extension). Un II ou II+ n'en a aucune, casse et accents y sont donc repliés en capitales ASCII à l'affichage — automatiquement, la machine est détectée à l'exécution (get_ostype()), même disquette des deux côtés, rien à recompiler. Le disque RAM sur 128 Ko est détecté à l'exécution et exploité s'il est présent, jamais exigé.

Pas de limite de taille d'aventure. Le moteur ne charge jamais l'histoire entière : chaque section est lue à la demande grâce à un index. L'aventure est bornée par la capacité de la disquette, pas par la RAM.

Le moteur ne contient aucun texte de langue. Menus, invites, messages de fin, libellés d'inventaire : tout vient de l'aventure. Traduire un jeu, c'est éditer son fichier source — sans recompiler le moteur.

Rien à la volée. Toute stat, tout objet, tout drapeau doit être déclaré. Le compilateur refuse une faute de frappe plutôt que de créer silencieusement une variable — et l'ordre figé des déclarations rend les sauvegardes stables.

Se tromper à la compilation, pas devant le joueur. Un analyseur détecte les sections inatteignables, les culs-de-sac, les fins injoignables, les objets requis mais jamais donnés.

Ce qui marche aujourd'hui (Apple II)

• Narration : sections, choix conditionnels, effets, drapeaux, objets, caractéristiques bornées, score et compteur de mouvements.
• Combat au tour par tour (2d6 + stat, armure, modificateurs d'équipement, fuite) avec branchements victoire / défaite / fuite.
• Énigmes à saisie : le joueur tape un mot ou un code, comparé à plusieurs réponses acceptées.
• Affichage : pilote texte maison 40/80 colonnes (le 80 colonnes passe par la mémoire auxiliaire du //e), images HIRES plein écran ou en mode mixte, paragraphes justifiés à la largeur réelle, styles centré et inversé.
• Son : haut-parleur 1 bit — effets courts entre deux écrans, volontairement sobre.
• Performance : cache des données d'histoire dans le disque RAM /RAM sur machine 128 Ko, avec fenêtre glissante sur les chapitres.
• Sauvegarde sur disquette (un emplacement).
• Découpage en chapitres : chaque chapitre devient son propre fichier, ce qui permet des aventures de taille arbitraire.

Non fait à ce jour : sauvegardes multi-emplacements, échange de disquettes réel, éditeur visuel.

Tout ceci tourne sur une machine réelle, pas seulement sur émulateur : le moteur boote et se joue sur un Apple //e physique. C'est d'ailleurs le //e qui a eu le dernier mot sur des bugs qu'aucun test hôte n'aurait révélés — un jeu de caractères alternatif laissé actif par la machine rendait toute vidéo inverse illisible en 80 colonnes.

Le portage Atari ST

Un second player, indépendant, réutilise le même cœur C et le même format STORY.DAT sans aucune modification (story.c, state.c, combat.c, ...) : seuls l'affichage (console VT52, images basse résolution 320×200/16 couleurs), le son (YM2149) et l'accès disque sont réécrits pour la machine. Narration, menus, combat, saisie et images fonctionnent et sont vérifiés à l'écran sous Hatari ; le son n'est pas encore vérifié à l'oreille. Détails et état d'avancement dans player/atarist/README.md.

cd player/atarist
make st ADV=homme_costume_blanc
# -> adventures/homme_costume_blanc/build/homme_costume_blanc.st

Fabrique une vraie image disquette .ST (FAT12 720 Ko), via mtools (sudo apt install mtools). make run reste plus rapide pour itérer : il monte directement le dossier de build dans Hatari sans produire de fichier.

Le portage PC DOS

Un troisième player, même principe, cible un PC DOS (compatible FreeDOS) avec carte VGA (mode 13h, 320×200/256 couleurs) ; sur une machine EGA seule, le jeu reste jouable en texte seul (repli automatique). Compilé avec Open Watcom v2 (cross-compilation Linux → DOS 16 bits réel), disquette .img bootable (FAT12 720 Ko, secteur de boot + noyau FreeDOS officiels). Texte et graphisme vérifiés à l'octet/au pixel près (relecture de la mémoire vidéo depuis l'hôte) ; son laissé de côté pour l'instant (Sound Blaster prévu). Détails dans player/dos/README.md.

cd player/dos
make img ADV=homme_costume_blanc
# -> adventures/homme_costume_blanc/build/homme_costume_blanc.img

Démarrage rapide

Il vous faut cc65 (compilateur 6502), Python 3 et Java (pour AppleCommander, qui fabrique la disquette).

# fabriquer la disquette d'une aventure
cd player/apple2
make dsk ADV=homme_costume_blanc
# -> adventures/homme_costume_blanc/build/homme_costume_blanc.dsk

Bootez le .dsk obtenu dans n'importe quel émulateur Apple II gérant ProDOS.

# compiler seulement, avec un résumé de l'aventure
cd compiler
python3 -m a2c ../adventures/homme_costume_blanc/homme_costume_blanc.adv -o /tmp/x --summary

# contrôle qualité : sections inatteignables, culs-de-sac, objets morts
python3 -m a2c.analyze ../adventures/homme_costume_blanc/homme_costume_blanc.adv

# rejouer le cœur du moteur sur PC, sans émulateur
cd player/apple2 && make hosttest

Organisation du dépôt

Dossier	Contenu
compiler/	a2c, le compilateur Python — parseur, validation, encodeur, analyseur QA. Aucune dépendance externe.
player/apple2/	Le moteur cc65 : pilote écran, streaming, combat, saisie, son, cache /RAM.
player/atarist/	Portage Atari ST (68000) du même moteur, en cours — cf. son README.
player/dos/	Portage PC DOS (VGA/EGA) du même moteur, en cours — cf. son README.
player/webng/	Player web (Angular) : catalogue d'aventures, jeu dans le navigateur, hors ligne — cf. son README.
adventures/	Une aventure par dossier : source .adv, images, disquette produite.
editor/	Éditeur visuel .adv (Angular, v0) : hiérarchie, graphe des choix, import/export.
docs/	La documentation du format .adv : référence, bonnes pratiques, présentation.
EVOLUTIONS.md	Idées d'évolution du format et des outils, classées par priorité.

Écrire une aventure

Le format source est décrit de bout en bout dans la référence du format .adv : chaque élément, sa syntaxe, ses limites. Une fois la syntaxe acquise, les bonnes pratiques montrent comment assembler tout cela en une aventure qui tient debout.

Un exemple complet et jouable : L'Homme en Costume Blanc, 60 sections, quatre chapitres.

Licence

Le code (compilateur a2c et les players player/apple2/, player/atarist/, player/dos/ et player/webng/) est sous licence MIT. La police bitmap player/dos/src/font8x8.h est dans le domaine public (cf. son entête pour la provenance).

Les aventures livrées dans adventures/ portent leurs propres licences de contenu, une par dossier :

• les quatre aventures de démonstration (chateau_hante, combat_demo, demo_simple, orbe_de_sortis) sont en CC0 — domaine public. Elles sont faites pour être copiées comme point de départ : partez de l'une d'elles, écrivez votre histoire par-dessus, publiez-la sous la licence que vous voulez. Vous ne devez rien ;
• L'Homme en Costume Blanc est sous CC BY-SA 4.0, licence héritée et non choisie : le scénario original de Cosmicsoap publié par Rolis est lui-même sous CC BY-SA, dont la clause de partage dans les mêmes conditions s'impose à toute adaptation.