Connaissances / Guides /

Comment repérer les images manquantes dans un projet Ren'Py avant la sortie

Mars 2026 5 min de lecture Débogage
Ren'Py Assets manquants Analyse statique QA avant sortie

Les erreurs d'images manquantes dans les jeux Ren'Py partagent une propriété frustrante : elles n'apparaissent que lorsque le moteur essaie d'afficher l'image. Si la référence se trouve dans une branche que vos testeurs n'atteignent jamais, le bug est livré. C'est le joueur qui le découvre.

L'analyse statique — vérifier les références des scripts par rapport aux fichiers sur le disque avant d'exécuter quoi que ce soit — les détecte avant qu'elles ne deviennent des erreurs d'exécution. Voici comment cela fonctionne et ce qu'il faut rechercher.

Pourquoi les images manquantes surviennent

Les causes les plus fréquentes ne sont pas des erreurs d'inattention. Ce sont des problèmes structurels :

Fichiers renommés Un asset image est renommé ou déplacé dans un nouveau dossier. Les scripts référencent toujours l'ancien chemin.
Fautes de frappe dans les appels de scène Un appel show bg_city_night a un underscore là où le nom de fichier utilise un espace, ou inversement.
Export manquant Un artiste a livré un placeholder. L'asset final n'a jamais été ajouté au projet.
Sensibilité à la casse Fonctionne sous Windows, casse sous Linux/Mac. BG_City.png vs bg_city.png.

Aucun de ces cas n'est détecté au moment de l'écriture. Les scripts Ren'Py ne valident pas les chemins des images lorsque vous les tapez — seulement lorsque le moteur a besoin de les afficher.

Pourquoi les erreurs Ren'Py sont difficiles à tracer à l'exécution

Lorsqu'une image manquante est rencontrée, Ren'Py produit une erreur de ce type :

Exception: Image 'bg city night' not found. While running game code: File "game/script.rpy", line 847, in script scene bg city night with dissolve

L'erreur est suffisamment claire en elle-même. Le problème est que la ligne 847 peut se trouver dans une branche de l'histoire qui nécessite une séquence spécifique de choix faits plus tôt dans une partie de 40 minutes. Vos testeurs doivent connaître ce chemin, penser à l'emprunter, et atteindre cette scène précise. Les trois conditions doivent être vraies simultanément.

Pourquoi les embranchements aggravent les choses Un visual novel avec 10 points de choix où chaque choix produit 2 résultats a jusqu'à 1 024 chemins possibles dans le script. Les tests manuels peuvent réalistement en couvrir une fraction. Les assets manquants dans des branches à faible probabilité sont exactement le type de bug qui arrives aux joueurs.

Comment l'analyse statique détecte les assets manquants

L'analyse statique fonctionne différemment de l'exécution du jeu. Au lieu de suivre un seul chemin dans l'histoire, elle lit chaque fichier .rpy et collecte toutes les références d'images — quelle que soit la branche dans laquelle elles apparaissent.

Les références qu'elle recherche incluent :

  • image bg_city_night = "images/bg_city_night.png" — déclarations d'images explicites
  • show bg city night — appels d'affichage (utilisant la convention de nommage des images Ren'Py)
  • scene bg city with dissolve — transitions de scènes
  • add "images/ui_frame.png" — références directes à des chemins

Chaque référence collectée est ensuite vérifiée par rapport aux fichiers présents sur le disque. Toute référence sans fichier correspondant sur le disque est un asset manquant.

Ce que cela détecte que les tests à l'exécution manquent Comme le scanner lit chaque branche — pas seulement celles qu'un testeur joue par hasard — il trouve les références manquantes dans des chemins qui n'auraient peut-être jamais été atteints pendant le développement. Un asset manquant dans une mauvaise fin, une route cachée, ou une scène optionnelle tardive apparaîtra dans le rapport de scan au même titre que tout le reste.

Erreurs courantes et leur signification

Image nommée avec des espaces vs des underscores

# Le script référence l'image avec des espaces (nom automatique Ren'Py) show bg city night # Fichier réel sur le disque : game/images/bg_city_night.png # underscore, pas espace # Résultat : Ren'Py cherche "bg city night" et ne le trouve pas

Ren'Py associe les noms d'images aux fichiers selon une règle de normalisation spécifique. Un fichier nommé bg_city_night.png est automatiquement disponible comme bg city night dans les appels d'affichage. Mais si vous avez déplacé ou renommé le fichier en bg-city-night.png (avec des tirets), l'association se rompt silencieusement.

Référence de chemin pointant vers un dossier supprimé

# Le script utilise une référence de chemin explicite add "images/ui/overlay_frame.png" # Le sous-dossier ui/ a été réorganisé pendant le développement # Le fichier se trouve maintenant à images/ui_elements/overlay_frame.png # Le script n'a pas été mis à jour

Référence placeholder jamais remplacée

# Placeholder ajouté au script en attendant l'asset final show bg_final_chapter_reveal # L'asset n'a jamais été livré # Le label contenant cet appel n'est atteint qu'au chapitre 8 final # Les tests n'y sont jamais arrivés avant la sortie

Comment effectuer une vérification d'assets manquants avec BranchPy

Dans le panneau de Validation des médias de BranchPy, les assets manquants apparaissent avec un badge MANQUANT dans le navigateur de médias. Ils sont listés quelle que soit la branche contenant la référence — l'intégralité du script est analysée, pas seulement les chemins que vos testeurs ont joués.

Chaque entrée MANQUANT indique le chemin du fichier qui était référencé et confirme qu'il est absent du disque. Aucune exécution requise. Inutile de naviguer jusqu'à cette branche de l'histoire.

L'avantage clé par rapport à la découverte à l'exécution Vous voyez toutes les références manquantes dans une seule liste, sur l'ensemble du projet, avant même de lancer le jeu. Un scan de 60 secondes remplace des heures de couverture des embranchements.

Que faire quand vous trouvez un asset manquant

  1. Vérifiez si le fichier a été renommé ou déplacé — recherchez dans votre dossier d'assets le nom de base du fichier, en ignorant le chemin et l'extension. Il existe souvent encore sous un chemin modifié.
  2. Vérifiez les différences de casse — comparez la casse exacte du nom de fichier dans la référence du script avec le fichier sur le disque.
  3. Vérifiez si l'asset a été intentionnellement supprimé — si c'est le cas, mettez à jour la référence dans le script. Ne laissez pas de références mortes pointant vers rien.
  4. Si le fichier n'a jamais été créé — créez un placeholder maintenant pour que l'erreur disparaisse du scan. Remplacez-le avant la sortie.

Résumé

  • Les images manquantes ne se déclenchent qu'à l'exécution, dans la branche spécifique qui les référence.
  • La structure des embranchements signifie que ces branches peuvent ne jamais être atteintes lors des tests manuels.
  • L'analyse statique lit chaque référence dans l'intégralité du script, pas seulement les chemins qu'un testeur a suivis.
  • Chaque asset manquant trouvé avant la sortie est un crash que vos joueurs ne verront jamais.
Analysez votre projet Ren'Py automatiquement Le panneau de Validation des médias de BranchPy analyse chaque fichier .rpy, détecte les références d'assets manquants et signale les fichiers protégés gérés par le moteur — directement dans VS Code.

Voir comment fonctionne la Validation des médias →
← Pourquoi les fichiers GUI semblent inutilisés Comprendre les embranchements dans un VN →