BranchPy
Se connecter

Media Validation

Excusez-nous — cette page est actuellement disponible en anglais uniquement.

La traduction française n'est pas encore prête. Le contenu ci-dessous est la version anglaise la plus récente.

Find missing assets, review unreferenced files safely, and avoid deleting engine-managed files.

When to use Media Validation

  • Before release/candidate build checks.
  • After large art/audio imports.
  • During cleanup to remove dead assets safely.

Quick run (CLI)

branchpy --project <path> media --open

Typical runtime (approx):

  • Small projects: 2-8 seconds
  • Medium projects: 10-35 seconds
  • Large projects: 30-120 seconds

What Media Validation does

Media Validation scans your project and classifies each media file into one status:

  • USED: referenced in scripts.
  • UNREFERENCED: found on disk but not currently referenced.
  • MISSING: referenced in scripts but not found on disk.
  • PROTECTED: engine-managed or policy-protected path; never offered for deletion.

This gives you an accurate inventory before runtime, so problems are found before release.

Before you run a scan

  1. Open Control Center and select your project.
  2. Open the Media Validation panel.
  3. Confirm your assets root (usually game/) is correct.

Run a full scan

  1. Click Run Full Scan.
  2. Wait for completion (you will see status updates while BranchPy runs missing, unused, and referenced scans).
  3. Review the Overview cards:
  • Total media on disk.
  • Referenced in scripts.
  • Missing on disk.
  • Unreferenced on disk.

Understanding unreferenced results (Phase 2A)

Unreferenced files are scored and grouped into review tiers:

  • Cleanup Candidate: high-confidence dead weight.
  • Needs Review: mixed signals, inspect manually.
  • Dynamic Risk: likely dynamic/runtime usage, do not delete.

Scoring uses deterministic heuristics (for example age, naming suffixes, dynamic-load tokens, folder density, and rename similarity to missing files).

Protected-path safety

BranchPy protects known engine-managed paths such as:

  • gui/
  • renpy/
  • common/
  • launcher/
  • fonts/

Protection is enforced in two layers:

  1. Protected files do not expose deletion checkboxes in the UI.
  2. Delete handling strips protected paths even if they were somehow selected.

You can also define project-specific protected path prefixes in branchpy.config.json:

{
	"mediaValidation": {
		"protectedPaths": ["game/cgs/", "game/music/licensed/"],
		"dynamicRiskPatterns": ["secret", "ending", "variant"]
	}
}

Typical workflow

  1. Fix MISSING first.
  2. Check rename candidates where an unreferenced file likely matches a missing reference.
  3. Review Needs Review and Dynamic Risk items manually.
  4. Use bulk delete only for Cleanup Candidate files after review.
  5. Re-run scan to verify clean state.

Example output pattern:

Media Validation complete

missing_images:
	- game/cg/ending.png
	- game/gui/save_button.png

unreferenced_images:
	- game/gui/button_idle.png
	- game/gui/button_hover.png

Browser and filtering tips

  • Use the usage filter (All, Referenced, Unreferenced, Missing) to focus review.
  • Open files/folders directly from results when triaging.
  • Use the Advanced Image Tools action for image-validation workflows when needed.

UI screenshots (March 2026)

Media Validation scan overview

Media Validation tiered review view

Media Validation browser and status badges

Media Validation protected-path handling

Media Validation advanced review workflow

Troubleshooting

  • Referenced count looks lower than expected: Ensure the correct project root is selected and scan completes without parser errors.
  • Too many dynamic-risk files: Review dynamicRiskPatterns in branchpy.config.json and narrow custom tokens.
  • A file should be protected but is not: Add its parent path to mediaValidation.protectedPaths and re-run.