Comment l'analyseur de médias Ren'Py est structuré

Mars 2026 7 min de lecture Architecture

Architecture Analyse de médias Ren'Py Classification

L'analyseur de médias de BranchPy peut être décrit en quatre mots : analyser, classer, protéger, réviser. Cette note explique ce que fait réellement chaque étape, pourquoi elle précède la suivante, et quelles seraient les conséquences de les effectuer dans un ordre différent.

La version courte : l'ordre est le mécanisme de sécurité. Ce n'est pas du rangement organisationnel.

Étape 1 — Analyser : construire un inventaire complet des fichiers

La première étape n'a qu'une mission : énumérer chaque fichier média présent dans l'arborescence du projet. Elle ne juge pas, ne classe pas, ne filtre pas. Elle produit un inventaire plat : ce fichier existe, à ce chemin, avec ces propriétés.

En parallèle, un second sous-processus parcourt tous les fichiers .rpy et construit une carte de références — chaque chaîne de chemin trouvée dans les déclarations image, show, scene, play music, play sound, voice, et les appels API Python équivalents. Cet ensemble de références est séparé de l'inventaire de fichiers. Aucun des deux ne dépend encore de l'autre.

Pourquoi deux passes séparées Garder l'inventaire de fichiers et la carte de références séparés signifie que chacun peut être utilisé indépendamment. Un rapport de fichiers manquants n'a pas besoin que le scan complet soit terminé. Une référence pointant vers un fichier qui n'existe pas encore est toujours une référence valide. Mélanger les deux passes effacerait des informations utiles à conserver distinctes.

Étape 2 — Classer : attribuer un statut à chaque fichier

Avec l'inventaire de fichiers et la carte de références disponibles, la classification attribue un statut à chaque fichier connu. Les statuts possibles sont :

Référencé — le fichier apparaît dans la carte de références.
Non référencé — le fichier est dans l'inventaire mais pas dans la carte de références.
Manquant — le fichier apparaît dans la carte de références mais pas dans l'inventaire (il est utilisé mais absent du disque).

La classification est intentionnellement mécanique à ce stade. Elle ne se demande pas encore si un fichier non référencé est sans danger à supprimer — c'est le rôle de l'étape suivante. Le classificateur répond simplement : est-ce que ce qui est sur le disque correspond à ce que les scripts attendent ?

Ce que la classification ne couvre pas L'analyse des références au niveau des scripts a des limites connues. Les assets chargés via des chaînes de chemins construites dynamiquement, les assets référencés uniquement dans des variables de configuration ou des blocs de style, et les assets chargés par les systèmes intégrés du moteur n'apparaissent pas dans la carte de références. C'est prévu — ils sont traités dans l'étape de protection.

Étape 3 — Protéger : appliquer les règles de protection avant d'afficher les résultats

La protection est l'étape qui fait la différence entre un outil utile et un outil dangereux. Avant qu'un résultat soit présenté à l'utilisateur, chaque fichier dans l'ensemble non référencé est vérifié par rapport à un ensemble de règles de protection.

Les fichiers qui correspondent à un chemin protégé reçoivent une classification distincte — PROTÉGÉ — et sont retirés entièrement de l'ensemble actionnable. Ils apparaissent dans les résultats, mais sans case à cocher et sans raison d'agir dessus.

Les chemins protégés couvrent deux catégories :

Chemins gérés par le moteur : game/gui/, renpy/, common/, launcher/ — chemins où le moteur Ren'Py lui-même charge des fichiers, en contournant le système de scripts.
Chemins protégés par politique : game/fonts/ et fonts/ — chemins contenant des assets qui peuvent être chargés indirectement via la configuration ou les définitions de style, où le mécanisme de chargement est moins prévisible.

Au-delà des règles intégrées, les utilisateurs peuvent étendre la liste de protection via branchpy.config.json en utilisant la clé protectedPaths. Si votre projet a une structure de répertoires personnalisée qui doit être exclue des candidats au nettoyage, c'est ainsi que vous l'indiquez à l'analyseur.

Pourquoi la protection se produit avant la présentation Si la protection était appliquée au niveau de l'interface — en cachant seulement la case à cocher pour certains fichiers —, un bug dans l'interface pourrait exposer des fichiers protégés comme sélectionnables. En retirant les fichiers protégés de l'ensemble actionnable avant même de construire l'interface, une défaillance de la couche UI ne peut pas escalader en une suppression accidentelle d'un asset du moteur.

Étape 4 — Réviser : présenter les résultats pour le jugement humain

Ce qui atteint l'étape de révision est déjà filtré. L'utilisateur voit :

Les fichiers classifiés comme Non référencés qui ne sont pas protégés — ce sont les candidats à réviser.
Les fichiers classifiés comme Manquants — référencés dans les scripts mais absents du disque.
Les fichiers classifiés comme Protégés — visibles mais non actionnables, avec une chaîne de raison.

Chaque fichier non référencé affiche le chemin, le type de fichier, et — quand disponible — des informations contextuelles sur la raison probable de l'absence de référence. Ce contexte existe pour soutenir le réviseur humain, non pour le remplacer.

Rien n'est supprimé depuis cette vue sans une seconde confirmation. La sélection et la confirmation sont des étapes distinctes : sélectionner des fichiers les marque comme candidats ; une boîte de dialogue de confirmation distincte les liste à nouveau avant qu'une opération sur le système de fichiers se produise.

Pourquoi l'ordre est le mécanisme de sécurité

L'ordre compte précisément parce que la sortie de chaque étape est l'entrée de la suivante. Une erreur contenue dans une étape ne se propage pas dans les étapes suivantes :

Une erreur de classification (un fichier protégé incorrectement marqué non référencé) est interceptée par l'étape de protection — le fichier est reclassifié avant d'atteindre l'interface.
Un manque dans l'étape de protection — un fichier qui devrait être protégé mais n'est pas intercepté par l'ensemble de règles — est une catégorie de limitation connue, pas un échec silencieux. Il apparaît en révision où un humain est présent.
Un bug d'interface qui afficherait les mauvais fichiers comme sélectionnables est intercepté par le gestionnaire de suppression, qui valide indépendamment l'ensemble de fichiers par rapport à la liste de protection avant toute opération.

Trois couches indépendantes doivent chacune échouer dans la même direction simultanément pour produire une fausse suppression. C'est intentionnel.

Le principe derrière la conception Chaque étape devrait pouvoir échouer sans rendre l'étape suivante dangereuse. La sécurité dans un pipeline destructif ne repose pas sur une bonne vérification — elle repose sur des vérifications redondantes à chaque point de transition, chacune ignorant si la précédente a fonctionné correctement.

Résumé

Analyser construit séparément un inventaire complet de fichiers et une carte de références, puis les compare.
Classer attribue un statut mécanique à chaque fichier connu en fonction de cette comparaison.
Protéger retire les fichiers gérés par le moteur et les fichiers protégés par politique de l'ensemble actionnable avant qu'une interface soit construite.
Réviser présente les résultats filtrés, classifiés et contextuels pour la décision humaine — avec une porte de confirmation avant toute suppression.
L'ordre est le mécanisme de sécurité. La sortie de chaque étape détermine ce que la suivante peut faire.

← Toutes les notes techniques Voir la validation des médias →