# Texture Rescue Lite 0.1.1

Find out what a missing texture breaks before changing its path.

Texture Rescue Lite inspects static image references in your Blender project, shows the objects, materials and worlds that use them, and searches a folder you choose for exact-filename replacements. It runs entirely on your computer.

## Install

1. Keep the add-on ZIP compressed.
2. In Blender, open **Edit → Preferences → Add-ons**, then the menu's **Install from Disk** action.
3. Select `texture_rescue_lite-0.1.1.zip` and enable **Texture Rescue Lite**.
4. In the 3D Viewport, press **N** to open the sidebar, then select **Texture Rescue**.

The ZIP is a standard Blender extension with a manifest. Install it from disk; no online repository or network permission is required. Its file permission is used to read the texture folder you select, reload chosen images and write CSV reports you request. The exact Blender version and operating system tested are recorded in `VALIDATION.md`. Compatibility with other versions or systems must be checked before relying on it.

## Repair a moved project's textures

1. Open a saved `.blend` project and make a backup using your normal project workflow.
2. Run **Scan Images**. Review missing images and their affected objects, materials and node paths.
3. Choose the folder containing the replacement images. Search is confined to this folder and its ordinary subfolders.
4. Run **Find Exact Matches**. Filenames must match exactly, including letter case.
5. Review every old path and proposed replacement. A unique match from a complete, error-free search is a suggestion, not proof it is the right picture. Duplicate filenames require an explicit choice: use the Candidate number (0 means no choice) to choose a numbered path. For a batch, tick Include for each intended image before Repair Selected.
6. Confirm the selected repairs. The add-on changes image references in memory and reloads those images; it does not save the project automatically.
7. Check your scene visually, then save the project yourself if you want to keep the changes.

An ordinary Ctrl/Cmd-Z undo or loading another project clears both scan and restore history; scan again before further changes. **Restore Last Repairs** is an explicit fallback for the most recent repair operation in the current session. It refuses to overwrite an image reference you changed after the repair. It is not a project backup or persistent repair history.

## What is checked

- Static, local Blender image datablocks using `FILE` source.
- Standard image texture and environment texture nodes.
- Shared materials, nested shader node groups and world shader groups.
- Exact-name replacement files in a user-selected directory.

Objects using a shared material remain visible individually. A missing image can have no detected shader user; it is still reported. Impact mapping does not certify every possible use of an image elsewhere in Blender or in a third-party renderer.

## What is deliberately held

Packed images and generated images do not need file repair. Images with unsaved pixel edits are held: save or pack those edits manually before repairing or restoring paths. Linked/read-only resources, UDIM/tiled images, multiview images, image sequences, movies and viewer images are not repaired by this version. Relative paths in an unsaved project are held until their base directory can be resolved. Keep these statuses distinct from “missing”.

The search skips file and directory symlinks. It stops after 50,000 inspected files or 100,000 filesystem entries and reports incomplete searches or access errors. Narrow the search folder if it cannot finish. A missing result from an incomplete search does not prove that no matching file exists.

Changes made after scanning are rechecked before applying or restoring paths. If the image was removed, its path changed, the source is no longer missing or the candidate cannot be loaded, refresh the scan and resolve the conflict. Do not assume the previous preview is still current. Saving the project into another directory can change relative-path meaning: rescan before new repairs. Restoring an old relative reference is blocked if its directory base changed; return to the original context or handle the path manually. Confirmation dialogs freeze their reviewed paths and reject intervening selection changes.

## Reports and privacy

CSV export is local and user initiated. Reports can include local file paths, image names and object/material names; review them before sharing. Formula-like values are escaped for spreadsheet safety. There is no telemetry, cloud upload, account, API key or subscription in the add-on.

## Compared with Blender's built-in command

Blender already provides **File → External Data → Find Missing Files**. Use it when a quick relink is sufficient. Texture Rescue Lite adds an inspectable list of affected shader users, exact-name candidates and explicit duplicate-name choices. It cannot recover a texture you do not possess, establish rights to another person's files or determine from a filename alone that two images depict the same thing.

## License and provenance

Add-on source is provided under GPL-3.0-or-later; see `LICENSE`. The demonstration scene and procedural textures were created for this project, without competitor code or third-party artwork. Development used AI assistance and automated tests under the user's product direction. No independent buyer validation or marketplace approval is claimed.