Tutoriel : porter une carte de Warhammer I dans Warhammer III

Avant de commencer

Ce tutoriel décrit une méthode, pas un bouton magique. Tout y a été vérifié sur notre portage, du 20 au 25 septembre 2026, jusqu'à la mise à jour 9.0 du jeu. Il faut être à l'aise avec les fichiers du jeu, et patient. Il vous faut :

• Warhammer III et son Assembly Kit, les outils officiels de CA (Steam → Bibliothèque → Outils), avec les DLC des factions de votre carte : sans eux, elles existent dans la base mais pas en jeu.
• Warhammer I et son Assembly Kit.
• CAIME (Campaign AI Map Editor), l'éditeur du Campaign Map Toolkit, pour la carte logique, et RPFM pour les packs et les tables.
• Un langage de script (Python chez nous) pour tout ce qui se répète : couches, tables, contrôles.
• Un débogueur, cdb (livré avec WinDbg) : c'est lui qui fait parler les plantages.

Voici le chemin complet, d'un coup d'œil. Chaque étape a sa section plus bas, avec ses commandes et ses pièges.

Le vocabulaire en une minute

• Moitié logique, moitié visuelle : une carte de campagne décrit deux fois la même terre. La moitié logique, c'est ce que le jeu calcule (régions, déplacements, villes) ; la moitié visuelle, ce que le joueur voit (relief, textures, arbres, eau).
• Hex : la case du damier de la moitié logique. Notre carte en compte 400 × 440.
• map.hex : le projet CAIME, c'est-à-dire la carte logique, couche par couche (régions, sols, climats, rivières, routes, villes).
• ESF : un format binaire de CA, celui de map_data.esf comme du startpos.
• Startpos : le fichier qui fige l'état de départ d'une campagne (factions, personnages, villes, diplomatie).
• Table de base : une table de la base de données du jeu (régions, campagnes, factions…).
• Pack : l'archive du mod, posée dans le dossier data du jeu.
• Terry : l'éditeur de terrain de l'Assembly Kit. BOB : le compilateur qui transforme les sources en fichiers du jeu.

Étape 0 : l'inventaire

Avant de toucher à quoi que ce soit, on mesure. Le kit de Warhammer I livre la carte logique de la mini-campagne (son map.hex : 400 × 440 hex, 61 régions) et sa base de données, mais pas son terrain de campagne. Le terrain compilé, le startpos et les scripts sont dans les packs du jeu, qu'on lit avec RPFM.

L'inventaire dit aussi ce qui a changé de nom. Les clés de faction changent de préfixe d'un opus à l'autre : on les apparie sur la culture et la fin de la clé, jamais sur le préfixe (wh_dlc05_brt_mini_bastonne devient wh_main_brt_bastonne). Un script applique les règles dans l'ordre et écrit la raison de chaque exception. Chez nous, les 30 factions ont trouvé une contrepartie ; seule une tribu orque manquait, remplacée par une tribu mineure absente de la carte.

Étape 1 : la carte logique avec CAIME

La carte logique dit au jeu où sont les régions, les villes, les rivières, les routes et les zones infranchissables. Prenez CAIME 1.0.1 (23 septembre 2026) ou plus récent : il lit les cartes des mini-campagnes de Warhammer I, que la 1.0.0 n'ouvrait pas, et la base sur les Windows dont le séparateur décimal est la virgule (en français, par exemple).

Déclarer la carte

D'abord la base du kit : la carte, sa campagne et sa zone jouable, ses régions (chacune avec une couleur RVB unique) et ses provinces. Neuf tables sont concernées (campaigns, campaign_map_playable_areas, regions, campaign_map_regions, region_to_province_junctions…), et le nom de la carte y revient partout, casse comprise. Colonne par colonne : le guide CAIME.

Recaler les couches

Puis on reprend dans CAIME les couches du map.hex de Warhammer I. Les index ne survivent pas au changement de jeu : 13 types de sol terrestres et 24 climats dans Warhammer I, 15 et 40 dans Warhammer III. On recale donc par nom, jamais par numéro. Les emplacements de ville grandissent aussi : 7 hex dans Warhammer I, 19 dans Warhammer III, en disque autour du centre, dont 16 sur terre et 3 côté mer pour un port.

Valider, puis exporter

La ligne de commande de CAIME fait les deux. Enregistrez d'abord, gardez le projet à sa place dans raw_data, et fermez Tweak et Terry : l'export Map Data en dépend, et l'alerte de CAIME ne voit pas l'outil du kit de Warhammer III.

CAIME.exe validate --map map.hex --all
CAIME.exe process --map map.hex --map-data --pathfinding --trade-routes --lookup

Les frontières (borders.pbd) se font ensuite par le menu Process → Borders data : en ligne de commande, leurs options restent vides et l'export échoue, c'est pourquoi process --all sort toujours en échec. On obtient map_data.esf, pathfinding.ppd, borders.pbd, trade_routes.ptd et l'image de correspondance des régions. Le succès se lit dans le Logger : « MapDataBuilder exited with code 0 (Success) ».

• La ligne 0 du damier est en bas de la carte : une image dessinée « haut en haut » se retourne avant d'être encodée.
• Dans un fichier de couche (.hex_layer), Impassable vaut 1 pour franchissable. Ne déduisez jamais le sens d'un drapeau de son nom.
• Si la ligne de votre carte est la dernière de campaign_map_playable_areas, l'export Map Data plante. Une ligne après la vôtre suffit.
• validate sort en échec dès le premier Warning, et même les cartes de CA échouent : lisez le rapport. Sa règle de l'étendue des villes fait échouer cinq villes en col de la carte des Empires : jugez-les en jeu.
• Un hex modifié, et il faut réexporter, puis régénérer le startpos : ce qu'il faut refaire.

Étape 2 : le startpos

Le startpos (startpos.esf) est la sauvegarde du tour 0 : factions, régions, personnages, armées, diplomatie. Une campagne n'en a qu'un, et un mod le remplace en entier. C'est le jeu lui-même qui le fabrique, à partir des tables start_pos_* de l'Assembly Kit.

Mais le jeu ne lit pas les XML du kit : on lui sert ces tables dans un pack de génération, chargé seulement le temps de la génération, à côté du pack du mod. Elles n'entrent jamais dans le pack que l'on joue. La génération se commande par %APPDATA%\The Creative Assembly\Warhammer3\scripts\user.script.txt, que le jeu lit au lancement :

mod mon_mod.pack;
mod mes_tables_de_depart.pack;
process_campaign_startpos ma_campagne;
process_campaign_ai_map_data;
quit_after_campaign_processing;

1. Posez le pack du mod, à jour (scripts compris), et le pack de génération dans le dossier data du jeu.
2. Gardez une copie de user.script.txt, puis écrivez-y les lignes ci-dessus : une ligne mod par pack.
3. Steam ouvert, lancez Warhammer3.exe et attendez qu'il se referme seul, sans toucher à sa fenêtre.
4. Vérifiez la date de startpos.esf, hlp_data.esf et spd_data.esf, copiez-les dans les sources du mod et reconstruisez le pack : il passe devant les copies en vrac, qu'on retire ensuite.
5. Remettez user.script.txt comme avant : sinon, quit_after_campaign_processing fermera le jeu à chaque lancement.

process_campaign_ai_map_data écrit les données de cheminement de l'IA (hlp_data.esf, spd_data.esf), indispensables à une carte neuve : sans elles, le jeu plante au réglage du joueur. Chez nous, 16 secondes pour 400 × 440 hex. Build Startpos de RPFM ne charge qu'un pack ; avec deux, nous écrivons le script à la main. Le détail : le guide des outils.

Ce qu'un startpos exige

Un startpos se génère souvent même quand il est faux : c'est au chargement, ou plus tard, que le jeu plante. Voici chaque symptôme que nous avons vécu, et ce qui manquait :

Étape 3 : le terrain avec Terry et BOB

Ni le kit de Warhammer III ni celui de Warhammer I ne livrent le terrain brut d'une campagne. ChaosRobie, l'auteur d'Immortal Empires Expanded, a reconstitué celui des Empires Immortels en projet Terry et l'a partagé : c'est le plan à suivre. Le projet vit dans raw_data/terrain/campaigns/<carte>/, et la recette de BOB dans le rules.bob du dossier parent.

Les rasters se dimensionnent sur le nombre d'hex : 8 pixels par hex (plus 4 lignes) pour le relief, le fond marin et les textures, soit 3200 × 3524 chez nous ; 4 pour le brouillard de guerre ; 2 pour les arbres, la neige, la corruption et tile_map.png. La mer se déclare dans tile_map.png (la tuile sea), pas par la hauteur. Le détail : le guide Terry.

Compiler avec BOB

BOB compile le projet en une minute environ ; le tout premier passage, qui compresse le relief, a pris environ 26 minutes. On itère donc sans lancer le jeu. Après chaque passage, lisez bob.log (le nombre d'actions annoncées, puis une ligne STATUS: Finished par action faite) et comptez les « Failed to find tile » de bob_warnings.log : chacun est un trou dans le terrain.

Le mur d'une carte neuve est là : pour une carte que la base du jeu (celle des packs de CA) ne connaît pas, BOB ne lance que 6 actions, sans relief ni textures, et sans message ; l'ajouter à la base du kit ou à un pack de mod n'y change rien. C'est une limite de l'outil : faites un témoin, puis demandez à la communauté (le Discord de CAIME, tw-modding), sans décortiquer l'outil de CA ni le contourner.

• L'action Generate Camera Height Map fait planter BOB : fabriquez camera_heightmap.png vous-même, à partir du relief.
• BOB ne produit pas lf_normal.dds, l'éclairage lointain du relief. Nous avons d'abord repris celui de Warhammer I, canal vert inversé ; nous le recalculons aujourd'hui depuis notre relief.
• Il écrit le brouillard de guerre (shroud_heights.dds) à plat : nous le recalculons après chaque passage.
• Il réécrit ses sorties à chaque passage : une retouche faite à la main dans working_data disparaît.
• Une campagne a deux terrains : le sien, et un terrain de bataille, nommé par la colonne terrain_folder de sa zone jouable. Sans lui, le jeu plante à la première bataille terrestre, même entre deux IA, donc souvent dès la première fin de tour.
• Terry ouvert verrouille working_data : fermez-le avant de lancer BOB depuis sa fenêtre ou de construire le pack. Et tant qu'aucun terrain n'est compilé, ouvrez le projet avec 3D View décoché, sinon Terry plante.

Étape 4 : objets, arbres et montagnes

C'est là que la carte prend sa personnalité. Je voulais la carte de Warhammer I à l'identique : ses objets, ses arbres, ses montagnes. Warhammer III lit encore les modèles de Warhammer I, mais pas toujours leurs matériaux : calez chaque conversion sur les objets que CA a lui-même convertis.

Warhammer I

Warhammer III

• N'écrasez jamais un fichier de Warhammer III : le pack le remplacerait dans toutes les campagnes. Rangez les versions de Warhammer I à des chemins que CA n'emploie pas (chez nous, _wh1/) : sinon le moteur va chercher les textures de CA posées à côté.
• Seul le décor naturel est visible de tous ; les décors du Chaos ou des vampires s'affichent selon la culture ou la corruption de la région, comme chez CA.
• Les Empires posent leurs montagnes comme des objets (3 044 poses) : nous avons fait de même avec les reliefs sculptés de Warhammer I : ses 514 montagnes et ses 635 falaises intérieures, 1 149 poses. Ses 233 falaises de côte, faites pour sa côte en escalier, sont retirées : sur une côte lissée, elles dessinaient des murs.
• La liste d'arbres de Warhammer I a déjà le format de Warhammer III : ses arbres s'embarquent à leurs positions.

Le piège qui nous a coûté le plus : deux repères. Les objets vivent dans l'espace des hex, le relief dans une grille de pixels carrés, et Terry étire l'un sur l'autre. Un point (x, z) lit donc le relief à la ligne z × √3/2 ; lu à la ligne z, les objets volent ou s'enterrent. Et un objet « volant » se juge au bas réel de sa boîte, jamais à son point d'origine.

Étape 5 : rivières, côte et eau

L'eau se juge en jeu : Terry ne la montre pas comme le jeu. Trois règles la font apparaître : sa surface est à 0, faite de grands plans d'eau posés comme objets ; le fond (sea_height) passe sous 0 partout, même sous la terre ; la mer se déclare dans tile_map.png.

Les rivières de Warhammer III sont des maillages qui portent le matériau d'eau de la mer. Nous avons reconstruit celles de Warhammer I en surfaces continues, quelques centimètres d'eau sur un lit sombre, avec un courant calculé le long du réseau jusqu'à l'embouchure : le sens de l'eau ne se lit pas dans les tuiles de Warhammer I.

Pour la côte, les tuiles de rivage de Warhammer III n'acceptent qu'une bande régulière : une pointe de terre d'un seul hex laisse un trou. Et de loin, le jeu simplifie le relief : une marche d'un pixel entre la terre et le fond y devient un escalier de plusieurs cases. La côte de Warhammer I ne reste lisse en jeu qu'avec une berge en pente douce et une mer qui reste au fond près des terres.

Avant

Après

Étape 6 : scripts et textes

Notre règle : gameplay de Warhammer III, histoire de Warhammer I. Les scripts de campagne sont réécrits en Lua sur les bibliothèques de CA. Bonne surprise : les 43 répliques doublées de la mini-campagne sont toujours dans les banques de sons de Warhammer III, en anglais comme en français.

• Prenez des clés à vous et ne remplacez jamais une table de CA : les autres campagnes doivent rester intactes, mod actif. Un fragment qui porte le nom du fichier du jeu le remplace tout entier (qui passe devant qui).
• Un mod ne pose que les clés de texte que le jeu ne connaît pas : sinon, il remplace le texte de CA dans toutes les langues. Deux langues, deux packs : le second ne contient que ses textes et passe devant le premier.
• Vérifiez chaque nom dans les textes français du jeu : c'est Gasconnie, Aquitanie et Bastogne, pas Carcassonne, Aquitaine et Bastonne.
• Régénérez le startpos après tout changement de scripts : c'est pendant la génération que les scripts passent le compteur de sauvegarde à 1. Sinon, chaque nouvelle partie se prend pour une sauvegarde, sans introduction ni missions.

Étape 7 : les essais

Tout pack qui ajoute ou change une table de base passe un essai de démarrage avant d'être annoncé : le jeu doit tenir 45 secondes. Chez nous, une seule table de trop (une table de propriété de contenu, qui n'a pas sa place dans un pack de mod) a suffi à fermer le jeu en huit secondes, sans message. Ensuite, à chaque reprise, on relit les rapports de plantage : l'arbre du diagnostic.

Pour les parties longues, Claude a mis en place des parties automatiques. Un pack d'essai séparé contient un script Lua qui clique dans l'interface comme un joueur, ferme les notifications une à une, puis finit le tour ; le pack est retiré à la fin, user.script.txt remis comme avant.

• Le mode où l'IA joue tout (all_players_ai) éprouve la stabilité, pas l'histoire : aucune mission n'est émise pour une IA. L'histoire d'un seigneur se teste en mode joueur.
• Un évènement qui n'arrive jamais : chez nous, FactionTurnStart n'arrivait à aucun script. Dans le jeu publié, une condition d'écouteur qui plante annule l'évènement pour tous, sans rien écrire au journal. Trois écouteurs de CA attendaient des systèmes de Kislev et de Cathay que notre campagne ne charge pas ; retirés au démarrage (core:remove_listener), l'évènement est revenu.
• Steam doit être lancé : sinon le jeu se referme en quelques secondes, et l'on croit à un plantage.

Dernier conseil : si quelqu'un est devant l'ordinateur, prévenez-le avant de lancer le jeu. J'ai moi-même cliqué dans des parties d'essai, et on a cru à des plantages.

Le récapitulatif

1. Inventaire : ce que livre chaque jeu, les clés appariées, un plan par phases.
2. Carte logique : base déclarée, couches recalées par nom, validation, export (Borders par le menu).
3. Startpos : tables de départ dans un pack de génération, données de l'IA, pack reconstruit, user.script.txt remis.
4. Terrain : projet Terry sur le modèle de ChaosRobie, BOB et ses journaux, terrain de bataille.
5. Objets et montagnes : fichiers de Warhammer I à des chemins à vous, repère vérifié.
6. Eau : surface à 0, fond sous 0 partout, rivières continues, côte en pente douce, jugement en jeu.
7. Scripts et textes : clés à vous, noms vérifiés, startpos régénéré.
8. Essais : démarrage de 45 secondes, rapports de plantage, parties automatiques.

Le récit de ces journées est dans cet article, et les leçons de méthode dans celui-ci. La suite se dessine sur la carte de la Bretonnie entière.