Automatic Token Image est un module pour Foundry VTT V14, principalement destiné aux mondes D&D5e. Lorsqu’un MJ place un token sur une scène, le module recherche une image appropriée dans une bibliothèque configurée puis met à jour uniquement l’image de ce token.
La recherche utilise le nom de l’acteur ou du token, les noms de fichiers et de dossiers, des alias français/anglais et le type de créature renseigné par D&D5e. Le module ne fournit aucune image : il travaille exclusivement avec la bibliothèque configurée par l’utilisateur.
- Foundry Virtual Tabletop : V14 ;
- système : D&D5e ;
- interface et traductions fournies : français ;
- stockage pris en charge actuellement : source Foundry
data; - stockage S3 : non pris en charge.
- recherche automatique lors de la création d’un token par un MJ ;
- recherche dans les noms de fichiers et l’arborescence des dossiers ;
- importante liste d’alias français/anglais, complétable dans les paramètres ;
- prise en compte séparée du rôle et de la race ;
- priorité donnée au type de créature D&D5e ;
- exclusions conditionnelles pour éviter des variantes indésirables ;
- choix aléatoire pondéré entre plusieurs variantes compatibles ;
- évitement des images récemment utilisées ;
- regroupement racial pour ne pas favoriser une race uniquement parce qu’elle possède davantage de fichiers ;
- index des images mis en cache, avec reconstruction manuelle possible ;
- activation ou désactivation individuelle sur un token ou un prototype ;
- exclusion configurable des personnages joueurs D&D5e.
La grande catégorie renseignée dans les détails D&D5e de l’acteur — humanoïde, bête, plante, mort-vivant, dragon, géant, etc. — est prioritaire. Le nom sert de secours si ce type est absent ou inconnu et permet de préciser la race, l’espèce, le rôle ou la variante.
Seuls les tokens créés par le MJ courant sont traités. Un token placé par un joueur est volontairement ignoré. Avec plusieurs MJ connectés, seul le MJ qui a créé le token effectue la recherche afin d’éviter une double mise à jour.
Un rôle générique comme Guerrier ou Garde peut recevoir une race quelconque
parmi les images compatibles. Lorsqu’une race est explicitement indiquée, elle
devient obligatoire : Guerrier nain ne doit pas recevoir un guerrier gobelin.
Le module ne réalise pas de lemmatisation générale. Les pluriels sont reconnus uniquement lorsqu’ils figurent dans les alias, dans une variante explicitement définie ou dans une règle ciblée du moteur. Cette restriction évite de créer des correspondances incorrectes en supprimant aveuglément des suffixes.
Dans l’écran d’installation des modules de Foundry VTT, utilisez cette URL :
https://raw.githubusercontent.com/theorikkdk/automatic-token-image/main/module.json
L’installation par manifeste fonctionne uniquement si la release GitHub correspondant à la version du manifeste existe et contient l’archive ZIP attendue.
- Téléchargez l’archive ZIP depuis la release GitHub de la version souhaitée.
- Extrayez son contenu dans
FoundryVTT/Data/modules/automatic-token-image. - Vérifiez que
module.jsonse trouve directement dans ce dossier, et non dans un sous-dossier supplémentaire. - Redémarrez Foundry VTT.
- Ouvrez un monde D&D5e.
- Activez Automatic Token Image dans la gestion des modules.
L’installation et la mise à jour automatiques par URL de manifeste ne sont pas encore disponibles. Les champs de release seront renseignés lorsqu’une archive GitHub stable et installable aura été publiée.
Les paramètres sont disponibles dans la configuration du monde :
- Activer le remplacement automatique : active le traitement global ;
- Dossier des images de tokens : dossier parcouru dans la source
data; - Parcourir les sous-dossiers : inclut toute l’arborescence ;
- Durée du cache : délai avant une nouvelle indexation ;
0conserve le cache jusqu’au rechargement ou à une invalidation manuelle ; - Choisir une variante aléatoire : active le tirage pondéré ;
- Diversité des variantes : écart de score autorisé autour du meilleur résultat ;
- Variantes récentes à éviter : taille de l’historique par nom ;
- Probabilité de conserver le token actuel : conserve parfois une image non générique déjà définie ;
- Mots indiquant une image générique : force le remplacement des images génériques reconnues ;
- Ignorer les personnages joueurs : ignore les acteurs D&D5e de type
character; - Utiliser en priorité le nom du token : emploie le nom du token avant celui de l’acteur ;
- Alias personnalisés : ajoute des équivalences aux alias intégrés ;
- Mots d’exclusion conditionnels : refuse ces mots sauf lorsqu’ils sont explicitement demandés.
La fiche de configuration d’un token et celle du prototype d’un acteur proposent également la case Token automatique.
Le module exige un rôle garde/guard et une race nain/dwarf. Une structure
comme celle-ci est reconnue :
Humanoid/Dwarf/Guards/Guard_Sword.png
Si aucune image rôle + race n’existe, une autre image naine compatible peut être utilisée comme secours. Les variantes zombie, esprit ou d’une autre race restent exclues pour un acteur humanoïde.
Un guerrier humain, nain, gobelin ou d’une autre race compatible peut être choisi. Les races sont regroupées avant le tirage afin qu’une collection très nombreuse ne monopolise pas automatiquement le résultat.
Pour un acteur D&D5e de type beast, Giant_Spider.png reste une bête et n’est
pas rejetée comme géant.
Pour un acteur de type humanoid, Dragonborn est traité comme une race
humanoïde et non comme un dragon.
Le cache peut être reconstruit depuis la console du navigateur :
await game.modules.get("automatic-token-image").api.refreshCache()Son état peut être consulté avec :
game.modules.get("automatic-token-image").api.getCacheInfo()Cette seconde commande indique notamment le dossier indexé, le nombre d’images, la date de construction et la taille des caches mémoire.
Si aucune image n’est appliquée :
- vérifiez que le token a été placé par un MJ ;
- vérifiez que le module et la case individuelle Token automatique sont activés ;
- vérifiez le dossier configuré et l’option de parcours récursif ;
- reconstruisez le cache avec la commande ci-dessus ;
- vérifiez le nom et le type de créature D&D5e de l’acteur ;
- vérifiez les mots d’exclusion et les alias personnalisés ;
- ouvrez la console du navigateur avec
F12et recherchez les messagesautomatic-token-image.
Les erreurs de parcours, d’indexation, de sélection et de mise à jour du token sont journalisées séparément.
Prérequis : Node.js 20 ou une version supérieure.
npm testLe projet utilise le testeur natif de Node.js et des modules ES sans compilation ni dépendance externe.
- aucune prise en charge de S3 ;
- aucune lemmatisation générale des pluriels ;
- qualité des résultats dépendante des noms de fichiers et de dossiers ;
- résultats moins fiables si le type D&D5e est vide, personnalisé ou incorrect ;
- expansion des alias limitée à 120 noms par recherche ;
- caches de résultats et d’historiques bornés à 250 groupes ;
- installation par manifeste dépendante de la présence de l’archive ZIP attendue dans la release GitHub correspondante.
Le code source du module est distribué sous la licence MIT, Copyright (c) 2026 TheoriK KDK.
Aucune image de token ni autre ressource visuelle n’est incluse ou distribuée avec le module. La licence MIT du code ne s’applique pas aux éventuelles ressources visuelles externes. Le module analyse uniquement les fichiers choisis par l’utilisateur. Chaque utilisateur reste responsable de vérifier qu’il dispose des droits nécessaires pour les utiliser ; le simple fait de posséder un fichier ne garantit pas un droit d’usage ou de redistribution.
La provenance et les exigences applicables aux futures ressources sont décrites dans ASSET_SOURCES.md.
Les anomalies et suggestions peuvent être signalées dans les issues GitHub.