Installing PVRZ

[Wisp]

These functions were written by Argent77 and will be included in WeiDU 238.

Summary:
Functions for installing custom PVRZ-based BAM and MOS resources in Enhanced Edition games.

Available functions:
UPDATE_PVRZ_INDICES   Patch function. Updates the PVRZ references in the BAM v2 or MOS v2 file to the next contiguous block of free PVRZ indices.
INSTALL_PVRZ          Action function. Installs a PVRZ file and updates the PVRZ index. Use in conjunction with "UPDATE_PVRZ_INDICES".
FIND_FREE_PVRZ_INDEX  Patch or action function. Attempts to find a contiguous block of free PVRZ indices in the game installation.

Examples
~~~~~~~~

Example 1: Installing the file "mypic.bam" and associated mos0000.pvrz, mos0001.pvrz, mos0002.pvrz
           located in the folder "mymod/bam".

// Installing BAM resource
COPY ~mymod/bam/mypic.bam~ ~override~
  LPF ~UPDATE_PVRZ_INDICES~
    RET
      original_base_index
      new_base_index
    END

// It is strongly recommended to check the return values of "UPDATE_PVRZ_INDICES".
ACTION_IF (original_base_index >= 0 && new_base_index >= 0) BEGIN
  // Installing associated PVRZ resources
  ACTION_FOR_EACH file IN ~mos0000.pvrz~ ~mos0001.pvrz~ ~mos0002.pvrz~
    LAF ~INSTALL_PVRZ~
      INT_VAR
        original_base_index = original_base_index
        new_base_index      = new_base_index
      STR_VAR
        source_file         = EVAL ~mymod/bam/%file%~
    END
  END
END

In a clean game installation, this script portion will copy all files into the override folder of the game,
rename the PVRZ files to mos1000.pvrz, mos1001.pvrz, mos1002.pvrz and update the PVRZ references in
"mypic.bam" accordingly.


Example 2: Installing the files "mypic1.mos" and "mypic2.mos" which share a single PVRZ file.
           "mypic1.mos" references mos0000.pvrz, mos0001.pvrz and mos0002.pvrz.
           "mypic2.mos" references mos0002.pvrz and mos0003.pvrz.

// Installing MOS resource 1
COPY ~mymod/mos/mypic1.mos~ ~override~
  LPF ~UPDATE_PVRZ_INDICES~
    RET
      original_base_index
      new_base_index
    END

ACTION_IF (original_base_index >= 0 && new_base_index >= 0) BEGIN
  // Installing PVRZ resources associated with "mypic1.mos"
  ACTION_FOR_EACH file IN ~mos0000.pvrz~ ~mos0001.pvrz~ ~mos0002.pvrz~
    LAF ~INSTALL_PVRZ~
      INT_VAR
        original_base_index = original_base_index
        new_base_index      = new_base_index
      STR_VAR
        source_file         = EVAL ~mymod/mos/%file%~
    END
  END
END

// Installing MOS resource 2
COPY ~mymod/mos/mypic2.mos~ ~override~
  LPF ~UPDATE_PVRZ_INDICES~
    RET
      original_base_index
      new_base_index
    END

ACTION_IF (original_base_index >= 0 && new_base_index >= 0) BEGIN
  // Installing PVRZ resources associated with "mypic2.mos"
  ACTION_FOR_EACH file IN ~mos0002.pvrz~ ~mos0003.pvrz~
    LAF ~INSTALL_PVRZ~
      INT_VAR
        original_base_index = original_base_index
        new_base_index      = new_base_index
      STR_VAR
        source_file         = EVAL ~mymod/mos/%file%~
    END
  END
END

The function "UPDATE_PVRZ_INDICES" does not directly support MOS or BAM files with shared PVRZ files.
As a result, copies of the shared PVRZ files will be installed for each affected MOS or BAM file.