PathPilot v1.0
==============

Path Maps for your whole project folder in a few clicks, without editing
preferences by hand.

PathPilot is a script for Blackmagic Fusion Studio. You pick your project's
root folder, and PathPilot finds every subfolder. You review the shortcuts in
one window, and it creates composition Path Maps such as footage, audio or
renders.

  - Your files are never renamed or moved.
  - Only the open composition is changed. Global preferences are never touched.
  - Path Maps that already exist in the comp are kept.


REQUIREMENTS
------------
  - Blackmagic Fusion Studio (standalone)
  - Windows, macOS or Linux


INSTALLATION
------------
1. Close Fusion.

2. Copy PathPilot.lua into Fusion's Comp scripts folder:

   Windows:  %APPDATA%\Blackmagic Design\Fusion\Scripts\Comp
   macOS:    ~/Library/Application Support/Blackmagic Design/Fusion/Scripts/Comp
   Linux:    ~/.fusion/BlackmagicDesign/Fusion/Scripts/Comp

   On Windows, paste %APPDATA%\Blackmagic Design\Fusion\Scripts\Comp into the
   Explorer address bar. If the Comp folder doesn't exist, create it.

3. Start Fusion. PathPilot appears under Scripts > Comp > PathPilot.


HOW TO USE
----------
1. Open or create a composition.

2. Run Scripts > Comp > PathPilot.

3. Choose your project's root folder.

4. In the PathPilot window:
   - Tick the folders you want shortcuts for. Ticking a parent ticks
     everything inside it, and you can still untick single folders afterwards.
   - Type in the filter box to find folders quickly. "Select all folders"
     only affects the folders currently shown.
   - Use Expand all and Collapse all to open or close the whole tree.
   - Double click a shortcut to rename it.
   - Turn on "Include parent name" for longer, more descriptive shortcuts
     (assets_audio).

5. Click Create Path Maps.

6. Save the composition. Path Maps are stored in the comp file.

The Console lists every map that was created, along with any that were
skipped.


HOW SHORTCUTS ARE NAMED
-----------------------
  - Number prefixes are removed: 01_brief becomes brief, 05_delivery becomes
    delivery. Names like 3d, 30s and mesh2 are kept.
  - Spaces and special characters become _.
  - If every folder starts with the same prefix (for example PRJ_), you can
    remove it with one click.

Repeated folder names

Shot-based projects often repeat names like comp or plates in every shot. A
shortcut also can't be the start of another one (mesh would also catch mesh2).
PathPilot fixes both automatically by adding the parent folder:

   Folder                Shortcut
   shots/SH010/mesh      mesh_010
   shots/SH020/mesh      mesh_020
   assets/mesh           mesh_assets

Shortcuts you rename yourself are never changed. Any that still clash are shown
in red, and their parent folders are tinted so you can spot them when the tree
is collapsed.


USING THE SHORTCUTS
-------------------
Path Maps appear under Path Maps in the Loader and Saver file browser sidebar.
Use them in file paths instead of long absolute paths, so the comp stays
portable when the project moves.

To remove maps later, go to File > Preferences > (your comp) > Path Maps.


TROUBLESHOOTING
---------------
  - Nothing happens: open a composition first, then run the script from
    Scripts > Comp.
  - A map was skipped: a map with the same name already exists in the comp and
    points somewhere else. The Console shows which one.
  - The maps are gone after reopening: the composition wasn't saved after
    running PathPilot.


--------------------------------------------------------------------------------
PathPilot v1.0 by Anton Grebenkin
