Template.cpp

/* File: Template.cpp
   Project: Kanabo
   Purpose: Defines the classes for every type of game data. An instance of one of these classes represents a single game data resource.
   Notes: Used by GameData to compose structured resources in memory from a game data file. See GameData.cpp's header comment for terminology.
   Margin Guide: |----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- ----- -----|
   Copyright 2026 Iritscen */

#include "Template.hpp"

#include <algorithm> // needed on Windows for std::sort
#include <array> // needed on Windows for std::array
#include <cstdio> // for fwrite() and fflush()
#include <cstdlib> // for std::strtod()
#include <format> // needed on Windows for std::format
#include <iomanip> // needed on Windows for std::quoted
#include <iostream>
#if MAC
#include <unistd.h> // for close() and mkstemp()
#endif

using std::array;
using std::cerr;
using std::copy;
using std::cout;
using std::format;
using std::function;
using std::make_unique;
using std::map;
using std::max;
using std::min;
using std::optional;
using std::pair;
using std::reference_wrapper;
using std::quoted;
using std::sort;
using std::span;
using std::stable_sort;
using std::string;
using std::to_string;
using std::unique_ptr;
using std::vector;

// Per-format order helpers
namespace
{
                                                      // WinAlpha6     PC1_0         MacBeta4      PC1_1         PS2
    constexpr array<int, 5> kAlphaOnly(int n) {return {  n,            kOrderAbsent, kOrderAbsent, kOrderAbsent, kOrderAbsent};}
    constexpr array<int, 5> kWindowsOnly(int n) {return {n,            n,            kOrderAbsent, kOrderAbsent, kOrderAbsent};}
    constexpr array<int, 5> kRetailOnly(int n) {return { kOrderAbsent, n,            n,            n,            n};}
    constexpr array<int, 5> kMacAndPS2(int n) {return {  kOrderAbsent, kOrderAbsent, n,            n,            n};}
    constexpr array<int, 5> kMacOnly(int n) {return {    kOrderAbsent, kOrderAbsent, n,            n,            kOrderAbsent};}
    constexpr array<int, 5> kPS2Only(int n) {return {    kOrderAbsent, kOrderAbsent, kOrderAbsent, kOrderAbsent, n};}
    constexpr array<int, 5> kNotPS2(int n) {return {     n,            n,            n,            n,            kOrderAbsent};}

    auto FormatUsesSepForBINA = [](Format f) {return (f >= Format::PC1_1);}; // BINA is found in separate file starting with v1.1, not beta 4
    auto BAP = [](uint32_t offset) {return (32 - (offset % 32)) % 32;}; // byte alignment padding
}

/****************************** Template ******************************/
// Fundamental base class used for polymorphic collections of Template____ objects; it is subclassed in order to create structs designed for the
// data payload of each type of game resource. See TemplateONCC for model comments that apply to all child classes.
Template::Template(string tagName, string instName, Format dataFormat)
        : vwvlaSizeOffset_(0x0),
          hasLinks_(false),
          hasAuxData_(false),
          hasPaletteData_(false),
          hasSoundData_(false),
          certified_(false),
          tag_(std::move(tagName)),
          name_(std::move(instName)),
          origFormat_(dataFormat),
          curFormat_(dataFormat),
          instDataSize_(0),
          auxDataSize_(0),
          isPlaceholder_(false),
          isUnnamed_(false),
          index_("index", 0),
          level_("level", 1),
          indexNew_("index (for writing)"),
          levelNew_("level (for writing)"),
          fields_{&index_, &level_}
{
    
}

// Sort "fields_" in place for the given format: sort by authored order (present fields first in ascending order, absent fields last), then walk
// the sorted present fields to compute each one's offset from the cumulative size of preceding fields. After this call, callers can iterate
// "fields_" directly and break when field->offset() == kOffsetAbsent.
void Template::sortFieldsFor(Format fmt)
{
    // Sort by order for this format: present fields first (ascending), absent fields last
    stable_sort(fields_.begin(), fields_.end(), [fmt](Field * a, Field * b) // NOLINT(bugprone-nondeterministic-pointer-iteration-order)
    {
        int oa = a->orderFor(fmt), ob = b->orderFor(fmt);
        if (oa == kOrderAbsent) return false;
        if (ob == kOrderAbsent) return true;
        return oa < ob;
    });

    // Compute offsets from accumulated sizes and set "curFormat_" on each field
    uint32_t runningOffset = 0;
    for (auto * field : fields_)
    {
        field->setCurrentFormat(fmt);
        if (field->orderFor(fmt) == kOrderAbsent)
        {
            field->offset() = kOffsetAbsent;
            continue;
        }
        field->offset() = runningOffset;
        runningOffset += field->size();
    }
    
    // Save our newly calculated size
    instDataSize_ = runningOffset;
}

// Same as sortFieldsFor() but operates on "fieldsAux_" and updates "auxDataSize_"
// Note: Templates that fully override processAuxData() (bypassing this call) are responsible for setting "auxDataSize_" themselves
void Template::sortFieldsAuxFor(Format fmt)
{
    stable_sort(fieldsAux_.begin(), fieldsAux_.end(), [fmt](Field * a, Field * b) // NOLINT(bugprone-nondeterministic-pointer-iteration-order)
    {
        int oa = a->orderFor(fmt), ob = b->orderFor(fmt);
        if (oa == kOrderAbsent) return false;
        if (ob == kOrderAbsent) return true;
        return oa < ob;
    });

    uint32_t runningOffset = 0;
    for (auto * field : fieldsAux_)
    {
        field->setCurrentFormat(fmt);
        if (field->orderFor(fmt) == kOrderAbsent)
        {
            field->offset() = kOffsetAbsent;
            continue;
        }
        field->offset() = runningOffset;
        runningOffset += field->size();
    }

    auxDataSize_ = runningOffset;
}

// Process full data payload from the level data file
void Template::processData(span<char> dataPacket)
{
    // Give the template a chance to create and add its variable array fields to "fields_" before we iterate over them
    bool fwvlaSafetyExceeded = false;
    uint32_t arraySize = 0, arraySizeToUse = 0;
    static constexpr uint32_t kVarArraySizeSafety = 300'000; // largest observed array size is AKOT IDXA for alpha's level18 which is 200,300
    if (hasFWVarArray())
    {
        if (fwvlaSizeOffset_.second == 16)
        {
            uint16_t arraySize16 = 0;
            DataIO::ReadNum(arraySize16, dataPacket, fwvlaSizeOffset_.first);
            arraySize = arraySize16;
        }
        else
            DataIO::ReadNum(arraySize, dataPacket, fwvlaSizeOffset_.first);

        // Important safety check in the event that we erroneously read a very large number from the data
        if (arraySize > kVarArraySizeSafety)
        {
            arraySizeToUse = kVarArraySizeSafety;
            fwvlaSafetyExceeded = true;
        }
        else
            arraySizeToUse = arraySize;

        createFWVarArray(static_cast<int32_t>(arraySizeToUse));
    }

    // Sort fields for "origFormat_" and set "curFormat_" member in each field
    sortFieldsFor(origFormat_);

    // Read in the data for each field
    for (auto * field : fields_)
    {
        if (field->offset() == kOffsetAbsent)
            break;
        DataIO::ReadData(field->var(), dataPacket, field->offset(), field->fixedSize());
    }

    // Adjust these values for the left-shifts Bungie applied to them when saving to disk
    index_.val() >>= 8;
    level_.val() >>= 25;

    postProcessData(dataPacket);

    if (fwvlaSafetyExceeded)
        cerr << "Warning: Fixed-width variable array size of " << arraySize << " in instance " << quoted(name_) << " (#" << index_.val()
             << ") exceeds the safety limit of " << kVarArraySizeSafety << "; capped at " << kVarArraySizeSafety << ".\n";
}

// Iterate over "fieldsAux_" to process the aux data payload (if there is one). Calls prepareAuxFields() first so that subclasses can determine
// the size of any dynamic fields, then sortFieldsAuxFor() to compute per-field offsets (also sets "auxDataSize_"), then reads each field at
// auxFieldsBaseOffset() + field offset.
void Template::processAuxData(vector<char> & dataPacket)
{
    // Give the template a chance to create and add variable array fields to "auxFields_" before we iterate over them
    bool vwvlaSafetyExceeded = false;
    uint32_t arraySize = 0, arraySizeToUse = 0, nextObjSize = 0, lastObjSize = 0;
    static constexpr uint32_t kVarArraySizeSafety = 300; // largest observed array size is 138 in the BINA CHAR of level8
    static constexpr uint32_t kObjSizeSafety = 10'000; // largest observed object size is 5416 bytes for MELE
    if (vwvlaSizeOffset_)
    {
        size_t sizeOffset = auxFieldsBaseOffset() + vwvlaSizeOffset_;
        DataIO::ReadNum(nextObjSize, dataPacket, sizeOffset);
        vwvlaObjectSizes_.clear();
        while (nextObjSize > 0)
        {
            if (nextObjSize > kObjSizeSafety)
            {
                cerr << "Warning: Next object size of " << nextObjSize << " exceeds object size safety limit of " << kObjSizeSafety << ".\n";
                break;
            }

            arraySize++;
            vwvlaObjectSizes_.push_back(nextObjSize);
            sizeOffset += nextObjSize + 4; // advance past this int32 field and the next object to find the next size
            lastObjSize = nextObjSize;
            if (not DataIO::ReadNum(nextObjSize, dataPacket, sizeOffset))
            {
                cerr << "Warning: Failure to read next object size in array.\n";
                break;
            }
        }
        
        // Important safety check in the event that we erroneously read a very large number from the data
        if (arraySize > kVarArraySizeSafety)
        {
            cerr << "Warning: Variable-width variable array size of " << arraySize << " in instance " << quoted(name_)
                 << " exceeds the safety limit of " << kVarArraySizeSafety << "; capping at " << kVarArraySizeSafety << ".\n";
            arraySizeToUse = kVarArraySizeSafety;
        }
        else
            arraySizeToUse = arraySize;
        
        createVWVarArray(static_cast<int32_t>(arraySizeToUse), lastObjSize, dataPacket);
    }

    if (fieldsAux_.empty())
        return;

    prepareAuxFields();
    sortFieldsAuxFor(origFormat_);
    size_t baseOffset = auxFieldsBaseOffset();
    for (auto * field : fieldsAux_)
    {
        if (field->offset() == kOffsetAbsent)
            break;
        DataIO::ReadData(field->var(), dataPacket, field->offset() + baseOffset, field->fixedSize());
    }
    postProcessAux();

    if (vwvlaSafetyExceeded)
        cerr << "Warning: Variable-width variable array size of " << arraySize << " in instance " << quoted(name_) << " (#" << index_.val()
             << ") exceeds the safety limit of " << kVarArraySizeSafety << "; capped at " << kVarArraySizeSafety << ".\n";
}

// Get the names of any resources linked by name from this one. GameData must pass us a lookup function in order to allow us to see the other
// instances in GameData's memory. Then we pass it to any FieldLink member that is possibly within this Template subclass so it can perform the
// actual lookup. It ain't pretty but it seemed like the best solution for sending information from GameData -> Template -> Field. Alternately
// GameData could iterate all fields in each instance as it creates them and then attempt to call FieldLink::resolveLink() on them, but this
// would be piercing two layers directly, GameData -> Field, and I didn't like that thought too much.
void Template::processLinks(const function<string(int)> & lookupFn)
{
    if (lookupFn)
    {
        // Iterate over every field and try to call FieldLink::resolveLink(), passing it the lookup function we got from GameData; the method is
        // only defined for class FieldLink. We could test with dynamic_cast if each field is class FieldLink and only call resolveLink() for
        // those fields, but it would be much slower.
        for (auto * field : fields_)
        {
            if (field->offset() == kOffsetAbsent)
                break;
            field->resolveLink(lookupFn);
        }
        for (auto * field : fieldsAux_)
        {
            if (field->offset() == kOffsetAbsent)
                break;
            field->resolveLink(lookupFn);
        }
    }
}

// Print out every field, relying on each Field___ class's str() method to smartly print its data
string Template::report(bool showOffsets, const string & filterField, const string & filterValue)
{
    // Lambda for wildcard field name matching. Supports '-' as a wildcard matching any sequence of characters.
    auto fieldNameMatchesPattern = [](const string & fieldName, const string & pattern) -> bool
    {
        size_t ni = 0, pi = 0, lastStar = string::npos, lastNi = 0;
        const size_t n = fieldName.size(), p = pattern.size();
        while (ni < n)
        {
            if (pi < p && pattern[pi] == '-')
            {
                lastStar = pi++;
                lastNi = ni;
            }
            else if (pi < p && pattern[pi] == fieldName[ni])
            {
                ++ni; ++pi;
            }
            else if (lastStar != string::npos)
            {
                pi = lastStar + 1;
                ni = ++lastNi;
            }
            else
                return false;
        }
        while (pi < p && pattern[pi] == '-')
            ++pi;
        return pi == p;
    };

    // Iterate and print the instance data fields
    string s;
    for (auto * field : fields_)
    {
        if (field->offset() == kOffsetAbsent)
            break;
        if (not filterField.empty() && not fieldNameMatchesPattern(field->name(), filterField))
            continue;
        if (not filterValue.empty() && not field->matchesFilter(filterValue))
            continue;
        if (field->show() /*&& field->name() != "index" && field->name() != "level"*/)
        {
            if (showOffsets)
                s += format("  {} (0x{:X}): {}\n", field->name(), field->offset(), field->str());
            else
                s += format("  {}: {}\n", field->name(), field->str());
        }
    }

    // Iterate and print the aux data fields
    for (auto * field : fieldsAux_)
    {
        if (field->offset() == kOffsetAbsent)
            break;
        if (not filterField.empty() && not fieldNameMatchesPattern(field->name(), filterField))
            continue;
        if (not filterValue.empty() && not field->matchesFilter(filterValue))
            continue;
        if (field->show())
        {
            if (showOffsets)
                s += format("  {} (0x{:X}): {}\n", field->name(), field->offset(), field->str());
            else
                s += format("  {}: {}\n", field->name(), field->str());
        }
    }

    return s;
}

// Return just the size of the instance data in the level data file, i.e. the total of all fields in "fields_"
uint32_t Template::dataSize()
{
    return instDataSize_;
}

// Return just the size of the instance data in the level data file, i.e. the total of all fields in "fields_"
uint32_t Template::auxDataSize()
{
    return auxDataSize_;
}

// Like auxDataSize() but includes the 32-byte alignment padding that OniSplit inserts between sections in multi-section templates (e.g. TRAM)
uint32_t Template::auxDataSizeAligned()
{
    if (auxSectionAnchors_.size() <= 1)
        return auxDataSize_;
    uint32_t total = 0;
    for (size_t i = 0; i < auxSectionAnchors_.size(); i++)
    {
        uint32_t sectionStart = auxSectionAnchors_[i].second->offset();
        uint32_t sectionEnd = (i + 1 < auxSectionAnchors_.size())
                              ? auxSectionAnchors_[i + 1].second->offset()
                              : auxDataSize_;
        total += sectionEnd - sectionStart;
        if (i + 1 < auxSectionAnchors_.size())
            total += BAP(total);
    }
    return total;
}

// Return total size of data from both the level data file and the raw/separate file
uint32_t Template::totalSize()
{
    return instDataSize_ + auxDataSize_;
}

// Stage the value each aux-data offset field should hold when this instance is exported, given the file offset where its aux block will begin.
// The exported value is written to defVar() so the field's original on-disk value (used for reporting) is preserved. The single-section case
// (one contiguous aux blob located by one offset field) is the default; multi-section templates describe their layout in "auxSectionAnchors_",
// each section's offset field pointing at the start of its data within the contiguous blob (the section's first field's combined offset).
void Template::assignExportAuxOffsets(uint32_t auxBlockStart)
{
    if (auxSectionAnchors_.empty())
    {
        for (auto * field : fields_)
            if (field->getAuxOffset())
                field->defVar() = auxBlockStart;
    }
    else
    {
        // Walk each section in order, aligning each one's start to a 32-byte boundary after the previous section ends
        uint32_t sectionStart = auxBlockStart;
        for (size_t i = 0; i < auxSectionAnchors_.size(); i++)
        {
            auto & [offsetField, firstField] = auxSectionAnchors_[i];
            offsetField->defVar() = sectionStart;
            size_t nextPackedOffset = (i + 1 < auxSectionAnchors_.size())
                                    ? auxSectionAnchors_[i + 1].second->offset()
                                    : auxDataSize_;
            uint32_t sectionEnd = sectionStart + static_cast<uint32_t>(nextPackedOffset - firstField->offset());
            sectionStart = sectionEnd + BAP(sectionEnd);
        }
    }
}

void Template::createKnowledgeVarFields()
{
    if (hasFWVarArray())
        createFWVarArray(1);
    if (vwvlaSizeOffset_)
    {
        vector<char> emptyData;
        createVWVarArray(1, 0, emptyData);
    }
}

/**************************** TemplateBINA ****************************/
/* The only purpose of this class is to serve as a parent for the BINA subtypes below; it is not used directly */
TemplateBINA::TemplateBINA(string tagName, string instName, Format dataFormat)
            : Template(std::move(tagName), std::move(instName), dataFormat),
              binaSize("aux data size",     2),
              binaOffset("aux data offset", 3)
{
    hasAuxData_ = true;
    certified_ = true;

    fields_.insert(fields_.end(), {&binaSize, &binaOffset});
}

unique_ptr<Template> TemplateBINA::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateBINA>("BINA", instName, dataFormat);
}

uint32_t TemplateBINA::binaDataSize()
{
    return binaSize.val();
}

uint32_t TemplateBINA::binaDataOffset()
{
    return binaOffset.val();
}

size_t TemplateBINA::auxFieldsBaseOffset()
{
    return binaDataOffset();
}

bool TemplateBINA::hasSepData()
{
    // Mac beta 4, which predated the Windows gold master by a few days, still had the BINA data stored in the raw file even though separate
    // files had been introduced to the Mac builds
    return FormatUsesSepForBINA(origFormat_);
}

/************************* TemplateBINA_OBJC *************************/
TemplateBINA_OBJC::TemplateBINA_OBJC(string tagName, string instName, Format dataFormat)
                 : TemplateBINA(std::move(tagName), std::move(instName), dataFormat),
                   binaSubtype("BINA subtype tag", 1),
                   objcListSize("OBJC list size",  2),
                   objcVersion("OBJC version",     3)
{
    certified_ = true;

    objectFlagValues =
    {
        {OFLocked, 0x1},
        {OFPlaced, 0x2},
        {OFTemp,   0x3},
        {OFGunk,   0x4}
    };
    objectFlagNames =
    {
        {OFLocked, "locked"},
        {OFPlaced, "placed by tool"},
        {OFTemp,   "to be deleted"},
        {OFGunk,   "has gunk in env"}
    };

    fieldsAux_.insert(fieldsAux_.end(), {&binaSubtype, &objcListSize, &objcVersion});
}

unique_ptr<Template> TemplateBINA_OBJC::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateBINA_OBJC>("BINA/OBJC", instName, dataFormat);
}

/*********************** TemplateBINA_OBJC_CHAR ***********************/
TemplateBINA_OBJC_CHAR::TemplateBINA_OBJC_CHAR(string instName, Format dataFormat)
                      : TemplateBINA_OBJC("BINA/OBJC/CHAR", std::move(instName), dataFormat)
{
    certified_ = true;

    vwvlaSizeOffset_ = 0x0C;

    charFlagValues =
    {
        {IsPlayer,    0x1},
        {RandVariant, 0x2},
        {NotInitial,  0x4},
        {NPC,         0x8},
        {MultSpawn,   0x10},
        {Spawned,     0x20},
        {Unkillable,  0x40},
        {Superammo,   0x80},
        {Omniscient,  0x100},
        {HasLSI,      0x200},
        {IsBoss,      0x400},
        {HardUpgrade, 0x800},
        {NoAutoDrop,  0x1000}
    };
    charFlagNames =
    {
        {IsPlayer,    "player"},
        {RandVariant, "random variant"},
        {NotInitial,  "not initially spawned"},
        {NPC,         "non-combatant"},
        {MultSpawn,   "can multiply spawn"},
        {Spawned,     "spawned (runtime)"},
        {Unkillable,  "un-killable"},
        {Superammo,   "infinite ammo"},
        {Omniscient,  "omniscient"},
        {HasLSI,      "has LSI"},
        {IsBoss,      "boss"},
        {HardUpgrade, "upgrade on Hard"},
        {NoAutoDrop,  "no auto-drop"}
    };

    jobTypeValues =
    {
        {JTNone,     0},
        {Idle,       1},
        {Guard,      2},
        {Patrol,     3},
        {TeamBattle, 4}
    };
    jobTypeNames =
    {
        {JTNone,     "None"},
        {Idle,       "Idle"},
        {Guard,      "Guard"},
        {Patrol,     "Patrol"},
        {TeamBattle, "Team Battle"}
    };

    teamNumValues =
    {
        {Konoko,             0},
        {TCTF,               1},
        {Syndicate,          2},
        {Neutral,            3},
        {SecurityGuard,      4},
        {RogueKonoko,        5},
        {Switzerland,        6},
        {SyndicateAccessory, 7}
    };
    teamNumNames =
    {
        {Konoko,             "Konoko"},
        {TCTF,               "TCTF"},
        {Syndicate,          "Syndicate"},
        {Neutral,            "Neutral"},
        {SecurityGuard,      "Security"},
        {RogueKonoko,        "Rogue Konoko"},
        {Switzerland,        "Switzerland"},
        {SyndicateAccessory, "Syndicate Accessory"}
    };

    alertLevelValues =
    {
        {Lull,   0},
        {Low,    1},
        {Medium, 2},
        {High,   3},
        {Combat, 4}
    };
    alertLevelNames =
    {
        {Lull,   "Lull"},
        {Low,    "Low"},
        {Medium, "Medium"},
        {High,   "High"},
        {Combat, "Combat"}
    };
    
    pursuitModeValues =
    {
        {PMNone, 0},
        {Forget, 1},
        {GoTo,   2},
        {Wait,   3},
        {Look,   4},
        {Move,   5},
        {Hunt,   6},
        {Glance, 7}
    };
    pursuitModeNames =
    {
        {PMNone, "None"},
        {Forget, "Forget"},
        {GoTo,   "GoTo"},
        {Wait,   "Wait"},
        {Look,   "Look"},
        {Move,   "Move"},
        {Hunt,   "Hunt"},
        {Glance, "Glance"}
    };
    
    pursuitLostValues =
    {
        {ReturnToJob, 0},
        {KeepLooking, 1},
        {FindAlarm,   2}
    };
    pursuitLostNames =
    {
        {ReturnToJob, "Return to job"},
        {KeepLooking, "Keep looking"},
        {FindAlarm,   "Find alarm"}
    };
}

unique_ptr<Template> TemplateBINA_OBJC_CHAR::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateBINA_OBJC_CHAR>(instName, dataFormat);
}

void TemplateBINA_OBJC_CHAR::createVWVarArray(int32_t arraySize, uint32_t lastObjSize, vector<char> & /*dataPacket*/)
{
    // Some levels in Win A6 have a different CHAR format than others, so here we validate that the object size is one of the three known values
    // and then we make a note of which alpha variant of CHAR is in play so that we can hide/show a single field that differs between them
    uint32_t correctWidthRel = 544, correctWidthAl1 = 448, correctWidthAl2 = 480;
    bool alphaVariant2 = (origFormat_ == Format::WinAlpha6 && lastObjSize == correctWidthAl2);
    if (lastObjSize > 0) // GameDataManager::reportKnowledge() will pass us 0 because it's manufacturing a dummy object
    {
        if ((origFormat_ > Format::WinAlpha6 && lastObjSize != correctWidthRel) ||
            ((origFormat_ == Format::WinAlpha6 && lastObjSize != correctWidthAl1) &&
             (origFormat_ == Format::WinAlpha6 && lastObjSize != correctWidthAl2)))
        {
            cerr << "Error: CHAR: Incorrect object size (" << lastObjSize << ") passed in for variable array. Expected ";
            if (origFormat_ == Format::WinAlpha6)
                cerr << correctWidthAl1 << " or " << correctWidthAl2 << ".\n";
            else
                cerr << correctWidthRel << ".\n";
            return;
        }
    }

    const size_t sz = static_cast<size_t>(arraySize);
    objcNextSize.reserve(sz + 1); // +1 for the zero terminator at end of list
    objcSubtype.reserve(sz);
    objcID.reserve(sz);
    objcFlags.reserve(sz);
    objcPosX.reserve(sz);
    objcPosY.reserve(sz);
    objcPosZ.reserve(sz);
    objcRotX.reserve(sz);
    objcRotY.reserve(sz);
    objcRotZ.reserve(sz);
    charFlags.reserve(sz);
    charClass.reserve(sz);
    charName.reserve(sz);
    weapName.reserve(sz);
    fnSpawn.reserve(sz);
    fnDie.reserve(sz);
    fnNotice.reserve(sz);
    fnAlarm.reserve(sz);
    fnHurt.reserve(sz);
    fnDefeat.reserve(sz);
    fnOutOfAmmo.reserve(sz);
    fnNoPath.reserve(sz);
    healthDelta.reserve(sz);
    jobType.reserve(sz);
    patrolPathID.reserve(sz);
    combatID.reserve(sz);
    meleeID.reserve(sz);
    neutralID.reserve(sz);
    invAmmoUse.reserve(sz);
    invAmmoDrop.reserve(sz);
    invCellsUse.reserve(sz);
    invCellsDrop.reserve(sz);
    invHypoUse.reserve(sz);
    invHypoDrop.reserve(sz);
    invShieldUse.reserve(sz);
    invShieldDrop.reserve(sz);
    invCloakUse.reserve(sz);
    invCloakDrop.reserve(sz);
    invUnusedUse.reserve(sz);
    invUnusedDrop.reserve(sz);
    teamNum.reserve(sz);
    clipPerc.reserve(sz);
    alertInitial.reserve(sz);
    alertMinimum.reserve(sz);
    alertJobStart.reserve(sz);
    alertInvestigate.reserve(sz);
    alarmGroups.reserve(sz);
    pursuitStrongUnseen.reserve(sz);
    pursuitWeakUnseen.reserve(sz);
    pursuitStrongSeen.reserve(sz);
    pursuitWeakSeen.reserve(sz);
    pursuitLost.reserve(sz);
    
    int s = static_cast<int>(fieldsAux_.size()) + 1; // resume adding fields after TemplateBINA_OBJC's fields were added
    int nf = 52; // number of fields that we're adding (OBJC header + CHAR fields)
    for (int32_t i = 0; i < arraySize; ++i)
    {
        objcNextSize.emplace_back("next object size [" + to_string(i) + "]",                s + (nf * i) + 0);
        objcSubtype.emplace_back("OBJC subtype [" + to_string(i) + "]",                     s + (nf * i) + 1);
        objcID.emplace_back("object ID [" + to_string(i) + "]",                             s + (nf * i) + 2);
        objcFlags.emplace_back("object flags [" + to_string(i) + "]",                       s + (nf * i) + 3, true, true, 0, 0,
                               &objectFlagValues, &objectFlagNames);
        objcPosX.emplace_back("position X [" + to_string(i) + "]",                          s + (nf * i) + 4);
        objcPosY.emplace_back("position Y [" + to_string(i) + "]",                          s + (nf * i) + 5);
        objcPosZ.emplace_back("position Z [" + to_string(i) + "]",                          s + (nf * i) + 6);
        objcRotX.emplace_back("rotation X [" + to_string(i) + "]",                          s + (nf * i) + 7);
        objcRotY.emplace_back("rotation Y [" + to_string(i) + "]",                          s + (nf * i) + 8);
        objcRotZ.emplace_back("rotation Z [" + to_string(i) + "]",                          s + (nf * i) + 9);
        charFlags.emplace_back("character flags [" + to_string(i) + "]",                    s + (nf * i) + 10, true, true, 0, 0,
                               &charFlagValues, &charFlagNames);
        charClass.emplace_back("character class [" + to_string(i) + "]",                    s + (nf * i) + 11, true, true, "", "", 64);
        charName.emplace_back("character name [" + to_string(i) + "]",                      s + (nf * i) + 12, true, true, "", "", 32);
        weapName.emplace_back("weapon name [" + to_string(i) + "]",                         s + (nf * i) + 13, true, true, "", "", 64);
        fnSpawn.emplace_back("spawn script [" + to_string(i) + "]",                         s + (nf * i) + 14, true, true, "", "", 32);
        fnDie.emplace_back("death script [" + to_string(i) + "]",                           s + (nf * i) + 15, true, true, "", "", 32);
        fnNotice.emplace_back("notice script [" + to_string(i) + "]",                       s + (nf * i) + 16, true, true, "", "", 32);
        fnAlarm.emplace_back("alarm script [" + to_string(i) + "]",                         s + (nf * i) + 17, true, true, "", "", 32);
        fnHurt.emplace_back("hurt script [" + to_string(i) + "]",                           s + (nf * i) + 18, true, true, "", "", 32);
        if (alphaVariant2)
            fnDefeat.emplace_back("defeat script [" + to_string(i) + "]",                   s + (nf * i) + 19, true, true, "", "", 32);
        else
            fnDefeat.emplace_back("defeat script [" + to_string(i) + "]",                   kRetailOnly(s + (nf * i) + 19), true, true, "", "",
                                  32);
        fnOutOfAmmo.emplace_back("out of ammo script [" + to_string(i) + "]",               kRetailOnly(s + (nf * i) + 20), true, true, "", "",
                                 32);
        fnNoPath.emplace_back("no path script [" + to_string(i) + "]",                      kRetailOnly(s + (nf * i) + 21), true, true, "", "",
                              32);
        healthDelta.emplace_back("health delta [" + to_string(i) + "]",                     s + (nf * i) + 22);
        jobType.emplace_back("job type [" + to_string(i) + "]",                             s + (nf * i) + 23, true, true, 0, 0, &jobTypeValues,
                             &jobTypeNames);
        patrolPathID.emplace_back("patrol path ID [" + to_string(i) + "]",                  s + (nf * i) + 24);
        combatID.emplace_back("combat ID [" + to_string(i) + "]",                           s + (nf * i) + 25);
        meleeID.emplace_back("melee ID [" + to_string(i) + "]",                             s + (nf * i) + 26);
        neutralID.emplace_back("neutral ID [" + to_string(i) + "]",                         s + (nf * i) + 27);
        invAmmoUse.emplace_back("ballistic ammo (use) [" + to_string(i) + "]",              s + (nf * i) + 28);
        invAmmoDrop.emplace_back("ballistic ammo (drop) [" + to_string(i) + "]",            s + (nf * i) + 29);
        invCellsUse.emplace_back("energy cells (use) [" + to_string(i) + "]",               s + (nf * i) + 30);
        invCellsDrop.emplace_back("energy cells (drop) [" + to_string(i) + "]",             s + (nf * i) + 31);
        invHypoUse.emplace_back("hypos (use) [" + to_string(i) + "]",                       s + (nf * i) + 32);
        invHypoDrop.emplace_back("hypos (drop) [" + to_string(i) + "]",                     s + (nf * i) + 33);
        invShieldUse.emplace_back("shield (use) [" + to_string(i) + "]",                    s + (nf * i) + 34);
        invShieldDrop.emplace_back("shield (drop) [" + to_string(i) + "]",                  s + (nf * i) + 35);
        invCloakUse.emplace_back("cloak (use) [" + to_string(i) + "]",                      s + (nf * i) + 36);
        invCloakDrop.emplace_back("cloak (drop) [" + to_string(i) + "]",                    s + (nf * i) + 37);
        invUnusedUse.emplace_back("unused item (use) [" + to_string(i) + "]",               s + (nf * i) + 38);
        invUnusedDrop.emplace_back("unused item (drop) [" + to_string(i) + "]",             s + (nf * i) + 39);
        teamNum.emplace_back("team [" + to_string(i) + "]",                                 s + (nf * i) + 40, true, true, 0, 0, &teamNumValues,
                             &teamNumNames);
        clipPerc.emplace_back("clip percentage [" + to_string(i) + "]",                     s + (nf * i) + 41);
        alertInitial.emplace_back("initial alert [" + to_string(i) + "]",                   s + (nf * i) + 42, true, true, 0, 0,
                                  &alertLevelValues, &alertLevelNames);
        alertMinimum.emplace_back("minimum alert [" + to_string(i) + "]",                   s + (nf * i) + 43, true, true, 0, 0,
                                  &alertLevelValues, &alertLevelNames);
        alertJobStart.emplace_back("job start alert [" + to_string(i) + "]",                s + (nf * i) + 44, true, true, 0, 0,
                                   &alertLevelValues, &alertLevelNames);
        alertInvestigate.emplace_back("investigate alert [" + to_string(i) + "]",           s + (nf * i) + 45, true, true, 0, 0,
                                      &alertLevelValues, &alertLevelNames);
        alarmGroups.emplace_back("alarm groups [" + to_string(i) + "]",                     s + (nf * i) + 46);
        pursuitStrongUnseen.emplace_back("pursuit (strong, unseen) [" + to_string(i) + "]", s + (nf * i) + 47, true, true, 0, 0,
                                         &pursuitModeValues, &pursuitModeNames);
        pursuitWeakUnseen.emplace_back("pursuit (weak, unseen) [" + to_string(i) + "]",     s + (nf * i) + 48, true, true, 0, 0,
                                       &pursuitModeValues, &pursuitModeNames);
        pursuitStrongSeen.emplace_back("pursuit (strong, seen) [" + to_string(i) + "]",     s + (nf * i) + 49, true, true, 0, 0,
                                       &pursuitModeValues, &pursuitModeNames);
        pursuitWeakSeen.emplace_back("pursuit (weak, seen) [" + to_string(i) + "]",         s + (nf * i) + 50, true, true, 0, 0,
                                     &pursuitModeValues, &pursuitModeNames);
        pursuitLost.emplace_back("pursuit (lost) [" + to_string(i) + "]",                   s + (nf * i) + 51, true, true, 0, 0,
                                 &pursuitLostValues, &pursuitLostNames);
    }

    for (size_t i = 0; i < sz; ++i)
        fieldsAux_.insert(fieldsAux_.end(), {&objcNextSize[i], &objcSubtype[i], &objcID[i], &objcFlags[i], &objcPosX[i], &objcPosY[i],
                                             &objcPosZ[i], &objcRotX[i], &objcRotY[i], &objcRotZ[i], &charFlags[i], &charClass[i], &charName[i],
                                             &weapName[i], &fnSpawn[i], &fnDie[i], &fnNotice[i], &fnAlarm[i], &fnHurt[i], &fnDefeat[i],
                                             &fnOutOfAmmo[i], &fnNoPath[i], &healthDelta[i], &jobType[i], &patrolPathID[i], &combatID[i],
                                             &meleeID[i], &neutralID[i], &invAmmoUse[i], &invAmmoDrop[i], &invCellsUse[i], &invCellsDrop[i],
                                             &invHypoUse[i], &invHypoDrop[i], &invShieldUse[i], &invShieldDrop[i], &invCloakUse[i],
                                             &invCloakDrop[i], &invUnusedUse[i], &invUnusedDrop[i], &teamNum[i], &clipPerc[i], &alertInitial[i],
                                             &alertMinimum[i], &alertJobStart[i], &alertInvestigate[i], &alarmGroups[i],
                                             &pursuitStrongUnseen[i], &pursuitWeakUnseen[i], &pursuitStrongSeen[i], &pursuitWeakSeen[i],
                                             &pursuitLost[i]});

    // Add the closing zero-value next-object field that terminates the OBJC list
    objcNextSize.emplace_back("next object size [end]", s + (nf * arraySize));
    fieldsAux_.push_back(&objcNextSize.back());
}

/*********************** TemplateBINA_OBJC_CMBT ***********************/
TemplateBINA_OBJC_CMBT::TemplateBINA_OBJC_CMBT(string instName, Format dataFormat)
                      : TemplateBINA_OBJC("BINA/OBJC/CMBT", std::move(instName), dataFormat)
{
    certified_ = true;

    vwvlaSizeOffset_ = 0x0C;

    behaviorTypeValues =
    {
        {BTNone,           0},
        {Stare,            1},
        {HoldAndFire,      2},
        {FiringCharge,     3},
        {Melee,            4},
        {BarabbasShoot,    5},
        {BarabbasAdvance,  6},
        {BarabbasMelee,    7},
        {SNinjaFireball,   8},
        {SNinjaAdvance,    9},
        {SNinjaMelee,      10},
        {RunForAlarm,      11},
        {MMuroMelee,       12},
        {MMuroThunderbolt, 13}
    };
    behaviorTypeNames =
    {
        {BTNone,           "None"},
        {Stare,            "Stare"},
        {HoldAndFire,      "Hold And Fire"},
        {FiringCharge,     "Firing Charge"},
        {Melee,            "Melee"},
        {BarabbasShoot,    "Barabbas Shoot"},
        {BarabbasAdvance,  "Barabbas Advance"},
        {BarabbasMelee,    "Barabbas Melee"},
        {SNinjaFireball,   "SNinja Fireball"},
        {SNinjaAdvance,    "SNinja Advance"},
        {SNinjaMelee,      "SNinja Melee"},
        {RunForAlarm,      "Run For Alarm"},
        {MMuroMelee,       "MMuro Melee"},
        {MMuroThunderbolt, "MMuro Thunderbolt"}
    };

    meleeOverrideValues =
    {
        {MONo,        0},
        {IfPunched,   1},
        {Canceled,    2},
        {ShortRange,  3},
        {MediumRange, 4},
        {AlwaysMelee, 5}
    };
    meleeOverrideNames =
    {
        {MONo,        "No"},
        {IfPunched,   "If Punched"},
        {Canceled,    "Canceled"},
        {ShortRange,  "Short Range"},
        {MediumRange, "Medium Range"},
        {AlwaysMelee, "Always Melee"}
    };

    noGunBehaviorValues =
    {
        {NGMelee,    0},
        {Retreat,    1},
        {RunToAlarm, 2}
    };
    noGunBehaviorNames =
    {
        {NGMelee,    "Melee"},
        {Retreat,    "Retreat"},
        {RunToAlarm, "Run To Alarm"}
    };
}

unique_ptr<Template> TemplateBINA_OBJC_CMBT::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateBINA_OBJC_CMBT>(instName, dataFormat);
}

void TemplateBINA_OBJC_CMBT::createVWVarArray(int32_t arraySize, uint32_t lastObjSize, vector<char> & /*dataPacket*/)
{
    uint32_t correctWidth = (origFormat_ == Format::WinAlpha6 ? 156U : 180U);
    if (lastObjSize > 0 && lastObjSize != correctWidth)
    {
        cerr << "Error: CMBT: Incorrect object size (" << lastObjSize << " vs. " << correctWidth << ") passed in for variable array.\n";
        return;
    }

    const size_t sz = static_cast<size_t>(arraySize);
    objcNextSize.reserve(sz + 1); // +1 for the zero terminator at end of list
    objcSubtype.reserve(sz);
    objcID.reserve(sz);
    objcFlags.reserve(sz);
    objcPosX.reserve(sz);
    objcPosY.reserve(sz);
    objcPosZ.reserve(sz);
    objcRotX.reserve(sz);
    objcRotY.reserve(sz);
    objcRotZ.reserve(sz);
    profileName.reserve(sz);
    combatID.reserve(sz);
    combatIDA6.reserve(sz);
    behaviorLongRange.reserve(sz);
    behaviorMedRange.reserve(sz);
    behaviorShortRange.reserve(sz);
    behaviorMedRetreat.reserve(sz);
    behaviorLongRetreat.reserve(sz);
    medRangeThreshold.reserve(sz);
    meleeOverride.reserve(sz);
    noGunBehavior.reserve(sz);
    shortRangeThreshold.reserve(sz);
    pursuitDistance.reserve(sz);
    panicHurt.reserve(sz);
    panicGunfire.reserve(sz);
    panicMelee.reserve(sz);
    panicSight.reserve(sz);
    paddingIDA6.reserve(sz);
    alarmSearchDist.reserve(sz);
    alarmIgnoreDist.reserve(sz);
    alarmAttackDist.reserve(sz);
    alarmDamageThreshold.reserve(sz);
    alarmFightTimer.reserve(sz);

    int s = static_cast<int>(fieldsAux_.size()) + 1; // resume adding fields after TemplateBINA_OBJC's fields were added
    int nf = 35; // number of fields that we're adding (OBJC header + CMBT fields)
    for (int32_t i = 0; i < arraySize; ++i)
    {
        objcNextSize.emplace_back("next object size [" + to_string(i) + "]",                  s + (nf * i) + 0);
        objcSubtype.emplace_back("OBJC subtype [" + to_string(i) + "]",                       s + (nf * i) + 1);
        objcID.emplace_back("object ID [" + to_string(i) + "]",                               s + (nf * i) + 2);
        objcFlags.emplace_back("object flags [" + to_string(i) + "]",                         s + (nf * i) + 3, true, true, 0, 0,
                               &objectFlagValues, &objectFlagNames);
        objcPosX.emplace_back("position X [" + to_string(i) + "]",                            s + (nf * i) + 4);
        objcPosY.emplace_back("position Y [" + to_string(i) + "]",                            s + (nf * i) + 5);
        objcPosZ.emplace_back("position Z [" + to_string(i) + "]",                            s + (nf * i) + 6);
        objcRotX.emplace_back("rotation X [" + to_string(i) + "]",                            s + (nf * i) + 7);
        objcRotY.emplace_back("rotation Y [" + to_string(i) + "]",                            s + (nf * i) + 8);
        objcRotZ.emplace_back("rotation Z [" + to_string(i) + "]",                            s + (nf * i) + 9);
        profileName.emplace_back("profile name [" + to_string(i) + "]",                       s + (nf * i) + 10, true, true, "", "", 64);
        combatID.emplace_back("combat ID [" + to_string(i) + "]",                             kRetailOnly(s + (nf * i) + 11));
        combatIDA6.emplace_back("combat ID (A6) [" + to_string(i) + "]",                      kAlphaOnly(s + (nf * i) + 12));
        behaviorLongRange.emplace_back("long range behavior [" + to_string(i) + "]",          s + (nf * i) + 13, true, true, 0, 0,
                                       &behaviorTypeValues, &behaviorTypeNames);
        behaviorMedRange.emplace_back("medium range behavior [" + to_string(i) + "]",         s + (nf * i) + 14, true, true, 0, 0,
                                      &behaviorTypeValues, &behaviorTypeNames);
        behaviorShortRange.emplace_back("short range behavior [" + to_string(i) + "]",        s + (nf * i) + 15, true, true, 0, 0,
                                        &behaviorTypeValues, &behaviorTypeNames);
        behaviorMedRetreat.emplace_back("medium retreat behavior [" + to_string(i) + "]",     s + (nf * i) + 16, true, true, 0, 0,
                                        &behaviorTypeValues, &behaviorTypeNames);
        behaviorLongRetreat.emplace_back("long retreat behavior [" + to_string(i) + "]",      s + (nf * i) + 17, true, true, 0, 0,
                                         &behaviorTypeValues, &behaviorTypeNames);
        medRangeThreshold.emplace_back("medium range threshold [" + to_string(i) + "]",       s + (nf * i) + 18);
        meleeOverride.emplace_back("melee override behavior [" + to_string(i) + "]",          s + (nf * i) + 19, true, true, 0, 0,
                                   &meleeOverrideValues, &meleeOverrideNames);
        noGunBehavior.emplace_back("no gun behavior [" + to_string(i) + "]",                  s + (nf * i) + 20, true, true, 0, 0,
                                   &noGunBehaviorValues, &noGunBehaviorNames);
        shortRangeThreshold.emplace_back("short range threshold [" + to_string(i) + "]",      s + (nf * i) + 21);
        pursuitDistance.emplace_back("pursuit distance [" + to_string(i) + "]",               s + (nf * i) + 22);
        panicHurt.emplace_back("panic hurt [" + to_string(i) + "]",                           kRetailOnly(s + (nf * i) + 23));
        panicGunfire.emplace_back("panic gunfire [" + to_string(i) + "]",                     s + (nf * i) + 24);
        panicMelee.emplace_back("panic melee [" + to_string(i) + "]",                         s + (nf * i) + 25);
        panicSight.emplace_back("panic sight [" + to_string(i) + "]",                         s + (nf * i) + 26);
        paddingIDA6.emplace_back("padding (alpha 6) [" + to_string(i) + "]",                  kAlphaOnly(s + (nf * i) + 27));
        alarmSearchDist.emplace_back("alarm search distance [" + to_string(i) + "]",          kRetailOnly(s + (nf * i) + 30));
        alarmIgnoreDist.emplace_back("alarm enemy ignore distance [" + to_string(i) + "]",    kRetailOnly(s + (nf * i) + 31));
        alarmAttackDist.emplace_back("alarm enemy attack distance [" + to_string(i) + "]",    kRetailOnly(s + (nf * i) + 32));
        alarmDamageThreshold.emplace_back("alarm damage threshold [" + to_string(i) + "]",    kRetailOnly(s + (nf * i) + 33));
        alarmFightTimer.emplace_back("alarm fight timer [" + to_string(i) + "]",              kRetailOnly(s + (nf * i) + 34));
    }

    for (size_t i = 0; i < sz; ++i)
        fieldsAux_.insert(fieldsAux_.end(), {&objcNextSize[i], &objcSubtype[i], &objcID[i], &objcFlags[i], &objcPosX[i], &objcPosY[i],
                                             &objcPosZ[i], &objcRotX[i], &objcRotY[i], &objcRotZ[i], &profileName[i], &combatID[i],
                                             &combatIDA6[i], &behaviorLongRange[i], &behaviorMedRange[i], &behaviorShortRange[i],
                                             &behaviorMedRetreat[i], &behaviorLongRetreat[i], &medRangeThreshold[i], &meleeOverride[i],
                                             &noGunBehavior[i], &shortRangeThreshold[i], &pursuitDistance[i], &panicHurt[i], &panicGunfire[i],
                                             &panicMelee[i], &panicSight[i], &paddingIDA6[i], &alarmSearchDist[i], &alarmIgnoreDist[i],
                                             &alarmAttackDist[i], &alarmDamageThreshold[i], &alarmFightTimer[i]});

    // Add the closing zero-value next-object field that terminates the OBJC list
    objcNextSize.emplace_back("next object size [end]", s + (nf * arraySize));
    fieldsAux_.push_back(&objcNextSize.back());
}

/*********************** TemplateBINA_OBJC_MELE ***********************/
TemplateBINA_OBJC_MELE::TemplateBINA_OBJC_MELE(string instName, Format dataFormat)
                      : TemplateBINA_OBJC("BINA/OBJC/MELE", std::move(instName), dataFormat)
{
    certified_ = true;
    vwvlaSizeOffset_ = 0x0C;

    techniqueFlagValues =
    {
        {Interruptible, 0x01},
        {GenerousDir,   0x02},
        {Fearless,      0x04}
    };
    techniqueFlagNames =
    {
        {Interruptible, "interruptible"},
        {GenerousDir,   "generous direction"},
        {Fearless,      "fearless"}
    };

    moveValues =
    {
        // Attack (type byte 0x00): raw value = index
        {AtkP,      0x00}, {AtkPP,     0x01}, {AtkPPP,    0x02}, {AtkPPPP,   0x03},
        {AtkPF,     0x04}, {AtkPL,     0x05}, {AtkPR,     0x06}, {AtkPB,     0x07},
        {AtkPD,     0x08}, {AtkPFPF,   0x09}, {AtkPFPFPF, 0x0A}, {AtkPLPL,   0x0B},
        {AtkPLPLPL, 0x0C}, {AtkPRPR,   0x0D}, {AtkPRPRPR, 0x0E}, {AtkPBPB,   0x0F},
        {AtkPBPBPB, 0x10}, {AtkPDPD,   0x11}, {AtkPDPDPD, 0x12}, {AtkK,      0x13},
        {AtkKK,     0x14}, {AtkKKK,    0x15}, {AtkKKKF,   0x16}, {AtkKF,     0x17},
        {AtkKL,     0x18}, {AtkKR,     0x19}, {AtkKB,     0x1A}, {AtkKD,     0x1B},
        {AtkKFKF,   0x1C}, {AtkKFKFKF, 0x1D}, {AtkKLKL,   0x1E}, {AtkKLKLKL, 0x1F},
        {AtkKRKR,   0x20}, {AtkKRKRKR, 0x21}, {AtkKBKB,   0x22}, {AtkKBKBKB, 0x23},
        {AtkKDKD,   0x24}, {AtkKDKDKD, 0x25}, {AtkPPK,    0x26}, {AtkPKK,    0x27},
        {AtkPKP,    0x28}, {AtkKPK,    0x29}, {AtkKPP,    0x2A}, {AtkKKP,    0x2B},
        {AtkPK,     0x2C}, {AtkKP,     0x2D}, {AtkPPKK,   0x2E}, {AtkPPKKK,  0x2F},
        {AtkPPKKKK, 0x30}, {AtkHP,     0x31}, {AtkHPF,    0x32}, {AtkHK,     0x33},
        {AtkHKF,    0x34}, {AtkCSP,    0x35}, {AtkCSK,    0x36}, {AtkCP,     0x37},
        {AtkCP2,    0x38}, {AtkCPF,    0x39}, {AtkCK,     0x3A}, {AtkCK2,    0x3B},
        {AtkCKF,    0x3C}, {AtkGUKF,   0x3D}, {AtkGUKB,   0x3E}, {AtkRP,     0x3F},
        {AtkRK,     0x40}, {AtkRBP,    0x41}, {AtkRBK,    0x42}, {AtkRLP,    0x43},
        {AtkRLK,    0x44}, {AtkRRP,    0x45}, {AtkRRK,    0x46}, {AtkRSlide, 0x47},
        {AtkJP,     0x48}, {AtkJK,     0x49}, {AtkJFP,    0x4A}, {AtkJFPB,   0x4B},
        {AtkJFK,    0x4C}, {AtkJFKB,   0x4D}, {AtkJBP,    0x4E}, {AtkJBK,    0x4F},
        {AtkJLP,    0x50}, {AtkJLK,    0x51}, {AtkJRP,    0x52}, {AtkJRK,    0x53},
        // Position (type byte 0x10): raw value = 0x10000000 + index
        {PosRunFwd,      0x10000000}, {PosRunLeft,     0x10000001}, {PosRunRight,     0x10000002}, {PosRunBack,     0x10000003},
        {PosJumpUp,      0x10000004}, {PosJumpFwd,     0x10000005}, {PosJumpLeft,     0x10000006}, {PosJumpRight,   0x10000007},
        {PosJumpBack,    0x10000008}, {PosCrouchStart, 0x10000009}, {PosCrouch,       0x1000000A}, {PosStand,       0x1000000B},
        {PosCloseFwd,    0x1000000C}, {PosCloseLeft,   0x1000000D}, {PosCloseRight,   0x1000000E}, {PosCloseBack,   0x1000000F},
        {PosRunJumpFwd,  0x10000010}, {PosRunJumpLeft, 0x10000011}, {PosRunJumpRight, 0x10000012}, {PosRunJumpBack, 0x10000013},
        // Maneuver (type byte 0x20): raw value = 0x20000000 + index
        {ManAdvance,        0x20000000}, {ManRetreat,      0x20000001}, {ManCircleLeft, 0x20000002}, {ManCircleRight,   0x20000003},
        {ManPause,          0x20000004}, {ManCrouch,       0x20000005}, {ManJump,       0x20000006}, {ManTaunt,         0x20000007},
        {ManRandStop,       0x20000008}, {ManGetupFwd,     0x20000009}, {ManGetupBack,  0x2000000A}, {ManGetupRollLeft, 0x2000000B},
        {ManGetupRollRight, 0x2000000C}, {ManBarabbasWave, 0x2000000D},
        // Evade (type byte 0x30): raw value = 0x30000000 + index
        {EvdJmpFwd,     0x30000000}, {EvdJmpFwd2,     0x30000001}, {EvdJmpBack,     0x30000002}, {EvdJmpBack2,     0x30000003},
        {EvdJmpLeft,    0x30000004}, {EvdJmpLeft2,    0x30000005}, {EvdJmpRight,    0x30000006}, {EvdJmpRight2,    0x30000007},
        {EvdRunJmpFwd,  0x30000008}, {EvdRunJmpFwd2,  0x30000009}, {EvdRunJmpBack,  0x3000000A}, {EvdRunJmpBack2,  0x3000000B},
        {EvdRunJmpLeft, 0x3000000C}, {EvdRunJmpLeft2, 0x3000000D}, {EvdRunJmpRight, 0x3000000E}, {EvdRunJmpRight2, 0x3000000F},
        {EvdRollFwd,    0x30000010}, {EvdRollBack,    0x30000011}, {EvdRollLeft,    0x30000012}, {EvdRollRight,    0x30000013},
        {EvdSlideFwd,   0x30000014}, {EvdSlideBack,   0x30000015}, {EvdSlideLeft,   0x30000016}, {EvdSlideRight,   0x30000017},
        // Throw (type byte 0x40): raw value = 0x40000000 + index
        {ThrPFront,           0x40000000}, {ThrKFront,            0x40000001}, {ThrPBehind,           0x40000002},
        {ThrKBehind,          0x40000003}, {ThrRPFront,           0x40000004}, {ThrRKFront,           0x40000005},
        {ThrRPBehind,         0x40000006}, {ThrRKBehind,          0x40000007}, {ThrPFrontDisarm,      0x40000008},
        {ThrKFrontDisarm,     0x40000009}, {ThrPBehindDisarm,     0x4000000A}, {ThrKBehindDisarm,     0x4000000B},
        {ThrRPFrontDisarm,    0x4000000C}, {ThrRKFrontDisarm,     0x4000000D}, {ThrRPBehindDisarm,    0x4000000E},
        {ThrRKBehindDisarm,   0x4000000F}, {ThrPFrontRifDisarm,   0x40000010}, {ThrKFrontRifDisarm,   0x40000011},
        {ThrPBehindRifDisarm, 0x40000012}, {ThrKBehindRifDisarm,  0x40000013}, {ThrRPFrontRifDisarm,  0x40000014},
        {ThrRKFrontRifDisarm, 0x40000015}, {ThrRPBehindRifDisarm, 0x40000016}, {ThrRKBehindRifDisarm, 0x40000017},
        {ThrTackle,           0x40000018}
    };
    moveNames =
    {
        {AtkP,                 "Attack: P"},
        {AtkPP,                "Attack: P P"},
        {AtkPPP,               "Attack: P P P"},
        {AtkPPPP,              "Attack: P P P P"},
        {AtkPF,                "Attack: PF"},
        {AtkPL,                "Attack: PL"},
        {AtkPR,                "Attack: PR"},
        {AtkPB,                "Attack: PB"},
        {AtkPD,                "Attack: PD"},
        {AtkPFPF,              "Attack: PF PF"},
        {AtkPFPFPF,            "Attack: PF PF PF"},
        {AtkPLPL,              "Attack: PL PL"},
        {AtkPLPLPL,            "Attack: PL PL PL"},
        {AtkPRPR,              "Attack: PR PR"},
        {AtkPRPRPR,            "Attack: PR PR PR"},
        {AtkPBPB,              "Attack: PB PB"},
        {AtkPBPBPB,            "Attack: PB PB PB"},
        {AtkPDPD,              "Attack: PD PD"},
        {AtkPDPDPD,            "Attack: PD PD PD"},
        {AtkK,                 "Attack: K"},
        {AtkKK,                "Attack: K K"},
        {AtkKKK,               "Attack: K K K"},
        {AtkKKKF,              "Attack: K K KF"},
        {AtkKF,                "Attack: KF"},
        {AtkKL,                "Attack: KL"},
        {AtkKR,                "Attack: KR"},
        {AtkKB,                "Attack: KB"},
        {AtkKD,                "Attack: KD"},
        {AtkKFKF,              "Attack: KF KF"},
        {AtkKFKFKF,            "Attack: KF KF KF"},
        {AtkKLKL,              "Attack: KL KL"},
        {AtkKLKLKL,            "Attack: KL KL KL"},
        {AtkKRKR,              "Attack: KR KR"},
        {AtkKRKRKR,            "Attack: KR KR KR"},
        {AtkKBKB,              "Attack: KB KB"},
        {AtkKBKBKB,            "Attack: KB KB KB"},
        {AtkKDKD,              "Attack: KD KD"},
        {AtkKDKDKD,            "Attack: KD KD KD"},
        {AtkPPK,               "Attack: P P K"},
        {AtkPKK,               "Attack: P K K"},
        {AtkPKP,               "Attack: P K P"},
        {AtkKPK,               "Attack: K P K"},
        {AtkKPP,               "Attack: K P P"},
        {AtkKKP,               "Attack: K K P"},
        {AtkPK,                "Attack: P K"},
        {AtkKP,                "Attack: K P"},
        {AtkPPKK,              "Attack: P P K K"},
        {AtkPPKKK,             "Attack: P P K K K"},
        {AtkPPKKKK,            "Attack: P P K K K K"},
        {AtkHP,                "Attack: HP"},
        {AtkHPF,               "Attack: HPF"},
        {AtkHK,                "Attack: HK"},
        {AtkHKF,               "Attack: HKF"},
        {AtkCSP,               "Attack: CS-P"},
        {AtkCSK,               "Attack: CS-K"},
        {AtkCP,                "Attack: C-P"},
        {AtkCP2,               "Attack: C-P (2)"},
        {AtkCPF,               "Attack: C-PF"},
        {AtkCK,                "Attack: C-K"},
        {AtkCK2,               "Attack: C-K (2)"},
        {AtkCKF,               "Attack: C-KF"},
        {AtkGUKF,              "Attack: GETUP-KF"},
        {AtkGUKB,              "Attack: GETUP-KB"},
        {AtkRP,                "Attack: R-P"},
        {AtkRK,                "Attack: R-K"},
        {AtkRBP,               "Attack: RB-P"},
        {AtkRBK,               "Attack: RB-K"},
        {AtkRLP,               "Attack: RL-P"},
        {AtkRLK,               "Attack: RL-K"},
        {AtkRRP,               "Attack: RR-P"},
        {AtkRRK,               "Attack: RR-K"},
        {AtkRSlide,            "Attack: R-SLIDE"},
        {AtkJP,                "Attack: J-P"},
        {AtkJK,                "Attack: J-K"},
        {AtkJFP,               "Attack: JF-P"},
        {AtkJFPB,              "Attack: JF-PB"},
        {AtkJFK,               "Attack: JF-K"},
        {AtkJFKB,              "Attack: JF-KB"},
        {AtkJBP,               "Attack: JB-P"},
        {AtkJBK,               "Attack: JB-K"},
        {AtkJLP,               "Attack: JL-P"},
        {AtkJLK,               "Attack: JL-K"},
        {AtkJRP,               "Attack: JR-P"},
        {AtkJRK,               "Attack: JR-K"},
        {PosRunFwd,            "Position: Run Forward"},
        {PosRunLeft,           "Position: Run Left"},
        {PosRunRight,          "Position: Run Right"},
        {PosRunBack,           "Position: Run Back"},
        {PosJumpUp,            "Position: Jump Up"},
        {PosJumpFwd,           "Position: Jump Forward"},
        {PosJumpLeft,          "Position: Jump Left"},
        {PosJumpRight,         "Position: Jump Right"},
        {PosJumpBack,          "Position: Jump Back"},
        {PosCrouchStart,       "Position: Start to Crouch"},
        {PosCrouch,            "Position: Crouch"},
        {PosStand,             "Position: Stand"},
        {PosCloseFwd,          "Position: Close Forward"},
        {PosCloseLeft,         "Position: Close Left"},
        {PosCloseRight,        "Position: Close Right"},
        {PosCloseBack,         "Position: Close Back"},
        {PosRunJumpFwd,        "Position: RunJump Forward"},
        {PosRunJumpLeft,       "Position: RunJump Left"},
        {PosRunJumpRight,      "Position: RunJump Right"},
        {PosRunJumpBack,       "Position: RunJump Back"},
        {ManAdvance,           "Maneuver: Advance"},
        {ManRetreat,           "Maneuver: Retreat"},
        {ManCircleLeft,        "Maneuver: Circle Left"},
        {ManCircleRight,       "Maneuver: Circle Right"},
        {ManPause,             "Maneuver: Pause"},
        {ManCrouch,            "Maneuver: Crouch"},
        {ManJump,              "Maneuver: Jump"},
        {ManTaunt,             "Maneuver: Taunt"},
        {ManRandStop,          "Maneuver: Random Stop"},
        {ManGetupFwd,          "Maneuver: Get-up Forward"},
        {ManGetupBack,         "Maneuver: Get-up Back"},
        {ManGetupRollLeft,     "Maneuver: Get-up Roll Left"},
        {ManGetupRollRight,    "Maneuver: Get-up Roll Right"},
        {ManBarabbasWave,      "Maneuver: Barabbas Wave"},
        {EvdJmpFwd,            "Evade: Jump Forwards"},
        {EvdJmpFwd2,           "Evade: Jump Forwards (2)"},
        {EvdJmpBack,           "Evade: Jump Backwards"},
        {EvdJmpBack2,          "Evade: Jump Backwards (2)"},
        {EvdJmpLeft,           "Evade: Jump Left"},
        {EvdJmpLeft2,          "Evade: Jump Left (2)"},
        {EvdJmpRight,          "Evade: Jump Right"},
        {EvdJmpRight2,         "Evade: Jump Right (2)"},
        {EvdRunJmpFwd,         "Evade: RunJump Forwards"},
        {EvdRunJmpFwd2,        "Evade: RunJump Forwards (2)"},
        {EvdRunJmpBack,        "Evade: RunJump Backwards"},
        {EvdRunJmpBack2,       "Evade: RunJump Backwards (2)"},
        {EvdRunJmpLeft,        "Evade: RunJump Left"},
        {EvdRunJmpLeft2,       "Evade: RunJump Left (2)"},
        {EvdRunJmpRight,       "Evade: RunJump Right"},
        {EvdRunJmpRight2,      "Evade: RunJump Right (2)"},
        {EvdRollFwd,           "Evade: Roll Forwards"},
        {EvdRollBack,          "Evade: Roll Backwards"},
        {EvdRollLeft,          "Evade: Roll Left"},
        {EvdRollRight,         "Evade: Roll Right"},
        {EvdSlideFwd,          "Evade: Slide Forwards"},
        {EvdSlideBack,         "Evade: Slide Backwards"},
        {EvdSlideLeft,         "Evade: Slide Left"},
        {EvdSlideRight,        "Evade: Slide Right"},
        {ThrPFront,            "Throw: P Front"},
        {ThrKFront,            "Throw: K Front"},
        {ThrPBehind,           "Throw: P Behind"},
        {ThrKBehind,           "Throw: K Behind"},
        {ThrRPFront,           "Throw: RP Front"},
        {ThrRKFront,           "Throw: RK Front"},
        {ThrRPBehind,          "Throw: RP Behind"},
        {ThrRKBehind,          "Throw: RK Behind"},
        {ThrPFrontDisarm,      "Throw: P Front Disarm"},
        {ThrKFrontDisarm,      "Throw: K Front Disarm"},
        {ThrPBehindDisarm,     "Throw: P Behind Disarm"},
        {ThrKBehindDisarm,     "Throw: K Behind Disarm"},
        {ThrRPFrontDisarm,     "Throw: RP Front Disarm"},
        {ThrRKFrontDisarm,     "Throw: RK Front Disarm"},
        {ThrRPBehindDisarm,    "Throw: RP Behind Disarm"},
        {ThrRKBehindDisarm,    "Throw: RK Behind Disarm"},
        {ThrPFrontRifDisarm,   "Throw: P Front RifDisarm"},
        {ThrKFrontRifDisarm,   "Throw: K Front RifDisarm"},
        {ThrPBehindRifDisarm,  "Throw: P Behind RifDisarm"},
        {ThrKBehindRifDisarm,  "Throw: K Behind RifDisarm"},
        {ThrRPFrontRifDisarm,  "Throw: RP Front RifDisarm"},
        {ThrRKFrontRifDisarm,  "Throw: RK Front RifDisarm"},
        {ThrRPBehindRifDisarm, "Throw: RP Behind RifDisarm"},
        {ThrRKBehindRifDisarm, "Throw: RK Behind RifDisarm"},
        {ThrTackle,            "Throw: Tackle"}
    };
}

unique_ptr<Template> TemplateBINA_OBJC_MELE::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateBINA_OBJC_MELE>(instName, dataFormat);
}

void TemplateBINA_OBJC_MELE::createVWVarArray(int32_t arraySize, uint32_t /*lastObjSize*/, vector<char> & dataPacket)
{
    // We would check here for correct "lastObjSize", but this is a VWVLA that contains FWVLAs, so each object is of differing size; we simply
    // have to hope that the field setup below reads the data correctly

    // Byte offsets of the four count fields within each MELE object
    const size_t kOffNumAttackTechs   = 0xE4 - (origFormat_ == Format::WinAlpha6 ? 0x4 : 0); // adjust for two blocking fields being one in WA6
    const size_t kOffNumEvadeTechs    = 0xE8 - (origFormat_ == Format::WinAlpha6 ? 0x4 : 0);
    const size_t kOffNumManeuverTechs = 0xEC - (origFormat_ == Format::WinAlpha6 ? 0xEC : 0); // this field is absent entirely in Win A6
    const size_t kOffNumMoves         = 0xF0 - (origFormat_ == Format::WinAlpha6 ? 0x8 : 0);

    // Phase A: pre-count pass - read technique and move counts from the raw data so all vectors can be reserved to their final sizes before any
    // emplace_back() calls; or, when no data is available (e.g. --knowledge), use dummy counts of 1 each to show one representative element
    const size_t sz = static_cast<size_t>(arraySize);
    vector<int32_t> nTechsPerObj(sz), nMovesPerObj(sz);
    int totalTechs = 0, totalMoves = 0;
    if (dataPacket.empty())
    {
        nTechsPerObj.assign(sz, 1);
        nMovesPerObj.assign(sz, 1);
        totalTechs = arraySize;
        totalMoves = arraySize;
    }
    else
    {
        size_t objOffset = 12; // skip 3 header fields (binaSubtype, objcListSize, objcVersion) × 4 bytes
        for (size_t i = 0; i < sz; ++i)
        {
            uint32_t nAttack = 0, nEvade = 0, nManeuver = 0, nMovesVal = 0;
            size_t dp = auxFieldsBaseOffset() + objOffset;
            DataIO::ReadNum(nAttack, dataPacket, dp + kOffNumAttackTechs);
            DataIO::ReadNum(nEvade, dataPacket, dp + kOffNumEvadeTechs);
            if (kOffNumManeuverTechs > 0)
                DataIO::ReadNum(nManeuver, dataPacket, dp + kOffNumManeuverTechs);
            else
                nManeuver = 0;
            DataIO::ReadNum(nMovesVal, dataPacket, dp + kOffNumMoves);
            nTechsPerObj[i] = static_cast<int32_t>(nAttack + nEvade + nManeuver);
            nMovesPerObj[i] = static_cast<int32_t>(nMovesVal);
            totalTechs += nTechsPerObj[i];
            totalMoves += nMovesPerObj[i];
            objOffset += vwvlaObjectSizes_[i] + 4;
        }
    }

    static constexpr int kMaxTechSafety = 10'000;
    static constexpr int kMaxMoveSafety = 30'000;
    if (totalTechs > kMaxTechSafety || totalMoves > kMaxMoveSafety)
    {
        cerr << "Warning: MELE instance " << quoted(name_) << " reports implausible technique or move counts ("
             << totalTechs << " and " << totalMoves << "); the data format may be unsupported."
             << " Populating this template's fields will be skipped.\n";
        return;
    }

    objcNextSize.reserve(sz + 1); // +1 for the zero terminator at end of list
    objcSubtype.reserve(sz);
    objcID.reserve(sz);
    objcFlags.reserve(sz);
    objcPosX.reserve(sz);
    objcPosY.reserve(sz);
    objcPosZ.reserve(sz);
    objcRotX.reserve(sz);
    objcRotY.reserve(sz);
    objcRotZ.reserve(sz);
    meleeID.reserve(sz);
    profileName.reserve(sz);
    charClassName.reserve(sz);
    noticeChance.reserve(sz);
    dodgeBaseChance.reserve(sz);
    dodgeAddChance.reserve(sz);
    dodgeAddThreshold.reserve(sz);
    block1v1Chance.reserve(sz);
    blockGroupChance.reserve(sz);
    blockChanceA6.reserve(sz);
    weightCantBeBlocked.reserve(sz);
    weightMustChangeStance.reserve(sz);
    weightUnblockable.reserve(sz);
    weightCausesStagger.reserve(sz);
    weightCausesBlockStun.reserve(sz);
    weightTotallyBlocked.reserve(sz);
    throwDangerWeight.reserve(sz);
    minDazedFrames.reserve(sz);
    maxDazedFrames.reserve(sz);
    numAttackTechs.reserve(sz);
    numEvadeTechs.reserve(sz);
    numManeuverTechs.reserve(sz);
    numMoves.reserve(sz);
    techName.reserve(static_cast<size_t>(totalTechs));
    techFlags.reserve(static_cast<size_t>(totalTechs));
    techWeight.reserve(static_cast<size_t>(totalTechs));
    techImportance.reserve(static_cast<size_t>(totalTechs));
    techRepeatDelay.reserve(static_cast<size_t>(totalTechs));
    techNumMoves.reserve(static_cast<size_t>(totalTechs));
    techFirstMove.reserve(static_cast<size_t>(totalTechs));
    move.reserve(static_cast<size_t>(totalMoves));
    moveParam1.reserve(static_cast<size_t>(totalMoves));
    moveParam2.reserve(static_cast<size_t>(totalMoves));
    moveParam3.reserve(static_cast<size_t>(totalMoves));

    // Phase B: create all field objects with variable-stride sequential order numbers
    int orderBase = static_cast<int>(fieldsAux_.size()) + 1;
    const int kNumProfileFields = 32; // number of fixed per-object fields in the profile part (order slots 0–31)
    for (size_t i = 0; i < sz; ++i)
    {
        int32_t nT = nTechsPerObj[i];
        int32_t nM = nMovesPerObj[i];
        string si = "[" + to_string(i) + "]";

        // Profile part
        objcNextSize.emplace_back("next object size " + si,                       orderBase + 0);
        fieldsAux_.push_back(&objcNextSize.back());
        objcSubtype.emplace_back("OBJC subtype " + si,                            orderBase + 1);
        fieldsAux_.push_back(&objcSubtype.back());
        objcID.emplace_back("object ID " + si,                                    orderBase + 2);
        fieldsAux_.push_back(&objcID.back());
        objcFlags.emplace_back("object flags " + si,                              orderBase + 3, true, true, 0, 0, &objectFlagValues,
                               &objectFlagNames);
        fieldsAux_.push_back(&objcFlags.back());
        objcPosX.emplace_back("position X " + si,                                 orderBase + 4);
        fieldsAux_.push_back(&objcPosX.back());
        objcPosY.emplace_back("position Y " + si,                                 orderBase + 5);
        fieldsAux_.push_back(&objcPosY.back());
        objcPosZ.emplace_back("position Z " + si,                                 orderBase + 6);
        fieldsAux_.push_back(&objcPosZ.back());
        objcRotX.emplace_back("rotation X " + si,                                 orderBase + 7);
        fieldsAux_.push_back(&objcRotX.back());
        objcRotY.emplace_back("rotation Y " + si,                                 orderBase + 8);
        fieldsAux_.push_back(&objcRotY.back());
        objcRotZ.emplace_back("rotation Z " + si,                                 orderBase + 9);
        fieldsAux_.push_back(&objcRotZ.back());
        meleeID.emplace_back("melee ID " + si,                                    orderBase + 10);
        fieldsAux_.push_back(&meleeID.back());
        profileName.emplace_back("profile name " + si,                            orderBase + 11, true, true, "", "", 64);
        fieldsAux_.push_back(&profileName.back());
        charClassName.emplace_back("character class name " + si,                  orderBase + 12, true, true, "", "", 64);
        fieldsAux_.push_back(&charClassName.back());
        noticeChance.emplace_back("notice chance " + si,                          orderBase + 13);
        fieldsAux_.push_back(&noticeChance.back());
        dodgeBaseChance.emplace_back("dodge base chance " + si,                   orderBase + 14);
        fieldsAux_.push_back(&dodgeBaseChance.back());
        dodgeAddChance.emplace_back("dodge additional chance " + si,              orderBase + 15);
        fieldsAux_.push_back(&dodgeAddChance.back());
        dodgeAddThreshold.emplace_back("dodge additional threshold " + si,        orderBase + 16);
        fieldsAux_.push_back(&dodgeAddThreshold.back());
        block1v1Chance.emplace_back("1v1 block chance " + si,                     kRetailOnly(orderBase + 17));
        fieldsAux_.push_back(&block1v1Chance.back());
        blockGroupChance.emplace_back("group block chance " + si,                 kRetailOnly(orderBase + 18));
        fieldsAux_.push_back(&blockGroupChance.back());
        blockChanceA6.emplace_back("group chance (alpha) " + si,                  kAlphaOnly(orderBase + 18));
        fieldsAux_.push_back(&blockChanceA6.back());
        weightCantBeBlocked.emplace_back("weight: can't be blocked " + si,        orderBase + 19);
        fieldsAux_.push_back(&weightCantBeBlocked.back());
        weightMustChangeStance.emplace_back("weight: must change stance " + si,   orderBase + 20);
        fieldsAux_.push_back(&weightMustChangeStance.back());
        weightUnblockable.emplace_back("weight: unblockable " + si,               orderBase + 21);
        fieldsAux_.push_back(&weightUnblockable.back());
        weightCausesStagger.emplace_back("weight: causes stagger " + si,          orderBase + 22);
        fieldsAux_.push_back(&weightCausesStagger.back());
        weightCausesBlockStun.emplace_back("weight: causes block-stun " + si,     orderBase + 23);
        fieldsAux_.push_back(&weightCausesBlockStun.back());
        weightTotallyBlocked.emplace_back("weight: can be totally blocked " + si, orderBase + 24);
        fieldsAux_.push_back(&weightTotallyBlocked.back());
        throwDangerWeight.emplace_back("throw-into-danger weight " + si,          orderBase + 25);
        fieldsAux_.push_back(&throwDangerWeight.back());
        minDazedFrames.emplace_back("min dazed frames " + si,                     orderBase + 26);
        fieldsAux_.push_back(&minDazedFrames.back());
        maxDazedFrames.emplace_back("max dazed frames " + si,                     orderBase + 27);
        fieldsAux_.push_back(&maxDazedFrames.back());
        numAttackTechs.emplace_back("num. attack techniques " + si,               orderBase + 28);
        fieldsAux_.push_back(&numAttackTechs.back());
        numEvadeTechs.emplace_back("num. evade techniques " + si,                 orderBase + 29);
        fieldsAux_.push_back(&numEvadeTechs.back());
        numManeuverTechs.emplace_back("num. maneuver techniques " + si,           kRetailOnly(orderBase + 30));
        fieldsAux_.push_back(&numManeuverTechs.back());
        numMoves.emplace_back("num. moves " + si,                                 orderBase + 31);
        fieldsAux_.push_back(&numMoves.back());

        // Technique part
        const int numT = 7;
        for (int j = 0; j < nT; ++j)
        {
            string sfx = "[" + to_string(i) + "][" + to_string(j) + "]";
            int tOrd = orderBase + kNumProfileFields + (j * numT);
            techName.emplace_back("technique name " + sfx,          tOrd + 0, true, true, "", "", 64);
            fieldsAux_.push_back(&techName.back());
            techFlags.emplace_back("technique flags " + sfx,        tOrd + 1, true, true, 0, 0,
                                   &techniqueFlagValues, &techniqueFlagNames);
            fieldsAux_.push_back(&techFlags.back());
            techWeight.emplace_back("technique weight " + sfx,      tOrd + 2);
            fieldsAux_.push_back(&techWeight.back());
            techImportance.emplace_back("technique importance " + sfx, tOrd + 3);
            fieldsAux_.push_back(&techImportance.back());
            techRepeatDelay.emplace_back("repeat delay " + sfx,    kRetailOnly(tOrd + 4));
            fieldsAux_.push_back(&techRepeatDelay.back());
            techNumMoves.emplace_back("num. moves in technique " + sfx, tOrd + 5);
            fieldsAux_.push_back(&techNumMoves.back());
            techFirstMove.emplace_back("first move index " + sfx,   tOrd + 6);
            fieldsAux_.push_back(&techFirstMove.back());
        }

        // Move part
        const int numM = 4;
        for (int j = 0; j < nM; ++j)
        {
            string sfx = "[" + to_string(i) + "][" + to_string(j) + "]";
            int mOrd = orderBase + kNumProfileFields + (nT * numT) + (j * numM);
            move.emplace_back("move " + sfx, mOrd + 0, true, true, 0, 0, &moveValues, &moveNames);
            fieldsAux_.push_back(&move.back());
            moveParam1.emplace_back("move param 1 " + sfx, mOrd + 1);
            fieldsAux_.push_back(&moveParam1.back());
            moveParam2.emplace_back("move param 2 " + sfx, mOrd + 2);
            fieldsAux_.push_back(&moveParam2.back());
            moveParam3.emplace_back("move param 3 " + sfx, mOrd + 3);
            fieldsAux_.push_back(&moveParam3.back());
        }

        orderBase += kNumProfileFields + nT * numT + nM * numM;
    }

    // Add the closing zero-value next-object field that terminates the OBJC list
    objcNextSize.emplace_back("next object size [end]", orderBase + 0);
    fieldsAux_.push_back(&objcNextSize.back());
}

/************************* TemplateBINA_PAR3 *************************/
TemplateBINA_PAR3::TemplateBINA_PAR3(string instName, Format dataFormat)
                 : TemplateBINA("BINA/PAR3", std::move(instName), dataFormat),
                   particleBlob("particle data blob", 1)
{
    certified_ = false;

    fieldsAux_.insert(fieldsAux_.end(), {&particleBlob});
}

unique_ptr<Template> TemplateBINA_PAR3::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateBINA_PAR3>(instName, dataFormat);
}

void TemplateBINA_PAR3::prepareAuxFields()
{
    particleBlob.setReservedSize(binaDataSize());
}

/**************************** TemplateCBPI ****************************/
TemplateCBPI::TemplateCBPI(string instName, Format dataFormat)
            : Template("CBPI", std::move(instName), dataFormat),
              imptHitPelvis("impact - hit - pelvis",                     2),
              imptHitLThigh("impact - hit - left thigh",                 3),
              imptHitLShin("impact - hit - left shin",                   4),
              imptHitLFoot("impact - hit - left foot",                   5),
              imptHitRThigh("impact - hit - right thigh",                6),
              imptHitRShin("impact - hit - right shin",                  7),
              imptHitRFoot("impact - hit - right foot",                  8),
              imptHitAbdomen("impact - hit - abdomen",                   9),
              imptHitChest("impact - hit - chest",                       10),
              imptHitNeck("impact - hit - neck",                         11),
              imptHitHead("impact - hit - head",                         12),
              imptHitLShoulder("impact - hit - left shoulder",           13),
              imptHitLUpperArm("impact - hit - left upper arm",          14),
              imptHitLForearm("impact - hit - left forearm",             15),
              imptHitLHand("impact - hit - left hand",                   16),
              imptHitRShoulder("impact - hit - right shoulder",          17),
              imptHitRUpperArm("impact - hit - right upper arm",         18),
              imptHitRForearm("impact - hit - right forearm",            19),
              imptHitRHand("impact - hit - right hand",                  20),
              imptBlockedPelvis("impact - blocked - pelvis",             21),
              imptBlockedLThigh("impact - blocked - left thigh",         22),
              imptBlockedLShin("impact - blocked - left shin",           23),
              imptBlockedLFoot("impact - blocked - left foot",           24),
              imptBlockedRThigh("impact - blocked - right thigh",        25),
              imptBlockedRShin("impact - blocked - right shin",          26),
              imptBlockedRFoot("impact - blocked - right foot",          27),
              imptBlockedAbdomen("impact - blocked - abdomen",           28),
              imptBlockedChest("impact - blocked - chest",               29),
              imptBlockedNeck("impact - blocked - neck",                 30),
              imptBlockedHead("impact - blocked - head",                 31),
              imptBlockedLShoulder("impact - blocked - left shoulder",   32),
              imptBlockedLUpperArm("impact - blocked - left upper arm",  33),
              imptBlockedLForearm("impact - blocked - left forearm",     34),
              imptBlockedLHand("impact - blocked - left hand",           35),
              imptBlockedRShoulder("impact - blocked - right shoulder",  36),
              imptBlockedRUpperArm("impact - blocked - right upper arm", 37),
              imptBlockedRForearm("impact - blocked - right forearm",    38),
              imptBlockedRHand("impact - blocked - right hand",          39),
              imptKilledPelvis("impact - killed - pelvis",               40),
              imptKilledLThigh("impact - killed - left thigh",           41),
              imptKilledLShin("impact - killed - left shin",             42),
              imptKilledLFoot("impact - killed - left foot",             43),
              imptKilledRThigh("impact - killed - right thigh",          44),
              imptKilledRShin("impact - killed - right shin",            45),
              imptKilledRFoot("impact - killed - right foot",            46),
              imptKilledAbdomen("impact - killed - abdomen",             47),
              imptKilledChest("impact - killed - chest",                 48),
              imptKilledNeck("impact - killed - neck",                   49),
              imptKilledHead("impact - killed - head",                   50),
              imptKilledLShoulder("impact - killed - left shoulder",     51),
              imptKilledLUpperArm("impact - killed - left upper arm",    52),
              imptKilledLForearm("impact - killed - left forearm",       53),
              imptKilledLHand("impact - killed - left hand",             54),
              imptKilledRShoulder("impact - killed - right shoulder",    55),
              imptKilledRUpperArm("impact - killed - right upper arm",   56),
              imptKilledRForearm("impact - killed - right forearm",      57),
              imptKilledRHand("impact - killed - right hand",            58)
{
    hasLinks_ = true;
    certified_ = true;

    fields_.insert(fields_.end(), {&imptHitPelvis, &imptHitLThigh, &imptHitLShin, &imptHitLFoot, &imptHitRThigh, &imptHitRShin, &imptHitRFoot,
                                   &imptHitAbdomen, &imptHitChest, &imptHitNeck, &imptHitHead, &imptHitLShoulder, &imptHitLUpperArm,
                                   &imptHitLForearm, &imptHitLHand, &imptHitRShoulder, &imptHitRUpperArm, &imptHitRForearm, &imptHitRHand,
                                   &imptBlockedPelvis, &imptBlockedLThigh, &imptBlockedLShin, &imptBlockedLFoot, &imptBlockedRThigh,
                                   &imptBlockedRShin, &imptBlockedRFoot, &imptBlockedAbdomen, &imptBlockedChest, &imptBlockedNeck,
                                   &imptBlockedHead, &imptBlockedLShoulder, &imptBlockedLUpperArm, &imptBlockedLForearm, &imptBlockedLHand,
                                   &imptBlockedRShoulder, &imptBlockedRUpperArm, &imptBlockedRForearm, &imptBlockedRHand, &imptKilledPelvis,
                                   &imptKilledLThigh, &imptKilledLShin, &imptKilledLFoot, &imptKilledRThigh, &imptKilledRShin, &imptKilledRFoot,
                                   &imptKilledAbdomen, &imptKilledChest, &imptKilledNeck, &imptKilledHead, &imptKilledLShoulder,
                                   &imptKilledLUpperArm, &imptKilledLForearm, &imptKilledLHand, &imptKilledRShoulder, &imptKilledRUpperArm,
                                   &imptKilledRForearm, &imptKilledRHand});
}

unique_ptr<Template> TemplateCBPI::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateCBPI>(instName, dataFormat);
}

/**************************** TemplateCBPM ****************************/
TemplateCBPM::TemplateCBPM(string instName, Format dataFormat)
            : Template("CBPM", std::move(instName), dataFormat),
              mtrlPelvis("material - pelvis",             2),
              mtrlLThigh("material - left thigh",         3),
              mtrlLShin("material - left shin",           4),
              mtrlLFoot("material - left foot",           5),
              mtrlRThigh("material - right thigh",        6),
              mtrlRShin("material - right shin",          7),
              mtrlRFoot("material - right foot",          8),
              mtrlAbdomen("material - abdomen",           9),
              mtrlChest("material - chest",               10),
              mtrlNeck("material - neck",                 11),
              mtrlHead("material - head",                 12),
              mtrlLShoulder("material - left shoulder",   13),
              mtrlLUpperArm("material - left upper arm",  14),
              mtrlLForearm("material - left forearm",     15),
              mtrlLHand("material - left hand",           16),
              mtrlRShoulder("material - right shoulder",  17),
              mtrlRUpperArm("material - right upper arm", 18),
              mtrlRForearm("material - right forearm",    19),
              mtrlRHand("material - right hand",          20)
{
    hasLinks_ = true;
    certified_ = true;

    fields_.insert(fields_.end(), {&mtrlPelvis, &mtrlLThigh, &mtrlLShin, &mtrlLFoot, &mtrlRThigh, &mtrlRShin, &mtrlRFoot, &mtrlAbdomen,
                                   &mtrlChest, &mtrlNeck, &mtrlHead, &mtrlLShoulder, &mtrlLUpperArm, &mtrlLForearm, &mtrlLHand, &mtrlRShoulder,
                                   &mtrlRUpperArm, &mtrlRForearm, &mtrlRHand});
}

unique_ptr<Template> TemplateCBPM::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateCBPM>(instName, dataFormat);
}

/**************************** TemplateIDXA ****************************/
TemplateIDXA::TemplateIDXA(string instName, Format dataFormat)
            : Template("IDXA", std::move(instName), dataFormat),
              padding("padding",       2, true, false),
              arraySize("index count", 3),
              idxaType(IDXAType::IDXA_unset)
{
    hasLinks_ = true;
    certified_ = true;

    fwvlaSizeOffset_ = {0x1C, 32};

    fields_.insert(fields_.end(), {&padding, &arraySize});

    padding.setFixedSize(20);
}

unique_ptr<Template> TemplateIDXA::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateIDXA>(instName, dataFormat);
}

void TemplateIDXA::createFWVarArray(int32_t n)
{
    index.reserve(static_cast<size_t>(n));

    for (int32_t i = 0; i < n; ++i)
    {
        index.emplace_back("index [" + to_string(i) + "]", 4 + i); // last field added by TemplateIDXA constructor was order 3
        fields_.insert(fields_.end(), {&index[static_cast<size_t>(i)]});
    }
}

IDXAType & TemplateIDXA::type()
{
    return idxaType;
}

/**************************** TemplateM3GM ****************************/
TemplateM3GM::TemplateM3GM(string instName, Format dataFormat)
            : Template("M3GM", std::move(instName), dataFormat),
              geomFlags("geometry flags (runtime)",      2),
              numFaces("number of faces",                kPS2Only(3)),
              linkPNTA("PNTA (vertex points)",           {3, 3, 3, 3, 4}),
              linkVCRA1("VCRA 1 (vertex normals)",       kNotPS2(4)),
              linkVCRA2("VCRA 2 (face normals)",         kNotPS2(5)),
              linkTXCA("TXCA (texture UVs)",             {6, 6, 6, 6, 5}),
              linkIDXA1("IDXA (triangle strips)",        {7, 7, 7, 7, 6}),
              linkIDXA2("IDXA (normal indexes)",         kNotPS2(8)), // also the tri count of the model
              numVertices("number of vertices",          kPS2Only(7)),
              rawOffset("compressed normals raw offset", kPS2Only(8)),
              linkTXMP("TXMP (texture)",                 9), // TXMP links to envmap if there is one
              linkGMAN("GMAN (unused)",                  10),
              vertexNormalBlob("compressed vertex normals (PS2)", 1)
{
    hasLinks_ = true;
    hasAuxData_ = (dataFormat == Format::PS2);
    certified_ = true;

    fields_.insert(fields_.end(), {&geomFlags, &numFaces, &linkPNTA, &linkVCRA1, &linkVCRA2, &linkTXCA, &linkIDXA1,
                                   &linkIDXA2, &numVertices, &rawOffset, &linkTXMP, &linkGMAN});
    fieldsAux_.insert(fieldsAux_.end(), {&vertexNormalBlob});
}

unique_ptr<Template> TemplateM3GM::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateM3GM>(instName, dataFormat);
}

void TemplateM3GM::prepareAuxFields()
{
    vertexNormalBlob.setReservedSize(108);
}

size_t TemplateM3GM::auxFieldsBaseOffset()
{
    return rawOffset.val();
}

/**************************** TemplateONCC ****************************/
// Initialize every field with its name and its known order (sequence position). From this, offsets are computed at runtime by sortFieldsFor().
// Gaps in the numbering leave room for discoveries of new fields in game versions that haven't been found yet as well as for inserting fields
// for a new data version in the future.
TemplateONCC::TemplateONCC(string instName, Format dataFormat)
            : Template("ONCC", std::move(instName), dataFormat),
              jumpGravityAI2("jump gravity AI2",                                2),
              jumpGravity("jump gravity",                                       3),
              jumpVelStart("starting jump velocity",                            4),
              fallMaxSpeed("maximum fall speed",                                5),
              jumpAccel("jump hold acceleration",                               6),
              jumpTimerAI2("jump gravity to jump gravity AI2 timer",            7),
              jumpAccelTimer("jump hold timer",                                 8),
              fallDamageMin("fall damage height min",                           9),
              fallDamageMax("fall damage height max",                           10),
              shadowTXMP("shadow texture",                                      kRetailOnly(11)),
              shadowMinHeight("height for min shadow size",                     kRetailOnly(12)),
              shadowMaxToMidRange("range for shadow max to mid size",           kRetailOnly(13)),
              shadowMaxSize("max shadow size",                                  kRetailOnly(14)),
              shadowMidSize("mid shadow size",                                  kRetailOnly(15)),
              shadowMinSize("min shadow size",                                  kRetailOnly(16)),
              shadowTransp1("normal shadow transparency",                       kRetailOnly(17)),
              shadowTransp2("fading shadow transparency",                       kRetailOnly(18)),
              shadowMystery1_A6("shadow mystery 1",                             kAlphaOnly(11)),
              shadowMystery2_A6("shadow mystery 2",                             kAlphaOnly(12)),
              shadowMystery3_A6("shadow mystery 3",                             kAlphaOnly(13)),
              shadowMystery4_A6("shadow mystery 4",                             kAlphaOnly(14)),
              unusedJump1("unused jump 1",                                      20),
              unusedJump2("unused jump 2",                                      21),
              unusedJump3("unused jump 3",                                      22),
              padding1("padding 1",                                             23, true, false),
              unusedCover1("unused cover 1",                                    24),
              unusedCover2("unused cover 2",                                    25),
              unusedCover3("unused cover 3",                                    26),
              unusedCover4("unused cover 4",                                    27),
              unusedAutofreeze1("unused autofreeze 1",                          28),
              unusedAutofreeze2("unused autofreeze 2",                          29),
              hypoRegenRate("hypo regeneration rate",                           30),
              padding2("padding 2",                                             31, true, false),
              lod1StartDist("min. distance for super-low LOD",                  32),
              lod2StartDist("min. distance for low LOD",                        33),
              lod3StartDist("min. distance for medium LOD",                     34),
              lod4StartDist("min. distance for high LOD",                       35),
              lod5StartDist("min. distance for super-high LOD",                 36),
              painBasePercentage("min chance for pain sound",                   kRetailOnly(40)),
              painMaxPercentage("max chance for pain sound",                    kRetailOnly(41)),
              painPercentageThreshold("pain sound rampup probability",          kRetailOnly(42)),
              painResetFrames("pain sound reset timer",                         kRetailOnly(43)),
              painMinTimer("pain sound min time",                               kRetailOnly(44)),
              painMaxLight("pain sound light max count",                        kRetailOnly(45)),
              painMaxMedium("pain sound med max count",                         kRetailOnly(46)),
              painDeathChance("death sound chance",                             kRetailOnly(47)),
              painVolumeThreshold("pain sound max volume damage threshold",     kRetailOnly(48)),
              painMediumThreshold("pain sound med upgrade threshold",           kRetailOnly(49)),
              painHeavyThreshold("pain sound heavy upgrade threshold",          kRetailOnly(50)),
              painSoundsFound("sounds found (runtime)",                         kRetailOnly(51)),
              padding3("padding 3",                                             kRetailOnly(52), true, false),
              painMinVolume("pain sound min volume",                            kRetailOnly(53)),
              painLightSound("light pain sound name",                           kRetailOnly(54)),
              painMediumSound("med pain sound name",                            kRetailOnly(55)),
              painHeavySound("heavy pain sound name",                           kRetailOnly(56)),
              painDeathSound("death pain sound name",                           kRetailOnly(57)),
              painLightImpulse("light pain sound impulse (runtime)",            kRetailOnly(58)),
              painMediumImpulse("med pain sound impulse (runtime)",             kRetailOnly(59)),
              painHeavyImpulse("heavy pain sound impulse (runtime)",            kRetailOnly(60)),
              painDeathImpulse("death pain sound impulse (runtime)",            kRetailOnly(61)),
              aiBehaviors("AI behaviors",                                       70),
              aiTurnSpeed("AI turn speed",                                      71),
              aiDazedMinFrames("AI dazed min frames",                           72),
              aiDazedMaxFrames("AI dazed max frames",                           73),
              gunDodgeFrames("AI gunfire awareness delay",                      kRetailOnly(80)),
              gunDodgeLinger("AI gunfire cover linger",                         kRetailOnly(81)),
              gunDodgePriority("AI gunfire priority",                           kRetailOnly(82)),
              startleMissAngle("startle shot miss angle",                       90),
              startleMissDistance("startle shot miss distance",                 91),
              predictAccuracy("aiming prediction accuracy",                     92),
              predictLookback("aiming prediction lookback",                     93),
              predictDelay("aiming prediction position delay",                  94),
              predictAverage("aiming prediction velocity average",              95),
              predictHistory("aiming prediction history size",                  96),
              w0_recoilComp("weapon 0 recoil compensation",                     97),
              w0_minAimError("weapon 0 min aiming error",                       98),
              w0_shotGroupingError("weapon 0 shot grouping error",              99),
              w0_shotErrorDecay("weapon 0 shot error decay",                    100),
              w0_gunErrorMult("weapon 0 error multiplier",                      101),
              w0_triggerDelayMin("weapon 0 trigger pull min delay",             102),
              w0_triggerDelayMax("weapon 0 trigger pull max delay",             103),
              w1_recoilComp("weapon 1 recoil compensation",                     104),
              w1_minAimError("weapon 1 min aiming error",                       105),
              w1_shotGroupingError("weapon 1 shot grouping error",              106),
              w1_shotErrorDecay("weapon 1 shot error decay",                    107),
              w1_gunErrorMult("weapon 1 error multiplier",                      108),
              w1_triggerDelayMin("weapon 1 trigger pull min delay",             109),
              w1_triggerDelayMax("weapon 1 trigger pull max delay",             110),
              w2_recoilComp("weapon 2 recoil compensation",                     111),
              w2_minAimError("weapon 2 min aiming error",                       112),
              w2_shotGroupingError("weapon 2 shot grouping error",              113),
              w2_shotErrorDecay("weapon 2 shot error decay",                    114),
              w2_gunErrorMult("weapon 2 error multiplier",                      115),
              w2_triggerDelayMin("weapon 2 trigger pull min delay",             116),
              w2_triggerDelayMax("weapon 2 trigger pull max delay",             117),
              w3_recoilComp("weapon 3 recoil compensation",                     118),
              w3_minAimError("weapon 3 min aiming error",                       119),
              w3_shotGroupingError("weapon 3 shot grouping error",              120),
              w3_shotErrorDecay("weapon 3 shot error decay",                    121),
              w3_gunErrorMult("weapon 3 error multiplier",                      122),
              w3_triggerDelayMin("weapon 3 trigger pull min delay",             123),
              w3_triggerDelayMax("weapon 3 trigger pull max delay",             124),
              w4_recoilComp("weapon 4 recoil compensation",                     125),
              w4_minAimError("weapon 4 min aiming error",                       126),
              w4_shotGroupingError("weapon 4 shot grouping error",              127),
              w4_shotErrorDecay("weapon 4 shot error decay",                    128),
              w4_gunErrorMult("weapon 4 error multiplier",                      129),
              w4_triggerDelayMin("weapon 4 trigger pull min delay",             130),
              w4_triggerDelayMax("weapon 4 trigger pull max delay",             131),
              w5_recoilComp("weapon 5 recoil compensation",                     132),
              w5_minAimError("weapon 5 min aiming error",                       133),
              w5_shotGroupingError("weapon 5 shot grouping error",              134),
              w5_shotErrorDecay("weapon 5 shot error decay",                    135),
              w5_gunErrorMult("weapon 5 error multiplier",                      136),
              w5_triggerDelayMin("weapon 5 trigger pull min delay",             137),
              w5_triggerDelayMax("weapon 5 trigger pull max delay",             138),
              w6_recoilComp("weapon 6 recoil compensation",                     139),
              w6_minAimError("weapon 6 min aiming error",                       140),
              w6_shotGroupingError("weapon 6 shot grouping error",              141),
              w6_shotErrorDecay("weapon 6 shot error decay",                    142),
              w6_gunErrorMult("weapon 6 error multiplier",                      143),
              w6_triggerDelayMin("weapon 6 trigger pull min delay",             144),
              w6_triggerDelayMax("weapon 6 trigger pull max delay",             145),
              w7_recoilComp("weapon 7 recoil compensation",                     146),
              w7_minAimError("weapon 7 min aiming error",                       147),
              w7_shotGroupingError("weapon 7 shot grouping error",              148),
              w7_shotErrorDecay("weapon 7 shot error decay",                    149),
              w7_gunErrorMult("weapon 7 error multiplier",                      150),
              w7_triggerDelayMin("weapon 7 trigger pull min delay",             151),
              w7_triggerDelayMax("weapon 7 trigger pull max delay",             152),
              w8_recoilComp("weapon 8 recoil compensation",                     153),
              w8_minAimError("weapon 8 min aiming error",                       154),
              w8_shotGroupingError("weapon 8 shot grouping error",              155),
              w8_shotErrorDecay("weapon 8 shot error decay",                    156),
              w8_gunErrorMult("weapon 8 error multiplier",                      157),
              w8_triggerDelayMin("weapon 8 trigger pull min delay",             158),
              w8_triggerDelayMax("weapon 8 trigger pull max delay",             159),
              w9_recoilComp("weapon 9 recoil compensation",                     160),
              w9_minAimError("weapon 9 min aiming error",                       161),
              w9_shotGroupingError("weapon 9 shot grouping error",              162),
              w9_shotErrorDecay("weapon 9 shot error decay",                    163),
              w9_gunErrorMult("weapon 9 error multiplier",                      164),
              w9_triggerDelayMin("weapon 9 trigger pull min delay",             165),
              w9_triggerDelayMax("weapon 9 trigger pull max delay",             166),
              w10_recoilComp("weapon 10 recoil compensation",                   167),
              w10_minAimError("weapon 10 min aiming error",                     168),
              w10_shotGroupingError("weapon 10 shot grouping error",            169),
              w10_shotErrorDecay("weapon 10 shot error decay",                  170),
              w10_gunErrorMult("weapon 10 error multiplier",                    171),
              w10_triggerDelayMin("weapon 10 trigger pull min delay",           172),
              w10_triggerDelayMax("weapon 10 trigger pull max delay",           173),
              w11_recoilComp("weapon 11 recoil compensation",                   174),
              w11_minAimError("weapon 11 min aiming error",                     175),
              w11_shotGroupingError("weapon 11 shot grouping error",            176),
              w11_shotErrorDecay("weapon 11 shot error decay",                  177),
              w11_gunErrorMult("weapon 11 error multiplier",                    178),
              w11_triggerDelayMin("weapon 11 trigger pull min delay",           179),
              w11_triggerDelayMax("weapon 11 trigger pull max delay",           180),
              w12_recoilComp("weapon 12 recoil compensation",                   181),
              w12_minAimError("weapon 12 min aiming error",                     182),
              w12_shotGroupingError("weapon 12 shot grouping error",            183),
              w12_shotErrorDecay("weapon 12 shot error decay",                  184),
              w12_gunErrorMult("weapon 12 error multiplier",                    185),
              w12_triggerDelayMin("weapon 12 trigger pull min delay",           186),
              w12_triggerDelayMax("weapon 12 trigger pull max delay",           187),
              deathEnsureFrames("death ensurance frames",                       188),
              deathInvestFrames("death investigation frames",                   189),
              pursuitDelay("pursuit mode delay",                                190),
              deathTauntChance("death taunt chance",                            191),
              gunPickupChance("gun pickup chance",                              kRetailOnly(200)),
              gunRunningPickupChance("gun running pickup chance",               kRetailOnly(201)),
              combatProfileID("combat profile ID",                              210),
              meleeProfileID("melee profile ID",                                211),
              tauntChance("taunt sound chance",                                 kRetailOnly(220)),
              alertChance("alert sound chance",                                 kRetailOnly(221)),
              startleChance("startle sound chance",                             kRetailOnly(222)),
              checkbodyChance("check body sound chance",                        kRetailOnly(223)),
              pursueChance("pursue sound chance",                               kRetailOnly(224)),
              cowerChance("cower sound chance",                                 kRetailOnly(225)),
              superpunchChance("superpunch sound chance",                       kRetailOnly(226)),
              superkickChance("superkick sound chance",                         kRetailOnly(227)),
              super3Chance("super3 sound chance",                               kRetailOnly(228)),
              super4Chance("super4 sound chance",                               kRetailOnly(229)),
              padding4("padding 4",                                             kRetailOnly(230), true, false),
              tauntSoundName("taunt sound name",                                kRetailOnly(231)),
              alertSoundName("alert sound name",                                kRetailOnly(232)),
              startleSoundName("startle sound name",                            kRetailOnly(233)),
              checkbodySoundName("check body sound name",                       kRetailOnly(234)),
              pursueSoundName("pursue sound name",                              kRetailOnly(235)),
              cowerSoundName("cower sound name",                                kRetailOnly(236)),
              superpunchSoundName("superpunch sound name",                      kRetailOnly(237)),
              superkickSoundName("superkick sound name",                        kRetailOnly(238)),
              super3SoundName("super3 sound name",                              kRetailOnly(239)),
              super4SoundName("super4 sound name",                              kRetailOnly(240)),
              centVisionDist("central vision distance",                         250),
              periphVisionDist("peripheral vision distance",                    251),
              vertVisionDist("vertical vision distances",                       252),
              centVisionRange("central vision range",                           253),
              centVisionMax("central vision max",                               254),
              periphVisionRange("peripheral vision range",                      255),
              periphVisionMax("peripheral vision max",                          256),
              memDefContactDecay("definite contact delay frames",               257),
              memStrongContactDecay("strong contact delay frames",              258),
              memWeakContactDecay("weak contact delay frames",                  259),
              memHiAlertDecay("high alert decay frames",                        260),
              memMedAlertDecay("med alert decay frames",                        261),
              memLowAlertDecay("low alert decay frames",                        262),
              hearing("hearing acuity",                                         263),
              variant("character variant name",                                 264),
              attackParticles("attack particle array name",                     265),
              attackImpacts("attack impact array name",                         266),
              impactsFound("impacts found (runtime)",                           267),
              padding5("padding 5",                                             268),
              modifierType("modifier type (runtime)",                           269),
              modifierName("modifier name",                                     270),
              imp1Name("impact 1 name",                                         271),
              imp1Type("impact 1 type (runtime)",                               272),
              imp2Name("impact 2 name",                                         273),
              imp2Type("impact 2 type (runtime)",                               274),
              imp3Name("impact 3 name",                                         275),
              imp3Type("impact 3 type (runtime)",                               276),
              imp4Name("impact 4 name",                                         277),
              imp4Type("impact 4 type (runtime)",                               278),
              imp5Name("impact 5 name",                                         279),
              imp5Type("impact 5 type (runtime)",                               280),
              imp6Name("impact 6 name",                                         281),
              imp6Type("impact 6 type (runtime)",                               282),
              imp7Name("impact 7 name",                                         283),
              imp7Type("impact 7 type (runtime)",                               284),
              imp8Name("impact 8 name",                                         285),
              imp8Type("impact 8 type (runtime)",                               286),
              imp9Name("impact 9 name",                                         287),
              imp9Type("impact 9 type (runtime)",                               288),
              imp10Name("impact 10 name",                                       289),
              imp10Type("impact 10 type (runtime)",                             290),
              imp11Name("impact 11 name",                                       291),
              imp11Type("impact 11 type (runtime)",                             292),
              imp12Name("impact 12 name",                                       293),
              imp12Type("impact 12 type (runtime)",                             294),
              imp13Name("impact 13 name",                                       295),
              imp13Type("impact 13 type (runtime)",                             296),
              imp14Name("impact 14 name",                                       297),
              imp14Type("impact 14 type (runtime)",                             298),
              imp15Name("impact 15 name",                                       kRetailOnly(310)),
              imp15Type("impact 15 type (runtime)",                             kRetailOnly(311)),
              padding6("padding 6",                                             kRetailOnly(312), true, false),
              deathParticleName("death particle name",                          kRetailOnly(313)),
              deathParticleClass("death particle class (runtime)",              kRetailOnly(314)),
              bodyGeomCache("body geometry cache (runtime)",                    kRetailOnly(315)),
              body("body geometry",                                             320),
              textures("body textures",                                         321),
              materials("body materials",                                       322),
              bodyImpacts("body part impacts",                                  323),
              fightModeDur("fight mode duration",                               324),
              idleAnimTimer1("idle animation initial timer",                    325),
              idleAnimTimer2("idle animation repeat timer",                     326),
              baseHealth("base health",                                         327),
              unusedFeetBits("unused feet bits",                                328),
              bodySizeMin("body size factor min",                               329),
              bodySizeMax("body size factor max",                               330),
              damageResistNormal("damage resistance - normal",                  kRetailOnly(340)),
              damageResistMinorStun("damage resistance - minor stun",           kRetailOnly(341)),
              damageResistMajorStun("damage resistance - major stun",           kRetailOnly(342)),
              damageResistMinorKnockdown("damage resistance - minor knockdown", kRetailOnly(343)),
              damageResistMajorKnockdown("damage resistance - major knockdown", kRetailOnly(344)),
              damageResistBlownup("damage resistance - blownup",                kRetailOnly(345)),
              damageResistPickup("damage resistance - pickup",                  kRetailOnly(346)),
              bossShieldStrength("boss shield strength",                        kRetailOnly(347)),
              animations("animations",                                          350),
              aimingScreens("aiming screens",                                   351),
              miscMystery1A6("misc. mystery 1",                                 kAlphaOnly(360)),
              unusedROF("rate of fire (unused)",                                370),
              miscMystery2A6("misc. mystery 2",                                 kAlphaOnly(380)),
              paddingA6("padding (alpha 6)",                                    kAlphaOnly(381)),
              deathDeleteDelay("death deletion delay",                          kRetailOnly(380)),
              lefthanded("lefthanded",                                          kRetailOnly(381)),
              hasOverpower("has overpower mode",                                kRetailOnly(382)),
              hasSupershield("has supershield",                                 kRetailOnly(383)),
              knockdownImmune("is knockdown immune",                            kRetailOnly(384))
{
    // Set any callback variables that deviate from the default value of false that is set in Template's constructor init
    hasLinks_ = true; // let GameData know that we need ::processLinks() to be called on us
    certified_ = true; // let GameData know that we have fully implemented the fields of this template

    // All fields are inserted unconditionally regardless of presence in the current data format we're reading from disk; per-format presence
    // is handled by Template::sortFieldsFor() later
    fields_.insert(fields_.end(), {&jumpGravityAI2, &jumpGravity, &jumpVelStart, &fallMaxSpeed, &jumpAccel, &jumpTimerAI2, &jumpAccelTimer,
                                   &fallDamageMin, &fallDamageMax, &shadowTXMP, &shadowMinHeight, &shadowMaxToMidRange, &shadowMaxSize,
                                   &shadowMidSize, &shadowMinSize, &shadowTransp1, &shadowTransp2, &shadowMystery1_A6, &shadowMystery2_A6,
                                   &shadowMystery3_A6, &shadowMystery4_A6, &unusedJump1, &unusedJump2, &unusedJump3, &padding1, &unusedCover1,
                                   &unusedCover2, &unusedCover3, &unusedCover4, &unusedAutofreeze1, &unusedAutofreeze2, &hypoRegenRate,
                                   &padding2, &lod1StartDist, &lod2StartDist, &lod3StartDist, &lod4StartDist, &lod5StartDist,
                                   &painBasePercentage, &painMaxPercentage, &painPercentageThreshold, &painResetFrames, &painMinTimer,
                                   &painMaxLight, &painMaxMedium, &painDeathChance, &painVolumeThreshold, &painMediumThreshold,
                                   &painHeavyThreshold, &painSoundsFound, &padding3, &painMinVolume, &painLightSound, &painMediumSound,
                                   &painHeavySound, &painDeathSound, &painLightImpulse, &painMediumImpulse, &painHeavyImpulse,
                                   &painDeathImpulse, &aiBehaviors, &aiTurnSpeed, &aiDazedMinFrames, &aiDazedMaxFrames, &gunDodgeFrames,
                                   &gunDodgeLinger, &gunDodgePriority, &startleMissAngle, &startleMissDistance, &predictAccuracy,
                                   &predictLookback, &predictDelay, &predictAverage, &predictHistory, &w0_recoilComp, &w0_minAimError,
                                   &w0_shotGroupingError, &w0_shotErrorDecay, &w0_gunErrorMult, &w0_triggerDelayMin, &w0_triggerDelayMax,
                                   &w1_recoilComp, &w1_minAimError, &w1_shotGroupingError, &w1_shotErrorDecay, &w1_gunErrorMult,
                                   &w1_triggerDelayMin, &w1_triggerDelayMax, &w2_recoilComp, &w2_minAimError, &w2_shotGroupingError,
                                   &w2_shotErrorDecay, &w2_gunErrorMult, &w2_triggerDelayMin, &w2_triggerDelayMax, &w3_recoilComp,
                                   &w3_minAimError, &w3_shotGroupingError, &w3_shotErrorDecay, &w3_gunErrorMult, &w3_triggerDelayMin,
                                   &w3_triggerDelayMax, &w4_recoilComp, &w4_minAimError, &w4_shotGroupingError, &w4_shotErrorDecay,
                                   &w4_gunErrorMult, &w4_triggerDelayMin, &w4_triggerDelayMax, &w5_recoilComp, &w5_minAimError,
                                   &w5_shotGroupingError, &w5_shotErrorDecay, &w5_gunErrorMult, &w5_triggerDelayMin, &w5_triggerDelayMax,
                                   &w6_recoilComp, &w6_minAimError, &w6_shotGroupingError, &w6_shotErrorDecay, &w6_gunErrorMult,
                                   &w6_triggerDelayMin, &w6_triggerDelayMax, &w7_recoilComp, &w7_minAimError, &w7_shotGroupingError,
                                   &w7_shotErrorDecay, &w7_gunErrorMult, &w7_triggerDelayMin, &w7_triggerDelayMax, &w8_recoilComp,
                                   &w8_minAimError, &w8_shotGroupingError, &w8_shotErrorDecay, &w8_gunErrorMult, &w8_triggerDelayMin,
                                   &w8_triggerDelayMax, &w9_recoilComp, &w9_minAimError, &w9_shotGroupingError, &w9_shotErrorDecay,
                                   &w9_gunErrorMult, &w9_triggerDelayMin, &w9_triggerDelayMax, &w10_recoilComp, &w10_minAimError,
                                   &w10_shotGroupingError, &w10_shotErrorDecay, &w10_gunErrorMult, &w10_triggerDelayMin, &w10_triggerDelayMax,
                                   &w11_recoilComp, &w11_minAimError, &w11_shotGroupingError, &w11_shotErrorDecay, &w11_gunErrorMult,
                                   &w11_triggerDelayMin, &w11_triggerDelayMax, &w12_recoilComp, &w12_minAimError, &w12_shotGroupingError,
                                   &w12_shotErrorDecay, &w12_gunErrorMult, &w12_triggerDelayMin, &w12_triggerDelayMax, &deathEnsureFrames,
                                   &deathInvestFrames, &pursuitDelay, &deathTauntChance, &gunPickupChance, &gunRunningPickupChance,
                                   &combatProfileID, &meleeProfileID, &tauntChance, &alertChance, &startleChance, &checkbodyChance,
                                   &pursueChance, &cowerChance, &superpunchChance, &superkickChance, &super3Chance, &super4Chance, &padding4,
                                   &tauntSoundName, &alertSoundName, &startleSoundName, &checkbodySoundName, &pursueSoundName, &cowerSoundName,
                                   &superpunchSoundName, &superkickSoundName, &super3SoundName, &super4SoundName, &centVisionDist,
                                   &periphVisionDist, &vertVisionDist, &centVisionRange, &centVisionMax, &periphVisionRange, &periphVisionMax,
                                   &memDefContactDecay, &memStrongContactDecay, &memWeakContactDecay, &memHiAlertDecay, &memMedAlertDecay,
                                   &memLowAlertDecay, &hearing, &variant, &attackParticles, &attackImpacts, &impactsFound, &padding5,
                                   &modifierType, &modifierName, &imp1Name, &imp1Type, &imp2Name, &imp2Type, &imp3Name, &imp3Type, &imp4Name,
                                   &imp4Type, &imp5Name, &imp5Type, &imp6Name, &imp6Type, &imp7Name, &imp7Type, &imp8Name, &imp8Type,
                                   &imp9Name, &imp9Type, &imp10Name, &imp10Type, &imp11Name, &imp11Type, &imp12Name, &imp12Type, &imp13Name,
                                   &imp13Type, &imp14Name, &imp14Type, &imp15Name, &imp15Type, &padding6, &deathParticleName,
                                   &deathParticleClass, &bodyGeomCache, &body, &textures, &materials, &bodyImpacts, &fightModeDur,
                                   &idleAnimTimer1, &idleAnimTimer2, &baseHealth, &unusedFeetBits, &bodySizeMin, &bodySizeMax,
                                   &damageResistNormal, &damageResistMinorStun, &damageResistMajorStun, &damageResistMinorKnockdown,
                                   &damageResistMajorKnockdown, &damageResistBlownup, &damageResistPickup, &bossShieldStrength, &animations,
                                   &aimingScreens, &miscMystery1A6, &unusedROF, &miscMystery2A6, &paddingA6, &deathDeleteDelay, &lefthanded,
                                   &hasOverpower, &hasSupershield, &knockdownImmune});

    // Tell the string fields how big they are since it's a variable number and can't be inferred from the field's underlying data type
    painLightSound.setFullSize(32);
    painMediumSound.setFullSize(32);
    painHeavySound.setFullSize(32);
    painDeathSound.setFullSize(32);
    tauntSoundName.setFullSize(32);
    alertSoundName.setFullSize(32);
    startleSoundName.setFullSize(32);
    checkbodySoundName.setFullSize(32);
    pursueSoundName.setFullSize(32);
    cowerSoundName.setFullSize(32);
    superpunchSoundName.setFullSize(32);
    superkickSoundName.setFullSize(32);
    super3SoundName.setFullSize(32);
    super4SoundName.setFullSize(32);
    modifierName.setFullSize(16);
    imp1Name.setFullSize(128);
    imp2Name.setFullSize(128);
    imp3Name.setFullSize(128);
    imp4Name.setFullSize(128);
    imp5Name.setFullSize(128);
    imp6Name.setFullSize(128);
    imp7Name.setFullSize(128);
    imp8Name.setFullSize(128);
    imp9Name.setFullSize(128);
    imp10Name.setFullSize(128);
    imp11Name.setFullSize(128);
    imp12Name.setFullSize(128);
    imp13Name.setFullSize(128);
    imp14Name.setFullSize(128);
    imp15Name.setFullSize(128);
    deathParticleName.setFullSize(64);

    // Set the size of any padding fields for the same reason
    padding1.setFixedSize(2);
    padding2.setFixedSize(2);
    padding3.setFixedSize(1);
    padding4.setFixedSize(2);
    padding5.setFixedSize(1);
    padding6.setFixedSize(2);
    paddingA6.setFixedSize(5);

    // Set up flag maps for our one FieldFlagSet32
    aiBehaviorFlagValues =
    {
        {aiNeverStartle, 0x01},
        {aiDodgeGunfire, 0x02},
        {aiDodgeWhileFiring, 0x04},
        {aiDodgeStopFiring, 0x08},
        {aiRunningPickup, 0x10}
    };
    aiBehaviorFlagNames =
    {
        {aiNeverStartle, "never startle"},
        {aiDodgeGunfire, "dodge gunfire"},
        {aiDodgeWhileFiring, "dodge while firing"},
        {aiDodgeStopFiring, "stop firing while dodging"},
        {aiRunningPickup, "running weapon pickup (ignored)"}
    };
    aiBehaviors.setFlagValueMap(&aiBehaviorFlagValues);
    aiBehaviors.setFlagNameMap(&aiBehaviorFlagNames);
}

unique_ptr<Template> TemplateONCC::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateONCC>(instName, dataFormat);
}

bool TemplateONCC::convertData(Format toFmt)
{
    if (toFmt == curFormat_)
        return true;

    if (toFmt == Format::WinAlpha6)
    {
        cerr << "Advisory: Conversion of ONCC to Win alpha 6 format is not supported at this time.\n";
        return false;
    }

    // Nothing to do as the other formats are all the same
    if (origFormat_ != Format::WinAlpha6)
        return true;

    // If we get this far, the request is to convert WinAlpha6 to another format (and fortunately all other formats are the same). To "convert"
    // the data we simply plug some standard values from retail ONCCs into the fields missing from WinAlpha6. Hypothetically a template's data
    // conversion might also entail more advanced calculation of missing field values from present data, but for ONCC this is not needed. The
    // values below are taken from ONCCkonoko_generic.
    shadowTXMP.linkedName() = "TXMPshadow1";
    shadowMinHeight.defVal() = 12.f;
    shadowMaxToMidRange.defVal() = 8.f;
    shadowMaxSize.defVal() = 6.f;
    shadowMidSize.defVal() = 4.5;
    shadowMinSize.defVal() = 3.f;
    shadowTransp1.defVal() = 48;
    shadowTransp2.defVal() = 48;
    painBasePercentage.defVal() = 35;
    painMaxPercentage.defVal() = 90;
    painPercentageThreshold.defVal() = 15;
    painResetFrames.defVal() = 120;
    painMinTimer.defVal() = 35;
    painMaxLight.defVal() = 1;
    painMaxMedium.defVal() = 2;
    painDeathChance.defVal() = 100;
    painVolumeThreshold.defVal() = 10;
    painMediumThreshold.defVal() = 12;
    painHeavyThreshold.defVal() = 22;
    painSoundsFound.defVal() = 0;
    painMinVolume.defVal() = 0.5;
    painLightSound.defVal() = "konoko_hurt_light";
    painMediumSound.defVal() = "konoko_hurt_medium";
    painHeavySound.defVal() = "konoko_hurt_heavy";
    painDeathSound.defVal() = "konoko_death";
    painLightImpulse.defVal() = 0;
    painMediumImpulse.defVal() = 0;
    painHeavyImpulse.defVal() = 0;
    painDeathImpulse.defVal() = 0;
    gunDodgeFrames.defVal() = 15;
    gunDodgeLinger.defVal() = 1.f;
    gunDodgePriority.defVal() = 1.f;
    gunPickupChance.defVal() = 55;
    gunRunningPickupChance.defVal() = 60;
    tauntChance.defVal() = 100;
    alertChance.defVal() = 0;
    startleChance.defVal() = 0;
    checkbodyChance.defVal() = 0;
    pursueChance.defVal() = 0;
    cowerChance.defVal() = 0;
    superpunchChance.defVal() = 100;
    superkickChance.defVal() = 100;
    super3Chance.defVal() = 0;
    super4Chance.defVal() = 0;
    tauntSoundName.defVal() = "c17_99_28konoko";
    alertSoundName.defVal() = "";
    startleSoundName.defVal() = "";
    checkbodySoundName.defVal() = "";
    pursueSoundName.defVal() = "";
    cowerSoundName.defVal() = "";
    superpunchSoundName.defVal() = "c18_79_14konoko";
    superkickSoundName.defVal() = "c18_79_15konoko";
    super3SoundName.defVal() = "";
    super4SoundName.defVal() = "";
    imp15Name.defVal() = "Footstep_RunSprint";
    imp15Type.defVal() = 65535;
    damageResistNormal.defVal() = 0.f;
    damageResistMinorStun.defVal() = 0.f;
    damageResistMajorStun.defVal() = 0.5;
    damageResistMinorKnockdown.defVal() = 0.25;
    damageResistMajorKnockdown.defVal() = 0.f;
    damageResistBlownup.defVal() = 0.f;
    damageResistPickup.defVal() = 0.f;
    bossShieldStrength.defVal() = 0.5;
    deathDeleteDelay.defVal() = 0;
    lefthanded.defVal() = 0;
    hasOverpower.defVal() = 1;
    hasSupershield.defVal() = 0;
    knockdownImmune.defVal() = 0;

    curFormat_ = toFmt;

    return true;
}

/**************************** TemplateONCP ****************************/
TemplateONCP::TemplateONCP(string instName, Format dataFormat)
            : Template("ONCP", std::move(instName), dataFormat),
              padding1("padding 1",                            2, true, false),
              classesFound("particle classes found (runtime)", 3),
              padding2("padding 2",                            4, true, false),
              arraySize("particle count",                      5)
{
    certified_ = true;

    fwvlaSizeOffset_ = {0x1C, 32};

    fields_.insert(fields_.end(), {&padding1, &classesFound, &padding2, &arraySize});

    padding1.setFixedSize(16);
    padding2.setFixedSize(3);
}

unique_ptr<Template> TemplateONCP::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateONCP>(instName, dataFormat);
}

void TemplateONCP::createFWVarArray(int32_t n)
{
    const size_t sz = static_cast<size_t>(n);
    particleName.reserve(sz);
    particleClassName.reserve(sz);
    bodyPart.reserve(sz);
    particlePadding.reserve(sz);
    particleClassOffset.reserve(sz);

    int s = static_cast<int>(fields_.size()) + 1; // resume adding fields after TemplateONCP::TemplateONCP's fields were added
    int nf = 5; // number of fields that we're adding
    for (int32_t i = 0; i < n; ++i)
    {
        particleName.emplace_back("particle name [" + to_string(i) + "]",            s + (nf * i) + 0, true, true, "", "", 16);
        particleClassName.emplace_back("particle class name [" + to_string(i) + "]", s + (nf * i) + 1, true, true, "", "", 64);
        bodyPart.emplace_back("body part [" + to_string(i) + "]",                    s + (nf * i) + 2);
        particlePadding.emplace_back("particle padding [" + to_string(i) + "]",      s + (nf * i) + 3, true, true, vector<char>{},
                                     vector<char>{}, 2);
        particleClassOffset.emplace_back("particle class offset (runtime) [" + to_string(i) + "]", kRetailOnly(s + (nf * i) + 4));
    }

    for (size_t i = 0; i < sz; ++i)
        fields_.insert(fields_.end(), {&particleName[i], &particleClassName[i], &bodyPart[i], &particlePadding[i], &particleClassOffset[i]});
}

/**************************** TemplateONCV ****************************/
TemplateONCV::TemplateONCV(string instName, Format dataFormat)
            : Template("ONCV", std::move(instName), dataFormat),
              oncvParent("parent",           2),
              poolName("standard pool name", 3),
              hardPoolName("hard pool name", kRetailOnly(4))
{
    hasLinks_ = true;
    certified_ = true;

    poolName.setFullSize(32);
    hardPoolName.setFullSize(32);

    fields_.insert(fields_.end(), {&oncvParent, &poolName, &hardPoolName});
}

unique_ptr<Template> TemplateONCV::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateONCV>(instName, dataFormat);
}

/**************************** TemplateONIA ****************************/
TemplateONIA::TemplateONIA(string instName, Format dataFormat)
            : Template("ONIA", std::move(instName), dataFormat),
              padding1("padding 1",                   2, true, false),
              indicesFound("indices found (runtime)", 3),
              padding2("padding 2",                   4, true, false),
              arraySize("impact count",               5)
{
    certified_ = true;

    fwvlaSizeOffset_ = {0x1C, 32};

    fields_.insert(fields_.end(), {&padding1, &indicesFound, &padding2, &arraySize});

    padding1.setFixedSize(16);
    padding2.setFixedSize(3);
}

unique_ptr<Template> TemplateONIA::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateONIA>(instName, dataFormat);
}

void TemplateONIA::createFWVarArray(int32_t n)
{
    const size_t sz = static_cast<size_t>(n);
    impactName.reserve(sz);
    impactTypeName.reserve(sz);
    impactModifier.reserve(sz);
    impactType.reserve(sz);
    modifierType.reserve(sz);

    int s = static_cast<int>(fields_.size()) + 1; // resume adding fields after TemplateONIA::TemplateONIA's fields were added
    int nf = 5; // number of fields that we're adding
    for (int32_t i = 0; i < n; ++i)
    {
        impactName.emplace_back("impact name [" + to_string(i) + "]",               s + (nf * i) + 0, true, true, "", "", 16);
        impactTypeName.emplace_back("impact type name [" + to_string(i) + "]",      s + (nf * i) + 1, true, true, "", "", 128);
        impactModifier.emplace_back("impact modifier [" + to_string(i) + "]",       s + (nf * i) + 2, true, true, "", "", 16);
        impactType.emplace_back("impact type (runtime) [" + to_string(i) + "]",     s + (nf * i) + 3);
        modifierType.emplace_back("modifier type (runtime) [" + to_string(i) + "]", s + (nf * i) + 4);
    }

    for (size_t i = 0; i < sz; ++i)
        fields_.insert(fields_.end(), {&impactName[i], &impactTypeName[i], &impactModifier[i], &impactType[i], &modifierType[i]});
}

/**************************** TemplatePNTA ****************************/
TemplatePNTA::TemplatePNTA(string instName, Format dataFormat)
            : Template("PNTA", std::move(instName), dataFormat),
              padding("padding",                            2, true, false),
              minX("minimum x coordinate",                  3),
              minY("minimum y coordinate",                  4),
              minZ("minimum z coordinate",                  5),
              maxX("maximum x coordinate",                  6),
              maxY("maximum y coordinate",                  7),
              maxZ("maximum z coordinate",                  8),
              centerX("x coordinate of center",             9),
              centerY("y coordinate of center",             10),
              centerZ("z coordinate of center",             11),
              radius("distance from center to each point",  12),
              arraySize("point count",                      13),
              deadSpace("dead space",                       1000000, true, false) // we need this to sort after every possible array element
{
    certified_ = true;

    fwvlaSizeOffset_ = {0x3C, 32};

    fields_.insert(fields_.end(), {&padding, &minX, &minY, &minZ, &maxX, &maxY, &maxZ, &centerX, &centerY, &centerZ, &radius, &arraySize});

    padding.setFixedSize(12);
}

unique_ptr<Template> TemplatePNTA::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplatePNTA>(instName, dataFormat);
}

void TemplatePNTA::postProcessData(span<char> dataPacket)
{
    // PNTA needs special post-processing because the single largest PNTA in each level data file (which is the one for the complete level
    // geometry) has about 700 bytes of junk at the end that can't be explained. If we don't read it in, we trigger a warning from the memory
    // audit in GDM's listInstances() method, but really for the sake of completeness we should be reading it in anyway.
    uint32_t kPNTAJunkSafety = 2000;
    uint32_t endOfReadData = fields_.back()->offset() + fields_.back()->size(); // find where end of data *should* be
    uint32_t postPadding = BAP(endOfReadData); // bytes needed to get from the end of the data to the next 32-byte boundary
    // Calculate the amount of stuff at the end of the data packet that can't be explained by post-instance 32-byte alignment padding
    uint32_t deadSpaceSize = static_cast<uint32_t>(dataPacket.size()) - endOfReadData - postPadding;
    if (deadSpaceSize)
    {
        if (deadSpaceSize > kPNTAJunkSafety)
        {
            cerr << "Advisory: Calculated dead space after PNTA exceeds safety limit; capping to " << kPNTAJunkSafety << ".\n";
            deadSpaceSize = kPNTAJunkSafety;
        }
        deadSpace.setFixedSize(deadSpaceSize);
        deadSpace.setOffset(endOfReadData);
        fields_.insert(fields_.end(), &deadSpace);
        DataIO::ReadData(deadSpace.var(), dataPacket, deadSpace.offset(), deadSpace.fixedSize());
        sortFieldsFor(origFormat_); // sort fields again so that "deadSpace"'s size is added to the total instance data size
    }
}

void TemplatePNTA::createFWVarArray(int32_t n)
{
    const size_t sz = static_cast<size_t>(n);
    pointX.reserve(sz);
    pointY.reserve(sz);
    pointZ.reserve(sz);

    int s = static_cast<int>(fields_.size()) + 1; // resume adding fields after fixed header fields
    int nf = 3; // number of fields per array element
    for (int32_t i = 0; i < n; ++i)
    {
        pointX.emplace_back("x coordinate [" + to_string(i) + "]", s + (nf * i) + 0);
        pointY.emplace_back("y coordinate [" + to_string(i) + "]", s + (nf * i) + 1);
        pointZ.emplace_back("z coordinate [" + to_string(i) + "]", s + (nf * i) + 2);
    }

    for (size_t i = 0; i < sz; ++i)
        fields_.insert(fields_.end(), {&pointX[i], &pointY[i], &pointZ[i]});
}

/**************************** TemplateSNDD ****************************/
TemplateSNDD::TemplateSNDD(string instName, Format dataFormat)
            : Template("SNDD", std::move(instName), dataFormat),
              soundFlags("sound flags",               2),
              soundFormat("sound format",             kWindowsOnly(3)),
              numChannels("number of channels",       kWindowsOnly(4)),
              sampleRate("sample rate",               kWindowsOnly(5)),
              avgByteRate("avg. byte rate",           kWindowsOnly(6)),
              blockSize("block size",                 kWindowsOnly(7)),
              bitsPerSample("bits per sample",        kWindowsOnly(8)),
              coefBlockSize("coefficient block size", kWindowsOnly(9)),
              samplesPerBlock("samples per block",    kWindowsOnly(10)),
              numCoefs("coefficient pair count",      kWindowsOnly(11)),
              coef1a("coef. pair 1a",                 kWindowsOnly(12)),
              coef1b("coef. pair 1b",                 kWindowsOnly(13)),
              coef2a("coef. pair 2a",                 kWindowsOnly(14)),
              coef2b("coef. pair 2b",                 kWindowsOnly(15)),
              coef3a("coef. pair 3a",                 kWindowsOnly(16)),
              coef3b("coef. pair 3b",                 kWindowsOnly(17)),
              coef4a("coef. pair 4a",                 kWindowsOnly(18)),
              coef4b("coef. pair 4b",                 kWindowsOnly(19)),
              coef5a("coef. pair 5a",                 kWindowsOnly(20)),
              coef5b("coef. pair 5b",                 kWindowsOnly(21)),
              coef6a("coef. pair 6a",                 kWindowsOnly(22)),
              coef6b("coef. pair 6b",                 kWindowsOnly(23)),
              coef7a("coef. pair 7a",                 kWindowsOnly(24)),
              coef7b("coef. pair 7b",                 kWindowsOnly(25)),
              duration("duration (ticks)",            26),
              padding("padding",                      kMacOnly(27)),
              soundIndex("sound index",               kPS2Only(27)),
              rawSize("raw part size",                28),
              rawOffset("raw offset",                 29),
              soundBlob("sound data blob",            1)
{
    // On PS2 the sample data is not in the level's raw/sep files; it lives in the SOUNDS/LEVEL#/SOUND.RAW/SOUND.SEP files and is located via the
    // "sound index" field rather than "rawOffset" (which is a runtime memory pointer on PS2). We therefore skip the normal aux-data path and let
    // GameData fill "soundBlob" via processSoundData() instead. For all other formats the sample data is read in the normal way.
    if (dataFormat == Format::PS2)
        hasSoundData_ = true;
    else
        hasAuxData_ = true;
    certified_ = true;

    if (origFormat_ == Format::WinAlpha6 || origFormat_ == Format::PC1_0)
    {
        soundFlagValues =
        {
            {Unknown0x01,   0x1},
            {Unknown0x02,   0x2},
            {SimpleHeader,  0x4},
            {ComplexHeader, 0x8}
        };
        soundFlagNames =
        {
            {Unknown0x01,   "unknown (0x1)"},
            {Unknown0x02,   "unknown (0x2)"},
            {SimpleHeader,  "simple header"},
            {ComplexHeader, "complex header"}
        };
    }
    else if (origFormat_ == Format::MacBeta4 || origFormat_ == Format::PC1_1)
    {
        soundFlagValues =
        {
            {Compressed, 0x1},
            {Stereo,     0x2}
        };
        soundFlagNames =
        {
            {Compressed, "compressed"},
            {Stereo,     "stereo"}
        };
    }
    soundFlags.setFlagValueMap(&soundFlagValues);
    soundFlags.setFlagNameMap(&soundFlagNames);

    soundFormatValues =
    {
        {PCM,   0x1},
        {ADPCM, 0x2}
    };
    soundFormatNames =
    {
        {PCM, "linear PCM"},
        {ADPCM, "MS ADPCM"}
    };
    soundFormat.setTypeValueMap(&soundFormatValues);
    soundFormat.setTypeNameMap(&soundFormatNames);

    fields_.insert(fields_.end(), {&soundFlags, &soundFormat, &numChannels, &sampleRate, &avgByteRate, &blockSize, &bitsPerSample,
                                   &coefBlockSize, &samplesPerBlock, &numCoefs, &coef1a, &coef1b, &coef2a, &coef2b, &coef3a, &coef3b, &coef4a,
                                   &coef4b, &coef5a, &coef5b, &coef6a, &coef6b, &coef7a, &coef7b, &duration, &padding, &soundIndex, &rawSize,
                                   &rawOffset});
    fieldsAux_.insert(fieldsAux_.end(), {&soundBlob});

    padding.setFixedSize(2);
}

unique_ptr<Template> TemplateSNDD::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateSNDD>(instName, dataFormat);
}

void TemplateSNDD::prepareAuxFields()
{
    soundBlob.setReservedSize(rawSize.val());
}

size_t TemplateSNDD::auxOffset()
{
    return rawOffset.val();
}

size_t TemplateSNDD::auxFieldsBaseOffset()
{
    return auxOffset();
}

// Fill "soundBlob" with this instance's PS2 sample data. Unlike pre-PS2 SNDDs, whose data lives in the level's raw/sep files at "rawOffset", a
// PS2 SNDD's data lives in the level's SOUND.RAW/SOUND.SEP files and is located by looking "soundIndex" up in the parsed SOUND.DAT table, which
// yields the data's size and offset and whether it resides in SOUND.RAW or SOUND.SEP
void TemplateSNDD::processSoundData(vector<char> & rawBuf, vector<char> & sepBuf, const map<uint16_t, PS2SoundEntry> & table)
{
    uint16_t index = soundIndex.val();
    auto it = table.find(index);
    if (it == table.end())
    {
        cerr << "Error: Sound index " << index << " for instance " << quoted(name_) << " was not found in the level's SOUND.DAT table.\n";
        return;
    }

    const PS2SoundEntry & entry = it->second;
    vector<char> & buf = (entry.inRaw ? rawBuf : sepBuf);
    string fileName = (entry.inRaw ? "SOUND.RAW" : "SOUND.SEP");
    if (static_cast<size_t>(entry.offset) + entry.size > buf.size())
    {
        cerr << "Error: Sound index " << index << " for instance " << quoted(name_) << " claims data that extends beyond the end of "
             << fileName << ".\n";
        return;
    }

    soundBlob.setReservedSize(entry.size);
    copy(buf.begin() + entry.offset, buf.begin() + entry.offset + entry.size, soundBlob.val().begin());
    sortFieldsAuxFor(origFormat_); // sets "soundBlob"'s offset and "auxDataSize_", matching what the normal aux-data path would have done
}

/**************************** TemplateTRAC ****************************/
TemplateTRAC::TemplateTRAC(string instName, Format dataFormat)
            : Template("TRAC", std::move(instName), dataFormat),
              padding("padding",            2, true, false),
              tracLink("TRAC link",         3),
              runtimeField("runtime field", 4, true, false),
              arraySize("animation count",  5)
{
    hasLinks_ = true;
    certified_ = true;

    fwvlaSizeOffset_ = {0x1E, 16};

    fields_.insert(fields_.end(), {&padding, &tracLink, &runtimeField, &arraySize});

    padding.setFixedSize(16);
}

unique_ptr<Template> TemplateTRAC::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTRAC>(instName, dataFormat);
}

void TemplateTRAC::createFWVarArray(int32_t n)
{
    const size_t sz = static_cast<size_t>(n);
    animWeight.reserve(sz);
    animRuntime1.reserve(sz);
    animRuntime2.reserve(sz);
    animTram.reserve(sz);

    int s = static_cast<int>(fields_.size()) + 1; // resume adding fields after TemplateTRAC::TemplateTRAC's fields were added
    int nf = 4; // number of fields that we're adding
    for (int32_t i = 0; i < n; ++i)
    {
        animWeight.emplace_back("animation weight [" + to_string(i) + "]",      s + (nf * i) + 0);
        animRuntime1.emplace_back("animation runtime 1 [" + to_string(i) + "]", s + (nf * i) + 1, true, false);
        animRuntime2.emplace_back("animation runtime 2 [" + to_string(i) + "]", s + (nf * i) + 2, true, false);
        animTram.emplace_back("TRAM link [" + to_string(i) + "]",               s + (nf * i) + 3);
    }

    for (size_t i = 0; i < sz; ++i)
        fields_.insert(fields_.end(), {&animWeight[i], &animRuntime1[i], &animRuntime2[i], &animTram[i]});
}

/**************************** TemplateTRAM ****************************/
TemplateTRAM::TemplateTRAM(string instName, Format dataFormat)
            : Template("TRAM", std::move(instName), dataFormat),
              animNamePtr("animation name pointer (runtime)",                        2, true, false),
              heightTrackOffset("height track raw offset",                           3),
              horizVelOffset("horizontal velocities raw offset",                     4),
              attackPartOffset("attack data raw offset",                             5),
              damagePartOffset("take-damage data raw offset",                        6),
              motionBlurPartOffset("motion blur data raw offset",                    7),
              shortcutDataOffset("shortcut data raw offset",                         8),
              throwDataOffset("throw data raw offset",                               9),
              footstepDataOffset("footstep data raw offset",                         10),
              particleDataOffset("particle data raw offset",                         11),
              positionDataOffset("position data raw offset",                         12),
              rotationsOffset("rotation data raw offset",                            13),
              soundDataOffset("sound data raw offset",                               kRetailOnly(14)),
              animFlags("animation flags",                                           15),
              directAnim0("direct animation 0",                                      16),
              directAnim1("direct animation 1",                                      17),
              usedBodyParts("used body parts",                                       18),
              replacedParts("replaced parts",                                        19),
              finalRotation("final rotation",                                        20),
              movingDir("moving direction",                                          21),
              vocalizationType("vocalization type",                                  22),
              maxHorizAttackExtent("max horizontal attack extent",                   23),
              minYOfAttack("min Y of attack",                                        24),
              maxYOfAttack("max Y of attack",                                        25),
              firstExtentFrame("first extent frame",                                 62),
              firstExtentAttackIdx("first extent attack index",                      63),
              firstExtentAttackFrameOffset("first extent attack frame offset",       64),
              firstExtentPelvisX("first extent pelvis X",                            65),
              firstExtentPelvisZ("first extent pelvis Z",                            66),
              firstExtentPelvisY("first extent pelvis Y",                            67),
              firstExtentLength("first extent length",                               68),
              firstExtentMinY("first extent min Y",                                  69),
              firstExtentMaxY("first extent max Y",                                  70),
              firstExtentAngle("first extent angle",                                 71),
              farthestExtentFrame("farthest extent frame",                           72),
              farthestExtentAttackIdx("farthest extent attack index",                73),
              farthestExtentAttackFrameOffset("farthest extent attack frame offset", 74),
              farthestExtentPelvisX("farthest extent pelvis X",                      75),
              farthestExtentPelvisZ("farthest extent pelvis Z",                      76),
              farthestExtentPelvisY("farthest extent pelvis Y",                      77),
              farthestExtentLength("farthest extent length",                         78),
              farthestExtentMinY("farthest extent min Y",                            79),
              farthestExtentMaxY("farthest extent max Y",                            80),
              farthestExtentAngle("farthest extent angle",                           81),
              altMoveDir("alternative move direction",                               82),
              extentPartCount("extent data part count",                              83),
              extentPartOffset("extent data raw offset",                             84),
              impactParticleName("impact particle name",                             85),
              hardPause("hard pause",                                                86),
              softPause("soft pause",                                                87),
              soundPartCount("sound data part count",                                kRetailOnly(88)),
              soundPtr("sound pointer (runtime)",                                    89, true, false),
              soundStartFrame("sound start frame (runtime)",                         90, true, false),
              frameRate("frame rate",                                                91),
              compressionSize("compression size",                                    92),
              animType("animation type",                                             93),
              aimingType("aiming type",                                              94),
              fromState("from state",                                                95),
              toState("to state",                                                    96),
              bodyPartCount("body part count",                                       97),
              frameCount("frame count",                                              98),
              duration("duration",                                                   99),
              variant("variant",                                                     100),
              variantEndMarker("variant end marker",                                 101, true, false),
              atomicStart("atomic start",                                            102),
              atomicEnd("atomic end",                                                103),
              endInterpolation("end interpolation",                                  104),
              maxInterpolation("max interpolation",                                  105),
              actionFrame("action frame",                                            106),
              firstLevelAvailable("first level available",                           107),
              firstInvulnerableFrame("first invulnerable frame",                     kRetailOnly(108)),
              lastInvulnerableFrame("last invulnerable frame",                       kRetailOnly(109)),
              attackPartCount("attack part count",                                   110),
              takeDamagePartCount("take-damage data part count",                     111),
              motionBlurPartCount("motion blur data part count",                     112),
              shortcutPartCount("shortcut data part count",                          113),
              footstepPartCount("footstep data part count",                          114),
              particlePartCount("particle data part count",                          115)
{
    hasLinks_   = true;
    hasAuxData_ = true;
    certified_  = true;

    animFlagValues =
    {
        {Prepared,           0x000001},
        {Invulnerable,       0x000002},
        {BlockHigh,          0x000004},
        {BlockLow,           0x000008},
        {Attack,             0x000010},
        {DropWeapon,         0x000020},
        {InAir,              0x000040},
        {Atomic,             0x000080},
        {NoTurn,             0x000100},
        {AimForward,         0x000200},
        {AimLeft,            0x000400},
        {AimRight,           0x000800},
        {AimBackward,        0x001000},
        {Overlay,            0x002000},
        {DontInterpVelocity, 0x004000},
        {ThrowSource,        0x008000},
        {ThrowTarget,        0x010000},
        {RealWorld,          0x020000},
        {DoAim,              0x040000},
        {DontAim,            0x080000},
        {CanPickup,          0x100000},
        {Aim360,             0x200000},
        {DisableShield,      0x400000},
        {NoAIPickup,         0x800000},
    };
    animFlagNames =
    {
        {Prepared,           "prepared"},
        {Invulnerable,       "invulnerable"},
        {BlockHigh,          "blockHigh"},
        {BlockLow,           "blockLow"},
        {Attack,             "attack"},
        {DropWeapon,         "dropWeapon"},
        {InAir,              "inAir"},
        {Atomic,             "atomic"},
        {NoTurn,             "noTurn"},
        {AimForward,         "aimForward"},
        {AimLeft,            "aimLeft"},
        {AimRight,           "aimRight"},
        {AimBackward,        "aimBackward"},
        {Overlay,            "overlay"},
        {DontInterpVelocity, "dontInterpolateVelocity"},
        {ThrowSource,        "throwSource"},
        {ThrowTarget,        "throwTarget"},
        {RealWorld,          "realWorld"},
        {DoAim,              "doAim"},
        {DontAim,            "dontAim"},
        {CanPickup,          "canPickup"},
        {Aim360,             "aim360"},
        {DisableShield,      "disableShield"},
        {NoAIPickup,         "noAIPickup"},
    };
    animFlags.setFlagValueMap(&animFlagValues);
    animFlags.setFlagNameMap(&animFlagNames);

    bodyPartValues =
    {
        {Pelvis,        0x00001},
        {LeftThigh,     0x00002},
        {LeftShin,      0x00004},
        {LeftFoot,      0x00008},
        {RightThigh,    0x00010},
        {RightShin,     0x00020},
        {RightFoot,     0x00040},
        {Abdomen,       0x00080},
        {Chest,         0x00100},
        {Neck,          0x00200},
        {Head,          0x00400},
        {LeftShoulder,  0x00800},
        {LeftUpperArm,  0x01000},
        {LeftForearm,   0x02000},
        {LeftHand,      0x04000},
        {RightShoulder, 0x08000},
        {RightUpperArm, 0x10000},
        {RightForeArm,  0x20000},
        {RightHand,     0x40000},
    };
    bodyPartNames =
    {
        {Pelvis,        "pelvis"},
        {LeftThigh,     "left thigh"},
        {LeftShin,      "left shin"},
        {LeftFoot,      "left foot"},
        {RightThigh,    "right thigh"},
        {RightShin,     "right shin"},
        {RightFoot,     "right foot"},
        {Abdomen,       "abdomen"},
        {Chest,         "chest"},
        {Neck,          "neck"},
        {Head,          "head"},
        {LeftShoulder,  "left shoulder"},
        {LeftUpperArm,  "left upper arm"},
        {LeftForearm,   "left forearm"},
        {LeftHand,      "left hand"},
        {RightShoulder, "right shoulder"},
        {RightUpperArm, "right upper arm"},
        {RightForeArm,  "right forearm"},
        {RightHand,     "right hand"},
    };
    usedBodyParts.setFlagValueMap(&bodyPartValues);
    usedBodyParts.setFlagNameMap(&bodyPartNames);
    replacedParts.setFlagValueMap(&bodyPartValues);
    replacedParts.setFlagNameMap(&bodyPartNames);

    bodyPartIdxValues =
    {
        {Pelvis,        0},
        {LeftThigh,     1},
        {LeftShin,      2},
        {LeftFoot,      3},
        {RightThigh,    4},
        {RightShin,     5},
        {RightFoot,     6},
        {Abdomen,       7},
        {Chest,         8},
        {Neck,          9},
        {Head,          10},
        {LeftShoulder,  11},
        {LeftUpperArm,  12},
        {LeftForearm,   13},
        {LeftHand,      14},
        {RightShoulder, 15},
        {RightUpperArm, 16},
        {RightForeArm,  17},
        {RightHand,     18},
    };
    bodyPartIdxNames =
    {
        {Pelvis,        "pelvis"},
        {LeftThigh,     "left thigh"},
        {LeftShin,      "left shin"},
        {LeftFoot,      "left foot"},
        {RightThigh,    "right thigh"},
        {RightShin,     "right shin"},
        {RightFoot,     "right foot"},
        {Abdomen,       "abdomen"},
        {Chest,         "chest"},
        {Neck,          "neck"},
        {Head,          "head"},
        {LeftShoulder,  "left shoulder"},
        {LeftUpperArm,  "left upper arm"},
        {LeftForearm,   "left forearm"},
        {LeftHand,      "left hand"},
        {RightShoulder, "right shoulder"},
        {RightUpperArm, "right upper arm"},
        {RightForeArm,  "right forearm"},
        {RightHand,     "right hand"},
    };

    attackFlagValues =
    {
        {Unblockable,       0x01},
        {HighAttack,        0x02},
        {LowAttack,         0x04},
        {HalfDamageOnBlock, 0x08},
    };
    attackFlagNames =
    {
        {Unblockable,       "unblockable"},
        {HighAttack,        "highAttack"},
        {LowAttack,         "lowAttack"},
        {HalfDamageOnBlock, "halfDamageOnBlock"},
    };

    footstepTypeValues =
    {
        {FSLeftFoot,  0x01},
        {FSRightFoot, 0x02},
        {FSBothFeet,  0x03},
    };
    footstepTypeNames =
    {
        {FSLeftFoot,  "left"},
        {FSRightFoot, "right"},
        {FSBothFeet,  "both"},
    };

    movDirValues =
    {
        {MDNone,   0},
        {Forward,  1},
        {Backward, 2},
        {Left,     3},
        {Right,    4},
        {Full360,  5},
    };
    movDirNames =
    {
        {MDNone,   "none"},
        {Forward,  "forward"},
        {Backward, "backward"},
        {Left,     "left"},
        {Right,    "right"},
        {Full360,  "360"},
    };
    movingDir.setTypeValueMap(&movDirValues);
    movingDir.setTypeNameMap(&movDirNames);
    altMoveDir.setTypeValueMap(&movDirValues);
    altMoveDir.setTypeNameMap(&movDirNames);

    vocTypeValues =
    {
        {Taunt,      0},
        {Alert,      1},
        {Startle,    2},
        {Checkbody,  3},
        {Pursue,     4},
        {Cower,      5},
        {Superpunch, 6},
        {Superkick,  7},
        {Super3,     8},
        {Super4,     9},
    };
    vocTypeNames =
    {
        {Taunt,      "taunt"},
        {Alert,      "alert"},
        {Startle,    "startle"},
        {Checkbody,  "checkbody"},
        {Pursue,     "pursue"},
        {Cower,      "cower"},
        {Superpunch, "superpunch"},
        {Superkick,  "superkick"},
        {Super3,     "super3"},
        {Super4,     "super4"},
    };
    vocalizationType.setTypeValueMap(&vocTypeValues);
    vocalizationType.setTypeNameMap(&vocTypeNames);

    animVariantValues =
    {
        {Sprint,       0x0100},
        {Fight,        0x0200},
        {Shoulder,     0x0400},
        {RightyPistol, 0x0800},
        {LeftyPistol,  0x1000},
        {RightyRifle,  0x2000},
        {LeftyRifle,   0x4000},
        {Panic,        0x8000},
    };
    animVariantNames =
    {
        {Sprint,       "sprint"},
        {Fight,        "fight"},
        {Shoulder,     "shoulder"},
        {RightyPistol, "righty pistol"},
        {LeftyPistol,  "lefty pistol"},
        {RightyRifle,  "righty rifle"},
        {LeftyRifle,   "lefty rifle"},
        {Panic,        "panic"},
    };
    variant.setFlagValueMap(&animVariantValues);
    variant.setFlagNameMap(&animVariantNames);

    animTypeValues =
    {
        {0,   0x00}, {1,   0x01}, {2,   0x02}, {3,   0x03}, {4,   0x04},
        {5,   0x05}, {6,   0x06}, {7,   0x07}, {8,   0x08}, {9,   0x09},
        {10,  0x0A}, {11,  0x0B}, {12,  0x0C}, {13,  0x0D}, {14,  0x0E},
        {15,  0x0F}, {16,  0x10}, {17,  0x11}, {18,  0x12}, {19,  0x13},
        {20,  0x14}, {21,  0x15}, {22,  0x16}, {23,  0x17}, {24,  0x18},
        {25,  0x19}, {26,  0x1A}, {27,  0x1B}, {28,  0x1C}, {29,  0x1D},
        {30,  0x1E}, {31,  0x1F}, {32,  0x20}, {33,  0x21}, {34,  0x22},
        {35,  0x23}, {36,  0x24}, {37,  0x25}, {38,  0x26}, {39,  0x27},
        {40,  0x28}, {41,  0x29}, {42,  0x2A}, {43,  0x2B}, {44,  0x2C},
        {45,  0x2D}, {46,  0x2E}, {47,  0x2F}, {48,  0x30}, {49,  0x31},
        {50,  0x32}, {51,  0x33}, {52,  0x34}, {53,  0x35}, {54,  0x36},
        {55,  0x37}, {56,  0x38}, {57,  0x39}, {58,  0x3A}, {59,  0x3B},
        {60,  0x3C}, {61,  0x3D}, {62,  0x3E}, {63,  0x3F}, {64,  0x40},
        {65,  0x41}, {66,  0x42}, {67,  0x43}, {68,  0x44}, {69,  0x45},
        {70,  0x46}, {71,  0x47}, {72,  0x48}, {73,  0x49}, {74,  0x4A},
        {75,  0x4B}, {76,  0x4C}, {77,  0x4D}, {78,  0x4E}, {79,  0x4F},
        {80,  0x50}, {81,  0x51}, {82,  0x52}, {83,  0x53}, {84,  0x54},
        {85,  0x55}, {86,  0x56}, {87,  0x57}, {88,  0x58}, {89,  0x59},
        {90,  0x5A}, {91,  0x5B}, {92,  0x5C}, {93,  0x5D}, {94,  0x5E},
        {95,  0x5F}, {96,  0x60}, {97,  0x61}, {98,  0x62}, {99,  0x63},
        {100, 0x64}, {101, 0x65}, {102, 0x66}, {103, 0x67}, {104, 0x68},
        {105, 0x69}, {106, 0x6A}, {107, 0x6B}, {108, 0x6C}, {109, 0x6D},
        {110, 0x6E}, {111, 0x6F}, {112, 0x70}, {113, 0x71}, {114, 0x72},
        {115, 0x73}, {116, 0x74}, {117, 0x75}, {118, 0x76}, {119, 0x77},
        {120, 0x78}, {121, 0x79}, {122, 0x7A}, {123, 0x7B}, {124, 0x7C},
        {125, 0x7D}, {126, 0x7E}, {127, 0x7F}, {128, 0x80}, {129, 0x81},
        {130, 0x82}, {131, 0x83}, {132, 0x84}, {133, 0x85}, {134, 0x86},
        {135, 0x87}, {136, 0x88}, {137, 0x89}, {138, 0x8A}, {139, 0x8B},
        {140, 0x8C}, {141, 0x8D}, {142, 0x8E}, {143, 0x8F}, {144, 0x90},
        {145, 0x91}, {146, 0x92}, {147, 0x93}, {148, 0x94}, {149, 0x95},
        {150, 0x96}, {151, 0x97}, {152, 0x98}, {153, 0x99}, {154, 0x9A},
        {155, 0x9B}, {156, 0x9C}, {157, 0x9D}, {158, 0x9E}, {159, 0x9F},
        {160, 0xA0}, {161, 0xA1}, {162, 0xA2}, {163, 0xA3}, {164, 0xA4},
        {165, 0xA5}, {166, 0xA6}, {167, 0xA7}, {168, 0xA8}, {169, 0xA9},
        {170, 0xAA}, {171, 0xAB}, {172, 0xAC}, {173, 0xAD}, {174, 0xAE},
        {175, 0xAF}, {176, 0xB0}, {177, 0xB1}, {178, 0xB2}, {179, 0xB3},
        {180, 0xB4}, {181, 0xB5}, {182, 0xB6}, {183, 0xB7}, {184, 0xB8},
        {185, 0xB9}, {186, 0xBA}, {187, 0xBB}, {188, 0xBC}, {189, 0xBD},
        {190, 0xBE}, {191, 0xBF}, {192, 0xC0}, {193, 0xC1}, {194, 0xC2},
        {195, 0xC3}, {196, 0xC4}, {197, 0xC5}, {198, 0xC6}, {199, 0xC7},
        {200, 0xC8}, {201, 0xC9}, {202, 0xCA}, {203, 0xCB}, {204, 0xCC},
        {205, 0xCD}, {206, 0xCE}, {207, 0xCF}, {208, 0xD0}, {209, 0xD1},
        {210, 0xD2}, {211, 0xD3}, {212, 0xD4}, {213, 0xD5}, {214, 0xD6},
        {215, 0xD7}, {216, 0xD8}, {217, 0xD9}, {218, 0xDA}, {219, 0xDB},
        {220, 0xDC}, {221, 0xDD}, {222, 0xDE}, {223, 0xDF}, {224, 0xE0},
        {225, 0xE1}, {226, 0xE2}, {227, 0xE3}, {228, 0xE4}, {229, 0xE5},
        {230, 0xE6}, {231, 0xE7}, {232, 0xE8},
    };
    animTypeNames =
    {
        {0,   "None"},                   {1,   "Anything"},              {2,   "Walk"},
        {3,   "Run"},                    {4,   "Slide"},                 {5,   "Jump"},
        {6,   "Stand"},                  {7,   "StandingTurnLeft"},      {8,   "StandingTurnRight"},
        {9,   "RunBackwards"},           {10,  "RunSidestepLeft"},       {11,  "RunSidestepRight"},
        {12,  "Kick"},                   {13,  "WalkSidestepLeft"},      {14,  "WalkSidestepRight"},
        {15,  "WalkBackwards"},          {16,  "Stance"},                {17,  "Crouch"},
        {18,  "JumpForward"},            {19,  "JumpBackward"},          {20,  "JumpLeft"},
        {21,  "JumpRight"},              {22,  "Punch"},                 {23,  "Block"},
        {24,  "Land"},                   {25,  "Fly"},                   {26,  "KickForward"},
        {27,  "KickLeft"},               {28,  "KickRight"},             {29,  "KickBack"},
        {30,  "KickLow"},                {31,  "PunchForward"},          {32,  "PunchLeft"},
        {33,  "PunchRight"},             {34,  "PunchBack"},             {35,  "PunchLow"},
        {36,  "Kick2"},                  {37,  "Kick3"},                 {38,  "Punch2"},
        {39,  "Punch3"},                 {40,  "LandForward"},           {41,  "LandRight"},
        {42,  "LandLeft"},               {43,  "LandBack"},              {44,  "PPK"},
        {45,  "PKK"},                    {46,  "PKP"},                   {47,  "KPK"},
        {48,  "KPP"},                    {49,  "KKP"},                   {50,  "PK"},
        {51,  "KP"},                     {52,  "PunchHeavy"},            {53,  "KickHeavy"},
        {54,  "PunchForwardHeavy"},      {55,  "KickForwardHeavy"},      {56,  "AimingOverlay"},
        {57,  "HitOverlay"},             {58,  "CrouchRun"},             {59,  "CrouchWalk"},
        {60,  "CrouchRunBackwards"},     {61,  "CrouchWalkBackwards"},   {62,  "CrouchRunSidestepLeft"},
        {63,  "CrouchRunSidestepRight"}, {64, "CrouchWalkSidestepLeft"}, {65, "CrouchWalkSidestepRight"},
        {66,  "RunKick"},                {67,  "RunPunch"},              {68,  "RunBackPunch"},
        {69,  "RunBackKick"},            {70,  "SidestepLeftKick"},      {71,  "SidestepLeftPunch"},
        {72,  "SidestepRightKick"},      {73,  "SidestepRightPunch"},    {74,  "Prone"},
        {75,  "Flip"},                   {76,  "HitHead"},               {77,  "HitBody"},
        {78,  "HitFoot"},                {79,  "KnockdownHead"},         {80,  "KnockdownBody"},
        {81,  "KnockdownFoot"},          {82,  "HitCrouch"},             {83,  "KnockdownCrouch"},
        {84,  "HitFallen"},              {85,  "HitHeadBehind"},         {86,  "HitBodyBehind"},
        {87,  "HitFootBehind"},          {88,  "KnockdownHeadBehind"},   {89,  "KnockdownBodyBehind"},
        {90,  "KnockdownFootBehind"},    {91,  "HitCrouchBehind"},       {92,  "KnockdownCrouchBehind"},
        {93,  "Idle"},                   {94,  "Taunt"},                 {95,  "Throw"},
        {96,  "Thrown1"},                {97,  "Thrown2"},               {98,  "Thrown3"},
        {99,  "Thrown4"},                {100, "Thrown5"},               {101, "Thrown6"},
        {102, "Special1"},               {103, "Special2"},              {104, "Special3"},
        {105, "Special4"},               {106, "ThrowForwardPunch"},     {107, "ThrowForwardKick"},
        {108, "ThrowBackwardPunch"},     {109, "ThrowBackwardKick"},     {110, "RunThrowForwardPunch"},
        {111, "RunThrowBackwardPunch"},  {112, "RunThrowForwardKick"},   {113, "RunThrowBackwardKick"},
        {114, "Thrown7"},                {115, "Thrown8"},               {116, "Thrown9"},
        {117, "Thrown10"},               {118, "Thrown11"},              {119, "Thrown12"},
        {120, "StartleLeft"},            {121, "StartleRight"},          {122, "Sit"},
        {123, "StandSpecial"},           {124, "Act"},                   {125, "Kick3Fw"},
        {126, "HitFootOuch"},            {127, "HitJewels"},             {128, "Thrown13"},
        {129, "Thrown14"},               {130, "Thrown15"},              {131, "Thrown16"},
        {132, "Thrown17"},               {133, "PPKK"},                  {134, "PPKKK"},
        {135, "PPKKKK"},                 {136, "LandHard"},              {137, "LandHardForward"},
        {138, "LandHardRight"},          {139, "LandHardLeft"},          {140, "LandHardBack"},
        {141, "LandDead"},               {142, "CrouchTurnLeft"},        {143, "CrouchTurnRight"},
        {144, "CrouchForward"},          {145, "CrouchBack"},            {146, "CrouchLeft"},
        {147, "CrouchRight"},            {148, "GetupKickBack"},         {149, "AutopistolRecoil"},
        {150, "PhaseRifleRecoil"},       {151, "PhaseStreamRecoil"},     {152, "SuperballRecoil"},
        {153, "VandegrafRecoil"},        {154, "ScramCannonRecoil"},     {155, "MercuryBowRecoil"},
        {156, "ScreamerRecoil"},         {157, "PickupObject"},          {158, "PickupPistol"},
        {159, "PickupRifle"},            {160, "Holster"},               {161, "DrawPistol"},
        {162, "DrawRifle"},              {163, "Punch4"},                {164, "ReloadPistol"},
        {165, "ReloadPhaseRifle"},       {166, "ReloadPhaseStream"},     {167, "ReloadSuperball"},
        {168, "ReloadVandegraf"},        {169, "ReloadScramCannon"},     {170, "ReloadMercuryBow"},
        {171, "ReloadScreamer"},         {172, "PfPf"},                  {173, "PfPfPf"},
        {174, "PlPl"},                   {175, "PlPlPl"},                {176, "PrPr"},
        {177, "PrPrPr"},                 {178, "PbPb"},                  {179, "PbPbPb"},
        {180, "PdPd"},                   {181, "PdPdPd"},                {182, "KfKf"},
        {183, "KfKfKf"},                 {184, "KlKl"},                  {185, "KlKlKl"},
        {186, "KrKr"},                   {187, "KrKrKr"},                {188, "KbKb"},
        {189, "KbKbKb"},                 {190, "KdKd"},                  {191, "KdKdKd"},
        {192, "StartleLt"},              {193, "StartleRt"},             {194, "StartleBk"},
        {195, "StartleFw"},              {196, "Console"},               {197, "ConsoleWalk"},
        {198, "Stagger"},                {199, "Watch"},                 {200, "ActNo"},
        {201, "ActYes"},                 {202, "ActTalk"},               {203, "ActShrug"},
        {204, "ActShout"},               {205, "ActGive"},               {206, "RunStop"},
        {207, "WalkStop"},               {208, "RunStart"},              {209, "WalkStart"},
        {210, "RunBackwardsStart"},      {211, "WalkBackwardsStart"},    {212, "Stun"},
        {213, "StaggerBehind"},          {214, "Blownup"},               {215, "BlownupBehind"},
        {216, "OneStepStop"},            {217, "RunSidestepLeftStart"},  {218, "RunSidestepRightStart"},
        {219, "Powerup"},                {220, "FallingFlail"},          {221, "ConsolePunch"},
        {222, "TeleportIn"},             {223, "TeleportOut"},           {224, "NinjaFireball"},
        {225, "NinjaInvisible"},         {226, "PunchRifle"},            {227, "PickupObjectMid"},
        {228, "PickupPistolMid"},        {229, "PickupRifleMid"},        {230, "Hail"},
        {231, "MuroThunderbolt"},        {232, "HitOverlayAI"},
    };
    animType.setTypeValueMap(&animTypeValues);
    animType.setTypeNameMap(&animTypeNames);
    aimingType.setTypeValueMap(&animTypeValues);
    aimingType.setTypeNameMap(&animTypeNames);

    animStateValues =
    {
        {0,  0x00}, {1,  0x01}, {2,  0x02}, {3,  0x03}, {4,  0x04},
        {5,  0x05}, {6,  0x06}, {7,  0x07}, {8,  0x08}, {9,  0x09},
        {10, 0x0A}, {11, 0x0B}, {12, 0x0C}, {13, 0x0D}, {14, 0x0E},
        {15, 0x0F}, {16, 0x10}, {17, 0x11}, {18, 0x12}, {19, 0x13},
        {20, 0x14}, {21, 0x15}, {22, 0x16}, {23, 0x17}, {24, 0x18},
        {25, 0x19}, {26, 0x1A}, {27, 0x1B}, {28, 0x1C}, {29, 0x1D},
        {30, 0x1E}, {31, 0x1F}, {32, 0x20}, {33, 0x21}, {34, 0x22},
        {35, 0x23}, {36, 0x24}, {37, 0x25}, {38, 0x26}, {39, 0x27},
        {40, 0x28}, {41, 0x29}, {42, 0x2A}, {43, 0x2B}, {44, 0x2C},
        {45, 0x2D}, {46, 0x2E}, {47, 0x2F}, {48, 0x30}, {49, 0x31},
        {50, 0x32}, {51, 0x33}, {52, 0x34}, {53, 0x35}, {54, 0x36},
        {55, 0x37}, {56, 0x38}, {57, 0x39}, {58, 0x3A}, {59, 0x3B},
        {60, 0x3C}, {61, 0x3D}, {62, 0x3E}, {63, 0x3F}, {64, 0x40},
        {65, 0x41}, {66, 0x42}, {67, 0x43}, {68, 0x44}, {69, 0x45},
    };
    animStateNames =
    {
        {0,  "None"},                    {1,  "Anything"},
        {2,  "RunningLeftDown"},         {3,  "RunningRightDown"},
        {4,  "Sliding"},                 {5,  "WalkingLeftDown"},
        {6,  "WalkingRightDown"},        {7,  "Standing"},
        {8,  "RunStart"},                {9,  "RunAccel"},
        {10, "RunSidestepLeft"},         {11, "RunSidestepRight"},
        {12, "RunSlide"},                {13, "RunJump"},
        {14, "RunJumpLand"},             {15, "RunBackStart"},
        {16, "RunningBackRightDown"},    {17, "RunningBackLeftDown"},
        {18, "FallenBack"},              {19, "Crouch"},
        {20, "RunningUpstairRightDown"}, {21, "RunningUpstairLeftDown"},
        {22, "SidestepLeftLeftDown"},    {23, "SidestepLeftRightDown"},
        {24, "SidestepRightLeftDown"},   {25, "SidestepRightRightDown"},
        {26, "SidestepRightJump"},       {27, "SidestepLeftJump"},
        {28, "JumpForward"},             {29, "JumpUp"},
        {30, "RunBackSlide"},            {31, "LieBack"},
        {32, "SsLtStart"},               {33, "SsRtStart"},
        {34, "WalkingSidestepLeft"},     {35, "CrouchWalk"},
        {36, "WalkingSidestepRight"},    {37, "Flying"},
        {38, "Falling"},                 {39, "FlyingForward"},
        {40, "FallingForward"},          {41, "FlyingBack"},
        {42, "FallingBack"},             {43, "FlyingLeft"},
        {44, "FallingLeft"},             {45, "FlyingRight"},
        {46, "FallingRight"},            {47, "CrouchStart"},
        {48, "WalkingBackLeftDown"},     {49, "WalkingBackRightDown"},
        {50, "FallenFront"},             {51, "SidestepLeftStart"},
        {52, "SidestepRightStart"},      {53, "Sit"},
        {54, "PunchLow"},                {55, "StandSpecial"},
        {56, "Acting"},                  {57, "CrouchRunLeft"},
        {58, "CrouchRunRight"},          {59, "CrouchRunBackLeft"},
        {60, "CrouchRunBackRight"},      {61, "Blocking1"},
        {62, "Blocking2"},               {63, "Blocking3"},
        {64, "CrouchBlocking1"},         {65, "Gliding"},
        {66, "WatchIdle"},               {67, "Stunned"},
        {68, "Powerup"},                 {69, "Thunderbolt"},
    };
    fromState.setTypeValueMap(&animStateValues);
    fromState.setTypeNameMap(&animStateNames);
    toState.setTypeValueMap(&animStateValues);
    toState.setTypeNameMap(&animStateNames);

    directionalExtents.reserve(36);
    for (int i = 0; i < 36; ++i)
        directionalExtents.emplace_back("extent at " + to_string(i * 10) + "\xC2\xB0", 26 + i);

    fields_.insert(fields_.end(),
    {
        &animNamePtr, &heightTrackOffset, &horizVelOffset, &attackPartOffset, &damagePartOffset, &motionBlurPartOffset, &shortcutDataOffset,
        &throwDataOffset, &footstepDataOffset, &particleDataOffset, &positionDataOffset, &rotationsOffset, &soundDataOffset, &animFlags,
        &directAnim0, &directAnim1, &usedBodyParts, &replacedParts, &finalRotation, &movingDir, &vocalizationType, &maxHorizAttackExtent,
        &minYOfAttack, &maxYOfAttack
    });
    for (FieldF32 & ext : directionalExtents)
        fields_.push_back(&ext);
    fields_.insert(fields_.end(),
    {
        &firstExtentFrame, &firstExtentAttackIdx, &firstExtentAttackFrameOffset, &firstExtentPelvisX, &firstExtentPelvisZ, &firstExtentPelvisY,
        &firstExtentLength, &firstExtentMinY, &firstExtentMaxY, &firstExtentAngle, &farthestExtentFrame, &farthestExtentAttackIdx,
        &farthestExtentAttackFrameOffset, &farthestExtentPelvisX, &farthestExtentPelvisZ, &farthestExtentPelvisY, &farthestExtentLength,
        &farthestExtentMinY, &farthestExtentMaxY, &farthestExtentAngle, &altMoveDir, &extentPartCount, &extentPartOffset, &impactParticleName,
        &hardPause, &softPause, &soundPartCount, &soundPtr, &soundStartFrame, &frameRate, &compressionSize, &animType, &aimingType, &fromState,
        &toState, &bodyPartCount, &frameCount, &duration, &variant, &variantEndMarker, &atomicStart, &atomicEnd, &endInterpolation,
        &maxInterpolation, &actionFrame, &firstLevelAvailable, &firstInvulnerableFrame, &lastInvulnerableFrame, &attackPartCount,
        &takeDamagePartCount, &motionBlurPartCount, &shortcutPartCount, &footstepPartCount, &particlePartCount
    });

    impactParticleName.setFullSize(16);
    variantEndMarker.setFixedSize(2);
}

void TemplateTRAM::createKnowledgeVarFields()
{
    // Fool processAuxData() into creating one element of every section by setting dummy field values and passing
    // a minimal zeroed fake buffer. This means the Knowledge display auto-syncs whenever processAuxData() changes.
    constexpr size_t kBoneCount    = 19;
    constexpr size_t kRotHdrSize   = kBoneCount * 2; // 38 B: 2-byte offset entry per bone
    constexpr size_t kRotTrackSize = 6; // 6 B per keyframe (compression=6), 1 frame/bone
    constexpr size_t kRotationSize = kRotHdrSize + (kBoneCount * kRotTrackSize); // 38 + 114 = 152 B

    frameCount.val()          = uint16_t(1);
    bodyPartCount.val()       = uint16_t(kBoneCount);
    compressionSize.val()     = uint16_t(6); // Euler-angle rotation
    attackPartCount.val()     = uint8_t(1);
    takeDamagePartCount.val() = uint8_t(1);
    animFlags.val()           = uint32_t(ThrowTarget); // enables the take-damage section
    motionBlurPartCount.val() = uint8_t(1);
    shortcutPartCount.val()   = uint8_t(1);
    footstepPartCount.val()   = uint8_t(1);
    particlePartCount.val()   = uint8_t(1);
    soundPartCount.val()      = uint32_t(1);
    extentPartCount.val()     = uint32_t(1);

    // Lay all sections out sequentially in the fake buffer; throw and position are conditional on a non-zero
    // offset field, so they must be placed somewhere even though their content is all zeros
    constexpr size_t kHeightOfs     = 0;                            // 1 frame × 4 B
    constexpr size_t kHorizVelOfs   = 4;                            // 1 frame × 8 B
    constexpr size_t kAttackOfs     = 12;                           // 1 attack × 0x20 B
    constexpr size_t kTakeDmgOfs    = 44;                           // 1 entry × 0x04 B
    constexpr size_t kMotionBlurOfs = 48;                           // 1 entry × 0x0C B
    constexpr size_t kShortcutOfs   = 60;                           // 1 entry × 0x08 B
    constexpr size_t kThrowOfs      = 68;                           // 1 × 0x16 B
    constexpr size_t kFootstepOfs   = 90;                           // 1 entry × 0x04 B
    constexpr size_t kParticleOfs   = 94;                           // 1 entry × 0x18 B
    constexpr size_t kPositionOfs   = 118;                          // 1 frame × 0x08 B
    constexpr size_t kRotationOfs   = 126;                          // 38 B header + 19 × 6 B tracks
    constexpr size_t kSoundOfs      = kRotationOfs + kRotationSize; // 278; 1 entry × 0x22 B
    constexpr size_t kExtentOfs     = kSoundOfs + 0x22;             // 312; 1 entry × 0x0C B
    constexpr size_t kBufSize       = kExtentOfs + 0x0C;            // 324

    vector<char> fakeData(kBufSize, 0);

    // Retail rotation header: each bone's track starts at (kRotHdrSize + b × kRotTrackSize) from the block start
    for (size_t b = 0; b < kBoneCount; b++)
    {
        auto offset = static_cast<uint16_t>(kRotHdrSize + (b * kRotTrackSize));
        fakeData[kRotationOfs + (b * 2)]     = static_cast<char>(offset & 0xFF);
        fakeData[kRotationOfs + (b * 2) + 1] = static_cast<char>(offset >> 8);
    }

    heightTrackOffset.val()    = uint32_t(kHeightOfs);
    horizVelOffset.val()       = uint32_t(kHorizVelOfs);
    attackPartOffset.val()     = uint32_t(kAttackOfs);
    damagePartOffset.val()     = uint32_t(kTakeDmgOfs);
    motionBlurPartOffset.val() = uint32_t(kMotionBlurOfs);
    shortcutDataOffset.val()   = uint32_t(kShortcutOfs);
    throwDataOffset.val()      = uint32_t(kThrowOfs);
    footstepDataOffset.val()   = uint32_t(kFootstepOfs);
    particleDataOffset.val()   = uint32_t(kParticleOfs);
    positionDataOffset.val()   = uint32_t(kPositionOfs);
    rotationsOffset.val()      = uint32_t(kRotationOfs);
    soundDataOffset.val()      = uint32_t(kSoundOfs);
    extentPartOffset.val()     = uint32_t(kExtentOfs);

    // Use retail format so the rotation block header is expected
    origFormat_ = Format::PC1_1;

    processAuxData(fakeData);
}

unique_ptr<Template> TemplateTRAM::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTRAM>(instName, dataFormat);
}

void TemplateTRAM::processAuxData(vector<char>& dataPacket)
{
    uint16_t numFrames = frameCount.val();
    if (numFrames == 0)
        return;
    
    // raw0x0C: height (y-position) track — one float per frame
    size_t rawFileOffset = heightTrackOffset.val();
    if (rawFileOffset + numFrames * sizeof(float) > dataPacket.size())
    {
        cerr << "Error: Height track data for instance " << quoted(name_) << " is out of bounds.\n";
        return;
    }

    heightTrack.reserve(numFrames);
    for (uint16_t i = 0; i < numFrames; i++)
    {
        heightTrack.emplace_back("height track [" + to_string(i) + "]", i + 1);
        fieldsAux_.push_back(&heightTrack.back());
    }
    auxSectionAnchors_.push_back({&heightTrackOffset, heightTrack.data()});
    sortFieldsAuxFor(origFormat_); // assigns offsets 0, 4, 8, … and sets "auxDataSize_"
    for (auto * field : fieldsAux_)
        DataIO::ReadData(field->var(), dataPacket, field->offset() + rawFileOffset, field->fixedSize());

    // raw0x10: horizontal velocities — (x, z) float pair per frame
    size_t hvBase = horizVelOffset.val();
    if (hvBase + static_cast<size_t>(numFrames) * 2 * sizeof(float) > dataPacket.size())
    {
        cerr << "Error: Horizontal velocity data for instance " << quoted(name_) << " is out of bounds.\n";
        return;
    }

    horizVelX.reserve(numFrames);
    horizVelZ.reserve(numFrames);
    for (uint16_t i = 0; i < numFrames; i++)
    {
        horizVelX.emplace_back("horiz vel X [" + to_string(i) + "]", numFrames + (2*i) + 1);
        horizVelZ.emplace_back("horiz vel Z [" + to_string(i) + "]", numFrames + (2*i) + 2);
        fieldsAux_.push_back(&horizVelX.back());
        fieldsAux_.push_back(&horizVelZ.back());
    }
    auxSectionAnchors_.push_back({&horizVelOffset, horizVelX.data()});
    sortFieldsAuxFor(origFormat_); // re-assigns offsets for all aux fields; updates auxDataSize_ to numFrames*12
    for (uint16_t i = 0; i < numFrames; i++)
    {
        DataIO::ReadData(horizVelX[i].var(), dataPacket, hvBase + (static_cast<size_t>(i) * 2 * sizeof(float)), horizVelX[i].fixedSize());
        DataIO::ReadData(horizVelZ[i].var(), dataPacket, hvBase + (static_cast<size_t>(i) * 2 * sizeof(float)) + sizeof(float),
                         horizVelZ[i].fixedSize());
    }

    // raw0x14: attack parts — 13-field struct (0x20 bytes) per entry
    size_t apBase = attackPartOffset.val();
    uint8_t apCount = attackPartCount.val();
    if (apCount > 0)
    {
        if (apBase + static_cast<size_t>(apCount) * 0x20 > dataPacket.size())
        {
            cerr << "Error: Attack part data for instance " << quoted(name_) << " is out of bounds.\n";
            return;
        }

        attackDamagingBones.reserve(apCount);
        attackKnockback.reserve(apCount);
        attackFlags.reserve(apCount);
        attackDamage.reserve(apCount);
        attackStartFrame.reserve(apCount);
        attackEndFrame.reserve(apCount);
        attackOpponentAnimType.reserve(apCount);
        attackHitStun.reserve(apCount);
        attackBlockStun.reserve(apCount);
        attackBlockStagger.reserve(apCount);
        attackPrecedence.reserve(apCount);
        attackExtentIdx.reserve(apCount);
        attackPad.reserve(apCount);

        for (uint8_t i = 0; i < apCount; i++)
        {
            int baseOrder = (3 * numFrames)
                            + (static_cast<int>(i) * 13);
            attackDamagingBones.emplace_back("attack damaging bones [" + to_string(i) + "]",        baseOrder + 1,  true, true,
                                             uint16_t{0}, uint16_t{0}, &bodyPartValues, &bodyPartNames);
            attackKnockback.emplace_back("attack knockback [" + to_string(i) + "]",                 baseOrder + 2);
            attackFlags.emplace_back("attack flags [" + to_string(i) + "]",                         baseOrder + 3,  true, true,
                                     uint16_t{0}, uint16_t{0}, &attackFlagValues, &attackFlagNames);
            attackDamage.emplace_back("attack damage [" + to_string(i) + "]",                       baseOrder + 4);
            attackStartFrame.emplace_back("attack start frame [" + to_string(i) + "]",              baseOrder + 5);
            attackEndFrame.emplace_back("attack end frame [" + to_string(i) + "]",                  baseOrder + 6);
            attackOpponentAnimType.emplace_back("attack opponent anim type [" + to_string(i) + "]", baseOrder + 7, true, true,
                                                uint16_t{0}, uint16_t{0}, &animTypeValues, &animTypeNames);
            attackHitStun.emplace_back("attack hit stun [" + to_string(i) + "]",                    baseOrder + 8);
            attackBlockStun.emplace_back("attack block stun [" + to_string(i) + "]",                baseOrder + 9);
            attackBlockStagger.emplace_back("attack block stagger [" + to_string(i) + "]",          baseOrder + 10);
            attackPrecedence.emplace_back("attack precedence [" + to_string(i) + "]",               baseOrder + 11, true, false);
            attackExtentIdx.emplace_back("attack extent idx [" + to_string(i) + "]",                baseOrder + 12, true, false);
            attackPad.emplace_back("attack pad [" + to_string(i) + "]",                             baseOrder + 13, true, false);
            attackPad.back().setFixedSize(2);
            fieldsAux_.push_back(&attackDamagingBones.back());
            fieldsAux_.push_back(&attackKnockback.back());
            fieldsAux_.push_back(&attackFlags.back());
            fieldsAux_.push_back(&attackDamage.back());
            fieldsAux_.push_back(&attackStartFrame.back());
            fieldsAux_.push_back(&attackEndFrame.back());
            fieldsAux_.push_back(&attackOpponentAnimType.back());
            fieldsAux_.push_back(&attackHitStun.back());
            fieldsAux_.push_back(&attackBlockStun.back());
            fieldsAux_.push_back(&attackBlockStagger.back());
            fieldsAux_.push_back(&attackPrecedence.back());
            fieldsAux_.push_back(&attackExtentIdx.back());
            fieldsAux_.push_back(&attackPad.back());
        }
        auxSectionAnchors_.push_back({&attackPartOffset, attackDamagingBones.data()});
        sortFieldsAuxFor(origFormat_);
        for (uint8_t i = 0; i < apCount; i++)
        {
            size_t entBase = apBase + (static_cast<size_t>(i) * 0x20);
            DataIO::ReadData(attackDamagingBones[i].var(),    dataPacket, entBase + 0x00, attackDamagingBones[i].fixedSize());
            DataIO::ReadData(attackKnockback[i].var(),        dataPacket, entBase + 0x04, attackKnockback[i].fixedSize());
            DataIO::ReadData(attackFlags[i].var(),            dataPacket, entBase + 0x08, attackFlags[i].fixedSize());
            DataIO::ReadData(attackDamage[i].var(),           dataPacket, entBase + 0x0C, attackDamage[i].fixedSize());
            DataIO::ReadData(attackStartFrame[i].var(),       dataPacket, entBase + 0x0E, attackStartFrame[i].fixedSize());
            DataIO::ReadData(attackEndFrame[i].var(),         dataPacket, entBase + 0x10, attackEndFrame[i].fixedSize());
            DataIO::ReadData(attackOpponentAnimType[i].var(), dataPacket, entBase + 0x12, attackOpponentAnimType[i].fixedSize());
            DataIO::ReadData(attackHitStun[i].var(),          dataPacket, entBase + 0x14, attackHitStun[i].fixedSize());
            DataIO::ReadData(attackBlockStun[i].var(),        dataPacket, entBase + 0x16, attackBlockStun[i].fixedSize());
            DataIO::ReadData(attackBlockStagger[i].var(),     dataPacket, entBase + 0x18, attackBlockStagger[i].fixedSize());
            DataIO::ReadData(attackPrecedence[i].var(),       dataPacket, entBase + 0x1A, attackPrecedence[i].fixedSize());
            DataIO::ReadData(attackExtentIdx[i].var(),        dataPacket, entBase + 0x1C, attackExtentIdx[i].fixedSize());
            DataIO::ReadData(attackPad[i].var(),              dataPacket, entBase + 0x1E, attackPad[i].fixedSize());
        }
    }

    // raw0x18: take-damage parts — 2-field struct (0x04 bytes) per entry
    // Only present for throw-target animations
    uint8_t dpCount = 0;
    if (animFlags.has(ThrowTarget))
    {
        size_t dpBase = damagePartOffset.val();
        dpCount = takeDamagePartCount.val();
        if (dpCount > 0)
        {
            if (dpBase + static_cast<size_t>(dpCount) * 0x04 > dataPacket.size())
            {
                cerr << "Error: Take-damage part data for instance " << quoted(name_) << " is out of bounds.\n";
                return;
            }

            takeDamageDamage.reserve(dpCount);
            takeDamageFrame.reserve(dpCount);
            for (uint8_t j = 0; j < dpCount; j++)
            {
                int baseOrder = (3 * numFrames)
                                + (static_cast<int>(apCount) * 13)
                                + (static_cast<int>(j) * 2);
                takeDamageDamage.emplace_back("take damage amount [" + to_string(j) + "]", baseOrder + 1);
                takeDamageFrame.emplace_back("take damage frame [" + to_string(j) + "]", baseOrder + 2);
                fieldsAux_.push_back(&takeDamageDamage.back());
                fieldsAux_.push_back(&takeDamageFrame.back());
            }
            auxSectionAnchors_.push_back({&damagePartOffset, takeDamageDamage.data()});
            sortFieldsAuxFor(origFormat_);
            for (uint8_t j = 0; j < dpCount; j++)
            {
                size_t entBase = dpBase + (static_cast<size_t>(j) * 0x04);
                DataIO::ReadData(takeDamageDamage[j].var(), dataPacket, entBase + 0x00, takeDamageDamage[j].fixedSize());
                DataIO::ReadData(takeDamageFrame[j].var(), dataPacket, entBase + 0x02, takeDamageFrame[j].fixedSize());
            }
        }
    }

    // raw0x1C: motion blur parts — 7-field struct (0x0C bytes) per entry
    size_t mbBase = motionBlurPartOffset.val();
    uint8_t mbCount = motionBlurPartCount.val();
    if (mbCount > 0)
    {
        if (mbBase + static_cast<size_t>(mbCount) * 0x0C > dataPacket.size())
        {
            cerr << "Error: Motion blur part data for instance " << quoted(name_) << " is out of bounds.\n";
            return;
        }

        motionBlurBones.reserve(mbCount);
        motionBlurStartFrame.reserve(mbCount);
        motionBlurStopFrame.reserve(mbCount);
        motionBlurQuantity.reserve(mbCount);
        motionBlurTransparency.reserve(mbCount);
        motionBlurFrameInterval.reserve(mbCount);
        motionBlurPad.reserve(mbCount);
        for (uint8_t k = 0; k < mbCount; k++)
        {
            int baseOrder = (3 * numFrames)
                            + (static_cast<int>(apCount) * 13)
                            + (static_cast<int>(dpCount) * 2)
                            + (static_cast<int>(k) * 7);
            motionBlurBones.emplace_back("motion blur bones [" + to_string(k) + "]",                  baseOrder + 1, true, true, 0, 0,
                                         &bodyPartValues, &bodyPartNames);
            motionBlurStartFrame.emplace_back("motion blur start frame [" + to_string(k) + "]",       baseOrder + 2);
            motionBlurStopFrame.emplace_back("motion blur stop frame [" + to_string(k) + "]",         baseOrder + 3);
            motionBlurQuantity.emplace_back("motion blur quantity [" + to_string(k) + "]",            baseOrder + 4);
            motionBlurTransparency.emplace_back("motion blur transparency [" + to_string(k) + "]",    baseOrder + 5);
            motionBlurFrameInterval.emplace_back("motion blur frame interval [" + to_string(k) + "]", baseOrder + 6);
            motionBlurPad.emplace_back("motion blur pad [" + to_string(k) + "]",                      baseOrder + 7, true, false);
            motionBlurPad.back().setFixedSize(1);
            fieldsAux_.push_back(&motionBlurBones.back());
            fieldsAux_.push_back(&motionBlurStartFrame.back());
            fieldsAux_.push_back(&motionBlurStopFrame.back());
            fieldsAux_.push_back(&motionBlurQuantity.back());
            fieldsAux_.push_back(&motionBlurTransparency.back());
            fieldsAux_.push_back(&motionBlurFrameInterval.back());
            fieldsAux_.push_back(&motionBlurPad.back());
        }
        auxSectionAnchors_.push_back({&motionBlurPartOffset, motionBlurBones.data()});
        sortFieldsAuxFor(origFormat_);
        for (uint8_t k = 0; k < mbCount; k++)
        {
            size_t entBase = mbBase + (static_cast<size_t>(k) * 0x0C);
            DataIO::ReadData(motionBlurBones[k].var(),         dataPacket, entBase + 0x00, motionBlurBones[k].fixedSize());
            DataIO::ReadData(motionBlurStartFrame[k].var(),    dataPacket, entBase + 0x04, motionBlurStartFrame[k].fixedSize());
            DataIO::ReadData(motionBlurStopFrame[k].var(),     dataPacket, entBase + 0x06, motionBlurStopFrame[k].fixedSize());
            DataIO::ReadData(motionBlurQuantity[k].var(),      dataPacket, entBase + 0x08, motionBlurQuantity[k].fixedSize());
            DataIO::ReadData(motionBlurTransparency[k].var(),  dataPacket, entBase + 0x09, motionBlurTransparency[k].fixedSize());
            DataIO::ReadData(motionBlurFrameInterval[k].var(), dataPacket, entBase + 0x0A, motionBlurFrameInterval[k].fixedSize());
            DataIO::ReadData(motionBlurPad[k].var(),           dataPacket, entBase + 0x0B, motionBlurPad[k].fixedSize());
        }
    }

    // raw0x20: shortcut data — 3-field struct (0x08 bytes) per entry
    size_t scBase = shortcutDataOffset.val();
    uint8_t scCount = shortcutPartCount.val();
    if (scCount > 0)
    {
        if (scBase + static_cast<size_t>(scCount) * 0x08 > dataPacket.size())
        {
            cerr << "Error: Shortcut data for instance " << quoted(name_) << " is out of bounds.\n";
            return;
        }

        shortcutState.reserve(scCount);
        shortcutLength.reserve(scCount);
        shortcutAtomic.reserve(scCount);
        for (uint8_t i = 0; i < scCount; i++)
        {
            int baseOrder = (3 * numFrames)
                            + (static_cast<int>(apCount) * 13)
                            + (static_cast<int>(dpCount) * 2)
                            + (static_cast<int>(mbCount) * 7)
                            + (static_cast<int>(i) * 3);
            shortcutState.emplace_back("shortcut state [" + to_string(i) + "]",  baseOrder + 1, true, true, uint16_t{0}, uint16_t{0},
                                       &animTypeValues, &animTypeNames);
            shortcutLength.emplace_back("shortcut length [" + to_string(i) + "]", baseOrder + 2);
            shortcutAtomic.emplace_back("shortcut overrides atomic [" + to_string(i) + "]", baseOrder + 3);
            fieldsAux_.push_back(&shortcutState.back());
            fieldsAux_.push_back(&shortcutLength.back());
            fieldsAux_.push_back(&shortcutAtomic.back());
        }
        auxSectionAnchors_.push_back({&shortcutDataOffset, shortcutState.data()});
        sortFieldsAuxFor(origFormat_);
        for (uint8_t i = 0; i < scCount; i++)
        {
            size_t entBase = scBase + (static_cast<size_t>(i) * 0x08);
            DataIO::ReadData(shortcutState[i].var(), dataPacket, entBase + 0x00, shortcutState[i].fixedSize());
            DataIO::ReadData(shortcutLength[i].var(), dataPacket, entBase + 0x02, shortcutLength[i].fixedSize());
            DataIO::ReadData(shortcutAtomic[i].var(), dataPacket, entBase + 0x04, shortcutAtomic[i].fixedSize());
        }
    }

    // raw0x24: throw data — singular 6-field struct (0x16 bytes); only present for throw-source animations
    size_t tdBase = throwDataOffset.val();
    if (tdBase != 0)
    {
        if (tdBase + 0x16 > dataPacket.size())
        {
            cerr << "Error: Throw data for instance " << quoted(name_) << " is out of bounds.\n";
            return;
        }

        int baseOrder = (3 * numFrames)
                        + (static_cast<int>(apCount) * 13)
                        + (static_cast<int>(dpCount) * 2)
                        + (static_cast<int>(mbCount) * 7)
                        + (static_cast<int>(scCount) * 3);
        throwTargetX.reserve(1);
        throwTargetY.reserve(1);
        throwTargetZ.reserve(1);
        throwAngle.reserve(1);
        throwDistance.reserve(1);
        throwAnimType.reserve(1);
        throwTargetX.emplace_back("throw target X [0]",          baseOrder + 1);
        throwTargetY.emplace_back("throw target Y [0]",          baseOrder + 2);
        throwTargetZ.emplace_back("throw target Z [0]",          baseOrder + 3);
        throwAngle.emplace_back("throw angle [0]",               baseOrder + 4);
        throwDistance.emplace_back("throw distance [0]",         baseOrder + 5);
        throwAnimType.emplace_back("throw target anim type [0]", baseOrder + 6, true, true, uint16_t{0}, uint16_t{0}, &animTypeValues,
                                   &animTypeNames);
        fieldsAux_.push_back(&throwTargetX.back());
        fieldsAux_.push_back(&throwTargetY.back());
        fieldsAux_.push_back(&throwTargetZ.back());
        fieldsAux_.push_back(&throwAngle.back());
        fieldsAux_.push_back(&throwDistance.back());
        fieldsAux_.push_back(&throwAnimType.back());
        auxSectionAnchors_.push_back({&throwDataOffset, throwTargetX.data()});
        sortFieldsAuxFor(origFormat_);
        DataIO::ReadData(throwTargetX[0].var(),  dataPacket, tdBase + 0x00, throwTargetX[0].fixedSize());
        DataIO::ReadData(throwTargetY[0].var(),  dataPacket, tdBase + 0x04, throwTargetY[0].fixedSize());
        DataIO::ReadData(throwTargetZ[0].var(),  dataPacket, tdBase + 0x08, throwTargetZ[0].fixedSize());
        DataIO::ReadData(throwAngle[0].var(),    dataPacket, tdBase + 0x0C, throwAngle[0].fixedSize());
        DataIO::ReadData(throwDistance[0].var(), dataPacket, tdBase + 0x10, throwDistance[0].fixedSize());
        DataIO::ReadData(throwAnimType[0].var(), dataPacket, tdBase + 0x14, throwAnimType[0].fixedSize());
    }

    // raw0x28: footstep data — 2-field struct (0x04 bytes) per entry
    size_t fsBase = footstepDataOffset.val();
    uint8_t fsCount = footstepPartCount.val();
    if (fsCount > 0)
    {
        if (fsBase + static_cast<size_t>(fsCount) * 0x04 > dataPacket.size())
        {
            cerr << "Error: Footstep data for instance " << quoted(name_) << " is out of bounds.\n";
            return;
        }

        footstepFrame.reserve(fsCount);
        footstepType.reserve(fsCount);
        for (uint8_t i = 0; i < fsCount; i++)
        {
            int baseOrder = (3 * numFrames)
                            + (static_cast<int>(apCount) * 13)
                            + (static_cast<int>(dpCount) * 2)
                            + (static_cast<int>(mbCount) * 7)
                            + (static_cast<int>(scCount) * 3)
                            + (tdBase != 0 ? 6 : 0)
                            + (static_cast<int>(i) * 2);
            footstepFrame.emplace_back("footstep frame [" + to_string(i) + "]", baseOrder + 1);
            footstepType.emplace_back("footstep type [" + to_string(i) + "]", baseOrder + 2, true, true, uint16_t{0}, uint16_t{0},
                                      &footstepTypeValues, &footstepTypeNames);
            fieldsAux_.push_back(&footstepFrame.back());
            fieldsAux_.push_back(&footstepType.back());
        }
        auxSectionAnchors_.push_back({&footstepDataOffset, footstepFrame.data()});
        sortFieldsAuxFor(origFormat_);
        for (uint8_t i = 0; i < fsCount; i++)
        {
            size_t entBase = fsBase + (static_cast<size_t>(i) * 0x04);
            DataIO::ReadData(footstepFrame[i].var(), dataPacket, entBase + 0x00, footstepFrame[i].fixedSize());
            DataIO::ReadData(footstepType[i].var(), dataPacket, entBase + 0x02, footstepType[i].fixedSize());
        }
    }

    // raw0x2C: particle data — 5-field struct (0x18 bytes) per entry
    size_t ppBase = particleDataOffset.val();
    uint8_t ppCount = particlePartCount.val();
    if (ppCount > 0)
    {
        if (ppBase + static_cast<size_t>(ppCount) * 0x18 > dataPacket.size())
        {
            cerr << "Error: Particle data for instance " << quoted(name_) << " is out of bounds.\n";
            return;
        }

        particleStartFrame.reserve(ppCount);
        particleEndFrame.reserve(ppCount);
        particleBodyPart.reserve(ppCount);
        particlePad.reserve(ppCount);
        particleName.reserve(ppCount);
        for (uint8_t i = 0; i < ppCount; i++)
        {
            int baseOrder = (3 * numFrames)
                            + (static_cast<int>(apCount) * 13)
                            + (static_cast<int>(dpCount) * 2)
                            + (static_cast<int>(mbCount) * 7)
                            + (static_cast<int>(scCount) * 3)
                            + (tdBase != 0 ? 6 : 0)
                            + (static_cast<int>(fsCount) * 2)
                            + (static_cast<int>(i) * 5);
            particleStartFrame.emplace_back("particle start frame [" + to_string(i) + "]", baseOrder + 1);
            particleEndFrame.emplace_back("particle end frame [" + to_string(i) + "]",     baseOrder + 2);
            particleBodyPart.emplace_back("particle body part [" + to_string(i) + "]",     baseOrder + 3, true, true, uint16_t{0}, uint16_t{0},
                                          &bodyPartIdxValues, &bodyPartIdxNames);
            particlePad.emplace_back("particle pad [" + to_string(i) + "]",                baseOrder + 4, true, false);
            particlePad.back().setFixedSize(2);
            particleName.emplace_back("particle class name [" + to_string(i) + "]",        baseOrder + 5);
            particleName.back().setFullSize(16);
            fieldsAux_.push_back(&particleStartFrame.back());
            fieldsAux_.push_back(&particleEndFrame.back());
            fieldsAux_.push_back(&particleBodyPart.back());
            fieldsAux_.push_back(&particlePad.back());
            fieldsAux_.push_back(&particleName.back());
        }
        auxSectionAnchors_.push_back({&particleDataOffset, particleStartFrame.data()});
        sortFieldsAuxFor(origFormat_);
        for (uint8_t i = 0; i < ppCount; i++)
        {
            size_t entBase = ppBase + (static_cast<size_t>(i) * 0x18);
            DataIO::ReadData(particleStartFrame[i].var(), dataPacket, entBase + 0x00, particleStartFrame[i].fixedSize());
            DataIO::ReadData(particleEndFrame[i].var(),   dataPacket, entBase + 0x02, particleEndFrame[i].fixedSize());
            DataIO::ReadData(particleBodyPart[i].var(),   dataPacket, entBase + 0x04, particleBodyPart[i].fixedSize());
            DataIO::ReadData(particlePad[i].var(),        dataPacket, entBase + 0x06, particlePad[i].fixedSize());
            DataIO::ReadData(particleName[i].var(),       dataPacket, entBase + 0x08, particleName[i].fixedSize());
        }
    }

    // raw0x30: position data — 4-field struct (0x08 bytes) per frame
    size_t pdBase = positionDataOffset.val();
    if (pdBase != 0)
    {
        if (pdBase + static_cast<size_t>(numFrames) * 0x08 > dataPacket.size())
        {
            cerr << "Error: Position data for instance " << quoted(name_) << " is out of bounds.\n";
            return;
        }

        positionX.reserve(numFrames);
        positionZ.reserve(numFrames);
        positionHeightSpan.reserve(numFrames);
        positionGroundOffset.reserve(numFrames);
        for (uint16_t i = 0; i < numFrames; i++)
        {
            int baseOrder = (3 * numFrames)
                          + (static_cast<int>(apCount) * 13)
                          + (static_cast<int>(dpCount) * 2)
                          + (static_cast<int>(mbCount) * 7)
                          + (static_cast<int>(scCount) * 3)
                          + (tdBase != 0 ? 6 : 0)
                          + (static_cast<int>(fsCount) * 2)
                          + (static_cast<int>(ppCount) * 5)
                          + (static_cast<int>(i) * 4);
            positionX.emplace_back("position X [" + to_string(i) + "]",                        baseOrder + 1);
            positionZ.emplace_back("position Z [" + to_string(i) + "]",                        baseOrder + 2);
            positionHeightSpan.emplace_back("position height span [" + to_string(i) + "]",     baseOrder + 3);
            positionGroundOffset.emplace_back("position ground offset [" + to_string(i) + "]", baseOrder + 4);
            fieldsAux_.push_back(&positionX.back());
            fieldsAux_.push_back(&positionZ.back());
            fieldsAux_.push_back(&positionHeightSpan.back());
            fieldsAux_.push_back(&positionGroundOffset.back());
        }
        auxSectionAnchors_.push_back({&positionDataOffset, positionX.data()});
        sortFieldsAuxFor(origFormat_);
        for (uint16_t i = 0; i < numFrames; i++)
        {
            size_t entBase = pdBase + (static_cast<size_t>(i) * 0x08);
            DataIO::ReadData(positionX[i].var(),            dataPacket, entBase + 0x00, positionX[i].fixedSize());
            DataIO::ReadData(positionZ[i].var(),            dataPacket, entBase + 0x02, positionZ[i].fixedSize());
            DataIO::ReadData(positionHeightSpan[i].var(),   dataPacket, entBase + 0x04, positionHeightSpan[i].fixedSize());
            DataIO::ReadData(positionGroundOffset[i].var(), dataPacket, entBase + 0x06, positionGroundOffset[i].fixedSize());
        }
    }

    // raw0x34: rotation data
    // Retail: the block starts with one uint16 offset per bone (relative to the block base), each pointing to that bone's track. A
    // track is keyframe 0 followed by repeating [interval byte] + [keyframe]. Each keyframe is either three quantized int16 Euler angles
    // (compression size 6) or a four-float quaternion (compression size 16). A track's length is self-describing: accumulate the intervals
    // until the running frame position reaches frameCount - 1.
    // WinAlpha6: no header and no keyframe system; every frame is present, laid out frame-major (all bones for frame 0, then frame 1, etc.).
    size_t rotDataStart = rotationsOffset.val();
    if (rotDataStart != 0)
    {
        uint16_t boneCount = bodyPartCount.val();
        uint16_t compressSize = compressionSize.val();
        if (compressSize != 6 && compressSize != 16)
        {
            cerr << "Error: Rotation data for instance " << quoted(name_) << " has an unsupported compression size.\n";
            return;
        }

        // Reverse-map each 0-based bone index to its name using the existing body-part maps
        vector<string> boneNames(boneCount);
        for (uint16_t b = 0; b < boneCount; b++)
            boneNames[b] = to_string(b);
        for (const auto & kv : bodyPartIdxValues)
            if (kv.second >= 0 && kv.second < boneCount)
            {
                auto it = bodyPartIdxNames.find(kv.first);
                if (it != bodyPartIdxNames.end())
                    boneNames[kv.second] = it->second;
            }

        // Starting order: strictly above every order any earlier section could have used
        int order = (3 * numFrames)
                    + (static_cast<int>(apCount) * 13) + (static_cast<int>(dpCount) * 2)
                    + (static_cast<int>(mbCount) * 7) + (static_cast<int>(scCount) * 3)
                    + (tdBase != 0 ? 6 : 0) + (static_cast<int>(fsCount) * 2)
                    + (static_cast<int>(ppCount) * 5)
                    + (static_cast<int>(numFrames) * 4)
                    + 1;

        if (origFormat_ == Format::WinAlpha6)
        {
            // WinAlpha6: no header, no sparse keyframes — all numFrames × boneCount rotations stored
            // contiguously, frame-major (all bones for frame 0, then all bones for frame 1, etc.)
            size_t totalKeyframes = static_cast<size_t>(numFrames) * boneCount;
            if (totalKeyframes > 0 && rotDataStart + totalKeyframes * compressSize > dataPacket.size())
            {
                cerr << "Error: Rotation data for instance " << quoted(name_) << " is out of bounds.\n";
                return;
            }
            if (compressSize == 6)
            {
                rotAngleX.reserve(totalKeyframes);
                rotAngleY.reserve(totalKeyframes);
                rotAngleZ.reserve(totalKeyframes);
            }
            else
            {
                rotQuatX.reserve(totalKeyframes);
                rotQuatY.reserve(totalKeyframes);
                rotQuatZ.reserve(totalKeyframes);
                rotQuatW.reserve(totalKeyframes);
            }

            // Pass B: emplace fields in on-disk order (frame-major, bone-minor)
            for (uint16_t f = 0; f < numFrames; f++)
            {
                for (uint16_t b = 0; b < boneCount; b++)
                {
                    string tag = " [" + to_string(f) + "] " + boneNames[b];
                    if (compressSize == 6)
                    {
                        rotAngleX.emplace_back("rotation" + tag + " x", order++);
                        rotAngleY.emplace_back("rotation" + tag + " y", order++);
                        rotAngleZ.emplace_back("rotation" + tag + " z", order++);
                        fieldsAux_.push_back(&rotAngleX.back());
                        fieldsAux_.push_back(&rotAngleY.back());
                        fieldsAux_.push_back(&rotAngleZ.back());
                    }
                    else
                    {
                        rotQuatX.emplace_back("rotation" + tag + " quat x", order++);
                        rotQuatY.emplace_back("rotation" + tag + " quat y", order++);
                        rotQuatZ.emplace_back("rotation" + tag + " quat z", order++);
                        rotQuatW.emplace_back("rotation" + tag + " quat w", order++);
                        fieldsAux_.push_back(&rotQuatX.back());
                        fieldsAux_.push_back(&rotQuatY.back());
                        fieldsAux_.push_back(&rotQuatZ.back());
                        fieldsAux_.push_back(&rotQuatW.back());
                    }
                }
            }
            sortFieldsAuxFor(origFormat_);

            // Pass C: read data in frame-major, bone-minor order
            size_t kfIdx = 0;
            for (uint16_t f = 0; f < numFrames; f++)
            {
                for (uint16_t b = 0; b < boneCount; b++)
                {
                    size_t kfBase = rotDataStart + (kfIdx * compressSize);
                    if (compressSize == 6)
                    {
                        DataIO::ReadData(rotAngleX[kfIdx].var(), dataPacket, kfBase + 0, rotAngleX[kfIdx].fixedSize());
                        DataIO::ReadData(rotAngleY[kfIdx].var(), dataPacket, kfBase + 2, rotAngleY[kfIdx].fixedSize());
                        DataIO::ReadData(rotAngleZ[kfIdx].var(), dataPacket, kfBase + 4, rotAngleZ[kfIdx].fixedSize());
                    }
                    else // disk order is x, y, z, w
                    {
                        DataIO::ReadData(rotQuatX[kfIdx].var(), dataPacket, kfBase + 0,  rotQuatX[kfIdx].fixedSize());
                        DataIO::ReadData(rotQuatY[kfIdx].var(), dataPacket, kfBase + 4,  rotQuatY[kfIdx].fixedSize());
                        DataIO::ReadData(rotQuatZ[kfIdx].var(), dataPacket, kfBase + 8,  rotQuatZ[kfIdx].fixedSize());
                        DataIO::ReadData(rotQuatW[kfIdx].var(), dataPacket, kfBase + 12, rotQuatW[kfIdx].fixedSize());
                    }
                    kfIdx++;
                }
            }
            if (totalKeyframes > 0)
                auxSectionAnchors_.push_back({&rotationsOffset, compressSize == 6 ? static_cast<Field *>(&rotAngleX.front())
                                                                                   : static_cast<Field *>(&rotQuatX.front())});
        }
        else
        {
            size_t keyframeStride = compressSize + 1; // a keyframe plus its trailing interval byte
            if (rotDataStart + static_cast<size_t>(boneCount) * 2 > dataPacket.size())
            {
                cerr << "Error: Rotation header for instance " << quoted(name_) << " is out of bounds.\n";
                return;
            }

            // Pass A: walk each bone's track to learn its keyframe count
            struct RotTrack
            {
                size_t rawFileOffset;
                uint16_t numKeyframes;
            };
            vector<RotTrack> tracks;
            tracks.reserve(boneCount);
            size_t totalKeyframes = 0, totalIntervals = 0;
            for (uint16_t b = 0; b < boneCount; b++)
            {
                size_t boneTrackOffsetAddress = rotDataStart + (static_cast<size_t>(b) * 2);
                size_t trackRelStart = static_cast<size_t>(static_cast<uint8_t>(dataPacket[boneTrackOffsetAddress])
                                       | (static_cast<uint8_t>(dataPacket[boneTrackOffsetAddress + 1]) << 8));
                size_t trackBase = rotDataStart + trackRelStart;
                uint16_t keyframes = 0;
                uint32_t curFrame = 0;
                size_t curOffset = trackBase;
                while (true)
                {
                    if (curOffset + compressSize > dataPacket.size())
                    {
                        cerr << "Error: Rotation track for instance " << quoted(name_) << " is out of bounds.\n";
                        return;
                    }
                    keyframes++;
                    if (curFrame >= static_cast<uint32_t>(numFrames) - 1) // then we're done reading the keyframes
                        break;
                    if (keyframes > numFrames) // safety: every interval advances the frame position by at least one
                    {
                        cerr << "Error: Rotation track for instance " << quoted(name_) << " is malformed: keyframes outnumber anim frames.\n";
                        return;
                    }
                    uint8_t interval = static_cast<uint8_t>(dataPacket[curOffset + compressSize]);
                    if (interval == 0)
                    {
                        cerr << "Error: Rotation track for instance " << quoted(name_) << " is malformed: interval of zero.\n";
                        return;
                    }
                    curFrame += interval;
                    curOffset += keyframeStride;
                }
                tracks.push_back({trackBase, keyframes});
                totalKeyframes += keyframes;
                totalIntervals += (keyframes - 1);
            }

            // reserve() every vector before any push so the pointers stored in "fieldsAux_" stay valid
            if (compressSize == 6)
            {
                rotAngleX.reserve(totalKeyframes);
                rotAngleY.reserve(totalKeyframes);
                rotAngleZ.reserve(totalKeyframes);
            }
            else
            {
                rotQuatX.reserve(totalKeyframes);
                rotQuatY.reserve(totalKeyframes);
                rotQuatZ.reserve(totalKeyframes);
                rotQuatW.reserve(totalKeyframes);
            }
            rotInterval.reserve(totalIntervals);

            // Store the per-bone offset table verbatim as the rotation section's first field. It is not otherwise captured as fields, so this
            // is what lets the block be exported with byte parity to the data files; "rotationsOffset" anchors to it so it points at the start
            // of the block on export.
            if (boneCount > 0)
            {
                size_t headerSize = static_cast<size_t>(boneCount) * 2;
                rotHeader.reserve(1);
                rotHeader.emplace_back("rotation track header", order++, false, true);
                rotHeader.back().setReservedSize(static_cast<uint32_t>(headerSize));
                copy(dataPacket.begin() + static_cast<ptrdiff_t>(rotDataStart),
                     dataPacket.begin() + static_cast<ptrdiff_t>(rotDataStart + headerSize), rotHeader.back().val().begin());
                fieldsAux_.push_back(&rotHeader.back());
                auxSectionAnchors_.push_back({&rotationsOffset, &rotHeader.back()});
            }

            // Pass B: emplace fields in on-disk order (keyframe, then trailing interval)
            for (uint16_t b = 0; b < boneCount; b++)
            {
                for (uint16_t k = 0; k < tracks[b].numKeyframes; k++)
                {
                    string tag = " " + boneNames[b] + " [" + to_string(k) + "]";
                    if (compressSize == 6)
                    {
                        rotAngleX.emplace_back("rotation" + tag + " x", order++);
                        rotAngleY.emplace_back("rotation" + tag + " y", order++);
                        rotAngleZ.emplace_back("rotation" + tag + " z", order++);
                        fieldsAux_.push_back(&rotAngleX.back());
                        fieldsAux_.push_back(&rotAngleY.back());
                        fieldsAux_.push_back(&rotAngleZ.back());
                    }
                    else
                    {
                        rotQuatX.emplace_back("rotation" + tag + " quat x", order++);
                        rotQuatY.emplace_back("rotation" + tag + " quat y", order++);
                        rotQuatZ.emplace_back("rotation" + tag + " quat z", order++);
                        rotQuatW.emplace_back("rotation" + tag + " quat w", order++);
                        fieldsAux_.push_back(&rotQuatX.back());
                        fieldsAux_.push_back(&rotQuatY.back());
                        fieldsAux_.push_back(&rotQuatZ.back());
                        fieldsAux_.push_back(&rotQuatW.back());
                    }
                    if (k + 1 < tracks[b].numKeyframes) // every keyframe but the last is followed by an interval
                    {
                        rotInterval.emplace_back("rotation" + tag + " interval", order++);
                        fieldsAux_.push_back(&rotInterval.back());
                    }
                }
            }
            sortFieldsAuxFor(origFormat_);

            // Pass C: read each field at its exact byte offset (field->offset() now reflects a
            // combined offset across all aux sections, so it cannot be used here)
            size_t kfIdx = 0, intIdx = 0;
            for (uint16_t b = 0; b < boneCount; b++)
            {
                for (uint16_t k = 0; k < tracks[b].numKeyframes; k++)
                {
                    size_t kfBase = tracks[b].rawFileOffset + (static_cast<size_t>(k) * keyframeStride);
                    if (compressSize == 6)
                    {
                        DataIO::ReadData(rotAngleX[kfIdx].var(), dataPacket, kfBase + 0, rotAngleX[kfIdx].fixedSize());
                        DataIO::ReadData(rotAngleY[kfIdx].var(), dataPacket, kfBase + 2, rotAngleY[kfIdx].fixedSize());
                        DataIO::ReadData(rotAngleZ[kfIdx].var(), dataPacket, kfBase + 4, rotAngleZ[kfIdx].fixedSize());
                    }
                    else // disk order is x, y, z, w
                    {
                        DataIO::ReadData(rotQuatX[kfIdx].var(), dataPacket, kfBase + 0,  rotQuatX[kfIdx].fixedSize());
                        DataIO::ReadData(rotQuatY[kfIdx].var(), dataPacket, kfBase + 4,  rotQuatY[kfIdx].fixedSize());
                        DataIO::ReadData(rotQuatZ[kfIdx].var(), dataPacket, kfBase + 8,  rotQuatZ[kfIdx].fixedSize());
                        DataIO::ReadData(rotQuatW[kfIdx].var(), dataPacket, kfBase + 12, rotQuatW[kfIdx].fixedSize());
                    }
                    kfIdx++;
                    if (k + 1 < tracks[b].numKeyframes)
                    {
                        DataIO::ReadData(rotInterval[intIdx].var(), dataPacket, kfBase + compressSize, rotInterval[intIdx].fixedSize());
                        intIdx++;
                    }
                }
            }
        }
    }

    // raw0x38: sound data — 2-field struct (0x22 bytes) per entry
    size_t sdBase = soundDataOffset.val();
    uint32_t sdCount = soundPartCount.val();
    if (sdCount > 0)
    {
        if (sdBase + static_cast<size_t>(sdCount) * 0x22 > dataPacket.size())
        {
            cerr << "Error: Sound data for instance " << quoted(name_) << " is out of bounds.\n";
            return;
        }

        soundPartName.reserve(sdCount);
        soundPartFrame.reserve(sdCount);
        for (uint32_t i = 0; i < sdCount; i++)
        {
            int baseOrder = (3 * numFrames)
                            + (static_cast<int>(apCount) * 13) + (static_cast<int>(dpCount) * 2)
                            + (static_cast<int>(mbCount) * 7) + (static_cast<int>(scCount) * 3)
                            + (tdBase != 0 ? 6 : 0) + (static_cast<int>(fsCount) * 2)
                            + (static_cast<int>(ppCount) * 5)
                            + (static_cast<int>(numFrames) * 4)
                            + (static_cast<int>(bodyPartCount.val()) * (5 * static_cast<int>(numFrames) - 1)) + 1 // +1 for rotation header field
                            + (static_cast<int>(i) * 2);
            soundPartName.emplace_back("sound OSBD name [" + to_string(i) + "]", baseOrder + 1);
            soundPartName.back().setFullSize(32);
            soundPartFrame.emplace_back("sound start frame [" + to_string(i) + "]", baseOrder + 2);
            fieldsAux_.push_back(&soundPartName.back());
            fieldsAux_.push_back(&soundPartFrame.back());
        }
        auxSectionAnchors_.push_back({&soundDataOffset, soundPartName.data()});
        sortFieldsAuxFor(origFormat_);
        for (uint32_t i = 0; i < sdCount; i++)
        {
            size_t entBase = sdBase + (static_cast<size_t>(i) * 0x22);
            DataIO::ReadData(soundPartName[i].var(), dataPacket, entBase + 0x00, soundPartName[i].fixedSize());
            DataIO::ReadData(soundPartFrame[i].var(), dataPacket, entBase + 0x20, soundPartFrame[i].fixedSize());
        }
    }

    // raw0x13C: extent data — 6-field struct (0x0C bytes) per entry; pre-calculated attack extents for AI melee prediction
    size_t epBase = extentPartOffset.val();
    uint32_t epCount = extentPartCount.val();
    if (epCount > 0)
    {
        if (epBase + static_cast<size_t>(epCount) * 0x0C > dataPacket.size())
        {
            cerr << "Error: Extent data for instance " << quoted(name_) << " is out of bounds.\n";
            return;
        }

        extentFrame.reserve(epCount);
        extentAngle.reserve(epCount);
        extentDistance.reserve(epCount);
        extentPad.reserve(epCount);
        extentMinY.reserve(epCount);
        extentMaxY.reserve(epCount);
        for (uint32_t i = 0; i < epCount; i++)
        {
            int baseOrder = (3 * numFrames)
                            + (static_cast<int>(apCount) * 13) + (static_cast<int>(dpCount) * 2)
                            + (static_cast<int>(mbCount) * 7) + (static_cast<int>(scCount) * 3)
                            + (tdBase != 0 ? 6 : 0) + (static_cast<int>(fsCount) * 2)
                            + (static_cast<int>(ppCount) * 5)
                            + (static_cast<int>(numFrames) * 4)
                            + (static_cast<int>(bodyPartCount.val()) * (5 * static_cast<int>(numFrames) - 1)) + 1 // +1 for rotation header field
                            + (static_cast<int>(sdCount) * 2)
                            + (static_cast<int>(i) * 6);
            extentFrame.emplace_back("extent frame [" + to_string(i) + "]",       baseOrder + 1);
            extentAngle.emplace_back("extent angle [" + to_string(i) + "]",       baseOrder + 2);
            extentDistance.emplace_back("extent distance [" + to_string(i) + "]", baseOrder + 3);
            extentPad.emplace_back("extent pad [" + to_string(i) + "]",           baseOrder + 4, true, false);
            extentPad.back().setFixedSize(2);
            extentMinY.emplace_back("extent min Y [" + to_string(i) + "]",        baseOrder + 5);
            extentMaxY.emplace_back("extent max Y [" + to_string(i) + "]",        baseOrder + 6);
            fieldsAux_.push_back(&extentFrame.back());
            fieldsAux_.push_back(&extentAngle.back());
            fieldsAux_.push_back(&extentDistance.back());
            fieldsAux_.push_back(&extentPad.back());
            fieldsAux_.push_back(&extentMinY.back());
            fieldsAux_.push_back(&extentMaxY.back());
        }
        auxSectionAnchors_.push_back({&extentPartOffset, extentFrame.data()});
        sortFieldsAuxFor(origFormat_);
        for (uint32_t i = 0; i < epCount; i++)
        {
            size_t entBase = epBase + (static_cast<size_t>(i) * 0x0C);
            DataIO::ReadData(extentFrame[i].var(),    dataPacket, entBase + 0x00, extentFrame[i].fixedSize());
            DataIO::ReadData(extentAngle[i].var(),    dataPacket, entBase + 0x02, extentAngle[i].fixedSize());
            DataIO::ReadData(extentDistance[i].var(), dataPacket, entBase + 0x04, extentDistance[i].fixedSize());
            DataIO::ReadData(extentPad[i].var(),      dataPacket, entBase + 0x06, extentPad[i].fixedSize());
            DataIO::ReadData(extentMinY[i].var(),     dataPacket, entBase + 0x08, extentMinY[i].fixedSize());
            DataIO::ReadData(extentMaxY[i].var(),     dataPacket, entBase + 0x0A, extentMaxY[i].fixedSize());
        }
    }
}

bool TemplateTRAM::convertData(Format toFmt)
{
    if (toFmt == curFormat_)
        return true;

    if (toFmt == Format::WinAlpha6)
    {
        cerr << "Advisory: Conversion of TRAM to Win alpha 6 format is not supported at this time.\n";
        return false;
    }

    if (origFormat_ != Format::WinAlpha6)
        return true; // All retail formats are interchangeable

    // Set the retail-only main-data fields to placeholder values
    soundDataOffset.val() = 0;
    soundPartCount.val() = 0;
    firstInvulnerableFrame.val() = 0;
    lastInvulnerableFrame.val() = 0;

    // Convert rotation section from WinAlpha6 frame-major dense layout to retail bone-major
    // sparse keyframe layout; all frames are preserved with interval=1 between each
    if (rotationsOffset.val() != 0)
    {
        uint16_t numFrames    = frameCount.val();
        uint16_t boneCount    = bodyPartCount.val();
        uint16_t compressSize = compressionSize.val();
        size_t   totalKF      = static_cast<size_t>(numFrames) * boneCount;

        if (totalKF > 0)
        {
            // Reconstruct boneNames from the existing body-part maps (same logic as processAuxData)
            vector<string> boneNames(boneCount);
            for (uint16_t b = 0; b < boneCount; b++)
                boneNames[b] = to_string(b);
            for (const auto& kv : bodyPartIdxValues)
                if (kv.second >= 0 && kv.second < boneCount)
                {
                    auto it = bodyPartIdxNames.find(kv.first);
                    if (it != bodyPartIdxNames.end())
                        boneNames[kv.second] = it->second;
                }

            // Reconstruct the starting order value (identical formula to processAuxData)
            uint8_t apCount = attackPartCount.val();
            uint8_t dpCount = takeDamagePartCount.val();
            uint8_t mbCount = motionBlurPartCount.val();
            uint8_t scCount = shortcutPartCount.val();
            size_t  tdBase  = throwDataOffset.val();
            uint8_t fsCount = footstepPartCount.val();
            uint8_t ppCount = particlePartCount.val();
            int order = (3 * numFrames)
                        + (static_cast<int>(apCount) * 13) + (static_cast<int>(dpCount) * 2)
                        + (static_cast<int>(mbCount) * 7)  + (static_cast<int>(scCount) * 3)
                        + (tdBase != 0 ? 6 : 0) + (static_cast<int>(fsCount) * 2)
                        + (static_cast<int>(ppCount) * 5)
                        + (static_cast<int>(numFrames) * 4)
                        + 1;

            // Header layout: boneCount uint16 offsets; each offset is relative to the block start
            // Track size: numFrames keyframes × compressSize bytes + (numFrames−1) interval bytes
            size_t headerSize = static_cast<size_t>(boneCount) * 2;
            size_t trackSize  = (static_cast<size_t>(numFrames) * (compressSize + 1)) - 1;

            if (compressSize == 6)
            {
                // Step 1: Save raw int16 values from frame-major WinAlpha6 layout
                vector<int16_t> savedX(totalKF), savedY(totalKF), savedZ(totalKF);
                for (size_t i = 0; i < totalKF; i++)
                {
                    savedX[i] = rotAngleX[i].val();
                    savedY[i] = rotAngleY[i].val();
                    savedZ[i] = rotAngleZ[i].val();
                }

                // Step 2: Remove stale rotation pointers from fieldsAux_ and the rotation anchor
                {
                    auto isRotField = [&](const Field* f)
                    {
                        for (const auto& x : rotAngleX) if (f == static_cast<const Field*>(&x)) return true;
                        for (const auto& x : rotAngleY) if (f == static_cast<const Field*>(&x)) return true;
                        for (const auto& x : rotAngleZ) if (f == static_cast<const Field*>(&x)) return true;
                        return false;
                    };
                    fieldsAux_.erase(remove_if(fieldsAux_.begin(), fieldsAux_.end(), isRotField),
                                     fieldsAux_.end());
                }
                auxSectionAnchors_.erase(remove_if(auxSectionAnchors_.begin(), auxSectionAnchors_.end(),
                                         [&](const pair<FieldOffset*, Field*>& a) {return a.first == &rotationsOffset;}),
                                         auxSectionAnchors_.end());
                rotAngleX.clear();
                rotAngleY.clear();
                rotAngleZ.clear();

                // Step 3: Build the per-bone offset-table header blob
                rotHeader.reserve(1);
                rotHeader.emplace_back("rotation track header", order++, false, true);
                rotHeader.back().setReservedSize(static_cast<uint32_t>(headerSize));
                auto& hdrData = rotHeader.back().val();
                for (uint16_t b = 0; b < boneCount; b++)
                {
                    uint16_t trackOff = static_cast<uint16_t>(headerSize + (static_cast<size_t>(b) * trackSize));
                    hdrData[static_cast<size_t>(b) * 2] = static_cast<char>(trackOff & 0xFF);
                    hdrData[(b * 2) + 1] = static_cast<char>((trackOff >> 8) & 0xFF);
                }
                fieldsAux_.push_back(&rotHeader.back());
                auxSectionAnchors_.push_back({&rotationsOffset, &rotHeader.back()});

                // Step 4: Emplace fields and assign values in bone-major, frame-minor order
                rotAngleX.reserve(totalKF);
                rotAngleY.reserve(totalKF);
                rotAngleZ.reserve(totalKF);
                rotInterval.reserve(static_cast<size_t>(boneCount) * (numFrames - 1));
                for (uint16_t b = 0; b < boneCount; b++)
                {
                    for (uint16_t f = 0; f < numFrames; f++)
                    {
                        string tag = " " + boneNames[b] + " [" + to_string(f) + "]";
                        rotAngleX.emplace_back("rotation" + tag + " x", order++);
                        rotAngleY.emplace_back("rotation" + tag + " y", order++);
                        rotAngleZ.emplace_back("rotation" + tag + " z", order++);
                        rotAngleX.back().val() = savedX[(f * boneCount) + b]; // transpose frame-major → bone-major
                        rotAngleY.back().val() = savedY[(f * boneCount) + b];
                        rotAngleZ.back().val() = savedZ[(f * boneCount) + b];
                        fieldsAux_.push_back(&rotAngleX.back());
                        fieldsAux_.push_back(&rotAngleY.back());
                        fieldsAux_.push_back(&rotAngleZ.back());
                        if (f + 1 < numFrames)
                        {
                            rotInterval.emplace_back("rotation" + tag + " interval", order++);
                            rotInterval.back().val() = 1;
                            fieldsAux_.push_back(&rotInterval.back());
                        }
                    }
                }
            }
            else // compressSize == 16
            {
                // Step 1: Save raw float values from frame-major WinAlpha6 layout
                vector<float> savedQX(totalKF), savedQY(totalKF), savedQZ(totalKF), savedQW(totalKF);
                for (size_t i = 0; i < totalKF; i++)
                {
                    savedQX[i] = rotQuatX[i].val();
                    savedQY[i] = rotQuatY[i].val();
                    savedQZ[i] = rotQuatZ[i].val();
                    savedQW[i] = rotQuatW[i].val();
                }

                // Step 2: Remove stale rotation pointers from fieldsAux_ and the rotation anchor
                {
                    auto isRotField = [&](const Field* f)
                    {
                        for (const auto& x : rotQuatX) if (f == static_cast<const Field*>(&x)) return true;
                        for (const auto& x : rotQuatY) if (f == static_cast<const Field*>(&x)) return true;
                        for (const auto& x : rotQuatZ) if (f == static_cast<const Field*>(&x)) return true;
                        for (const auto& x : rotQuatW) if (f == static_cast<const Field*>(&x)) return true;
                        return false;
                    };
                    fieldsAux_.erase(remove_if(fieldsAux_.begin(), fieldsAux_.end(), isRotField),
                                     fieldsAux_.end());
                }
                auxSectionAnchors_.erase(remove_if(auxSectionAnchors_.begin(), auxSectionAnchors_.end(),
                                         [&](const pair<FieldOffset*, Field*>& a) {return a.first == &rotationsOffset;}),
                                         auxSectionAnchors_.end());
                rotQuatX.clear();
                rotQuatY.clear();
                rotQuatZ.clear();
                rotQuatW.clear();

                // Step 3: Build the per-bone offset-table header blob
                rotHeader.reserve(1);
                rotHeader.emplace_back("rotation track header", order++, false, true);
                rotHeader.back().setReservedSize(static_cast<uint32_t>(headerSize));
                auto& hdrData = rotHeader.back().val();
                for (uint16_t b = 0; b < boneCount; b++)
                {
                    uint16_t trackOff = static_cast<uint16_t>(headerSize + (static_cast<size_t>(b) * trackSize));
                    hdrData[static_cast<size_t>(b) * 2] = static_cast<char>(trackOff & 0xFF);
                    hdrData[(b * 2) + 1] = static_cast<char>((trackOff >> 8) & 0xFF);
                }
                fieldsAux_.push_back(&rotHeader.back());
                auxSectionAnchors_.push_back({&rotationsOffset, &rotHeader.back()});

                // Step 4: Emplace fields and assign values in bone-major, frame-minor order
                rotQuatX.reserve(totalKF);
                rotQuatY.reserve(totalKF);
                rotQuatZ.reserve(totalKF);
                rotQuatW.reserve(totalKF);
                rotInterval.reserve(static_cast<size_t>(boneCount) * (numFrames - 1));
                for (uint16_t b = 0; b < boneCount; b++)
                {
                    for (uint16_t f = 0; f < numFrames; f++)
                    {
                        string tag = " " + boneNames[b] + " [" + to_string(f) + "]";
                        rotQuatX.emplace_back("rotation" + tag + " quat x", order++);
                        rotQuatY.emplace_back("rotation" + tag + " quat y", order++);
                        rotQuatZ.emplace_back("rotation" + tag + " quat z", order++);
                        rotQuatW.emplace_back("rotation" + tag + " quat w", order++);
                        rotQuatX.back().val() = savedQX[(f * boneCount) + b]; // transpose frame-major → bone-major
                        rotQuatY.back().val() = savedQY[(f * boneCount) + b];
                        rotQuatZ.back().val() = savedQZ[(f * boneCount) + b];
                        rotQuatW.back().val() = savedQW[(f * boneCount) + b];
                        fieldsAux_.push_back(&rotQuatX.back());
                        fieldsAux_.push_back(&rotQuatY.back());
                        fieldsAux_.push_back(&rotQuatZ.back());
                        fieldsAux_.push_back(&rotQuatW.back());
                        if (f + 1 < numFrames)
                        {
                            rotInterval.emplace_back("rotation" + tag + " interval", order++);
                            rotInterval.back().val() = 1;
                            fieldsAux_.push_back(&rotInterval.back());
                        }
                    }
                }
            }
        }
    }

    sortFieldsAuxFor(toFmt);

    // convertData() rebuilds the rotation section and re-appends its anchor at the end of "auxSectionAnchors_"; restore ascending-offset order
    // so auxDataSizeAligned() and the export aux-writing loop (which both assume this ordering) compute matching sizes and padding
    sort(auxSectionAnchors_.begin(), auxSectionAnchors_.end(),
         [](const pair<FieldOffset *, Field *> & a, const pair<FieldOffset *, Field *> & b) {return a.second->offset() < b.second->offset();});

    curFormat_ = toFmt;
    return true;
}

/**************************** TemplateTRAS ****************************/
TemplateTRAS::TemplateTRAS(string instName, Format dataFormat)
            : Template("TRAS", std::move(instName), dataFormat),
              tramLink("frames link",                          2),
              negYawDelta("negative yaw delta",                3),
              posYawDelta("positive yaw delta",                4),
              numNegYawFrames("negative yaw frame count",      5),
              numPosYawFrames("positive yaw frame count",      6),
              negPitchDelta("negative pitch delta",            7),
              posPitchDelta("positive pitch delta",            8),
              numNegPitchFrames("negative pitch frame count",  9),
              numPosPitchFrames("positive pitch frame count", 10)
{
    hasLinks_ = true;
    certified_ = true;

    fields_.insert(fields_.end(), {&tramLink, &negYawDelta, &posYawDelta, &numNegYawFrames, &numPosYawFrames, &negPitchDelta, &posPitchDelta,
                                   &numNegPitchFrames, &numPosPitchFrames});
}

unique_ptr<Template> TemplateTRAS::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTRAS>(instName, dataFormat);
}

/**************************** TemplateTRBS ****************************/
TemplateTRBS::TemplateTRBS(string instName, Format dataFormat)
            : Template("TRBS", std::move(instName), dataFormat),
              LODsuperlow("super-low LOD body",   2),
              LODlow("low LOD body",              3),
              LODmedium("medium LOD body",        4),
              LODhigh("high LOD body",            5),
              LODsuperhigh("super-high LOD body", 6)
{
    hasLinks_ = true;
    certified_ = true;

    fields_.insert(fields_.end(), {&LODsuperlow, &LODlow, &LODmedium, &LODhigh, &LODsuperhigh});
}

unique_ptr<Template> TemplateTRBS::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTRBS>(instName, dataFormat);
}

/**************************** TemplateTRCM ****************************/
TemplateTRCM::TemplateTRCM(string instName, Format dataFormat)
            : Template("TRCM", std::move(instName), dataFormat),
              polysUnused("polygon count (unused)",      2, true, false),
              bodyPartCount("body part count",           3),
              padding("padding",                         4, true, false),
              sourceFile("source file name",             5, true, false),
              geomPtr("geometries pointer (runtime)",    6, true, false),
              transPtr("translations pointer (runtime)", 7, true, false),
              indexPtr("indexes pointer (runtime)",      8, true, false),
              trga("TRGA link",                          9),
              trta("TRTA link",                          10),
              tria("TRIA link",                          11)
{
    hasLinks_ = true;
    certified_ = true;

    fields_.insert(fields_.end(), {&polysUnused, &bodyPartCount, &padding, &sourceFile, &geomPtr, &transPtr, &indexPtr, &trga, &trta, &tria});

    padding.setFixedSize(2);

    sourceFile.setFullSize(64);
}

unique_ptr<Template> TemplateTRCM::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTRCM>(instName, dataFormat);
}

/**************************** TemplateTRGA ****************************/
TemplateTRGA::TemplateTRGA(string instName, Format dataFormat)
            : Template("TRGA", std::move(instName), dataFormat),
              padding("padding",           2, true, false),
              arraySize("body part count", 3)
{
    hasLinks_ = true;
    certified_ = true;

    fwvlaSizeOffset_ = {0x1E, 16};

    fields_.insert(fields_.end(), {&padding, &arraySize});

    padding.setFixedSize(22);
}

unique_ptr<Template> TemplateTRGA::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTRGA>(instName, dataFormat);
}

void TemplateTRGA::createFWVarArray(int32_t n)
{
    m3gm.reserve(static_cast<size_t>(n));

    for (int32_t i = 0; i < n; ++i)
    {
        m3gm.emplace_back("part geometry [" + to_string(i) + "]", 4 + i); // last field added by TemplateTRGA constructor was order 3
        fields_.insert(fields_.end(), {&m3gm[static_cast<size_t>(i)]});
    }
}

/**************************** TemplateTRIA ****************************/
TemplateTRIA::TemplateTRIA(string instName, Format dataFormat)
            : Template("TRIA", std::move(instName), dataFormat),
              padding("padding",            2, true, false),
              arraySize("part index count", 3)
{
    hasLinks_ = true;
    certified_ = true;

    fwvlaSizeOffset_ = {0x1E, 16};

    bodyPartValues =
    {
        {NoneOrPelvis,  0},
        {LeftThigh,     1},
        {LeftShin,      2},
        {LeftFoot,      3},
        {RightThigh,    4},
        {RightShin,     5},
        {RightFoot,     6},
        {Abdomen,       7},
        {Chest,         8},
        {Neck,          9},
        {Head,          10},
        {LeftShoulder,  11},
        {LeftUpperArm,  12},
        {LeftForearm,   13},
        {LeftHand,      14},
        {RightShoulder, 15},
        {RightUpperArm, 16},
        {RightForeArm,  17},
        {RightHand,     18},
    };
    bodyPartNames =
    {
        {NoneOrPelvis,  "pelvis/none"},
        {LeftThigh,     "left thigh"},
        {LeftShin,      "left shin"},
        {LeftFoot,      "left foot"},
        {RightThigh,    "right thigh"},
        {RightShin,     "right shin"},
        {RightFoot,     "right foot"},
        {Abdomen,       "abdomen"},
        {Chest,         "chest"},
        {Neck,          "neck"},
        {Head,          "head"},
        {LeftShoulder,  "left shoulder"},
        {LeftUpperArm,  "left upper arm"},
        {LeftForearm,   "left forearm"},
        {LeftHand,      "left hand"},
        {RightShoulder, "right shoulder"},
        {RightUpperArm, "right upper arm"},
        {RightForeArm,  "right forearm"},
        {RightHand,     "right hand"},
    };

    fields_.insert(fields_.end(), {&padding, &arraySize});

    padding.setFixedSize(22);
}

unique_ptr<Template> TemplateTRIA::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTRIA>(instName, dataFormat);
}

void TemplateTRIA::createFWVarArray(int32_t n)
{
    const size_t sz = static_cast<size_t>(n);
    parentBone.reserve(sz);
    childBone.reserve(sz);
    siblingBone.reserve(sz);
    zeroBoneUnused.reserve(sz);

    int nf = 4, st = 4; // last field added by TemplateTRIA constructor was order 3
    for (int32_t i = 0; i < n; ++i)
    {
        parentBone.emplace_back("parent bone (unused) [" + to_string(i) + "]", st + (nf * i) + 0, true, true, uint8_t{0}, uint8_t{0},
                                &bodyPartValues, &bodyPartNames);
        childBone.emplace_back("child bone [" + to_string(i) + "]",            st + (nf * i) + 1, true, true, uint8_t{0}, uint8_t{0},
                               &bodyPartValues, &bodyPartNames);
        siblingBone.emplace_back("sibling bone [" + to_string(i) + "]",        st + (nf * i) + 2, true, true, uint8_t{0}, uint8_t{0},
                                 &bodyPartValues, &bodyPartNames); 
        zeroBoneUnused.emplace_back("unused bone [" + to_string(i) + "]",      st + (nf * i) + 3, true, false, uint8_t{0}, uint8_t{0},
                                    &bodyPartValues, &bodyPartNames); 
        fields_.insert(fields_.end(), {&parentBone[static_cast<size_t>(i)], &childBone[static_cast<size_t>(i)],
                                       &siblingBone[static_cast<size_t>(i)], &zeroBoneUnused[static_cast<size_t>(i)]});
    }
}

/**************************** TemplateTRMA ****************************/
TemplateTRMA::TemplateTRMA(string instName, Format dataFormat)
            : Template("TRMA", std::move(instName), dataFormat),
              padding("padding",         2, true, false),
              arraySize("texture count", 3)
{
    hasLinks_ = true;
    certified_ = true;

    fwvlaSizeOffset_ = {0x1E, 16};

    fields_.insert(fields_.end(), {&padding, &arraySize});

    padding.setFixedSize(22);
}

unique_ptr<Template> TemplateTRMA::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTRMA>(instName, dataFormat);
}

void TemplateTRMA::createFWVarArray(int32_t n)
{
    txmp.reserve(static_cast<size_t>(n));

    for (int32_t i = 0; i < n; ++i)
    {
        txmp.emplace_back("texture [" + to_string(i) + "]", 4 + i); // last field added by TemplateTRMA constructor was order 3
        fields_.insert(fields_.end(), {&txmp[static_cast<size_t>(i)]});
    }
}

/**************************** TemplateTRSC ****************************/
TemplateTRSC::TemplateTRSC(string instName, Format dataFormat)
            : Template("TRSC", std::move(instName), dataFormat),
              padding("padding",               2, true, false),
              arraySize("aiming screen count", 3)
{
    hasLinks_ = true;
    certified_ = true;

    fwvlaSizeOffset_ = {0x1E, 16};

    fields_.insert(fields_.end(), {&padding, &arraySize});

    padding.setFixedSize(22);
}

unique_ptr<Template> TemplateTRSC::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTRSC>(instName, dataFormat);
}

void TemplateTRSC::createFWVarArray(int32_t n)
{
    tras.reserve(static_cast<size_t>(n));

    for (int32_t i = 0; i < n; ++i)
    {
        tras.emplace_back("aiming screen [" + to_string(i) + "]", 4 + i); // last field added by TemplateTRSC constructor was order 3
        fields_.insert(fields_.end(), {&tras[static_cast<size_t>(i)]});
    }
}

/**************************** TemplateTRTA ****************************/
TemplateTRTA::TemplateTRTA(string instName, Format dataFormat)
            : Template("TRTA", std::move(instName), dataFormat),
              padding("padding",             2, true, false),
              arraySize("part offset count", 3)
{
    hasLinks_ = true;
    certified_ = true;

    fwvlaSizeOffset_ = {0x1E, 16};

    fields_.insert(fields_.end(), {&padding, &arraySize});

    padding.setFixedSize(22);
}

unique_ptr<Template> TemplateTRTA::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTRTA>(instName, dataFormat);
}

void TemplateTRTA::createFWVarArray(int32_t n)
{
    const size_t sz = static_cast<size_t>(n);
    offsetX.reserve(sz);
    offsetY.reserve(sz);
    offsetZ.reserve(sz);

    int nf = 3, st = 4; // last field added by TemplateTRTA constructor was order 3
    for (int32_t i = 0; i < n; ++i)
    {
        offsetX.emplace_back("x offset [" + to_string(i) + "]", st + (nf * i) + 0);
        offsetY.emplace_back("y offset [" + to_string(i) + "]", st + (nf * i) + 1);
        offsetZ.emplace_back("z offset [" + to_string(i) + "]", st + (nf * i) + 2);
        fields_.insert(fields_.end(), {&offsetX[static_cast<size_t>(i)], &offsetY[static_cast<size_t>(i)], &offsetZ[static_cast<size_t>(i)]});
    }
}

/**************************** TemplateTSFF ****************************/
TemplateTSFF::TemplateTSFF(string instName, Format dataFormat)
            : Template("TSFF", std::move(instName), dataFormat),
              padding("padding",           kRetailOnly(2), true, false),
              tsflLink("font language",    3),
              arraySize("font type count", kRetailOnly(4)),
              tsftLink1("font 1",          kAlphaOnly(5)),
              tsftLink2("font 2",          kAlphaOnly(6)),
              tsftLink3("font 3",          kAlphaOnly(7))
{
    hasLinks_ = true;
    certified_ = true;

    fwvlaSizeOffset_ = {0x1C, 32};

    fields_.insert(fields_.end(), {&padding, &tsflLink, &arraySize, &tsftLink1, &tsftLink2, &tsftLink3});

    padding.setFixedSize(16);
}

unique_ptr<Template> TemplateTSFF::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTSFF>(instName, dataFormat);
}

bool TemplateTSFF::hasFWVarArray() const
{
    return origFormat_ != Format::WinAlpha6;
}

void TemplateTSFF::createFWVarArray(int32_t n)
{
    const size_t sz = static_cast<size_t>(n);
    tsftLink.reserve(sz);

    int s = static_cast<int>(fields_.size()) + 1; // resume adding fields after fixed header fields
    int nf = 1; // number of fields per array element
    for (int32_t i = 0; i < n; ++i)
        tsftLink.emplace_back("font [" + to_string(i) + "]", s + (nf * i) + 0);

    for (size_t i = 0; i < sz; ++i)
        fields_.insert(fields_.end(), {&tsftLink[i]});
}

void TemplateTSFF::displayViaTerminal(TerminalImageSupport termSupport, int displayScale,
                                      const vector<unique_ptr<Template>> & instances)
{
    // Helper lambda to attempt display of one TSFT link
    auto tryDisplayLink = [&](FieldLink & link) -> bool
    {
        if (!link.hasLink())
            return false;
        uint32_t idx = link.val();
        if (idx >= instances.size() || !instances[idx])
            return false;
        TemplateTSFT * tsft = dynamic_cast<TemplateTSFT *>(instances[idx].get());
        if (!tsft)
            return false;
        cout << "Font: " << tsft->name_ << " (#" << tsft->index_.val() << ")\n";
        tsft->displayViaTerminal(termSupport, displayScale, instances);
        return true;
    };

    int displayed = 0;
    if (origFormat_ == Format::WinAlpha6)
    {
        if (tryDisplayLink(tsftLink1)) ++displayed;
        if (tryDisplayLink(tsftLink2)) ++displayed;
        if (tryDisplayLink(tsftLink3)) ++displayed;
    }
    else
    {
        for (auto & link : tsftLink)
            if (tryDisplayLink(link)) ++displayed;
    }

    if (displayed == 0)
        cerr << "Advisory: No valid TSFT instances found in TSFF instance " << quoted(name_) << ".\n";
}

bool TemplateTSFF::exportToPNG(const string & baseDir, const vector<unique_ptr<Template>> & instances)
{
    // Helper lambda to export one TSFT link; files are named with the TSFF family name and the TSFT's size and style
    auto tryExportLink = [&](FieldLink & link) -> bool
    {
        if (!link.hasLink())
            return false;
        uint32_t idx = link.val();
        if (idx >= instances.size() || !instances[idx])
            return false;
        TemplateTSFT * tsft = dynamic_cast<TemplateTSFT *>(instances[idx].get());
        if (!tsft)
            return false;

        string familyName = name_.substr(0, 4) == "TSFF" ? name_.substr(4) : name_;
        string stem = "TSFT" + familyName + "-" + tsft->fontDescription(); // DiskItem sanitizes the name when the file is written
        return tsft->exportToPNG(baseDir, stem, instances);
    };

    int exported = 0;
    if (origFormat_ == Format::WinAlpha6)
    {
        if (tryExportLink(tsftLink1)) ++exported;
        if (tryExportLink(tsftLink2)) ++exported;
        if (tryExportLink(tsftLink3)) ++exported;
    }
    else
    {
        for (auto & link : tsftLink)
            if (tryExportLink(link)) ++exported;
    }

    if (exported == 0)
    {
        cerr << "Advisory: No valid TSFT instances found in TSFF instance " << quoted(name_) << ".\n";
        return false;
    }
    return true;
}

/**************************** TemplateTSFL ****************************/
TemplateTSFL::TemplateTSFL(string instName, Format dataFormat)
            : Template("TSFL", std::move(instName), dataFormat),
              truncaters("truncate chars (unused)",               2),
              breakers("breaking chars",                          3),
              wordEnders("word ending chars (unused)",            4),
              wordNonEnders("word non-ending chars (unused)",     5),
              wordNonStarters("word non-starting chars (unused)", 6)
{
    certified_ = true;

    fields_.insert(fields_.end(), {&truncaters, &breakers, &wordEnders, &wordNonEnders, &wordNonStarters});

    truncaters.setFullSize(64);
    breakers.setFullSize(64);
    wordEnders.setFullSize(64);
    wordNonEnders.setFullSize(64);
    wordNonStarters.setFullSize(64);
}

unique_ptr<Template> TemplateTSFL::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTSFL>(instName, dataFormat);
}

/**************************** TemplateTSFT ****************************/
TemplateTSFT::TemplateTSFT(string instName, Format dataFormat)
            : Template("TSFT", std::move(instName), dataFormat),
              padding("padding",                     2, true, false),
              fontSize("font size",                  3),
              fontStyle("font style",                4),
              ascHeight("ascending height",          5),
              descHeight("descending height",        6),
              leadingHeight("leading height",        7),
              leadingWidth("leading width (unused)", 8),
              arraySize("pixel array size",          kNotPS2(265)),
              rawOffset("pixel data offset",         kPS2Only(265)),
              ps2PixelData("pixel data (PS2)",       1)
{
    hasLinks_   = true;
    certified_  = true;
    hasAuxData_ = (dataFormat == Format::PS2);

    fwvlaSizeOffset_ = {0x41C, 32};

    fontStyleValues = {{Plain, 0}, {Bold, 1}, {Italic, 2}};
    fontStyleNames  = {{Plain, "plain"}, {Bold, "bold"}, {Italic, "italic"}};
    fontStyle.setTypeValueMap(&fontStyleValues);
    fontStyle.setTypeNameMap(&fontStyleNames);

    // Build the fixed table of 256 TSGA links in the constructor body (fixed count, not a FWVLA)
    tsgaLink.reserve(256);
    for (int i = 0; i < 256; ++i)
        tsgaLink.emplace_back("TSGA link [" + to_string(i) + "]", 9 + i);

    padding.setFixedSize(6);

    fields_.insert(fields_.end(), {&padding, &fontSize, &fontStyle, &ascHeight, &descHeight, &leadingHeight, &leadingWidth});
    for (size_t i = 0; i < 256; ++i)
        fields_.insert(fields_.end(), {&tsgaLink[i]});
    fields_.insert(fields_.end(), {&arraySize, &rawOffset});

    if (dataFormat == Format::PS2)
        fieldsAux_.insert(fieldsAux_.end(), {&ps2PixelData});
}

unique_ptr<Template> TemplateTSFT::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTSFT>(instName, dataFormat);
}

bool TemplateTSFT::hasFWVarArray() const
{
    return origFormat_ != Format::PS2;
}

void TemplateTSFT::createFWVarArray(int32_t n)
{
    const size_t sz = static_cast<size_t>(n);
    pixel.reserve(sz);

    int s  = static_cast<int>(fields_.size()) + 1; // next slot after fixed header + both conditional fields
    int nf = 1; // one FieldU32 per pixel element
    for (int32_t i = 0; i < n; ++i)
        pixel.emplace_back("pixel data [" + to_string(i) + "]", s + (nf * i) + 0);

    for (size_t i = 0; i < sz; ++i)
        fields_.insert(fields_.end(), {&pixel[i]});
}

void TemplateTSFT::processAuxData(vector<char> & dataPacket)
{
    uint32_t offset = rawOffset.val();
    if (offset >= dataPacket.size())
    {
        cerr << "Error: Raw pixel data offset for instance " << quoted(name_) << " is out of bounds.\n";
        return;
    }

    static constexpr uint32_t kFontPixelDataSafety = 20'000; // largest observed PS2 TSFT is around 10K
    ps2PixelData.setReservedSize(min(static_cast<uint32_t>(dataPacket.size()) - offset, kFontPixelDataSafety));
    size_t copySize = ps2PixelData.val().size(); // should always be the number above
    copy(dataPacket.begin() + static_cast<ptrdiff_t>(offset),
         dataPacket.begin() + static_cast<ptrdiff_t>(offset + copySize),
         ps2PixelData.val().begin());
    sortFieldsAuxFor(origFormat_); // computes field offsets and sets auxDataSize_
}

void TemplateTSFT::finalizeAuxData(const vector<unique_ptr<Template>> & instances)
{
    if (origFormat_ != Format::PS2)
        return;

    uint32_t maxExtent = 0;
    for (auto & link : tsgaLink)
    {
        if (!link.hasLink())
            continue;
        uint32_t idx = link.val();
        if (idx >= instances.size())
            continue;
        auto * tsga = dynamic_cast<TemplateTSGA *>(instances[idx].get());
        if (tsga == nullptr)
            continue;
        maxExtent = max(maxExtent, tsga->pixelDataExtent());
    }

    if (maxExtent == 0)
    {
        cerr << "Error: Could not determine pixel data size for instance " << quoted(name_) << " from TSGA links.\n";
        return;
    }
    if (maxExtent > ps2PixelData.val().size())
    {
        cerr << "Error: Computed pixel data size for instance " << quoted(name_) << " exceeds blob allocation.\n";
        return;
    }

    ps2PixelData.trim(maxExtent);
    sortFieldsAuxFor(origFormat_); // recompute auxDataSize_ with trimmed size
}

bool TemplateTSFT::buildGlyphSheetRGBA(const vector<unique_ptr<Template>> & instances,
                                       vector<uint8_t> & outSheet, size_t & outW, size_t & outH)
{
    constexpr int kGlyphCount = 256;
    constexpr int kSheetCols = 16;
    bool isPS2 = (origFormat_ == Format::PS2);

    // Collect unique TSGA instances referenced by the 256 tsgaLink entries
    vector<TemplateTSGA *> tsgaList;
    for (auto & link : tsgaLink)
    {
        if (!link.hasLink())
            continue;
        uint32_t idx = link.val();
        if (idx >= instances.size() || !instances[idx])
            continue;
        TemplateTSGA * tsga = dynamic_cast<TemplateTSGA *>(instances[idx].get());
        if (!tsga)
            continue;
        bool already = false;
        for (TemplateTSGA * existing : tsgaList)
        {
            if (existing == tsga)
            {
                already = true;
                break;
            }
        }
        if (!already)
            tsgaList.push_back(tsga);
    }
    if (tsgaList.empty())
    {
        cerr << "Error: No glyph data found for instance " << quoted(name_) << ".\n";
        return false;
    }

    if (isPS2 && ps2PixelData.val().empty())
    {
        cerr << "Error: No PS2 pixel data loaded for instance " << quoted(name_) << ".\n";
        return false;
    }
    if (!isPS2 && pixel.empty())
    {
        cerr << "Error: No pixel data loaded for instance " << quoted(name_) << ".\n";
        return false;
    }

    // Map each glyph by code point for grid-based layout
    struct GlyphRef
    {
        TemplateTSGA * tsga = nullptr;
        int slot = -1;
        bool valid = false;
    };
    array<GlyphRef, 256> glyphByCode;
    uint16_t maxGlyphW = 0, maxGlyphH = 0;
    for (TemplateTSGA * tsga : tsgaList)
    {
        for (int i = 0; i < kGlyphCount; ++i)
        {
            GlyphInfo g = tsga->glyphAt(i);
            if (g.glyphW == 0 || g.glyphH == 0)
                continue;
            if (glyphByCode[g.code].valid)
                continue;
            glyphByCode[g.code] = {tsga, i, true};
            maxGlyphW = max(maxGlyphW, g.glyphW);
            maxGlyphH = max(maxGlyphH, g.glyphH);
        }
    }
    if (maxGlyphW == 0)
    {
        cerr << "Error: No renderable glyphs found for instance " << quoted(name_) << ".\n";
        return false;
    }

    // Determine which row groups (code >> 4) contain at least one glyph
    vector<int> activeRows;
    for (int row = 0; row < kSheetCols; ++row)
    {
        for (int col = 0; col < kSheetCols; ++col)
        {
            if (glyphByCode[(size_t(row) * size_t(kSheetCols)) + size_t(col)].valid)
            {
                activeRows.push_back(row);
                break;
            }
        }
    }
    size_t numDataRows = activeRows.size();

    // Header label layout: 5x7 pixel bitmap font, 1px gap between chars, 2px cell padding
    constexpr int kFontW = 5;
    constexpr int kFontH = 7;
    constexpr int kFontGap = 1;
    constexpr int kPad = 2;
    constexpr int kColLabelW = (4 * kFontW) + (3 * kFontGap); // "...X" = 4 chars = 23 px
    constexpr int kRowLabelW = (6 * kFontW) + (5 * kFontGap); // "0xX..." = 6 chars = 35 px

    constexpr int kGlyphPadV = 4; // extra pixels above and below each glyph within its cell

    const int cellW = max(int(maxGlyphW), kColLabelW + (2 * kPad));
    const int cellH = max(int(maxGlyphH) + (2 * kGlyphPadV), kFontH + (2 * kPad));
    const int colHdrH = kFontH + (2 * kPad);
    const int rowHdrW = kRowLabelW + (2 * kPad);

    // Sheet: 1px black border around and between every cell
    // Width:  left_border + row_header + col_separator + 16*(cell + right_border)
    // Height: top_border + col_header + row_separator + N*(cell + bottom_border)
    const size_t sheetW = size_t(1 + rowHdrW + 1) + (size_t(kSheetCols) * size_t(cellW + 1));
    const size_t sheetH = size_t(1 + colHdrH + 1) + (numDataRows * size_t(cellH + 1));

    // Pixel origin of data column c and data row r
    auto colX = [&](int c) {return size_t(1 + rowHdrW + 1) + (size_t(c) * size_t(cellW + 1));};
    auto rowY = [&](int r) {return size_t(1 + colHdrH + 1) + (size_t(r) * size_t(cellH + 1));};

    // Black background serves as grid lines; fully opaque throughout
    vector<uint8_t> sheet(sheetW * sheetH * 4, 0);
    for (size_t i = 3; i < sheet.size(); i += 4) sheet[i] = 255;

    auto fillRect = [&](size_t x0, size_t y0, size_t w, size_t h, uint8_t rv, uint8_t gv, uint8_t bv)
    {
        for (size_t py = y0; py < y0 + h && py < sheetH; ++py)
            for (size_t px = x0; px < x0 + w && px < sheetW; ++px)
            {
                size_t dst = (py * sheetW + px) * 4;
                sheet[dst]     = rv;
                sheet[dst + 1] = gv;
                sheet[dst + 2] = bv;
            }
    };

    // 5x7 bitmap font for header labels; each byte is one pixel row (bit 4 = leftmost, bit 0 = rightmost)
    // Index: 0='.'  1-10='0'-'9'  11-16='A'-'F'  17='x'
    static const uint8_t kFont[][7] =
    {
        {0x00, 0x00, 0x00, 0x00, 0x00, 0x04, 0x04}, // '.'
        {0x0E, 0x11, 0x11, 0x11, 0x11, 0x11, 0x0E}, // '0'
        {0x04, 0x0C, 0x04, 0x04, 0x04, 0x04, 0x0E}, // '1'
        {0x0E, 0x11, 0x01, 0x02, 0x04, 0x08, 0x1F}, // '2'
        {0x0E, 0x11, 0x01, 0x06, 0x01, 0x11, 0x0E}, // '3'
        {0x02, 0x06, 0x0A, 0x12, 0x1F, 0x02, 0x02}, // '4'
        {0x1F, 0x10, 0x1E, 0x01, 0x01, 0x11, 0x0E}, // '5'
        {0x0E, 0x10, 0x10, 0x1E, 0x11, 0x11, 0x0E}, // '6'
        {0x1F, 0x01, 0x02, 0x04, 0x04, 0x04, 0x04}, // '7'
        {0x0E, 0x11, 0x11, 0x0E, 0x11, 0x11, 0x0E}, // '8'
        {0x0E, 0x11, 0x11, 0x0F, 0x01, 0x01, 0x0E}, // '9'
        {0x0E, 0x11, 0x11, 0x1F, 0x11, 0x11, 0x11}, // 'A'
        {0x1E, 0x11, 0x11, 0x1E, 0x11, 0x11, 0x1E}, // 'B'
        {0x0E, 0x11, 0x10, 0x10, 0x10, 0x11, 0x0E}, // 'C'
        {0x1E, 0x11, 0x11, 0x11, 0x11, 0x11, 0x1E}, // 'D'
        {0x1F, 0x10, 0x10, 0x1E, 0x10, 0x10, 0x1F}, // 'E'
        {0x1F, 0x10, 0x10, 0x1E, 0x10, 0x10, 0x10}, // 'F'
        {0x00, 0x00, 0x11, 0x0A, 0x04, 0x0A, 0x11}, // 'x'
    };
    auto fontIndex = [](char c) -> int
    {
        if (c == '.') return 0;
        if (c >= '0' && c <= '9') return 1 + (c - '0');
        if (c >= 'A' && c <= 'F') return 11 + (c - 'A');
        if (c == 'x') return 17;
        return 0;
    };
    auto drawLabel = [&](const string & text, size_t cellLeft, size_t cellTop, size_t cw, size_t ch)
    {
        size_t nChars = text.size();
        if (nChars == 0) return;
        size_t textW  = (nChars * size_t(kFontW)) + ((nChars - 1) * size_t(kFontGap));
        size_t startX = cellLeft + ((cw - textW) / 2);
        size_t startY = cellTop  + ((ch - size_t(kFontH)) / 2);
        for (size_t ci = 0; ci < nChars; ++ci)
        {
            const uint8_t * bm = kFont[fontIndex(text[ci])];
            size_t charX = startX + (ci * size_t(kFontW + kFontGap));
            for (int fy = 0; fy < kFontH; ++fy)
            {
                uint8_t bits = bm[fy];
                for (int fx = 0; fx < kFontW; ++fx)
                {
                    if (!((bits >> (kFontW - 1 - fx)) & 1))
                        continue;
                    size_t px = charX + size_t(fx), py = startY + size_t(fy);
                    if (px >= sheetW || py >= sheetH)
                        continue;
                    size_t dst = (py * sheetW + px) * 4;
                    sheet[dst] = sheet[dst + 1] = sheet[dst + 2] = 0; // black text
                }
            }
        }
    };

    constexpr uint8_t kHdrR = 200, kHdrG = 200, kHdrB = 220;

    // Corner cell
    fillRect(1, 1, rowHdrW, colHdrH, kHdrR, kHdrG, kHdrB);

    // Column header cells: "...0" through "...F"
    for (int c = 0; c < kSheetCols; ++c)
    {
        size_t cx = colX(c);
        fillRect(cx, 1, size_t(cellW), size_t(colHdrH), kHdrR, kHdrG, kHdrB);
        char d = (c < 10) ? char('0' + c) : char('A' + c - 10);
        string label = "...";
        label += d;
        drawLabel(label, cx, 1, size_t(cellW), size_t(colHdrH));
    }

    // Row header cells and glyph data cells
    for (size_t ri = 0; ri < numDataRows; ++ri)
    {
        int rowGroup = activeRows[ri];
        size_t ry = rowY(int(ri));

        // Row header: "0x2..." through "0xF..."
        fillRect(1, ry, size_t(rowHdrW), size_t(cellH), kHdrR, kHdrG, kHdrB);
        char d = (rowGroup < 10) ? char('0' + rowGroup) : char('A' + rowGroup - 10);
        string label = "0x";
        label += d;
        label += "...";
        drawLabel(label, 1, ry, size_t(rowHdrW), size_t(cellH));

        for (int c = 0; c < kSheetCols; ++c)
        {
            size_t cx = colX(c);
            fillRect(cx, ry, size_t(cellW), size_t(cellH), 255, 255, 255); // white cell background

            size_t codePoint = (size_t(rowGroup) * size_t(kSheetCols)) + size_t(c);
            if (!glyphByCode[codePoint].valid)
                continue;

            const size_t cpIdx = codePoint;
            GlyphInfo info = glyphByCode[cpIdx].tsga->glyphAt(glyphByCode[cpIdx].slot);
            uint16_t gw = info.glyphW;
            uint16_t gh = info.glyphH;
            uint32_t pixelPos = info.pixelPos;
            size_t offX = size_t(cellW - gw) / 2; // center glyph in cell
            size_t offY = size_t(cellH - gh) / 2;

            if (isPS2)
            {
                // PS2: A2 format, 2 bits per pixel; 0x03 = fully opaque, 0x00 = transparent
                uint32_t endQB = pixelPos + (uint32_t(gw) * gh);
                if ((endQB + 3) / 4 > ps2PixelData.val().size())
                {
                    cerr << "Error: PS2 glyph pixel data out of bounds for instance " << quoted(name_)
                         << " (code point 0x" << format("{:02X}", codePoint) << ").\n";
                    continue;
                }
                const auto & blob = ps2PixelData.val();
                for (uint16_t py = 0; py < gh; ++py)
                {
                    for (uint16_t px = 0; px < gw; ++px)
                    {
                        uint32_t bitPos  = pixelPos + (uint32_t(py) * gw) + px;
                        uint8_t byteVal = static_cast<uint8_t>(blob[bitPos / 4]);
                        uint8_t val = (byteVal >> (2 * (bitPos % 4))) & 0x03;
                        uint8_t grey = uint8_t(255 - (val * 85)); // 3→0 (black), 0→255 (white)
                        size_t dstX = cx + offX + px;
                        size_t dstY = ry + offY + py;
                        if (dstX >= sheetW || dstY >= sheetH)
                            continue;
                        size_t dst = (dstY * sheetW + dstX) * 4;
                        sheet[dst] = sheet[dst + 1] = sheet[dst + 2] = grey;
                    }
                }
            }
            else
            {
                // PC: A8 format, 1 byte per pixel packed into U32s; 0xFF = transparent, 0x00 = opaque
                uint32_t numElems = (uint32_t(gw) * gh + 3) / 4;
                if (pixelPos + numElems > pixel.size())
                {
                    cerr << "Error: Glyph pixel data out of bounds for instance " << quoted(name_)
                         << " (code point 0x" << format("{:02X}", codePoint) << ").\n";
                    continue;
                }
                for (uint16_t py = 0; py < gh; ++py)
                {
                    for (uint16_t px = 0; px < gw; ++px)
                    {
                        uint32_t p = (uint32_t(py) * gw) + px;
                        uint8_t val = (pixel[pixelPos + (p / 4)].val() >> (8 * (p % 4))) & 0xFF;
                        size_t dstX = cx + offX + px;
                        size_t dstY = ry + offY + py;
                        if (dstX >= sheetW || dstY >= sheetH)
                            continue;
                        size_t dst = (dstY * sheetW + dstX) * 4;
                        sheet[dst] = sheet[dst + 1] = sheet[dst + 2] = val; // 0xFF→white, 0x00→black
                    }
                }
            }
        }
    }

    outSheet = std::move(sheet);
    outW = sheetW;
    outH = sheetH;
    return true;
}

void TemplateTSFT::displayViaTerminal(TerminalImageSupport termSupport, int displayScale, const vector<unique_ptr<Template>> & instances)
{
    vector<uint8_t> sheet;
    size_t sheetW = 0, sheetH = 0;
    if (!buildGlyphSheetRGBA(instances, sheet, sheetW, sheetH))
        return;
    TemplateDisplay::displayStaticRGBA(sheet, sheetW, sheetH, termSupport, displayScale, name_);
}

string TemplateTSFT::fontDescription()
{
    auto it = fontStyleNames.find(fontStyle.val());
    string styleName = (it != fontStyleNames.end()) ? it->second : to_string(static_cast<int>(fontStyle.val()));
    return to_string(fontSize.val()) + "-" + styleName;
}

bool TemplateTSFT::exportToPNG(const string & dir, const string & stem, const vector<unique_ptr<Template>> & instances)
{
    vector<uint8_t> sheet;
    size_t sheetW = 0, sheetH = 0;
    if (!buildGlyphSheetRGBA(instances, sheet, sheetW, sheetH))
        return false;

    vector<vector<uint8_t>> singleFrame {sheet};
    vector<uint8_t> png = TemplateDisplay::buildAnimatedPNG(singleFrame, sheetW, sheetH, 0, 1);
    if (png.empty())
    {
        cerr << "Error: Failed to build PNG data for instance " << quoted(name_) << ".\n";
        return false;
    }
    // DiskItem sanitizes the file name and enforces the program-wide overwrite policy
    return DiskItem(dir, stem, "png", ReadingMode::None, ReportingMode::ErrorsOnly).write(png) == WriteResult::Written;
}

/**************************** TemplateTSGA ****************************/
TemplateTSGA::TemplateTSGA(string instName, Format dataFormat)
            : Template("TSGA", std::move(instName), dataFormat)
{
    certified_ = true;

    // Build the fixed glyph table of 256 elements in the constructor body (fixed count, not a FWVLA)
    constexpr int kGlyphCount     = 256;
    constexpr int kFieldsPerGlyph = 8;
    charCode.reserve(kGlyphCount);
    kerning.reserve(kGlyphCount);
    bitmapWidth.reserve(kGlyphCount);
    bitmapHeight.reserve(kGlyphCount);
    originX.reserve(kGlyphCount);
    originY.reserve(kGlyphCount);
    tsftPos.reserve(kGlyphCount);
    runtimeData.reserve(kGlyphCount);

    for (int i = 0; i < kGlyphCount; ++i)
    {
        int base = 2 + (kFieldsPerGlyph * i);
        charCode.emplace_back(    "char code [" + to_string(i) + "]",             base + 0);
        kerning.emplace_back(     "kerning [" + to_string(i) + "]",               base + 1);
        bitmapWidth.emplace_back( "bitmap width [" + to_string(i) + "]",          base + 2);
        bitmapHeight.emplace_back("bitmap height [" + to_string(i) + "]",         base + 3);
        originX.emplace_back(     "x origin [" + to_string(i) + "]",              base + 4);
        originY.emplace_back(     "y origin [" + to_string(i) + "]",              base + 5);
        tsftPos.emplace_back(     "TSFT position [" + to_string(i) + "]",         base + 6);
        runtimeData.emplace_back( "runtime data [" + to_string(i) + "] (unused)", base + 7);
    }

    for (size_t i = 0; i < size_t(kGlyphCount); ++i)
        fields_.insert(fields_.end(), {&charCode[i], &kerning[i], &bitmapWidth[i], &bitmapHeight[i],
                                       &originX[i], &originY[i], &tsftPos[i], &runtimeData[i]});
}

unique_ptr<Template> TemplateTSGA::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTSGA>(instName, dataFormat);
}

uint32_t TemplateTSGA::pixelDataExtent()
{
    // PS2 TSFT uses 2 bits per pixel, thus "tsftPos" counts in 2-bit (quarter-byte) increments
    // Find the maximum 2-bit extent across all glyph slots, then ceiling-divide to whole bytes
    uint32_t maxQuarterBytes = 0;
    for (size_t i = 0; i < 256; ++i)
    {
        uint32_t end = tsftPos[i].val() + (static_cast<uint32_t>(bitmapWidth[i].val()) * bitmapHeight[i].val());
        maxQuarterBytes = max(maxQuarterBytes, end);
    }
    return (maxQuarterBytes + 3) / 4;
}

GlyphInfo TemplateTSGA::glyphAt(int i)
{
    size_t si = static_cast<size_t>(i);
    return {charCode[si].val(), bitmapWidth[si].val(), bitmapHeight[si].val(),
            originX[si].val(), originY[si].val(), tsftPos[si].val()};
}

/************************** TemplateDisplay **************************/
namespace TemplateDisplay
{

// Base64-encodes rgbaData and sends it to stdout as a kitty graphics protocol APC escape sequence, split into chunks of at most 4096 bytes.
// firstChunkKeys: comma-separated control keys for the first chunk, excluding the 'm' key.
// isAnimFrame: if true, continuation chunks carry the 'a=f' key, which is required by the protocol for animation frame data.
void sendKittyChunkedImage(const vector<uint8_t> & rgbaData, const string & firstChunkKeys, bool isAnimFrame)
{
    static const char b64Chars[] = "ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789+/";

    string b64Data;
    b64Data.reserve(((rgbaData.size() + 2) / 3) * 4);
    for (size_t i = 0; i < rgbaData.size(); i += 3)
    {
        uint8_t b0 = rgbaData[i];
        uint8_t b1 = (i + 1 < rgbaData.size()) ? rgbaData[i + 1] : 0;
        uint8_t b2 = (i + 2 < rgbaData.size()) ? rgbaData[i + 2] : 0;
        b64Data += b64Chars[b0 >> 2];
        b64Data += b64Chars[((b0 & 0x03) << 4) | (b1 >> 4)];
        b64Data += (i + 1 < rgbaData.size()) ? b64Chars[((b1 & 0x0F) << 2) | (b2 >> 6)] : '=';
        b64Data += (i + 2 < rgbaData.size()) ? b64Chars[b2 & 0x3F] : '=';
    }

    constexpr size_t kMaxChunkSize = 4096;
    size_t offset = 0;
    bool firstChunk = true;
    do
    {
        string chunk = b64Data.substr(offset, kMaxChunkSize);
        offset += chunk.size();
        bool isLast = (offset >= b64Data.size());
        string seq = "\033_G";
        if (firstChunk)
            seq += firstChunkKeys + format(",m={};", isLast ? 0 : 1);
        else if (isAnimFrame)
            seq += format("a=f,m={};", isLast ? 0 : 1);
        else
            seq += format("m={};", isLast ? 0 : 1);
        seq += chunk;
        seq += "\033\\";
        (void)fwrite(seq.data(), 1, seq.size(), stdout);
        firstChunk = false;
    }
    while (offset < b64Data.size());
}

// Builds the bytes of an (A)PNG file in memory and returns them. Each element of "frames" is a w*h*4-byte RGBA buffer. "delayNum" and
// "delayDen" give the inter-frame delay in seconds. Returns an empty vector on failure. The actual writing to disk is left to the caller so
// that user-facing exports can go through DiskItem (which enforces the file name and overwrite policies) while temp-file display paths can
// write the bytes however they need.
vector<uint8_t> buildAnimatedPNG(const vector<vector<uint8_t>> & frames, size_t w, size_t h, uint16_t delayNum, uint16_t delayDen)
{
    vector<uint8_t> out;
    if (frames.empty() || w == 0 || h == 0)
        return out; // an empty result signals failure

    // CRC32 lookup table (IEEE polynomial), computed once on the first call
    static const auto crc32Table = []()
    {
        array<uint32_t, 256> t = {};
        for (uint32_t n = 0; n < 256; ++n)
        {
            uint32_t c = n;
            for (int k = 0; k < 8; ++k)
                c = (c & 1) ? 0xEDB88320u ^ (c >> 1) : c >> 1;
            t[n] = c;
        }
        return t;
    }();

    // Append one PNG/APNG chunk to "out": [length (BE)][type][data][CRC32 (BE)]
    auto writeChunk = [&](const char * type, const uint8_t * data, uint32_t len)
    {
        auto append32BE = [&](uint32_t v)
        {
            out.push_back(uint8_t(v >> 24)); out.push_back(uint8_t(v >> 16));
            out.push_back(uint8_t(v >> 8));  out.push_back(uint8_t(v));
        };
        append32BE(len);
        out.insert(out.end(), type, type + 4);
        if (len > 0)
            out.insert(out.end(), data, data + len);
        uint32_t crc = ~uint32_t(0);
        const uint8_t * typeBytes = reinterpret_cast<const uint8_t *>(type);
        for (int i = 0; i < 4; ++i)
            crc = crc32Table[(crc ^ typeBytes[i]) & 0xFF] ^ (crc >> 8);
        for (uint32_t i = 0; i < len; ++i)
            crc = crc32Table[(crc ^ data[i]) & 0xFF] ^ (crc >> 8);
        append32BE(~crc);
    };

    // Wrap rawData in a valid zlib stream using DEFLATE stored blocks (no compression)
    auto compress = [](const vector<uint8_t> & rawData) -> vector<uint8_t>
    {
        vector<uint8_t> out;
        // zlib header: CMF=0x78 (deflate, 32K window), FLG=0x01 (fcheck; (0x78<<8|0x01) % 31 == 0)
        out.push_back(0x78);
        out.push_back(0x01);
        // DEFLATE stored blocks: 1 flag byte (BFINAL|BTYPE) + 2-byte LEN + 2-byte NLEN (one's complement) + data
        size_t remaining = rawData.size();
        size_t offset = 0;
        do
        {
            size_t blockLen  = min(remaining, size_t(65535));
            remaining -= blockLen;
            out.push_back(remaining == 0 ? 0x01 : 0x00); // BFINAL=1 on last block, BTYPE=00 (stored)
            out.push_back(uint8_t(blockLen));
            out.push_back(uint8_t(blockLen >> 8));
            uint16_t nlen = static_cast<uint16_t>(~static_cast<uint16_t>(blockLen));
            out.push_back(uint8_t(nlen));
            out.push_back(uint8_t(nlen >> 8));
            out.insert(out.end(), rawData.begin() + static_cast<ptrdiff_t>(offset), rawData.begin() + static_cast<ptrdiff_t>(offset + blockLen));
            offset += blockLen;
        }
        while (remaining > 0);
        // Adler-32 checksum over the uncompressed data, stored big-endian
        uint32_t s1 = 1, s2 = 0;
        for (uint8_t b : rawData) {s1 = (s1 + b) % 65521; s2 = (s2 + s1) % 65521;}
        uint32_t adler = (s2 << 16) | s1;
        out.push_back(uint8_t(adler >> 24)); out.push_back(uint8_t(adler >> 16));
        out.push_back(uint8_t(adler >> 8));  out.push_back(uint8_t(adler));
        return out;
    };

    // PNG signature
    const uint8_t sig[8] = {0x89, 0x50, 0x4E, 0x47, 0x0D, 0x0A, 0x1A, 0x0A};
    out.insert(out.end(), sig, sig + 8);

    // IHDR: width(4), height(4), bit depth=8, color type=6 (RGBA), compression=0, filter=0, interlace=0
    {
        uint8_t ihdr[13] = {};
        ihdr[0] = uint8_t(w >> 24); ihdr[1] = uint8_t(w >> 16); ihdr[2] = uint8_t(w >> 8); ihdr[3] = uint8_t(w);
        ihdr[4] = uint8_t(h >> 24); ihdr[5] = uint8_t(h >> 16); ihdr[6] = uint8_t(h >> 8); ihdr[7] = uint8_t(h);
        ihdr[8] = 8; ihdr[9] = 6; // 8-bit depth, RGBA color type
        writeChunk("IHDR", ihdr, 13);
    }

    // acTL: num_frames(4), num_plays=0 (infinite)(4)
    {
        uint32_t numFrames = uint32_t(frames.size());
        uint8_t actl[8] = {};
        actl[0] = uint8_t(numFrames >> 24); actl[1] = uint8_t(numFrames >> 16);
        actl[2] = uint8_t(numFrames >> 8);  actl[3] = uint8_t(numFrames);
        writeChunk("acTL", actl, 8);
    }

    uint32_t seqNum = 0;
    for (size_t fi = 0; fi < frames.size(); ++fi)
    {
        // fcTL: seq(4), width(4), height(4), x_off(4), y_off(4), delay_num(2), delay_den(2), dispose_op(1), blend_op(1)
        {
            uint8_t fctl[26] = {};
            fctl[0] = uint8_t(seqNum >> 24); fctl[1] = uint8_t(seqNum >> 16);
            fctl[2] = uint8_t(seqNum >> 8);  fctl[3] = uint8_t(seqNum); ++seqNum;
            fctl[4] = uint8_t(w >> 24); fctl[5] = uint8_t(w >> 16); fctl[6] = uint8_t(w >> 8); fctl[7] = uint8_t(w);
            fctl[8] = uint8_t(h >> 24); fctl[9] = uint8_t(h >> 16); fctl[10] = uint8_t(h >> 8); fctl[11] = uint8_t(h);
            // x_offset and y_offset are zero (bytes 12-19 already zeroed by {})
            fctl[20] = uint8_t(delayNum >> 8); fctl[21] = uint8_t(delayNum);
            fctl[22] = uint8_t(delayDen >> 8); fctl[23] = uint8_t(delayDen);
            // dispose_op=0 (APNG_DISPOSE_OP_NONE), blend_op=0 (APNG_BLEND_OP_SOURCE) — already zeroed
            writeChunk("fcTL", fctl, 26);
        }

        // Build filter-byte-prepended row data: filter type 0 (None) before each scanline
        vector<uint8_t> filtered;
        filtered.reserve((1 + w * 4) * h);
        for (size_t y = 0; y < h; ++y)
        {
            filtered.push_back(0); // filter type: None
            size_t rowStart = y * w * 4;
            filtered.insert(filtered.end(), frames[fi].begin() + static_cast<ptrdiff_t>(rowStart),
                                            frames[fi].begin() + static_cast<ptrdiff_t>(rowStart + (w * 4)));
        }
        vector<uint8_t> compressed = compress(filtered);

        if (fi == 0)
        {
            // The first frame's pixel data is placed in a standard IDAT chunk (per the APNG spec)
            writeChunk("IDAT", compressed.data(), uint32_t(compressed.size()));
        }
        else
        {
            // Subsequent frames go in fdAT chunks, which prepend a 4-byte sequence number to the data
            vector<uint8_t> fdat;
            fdat.reserve(4 + compressed.size());
            fdat.push_back(uint8_t(seqNum >> 24)); fdat.push_back(uint8_t(seqNum >> 16));
            fdat.push_back(uint8_t(seqNum >> 8));  fdat.push_back(uint8_t(seqNum)); ++seqNum;
            fdat.insert(fdat.end(), compressed.begin(), compressed.end());
            writeChunk("fdAT", fdat.data(), uint32_t(fdat.size()));
        }
    }

    writeChunk("IEND", nullptr, 0);
    return out;
}

// Writes an (A)PNG file to "path" by building the bytes with buildAnimatedPNG() and writing them out. This raw-write path is used by the
// terminal-display code for the temporary files it creates; user-facing exports build the bytes and write them through DiskItem instead.
bool writeAnimatedPNG(const vector<vector<uint8_t>> & frames, size_t w, size_t h,
                      uint16_t delayNum, uint16_t delayDen, const string & path)
{
    vector<uint8_t> png = buildAnimatedPNG(frames, w, h, delayNum, delayDen);
    if (png.empty())
        return false;

    FILE * fp = nullptr;
#if MAC
    fp = fopen(path.c_str(), "wb");
#elif WIN
    fopen_s(&fp, path.c_str(), "wb");
#endif
    if (!fp)
        return false;

    bool ok = (fwrite(png.data(), 1, png.size(), fp) == png.size());
    (void)fclose(fp);
    return ok;
}

// Displays an RGBA image in the terminal using the available graphics protocol, or by opening it in the default OS image viewer.
// For Kitty, "rgba" is scaled up by displayScale for visibility; for the fallback path, it is written to a PNG at native scale.
void displayStaticRGBA(const vector<uint8_t> & rgba, size_t w, size_t h,
                       TerminalImageSupport termSupport, int displayScale, const string & instName)
{
    int effectiveScale = max(1, displayScale);

    if (termSupport == TerminalImageSupport::Kitty)
    {
        size_t outW = w * static_cast<size_t>(effectiveScale);
        size_t outH = h * static_cast<size_t>(effectiveScale);
        vector<uint8_t> scaled;
        scaled.reserve(outW * outH * 4);
        for (size_t y = 0; y < h; ++y)
            for (int ry = 0; ry < effectiveScale; ++ry)
                for (size_t x = 0; x < w; ++x)
                {
                    size_t src = ((y * w) + x) * 4;
                    for (int rx = 0; rx < effectiveScale; ++rx)
                    {
                        scaled.push_back(rgba[src]);
                        scaled.push_back(rgba[src + 1]);
                        scaled.push_back(rgba[src + 2]);
                        scaled.push_back(rgba[src + 3]);
                    }
                }
        // We write directly to stdout via fwrite() rather than through cout so that the word-wrap
        // streambuf installed in Main does not interfere with the binary escape sequences.
        // f=32 specifies 32-bit RGBA pixel format
        sendKittyChunkedImage(scaled, format("a=T,f=32,s={},v={},q=2", outW, outH), false);
        (void)fwrite("\n", 1, 1, stdout);
        (void)fflush(stdout);
    }
    else
    {
        // Fallback: write a PNG file at native scale and open it with the default OS image viewer. We ignore any user-specified
        // scale in this case because the user can adjust the image viewer's zoom as they desire, and it's not a good idea to
        // write even a temporary file to disk that has been modified (scaled up) because the user might copy it somewhere and,
        // depending on the image, it may not be clear that it is not at 1:1 scale.
#if MAC
        char tmpTemplate[] = "/tmp/kanabo_XXXXXX";
        int tmpFd = mkstemp(tmpTemplate);
        if (tmpFd == -1)
        {
            cerr << "Error: Failed to create a temporary file for instance " << quoted(instName) << ".\n";
            return;
        }
        string tmpFilePath = string(tmpTemplate) + ".png";
        if (rename(tmpTemplate, tmpFilePath.c_str()) != 0)
        {
            close(tmpFd);
            cerr << "Error: Failed to rename temporary file for instance " << quoted(instName) << ".\n";
            return;
        }
        close(tmpFd);
#elif WIN
        char * tmpBasePath = _tempnam(nullptr, "kanabo_");
        if (!tmpBasePath)
        {
            cerr << "Error: Failed to generate a temporary file path for instance " << quoted(instName) << ".\n";
            return;
        }
        string tmpFilePath = string(tmpBasePath) + ".png";
        free(tmpBasePath);
#endif
        vector<vector<uint8_t>> singleFrame {rgba};
        if (!writeAnimatedPNG(singleFrame, w, h, 0, 1, tmpFilePath))
        {
            cerr << "Error: Failed to write PNG file for instance " << quoted(instName) << ".\n";
            return;
        }

        // Open the image for display: use wezterm imgcat for inline display in WezTerm on Windows,
        // or the default OS image viewer otherwise
#if MAC
        cout << "Terminal does not support inline image display; opening image in default viewer instead.\n";
        cout << "Temporary image file: " << tmpFilePath << "\n";
        system(("open \"" + tmpFilePath + "\"").c_str());
#elif WIN
        if (termSupport == TerminalImageSupport::WezTerm)
        {
            // Scale the displayed image to the user's requested display scale
            string imgcatCmd = format("wezterm imgcat --width {}px --height {}px \"{}\"",
                                      w * static_cast<size_t>(effectiveScale),
                                      h * static_cast<size_t>(effectiveScale),
                                      tmpFilePath);
            system(imgcatCmd.c_str());
            remove(tmpFilePath.c_str());
        }
        else
        {
            cout << "Terminal does not support inline image display; opening image in default viewer instead.\n";
            cout << "Temporary image file: " << tmpFilePath << "\n";
            // Use explorer.exe to open the file with its default viewer; this is more reliable than
            // ShellExecuteA (which requires COM initialization) or system("start ...") from a console process
            string openCmd = "explorer.exe \"" + tmpFilePath + "\"";
            system(openCmd.c_str());
        }
#endif
    }
}

} // namespace TemplateDisplay

/**************************** TemplateTXAN ****************************/
TemplateTXAN::TemplateTXAN(string instName, Format dataFormat)
            : Template("TXAN", std::move(instName), dataFormat),
              padding1("padding 1",            2, true, false),
              ticksPerFrame("ticks per frame", 3),
              tpfUnused1("TPF low (unused)",   4),
              tpfUnused2("TPF range (unused)", 5),
              padding2("padding 2",            6, true, false),
              arraySize("frame count",         7)
{
    hasLinks_ = true;
    certified_ = true;

    fwvlaSizeOffset_ = {0x1C, 32};

    fields_.insert(fields_.end(), {&padding1, &ticksPerFrame, &tpfUnused1, &tpfUnused2, &padding2, &arraySize});

    padding1.setFixedSize(12);
    padding2.setFixedSize(2);
}

unique_ptr<Template> TemplateTXAN::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTXAN>(instName, dataFormat);
}

void TemplateTXAN::createFWVarArray(int32_t n)
{
    txmp.reserve(static_cast<size_t>(n));

    for (int32_t i = 0; i < n; ++i)
    {
        txmp.emplace_back("texture name [" + to_string(i) + "]", 8 + i); // last field added by TemplateTXAN constructor was order 7
        fields_.insert(fields_.end(), {&txmp[static_cast<size_t>(i)]});
    }
}

// Returns the non-null TXMP frames from the txmps array (skipping the always-empty first slot). The first frame of the animation is the
// inciting TXMP instance that holds the linkTXAN, so it is not in this array and is not returned here.
vector<TemplateTXMP *> TemplateTXAN::getAdditionalFrames(const vector<unique_ptr<Template>> & instances)
{
    vector<TemplateTXMP *> frames;
    for (auto & link : txmp)
    {
        uint32_t idx = link.val();
        if (idx == 0)
            continue; // null/empty slot — txmps[0] is always null per the format spec
        if (idx >= instances.size() || !instances[idx])
        {
            cerr << "Error: getAdditionalFrames(): Texture link index " << idx << " in TXAN instance " << quoted(name_)
                 << " is out of bounds.\n";
            continue;
        }
        TemplateTXMP * txmpInst = dynamic_cast<TemplateTXMP *>(instances[idx].get());
        if (!txmpInst)
        {
            cerr << "Error: getAdditionalFrames(): Instance at index " << idx << " linked from TXAN instance " << quoted(name_)
                 << " is not a TXMP instance.\n";
            continue;
        }
        frames.push_back(txmpInst);
    }
    return frames;
}

// Returns the per-frame display delay in milliseconds, derived from ticksPerFrame at Oni's 60 Hz game clock
int TemplateTXAN::frameDelayMs()
{
    int tpf = max(1, static_cast<int>(ticksPerFrame.val()));
    return (tpf * 1000 + 30) / 60;
}

// Fills "out" with scaled RGBA data for each frame in "frames"
bool TemplateTXAN::collectRGBAFrames(const vector<TemplateTXMP *> & frames, int effectiveScale,
                        const string & instName, vector<vector<uint8_t>> & out)
{
    out.reserve(frames.size());
    for (size_t i = 0; i < frames.size(); ++i)
    {
        vector<uint8_t> rgba = frames[i]->getScaledRGBA(effectiveScale);
        if (rgba.empty())
        {
            cerr << "Error: Failed to get pixel data for frame " << (i + 1) << " of animated texture " << quoted(instName) << ".\n";
            return false;
        }
        out.push_back(rgba);
    }
    return true;
}

// Streams all frames in "frames" to the Kitty terminal as a looping animation
void TemplateTXAN::sendKittyAnimatedFrames(const vector<TemplateTXMP *> & frames, int effectiveScale,
                              size_t outW, size_t outH, int gapMs, const string & instName)
{
    // Transmit and place the first frame as the base image; I=1 (image number) ensures a fresh
    // image each time without requiring us to read back the terminal-assigned id (suppressed with q=2)
    vector<uint8_t> frame0Rgba = frames[0]->getScaledRGBA(effectiveScale);
    if (frame0Rgba.empty())
        return;
    TemplateDisplay::sendKittyChunkedImage(frame0Rgba, format("a=T,f=32,s={},v={},I=1,q=2", outW, outH), false);

    // Set the gap for the root frame, which defaults to zero and must be set explicitly
    string gapSeq = format("\033_Ga=a,I=1,r=1,z={},q=2\033\\", gapMs);
    (void)fwrite(gapSeq.data(), 1, gapSeq.size(), stdout);

    // Transmit the remaining frames as animation frames; each carries its own gap
    for (size_t i = 1; i < frames.size(); ++i)
    {
        vector<uint8_t> frameRgba = frames[i]->getScaledRGBA(effectiveScale);
        if (frameRgba.empty())
        {
            cerr << "Error: Failed to get pixel data for frame " << (i + 1) << " of animated texture " << quoted(instName) << ".\n";
            continue;
        }
        TemplateDisplay::sendKittyChunkedImage(frameRgba, format("a=f,f=32,s={},v={},I=1,z={},q=2", outW, outH, gapMs), true);
    }

    // Start terminal-driven looping animation (s=3: loop continuously, v=1: infinite loops)
    string startSeq = "\033_Ga=a,I=1,s=3,v=1,q=2\033\\";
    (void)fwrite(startSeq.data(), 1, startSeq.size(), stdout);

    (void)fwrite("\n", 1, 1, stdout);
    (void)fflush(stdout);
}

// Writes "rgbaFrames" as an animated PNG to a temp file and displays it inline via wezterm imgcat
bool TemplateTXAN::displayViaWezTermAPNG(const vector<vector<uint8_t>> & rgbaFrames, size_t outW, size_t outH,
                            uint16_t delayMs, const string & instName)
{
#if MAC
    char tmpTemplate[] = "/tmp/kanabo_XXXXXX";
    int tmpFd = mkstemp(tmpTemplate);
    if (tmpFd == -1)
    {
        cerr << "Error: Failed to create a temporary file for animated texture " << quoted(instName) << ".\n";
        return false;
    }
    string tmpPath = string(tmpTemplate) + ".png";
    if (rename(tmpTemplate, tmpPath.c_str()) != 0)
    {
        close(tmpFd);
        cerr << "Error: Failed to rename temporary file for animated texture " << quoted(instName) << ".\n";
        return false;
    }
    close(tmpFd);
#elif WIN
    char * tmpBase = _tempnam(nullptr, "kanabo_");
    if (!tmpBase)
        return false;
    string tmpPath = string(tmpBase) + ".png";
    free(tmpBase);
#endif
    if (!TemplateDisplay::writeAnimatedPNG(rgbaFrames, outW, outH, delayMs, 1000, tmpPath))
    {
        cerr << "Error: Failed to write animated PNG for animated texture " << quoted(instName) << ".\n";
        return false;
    }
    string cmd = format("wezterm imgcat --width {}px --height {}px \"{}\"", outW, outH, tmpPath);
    system(cmd.c_str());
    (void)remove(tmpPath.c_str());
    return true;
}

// Writes "rgbaFrames" as an animated PNG to a temp file and then creates an HTML wrapper containing the APNG, which allows us to guarantee that
// the APNG will open in the system's web browser (since this is the most reliable playback tool for APNG)
bool TemplateTXAN::displayViaBrowserAPNG(const vector<vector<uint8_t>> & rgbaFrames, size_t outW, size_t outH,
                            uint16_t delayMs, const string & instName)
{
    string pngPath, htmlPath;
#if MAC
    char tmpTemplate[] = "/tmp/kanabo_XXXXXX";
    int tmpFd = mkstemp(tmpTemplate);
    if (tmpFd == -1)
    {
        cerr << "Error: Failed to create a temporary file for animated texture " << quoted(instName) << ".\n";
        return false;
    }
    pngPath  = string(tmpTemplate) + ".png";
    htmlPath = string(tmpTemplate) + ".html";
    if (rename(tmpTemplate, pngPath.c_str()) != 0)
    {
        close(tmpFd);
        cerr << "Error: Failed to rename temporary file for animated texture " << quoted(instName) << ".\n";
        return false;
    }
    close(tmpFd);
#elif WIN
    char * tmpBase = _tempnam(nullptr, "kanabo_");
    if (!tmpBase)
    {
        cerr << "Error: Failed to generate a temporary file path for animated texture " << quoted(instName) << ".\n";
        return false;
    }
    pngPath  = string(tmpBase) + ".png";
    htmlPath = string(tmpBase) + ".html";
    free(tmpBase);
#endif
    if (!TemplateDisplay::writeAnimatedPNG(rgbaFrames, outW, outH, delayMs, 1000, pngPath))
    {
        cerr << "Error: Failed to write animated PNG for animated texture " << quoted(instName) << ".\n";
        return false;
    }
#if MAC
    size_t sep = pngPath.rfind('/');
#elif WIN
    size_t sep = pngPath.rfind('\\');
#endif
    string pngFilename = (sep != string::npos) ? pngPath.substr(sep + 1) : pngPath;
    string htmlContent = "<!DOCTYPE html><html><head><meta charset=\"utf-8\"></head>"
                         "<body style=\"margin:0;background:#000;display:flex;align-items:center;"
                         "justify-content:center;min-height:100vh\">"
                         "<img src=\"" + pngFilename + "\"></body></html>";
#if MAC
    FILE * htmlFile = fopen(htmlPath.c_str(), "w");
#elif WIN
    FILE * htmlFile = nullptr;
    fopen_s(&htmlFile, htmlPath.c_str(), "w");
#endif
    if (!htmlFile)
    {
        cerr << "Error: Failed to write HTML file " << quoted(htmlPath) << " for animated texture " << quoted(instName) << ".\n";
        return false;
    }
    (void)fwrite(htmlContent.c_str(), 1, htmlContent.size(), htmlFile);
    (void)fclose(htmlFile);
    cerr << "Advisory: Terminal does not support inline image display; opening animation in default web browser instead.\n";
    cout << "Temporary PNG file: " << pngPath << "\n";
    cout << "Temporary HTML file: " << htmlPath << "\n";
#if MAC
    system(("open \"" + htmlPath + "\"").c_str());
#elif WIN
    system(("explorer.exe \"" + htmlPath + "\"").c_str());
#endif
    return true;
}

void TemplateTXAN::displayViaTerminal(TerminalImageSupport termSupport, int displayScale,
                                      const vector<unique_ptr<Template>> & instances)
{
    // Resolve each TXMP link to its instance pointer
    vector<TemplateTXMP *> frames;
    for (auto & link : txmp)
    {
        uint32_t idx = link.val();
        if (idx == 0)
            continue; // null link
        if (idx >= instances.size() || !instances[idx])
        {
            cerr << "Error: displayViaTerminal(): Texture link index " << idx << " in TXAN instance " << quoted(name_)
                 << " is out of bounds.\n";
            continue;
        }
        TemplateTXMP * txmpInst = dynamic_cast<TemplateTXMP *>(instances[idx].get());
        if (!txmpInst)
        {
            cerr << "Error: displayViaTerminal(): Instance at index " << idx << " linked from TXAN instance " << quoted(name_)
                 << " is not a TXMP instance.\n";
            continue;
        }
        frames.push_back(txmpInst);
    }

    if (frames.empty())
    {
        cerr << "Error: No valid texture frames found for TXAN instance " << quoted(name_) << ".\n";
        return;
    }

    // For a single frame, delegate directly to the TXMP's display method
    if (frames.size() == 1)
    {
        frames[0]->displayViaTerminal(termSupport, displayScale);
        return;
    }

    int effectiveScale  = (displayScale > 1) ? displayScale : 1;
    size_t outW = static_cast<size_t>(frames[0]->width())  * static_cast<size_t>(effectiveScale);
    size_t outH = static_cast<size_t>(frames[0]->height()) * static_cast<size_t>(effectiveScale);

    // Compute per-frame delay: Oni's game clock runs at 60 Hz, so one tick = 1000/60 ms
    int tpf   = max(1, static_cast<int>(ticksPerFrame.val()));
    int gapMs = (tpf * 1000 + 30) / 60; // rounded integer division

    if (termSupport == TerminalImageSupport::Kitty)
    {
        sendKittyAnimatedFrames(frames, effectiveScale, outW, outH, gapMs, name_);
    }
    else
    {
        // WezTerm: write an animated PNG to a temp file and display it inline via wezterm imgcat
        if (termSupport == TerminalImageSupport::WezTerm && frames.size() > 1)
        {
            vector<vector<uint8_t>> rgbaFrames;
            if (collectRGBAFrames(frames, effectiveScale, name_, rgbaFrames)
                && displayViaWezTermAPNG(rgbaFrames, outW, outH, uint16_t(gapMs), name_))
                return;
        }

        // Terminal does not support inline image display; write an animated PNG and an HTML wrapper to disk, then open the HTML in the default
        // web browser so the animation can be viewed
        if (termSupport == TerminalImageSupport::None && frames.size() > 1)
        {
            vector<vector<uint8_t>> rgbaFrames;
            if (collectRGBAFrames(frames, effectiveScale, name_, rgbaFrames)
                && displayViaBrowserAPNG(rgbaFrames, outW, outH, uint16_t(gapMs), name_))
                return;
        }
        // Fallback: display the first frame only, since non-Kitty terminals cannot animate
        frames[0]->displayViaTerminal(termSupport, displayScale);
    }
}

bool TemplateTXAN::exportToPNG(const string & dir, const string & stem, const vector<unique_ptr<Template>> & instances)
{
    // Resolve TXMP links to frame pointers
    vector<TemplateTXMP *> frames;
    for (auto & link : txmp)
    {
        uint32_t idx = link.val();
        if (idx == 0)
            continue;
        if (idx >= instances.size() || !instances[idx])
        {
            cerr << "Error: exportToPNG(): Texture link index " << idx << " in TXAN instance " << quoted(name_) << " is out of bounds.\n";
            continue;
        }
        TemplateTXMP * txmpPtr = dynamic_cast<TemplateTXMP *>(instances[idx].get());
        if (!txmpPtr)
        {
            cerr << "Error: exportToPNG(): Instance at index " << idx << " linked from TXAN instance " << quoted(name_)
                 << " is not a TXMP instance.\n";
            continue;
        }
        frames.push_back(txmpPtr);
    }

    if (frames.empty())
    {
        cerr << "Error: No valid texture frames found for TXAN instance " << quoted(name_) << ".\n";
        return false;
    }

    // The first animation frame (the TXMP that holds the TXAN link) is not stored in this TXAN's txmp array
    // and is therefore not included in this export. To export the full animation, filter for that TXMP instead.
    cout << "Note: exporting TXAN " << quoted(name_) << " directly will omit the first animation frame. "
            "Export the linked TXMP instance instead to get the complete animation.\n";

    if (frames.size() == 1)
        return frames[0]->exportToPNG(dir, stem);

    size_t outW = static_cast<size_t>(frames[0]->width());
    size_t outH = static_cast<size_t>(frames[0]->height());
    int tpf = max(1, static_cast<int>(ticksPerFrame.val()));
    uint16_t delayMs = static_cast<uint16_t>((tpf * 1000 + 30) / 60);

    vector<vector<uint8_t>> rgbaFrames;
    if (!collectRGBAFrames(frames, 1, name_, rgbaFrames))
        return false;

    vector<uint8_t> png = TemplateDisplay::buildAnimatedPNG(rgbaFrames, outW, outH, delayMs, 1000);
    if (png.empty())
    {
        cerr << "Error: Failed to build APNG data for instance " << quoted(name_) << ".\n";
        return false;
    }
    // DiskItem sanitizes the file name and enforces the program-wide overwrite policy
    return DiskItem(dir, stem, "png", ReadingMode::None, ReportingMode::ErrorsOnly).write(png) == WriteResult::Written;
}

/**************************** TemplateTXCA ****************************/
TemplateTXCA::TemplateTXCA(string instName, Format dataFormat)
            : Template("TXCA", std::move(instName), dataFormat),
              padding("padding",                2, true, false),
              arraySize("texture coord count",  3),
              trailingPadding("runtime coords", 1000000, true, false) // high order ensures it sorts after all array elements
{
    certified_ = true;

    fwvlaSizeOffset_ = {0x1C, 32};

    fields_.insert(fields_.end(), {&padding, &arraySize});

    padding.setFixedSize(20);
    trailingPadding.setFixedSize(480);
}

unique_ptr<Template> TemplateTXCA::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTXCA>(instName, dataFormat);
}

void TemplateTXCA::createFWVarArray(int32_t n)
{
    const size_t sz = static_cast<size_t>(n);
    coordU.reserve(sz);
    coordV.reserve(sz);

    int s = static_cast<int>(fields_.size()) + 1; // resume adding fields after fixed header fields
    int nf = 2; // number of fields per array element: u, v
    for (int32_t i = 0; i < n; ++i)
    {
        coordU.emplace_back("u coordinate [" + to_string(i) + "]", s + (nf * i) + 0);
        coordV.emplace_back("v coordinate [" + to_string(i) + "]", s + (nf * i) + 1);
    }

    for (size_t i = 0; i < sz; ++i)
        fields_.insert(fields_.end(), {&coordU[i], &coordV[i]});

    fields_.push_back(&trailingPadding);
}

/**************************** TemplateTXMP ****************************/
TemplateTXMP::TemplateTXMP(string instName, Format dataFormat)
            : Template("TXMP", std::move(instName), dataFormat),
              nameUnused("name (unused)",                2, true, false),
              textureFlags("texture format flags",       3),
              texWidth("width",                          4),
              texHeight("height",                        5),
              paletteNum("palette index (PS2)",          kPS2Only(6)),
              texFormat("compression format",            7),
              linkTXAN("TXAN link",                      8),
              linkEnvmap("envmap",                       9),
              pixelOffsetRaw("pixel data offset (raw)",  10),
              pixelOffsetSep("pixel data offset (sep)",  11),
              materialType("material type (runtime)",    kMacAndPS2(12), true, false),
              OGLname("OpenGL name (runtime)",           13, false, false),
              OGLdirty("padding/OpenGL flags (runtime)", 14, false, false),
              paletteData("palette data (PS2)"),
              pixelBlob("pixel data",                    1)
{
    // Set callback flags
    hasLinks_ = true;
    hasAuxData_ = true;
    if (dataFormat == Format::PS2)
        hasPaletteData_ = true;
    certified_ = true;

    fields_.insert(fields_.end(), {&nameUnused, &textureFlags, &texWidth, &texHeight, &paletteNum, &texFormat, &linkTXAN, &linkEnvmap,
                                   &pixelOffsetRaw, &pixelOffsetSep, &materialType, &OGLname, &OGLdirty});
    fieldsAux_.insert(fieldsAux_.end(), {&pixelBlob});

    nameUnused.setFullSize(128);

    materialType.setFixedSize(4);

    textureFlagValues =
    {
        {texHasMipMaps,           0x1},
        {texTrilinear,            0x2},
        {texClampHoriz,           0x4},
        {texClampVert,            0x8},
        {texPixelType,           0x10},
        {texOffscreen,           0x20},
        {texAnimPingPong,        0x40},
        {texAnimRandomOrder,     0x80},
        {texAnimRandomStart,    0x100},
        {texHasEnvMap,          0x200},
        {texAdditiveBlend,      0x400},
        {texSelfIlluminant,     0x800},
        {texLittleEndian,      0x1000},
        {texPrepared,          0x2000},
        {texAnimNone,          0x4000},
        {texEffectPhaseShield, 0x8000},
        {texEffectPhaseCloak, 0x10000},
        {texEffectBossShield, 0x20000}
    };
    textureFlagNames =
    {
        {texHasMipMaps,        "has mipmaps"},
        {texTrilinear,         "trilinear candidate"},
        {texClampHoriz,        "horiz. clamp"},
        {texClampVert,         "vert. clamp"},
        {texPixelType,         "pixel type (unused)"},
        {texOffscreen,         "offscreen only"},
        {texAnimPingPong,      "animation type: pingpong"},
        {texAnimRandomOrder,   "animation type: random order"},
        {texAnimRandomStart,   "animation type: random start"},
        {texHasEnvMap,         "has envmap"},
        {texAdditiveBlend,     "additive blending"},
        {texSelfIlluminant,    "self-illuminant"},
        {texLittleEndian,      "little-endian"},
        {texPrepared,          "prepared (runtime)"},
        {texAnimNone,          "animation type: none"},
        {texEffectPhaseShield, "special effect: phase shield"},
        {texEffectPhaseCloak,  "special effect: phase cloak"},
        {texEffectBossShield,  "special effect: boss shield"}
    };
    textureFlags.setFlagValueMap(&textureFlagValues);
    textureFlags.setFlagNameMap(&textureFlagNames);

    textureFormatValues =
    {
        {texFmtARGB4444,     0},
        {texFmtRGB555,       1},
        {texFmtARGB1555,     2},
        {texFmtI8,           3},
        {texFmtI1,           4},
        {texFmtA8,           5},
        {texFmtA4I4,         6},
        {texFmtARGB8888,     7},
        {texFmtRGB888,       8},
        {texFmtDXT1,         9},
        {texFmtRGB_Bytes,   10},
        {texFmtRGBA_Bytes,  11},
        {texFmtRGBA5551,    12},
        {texFmtRGBA4444,    13},
        {texFmtRGB565,      14},
        {texFmtABGR1555,    15},
        {texFmtRGB888PS2,   16},
        {texFmtARGB8888PS2, 17}
    };
    textureFormatNames =
    {
        {texFmtARGB4444,    "ARGB4444"},
        {texFmtRGB555,      "RGB555"},
        {texFmtARGB1555,    "ARGB1555"},
        {texFmtI8,          "I8"},
        {texFmtI1,          "I1"},
        {texFmtA8,          "A8"},
        {texFmtA4I4,        "A4I4"},
        {texFmtARGB8888,    "ARGB8888"},
        {texFmtRGB888,      "RGB888"},
        {texFmtDXT1,        "S3C/DXT1"},
        {texFmtRGB_Bytes,   "RGB Bytes"},
        {texFmtRGBA_Bytes,  "RGBA Bytes"},
        {texFmtRGBA5551,    "RGB5551"},
        {texFmtRGBA4444,    "RGBA4444"},
        {texFmtRGB565,      "RGB565"},
        {texFmtABGR1555,    "ABGR1555"},
        {texFmtRGB888PS2,   "RGB888 (PS2)"},
        {texFmtARGB8888PS2, "ARGB8888 (PS2)"}
    };
    texFormat.setTypeValueMap(&textureFormatValues);
    texFormat.setTypeNameMap(&textureFormatNames);
}

unique_ptr<Template> TemplateTXMP::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateTXMP>(instName, dataFormat);
}

void TemplateTXMP::prepareAuxFields()
{
    static constexpr uint16_t kMaxTextureDimension = 4096;
    uint16_t tempWidth = texWidth.val();
    uint16_t tempHeight = texHeight.val();

    if (tempWidth > kMaxTextureDimension || tempHeight > kMaxTextureDimension)
    {
        cerr << "Error: Texture dimensions for instance " << quoted(name_) << " (" << tempWidth << "x" << tempHeight
             << ") exceed the maximum supported size of " << kMaxTextureDimension << "x" << kMaxTextureDimension << ".\n";
        return;
    }

    uint32_t length = 0;

    // First calculate the main bitmap's size
    switch (texFormat.code())
    {
        case texFmtARGB8888:
        case texFmtRGB888:
        case texFmtRGBA_Bytes:
        length = tempWidth * tempHeight * 4;
        break;

        case texFmtRGB_Bytes:
        length = tempWidth * tempHeight * 3;
        break;

        case texFmtARGB4444:
        case texFmtRGB555:
        case texFmtARGB1555:
        case texFmtRGBA5551:
        case texFmtRGBA4444:
        case texFmtRGB565:
        case texFmtABGR1555:
        length = tempWidth * tempHeight * 2;
        break;

        case texFmtI8:
        case texFmtA8:
        case texFmtA4I4:
        case texFmtRGB888PS2:
        case texFmtARGB8888PS2:
        length = tempWidth * tempHeight;
        break;

        case texFmtDXT1:
        length = tempWidth * tempHeight / 2;
        break;

        case texFmtI1:
        length = tempWidth * tempHeight / 8;
        break;

        default:
        cerr << "Error: Unrecognized texture format!\n";
    }

    if (length == 0)
        return;

    uint32_t totalLength = length;
    uint32_t tempLength = length;

    // Add on the size of the mipmaps if present
    if (textureFlags.has(texHasMipMaps))
    {
        if (texFormat.code() == texFmtDXT1)
        {
            do
            {
                if (tempWidth > 1)
                    tempWidth >>= 1;

                if (tempHeight > 1)
                    tempHeight >>= 1;

                totalLength += static_cast<size_t>(max(1, tempWidth / 4)) * static_cast<size_t>(max(1, tempHeight / 4)) * 8;
            }
            while (tempHeight > 1 || tempWidth > 1);
        }
        else
        {
            do
            {
                if (tempWidth > 1)
                {
                    tempWidth >>= 1;
                    tempLength >>= 1;
                }

                if (tempHeight > 1)
                {
                    tempHeight >>= 1;
                    tempLength >>= 1;
                }

                totalLength += tempLength;
            }
            while (tempHeight > 1 || tempWidth > 1);
        }
    }

    // Store the computed total so auxOffset() can validate it, then size the blob for the base processAuxData() loop to fill
    auxDataSize_ = totalLength;
    pixelBlob.setReservedSize(totalLength);
}

void TemplateTXMP::processPaletteData(vector<char> & dataPacket)
{
    if (auto pal = palData())
    {
        size_t palOffset = static_cast<size_t>(paletteNum.val()) * kPS2PaletteSize;
        if (palOffset + kPS2PaletteSize > dataPacket.size())
        {
            cerr << "Error: Palette data offset for instance " << quoted(name_) << " is out of bounds.\n";
            return;
        }
        span<char> & palette = pal->get();
        palette = span<char>(dataPacket.begin() + static_cast<ptrdiff_t>(palOffset), kPS2PaletteSize);
    }
}

// Convert PS2 palette-indexed pixel data (including all mip maps if present) to a pure pixel-based image format that can be written to disk in
// PC format
vector<char> TemplateTXMP::convertPS2PixelsToPC(int targetFmt)
{
    const vector<char> * srcData = &pixelBlob.val();

    if (!srcData || srcData->empty())
    {
        cerr << "Error: No pixel data found for PS2 texture instance " << quoted(name_) << ".\n";
        return {};
    }

    span<char> & palette = paletteData.val();
    if (palette.size() < kPS2PaletteSize)
    {
        cerr << "Error: Palette data missing or too small for PS2 texture instance " << quoted(name_) << ".\n";
        return {};
    }

    uint16_t mipW   = texWidth.val();
    uint16_t mipH   = texHeight.val();
    size_t mipSize  = static_cast<size_t>(mipW) * mipH; // 1 byte per pixel for PS2 indexed formats
    int srcFmt      = texFormat.code();
    size_t srcOffset = 0;
    vector<char> result;

    // Convert one mip level: extract the index sub-slice, de-palettize to RGBA, write out in PC disk byte order
    auto convertLevel = [&](uint16_t lw, uint16_t lh, size_t lSize) -> bool
    {
        if (srcOffset + lSize > srcData->size())
        {
            cerr << "Error: Pixel data too small while converting PS2 texture instance " << quoted(name_) << ".\n";
            return false;
        }
        vector<char> levelIndices(srcData->begin() + static_cast<ptrdiff_t>(srcOffset),
                                  srcData->begin() + static_cast<ptrdiff_t>(srcOffset + lSize));
        srcOffset += lSize;

        vector<uint8_t> rgba = convertPixelsToRGBA(levelIndices, lw, lh, srcFmt);
        if (rgba.empty())
            return false;

        size_t pixelCount = static_cast<size_t>(lw) * lh;
        for (size_t i = 0; i < pixelCount; ++i)
        {
            uint8_t r = rgba[i * 4];
            uint8_t g = rgba[(i * 4) + 1];
            uint8_t b = rgba[(i * 4) + 2];
            uint8_t a = rgba[(i * 4) + 3];
            result.push_back(static_cast<char>(b));
            result.push_back(static_cast<char>(g));
            result.push_back(static_cast<char>(r));
            result.push_back(targetFmt == texFmtARGB8888 ? static_cast<char>(a) : '\0');
        }
        return true;
    };

    if (!convertLevel(mipW, mipH, mipSize))
        return {};

    if (textureFlags.has(texHasMipMaps))
    {
        size_t tempSize = mipSize;
        do
        {
            if (mipW > 1)
            {
                mipW >>= 1;
                tempSize >>= 1;
            }

            if (mipH > 1)
            {
                mipH >>= 1;
                tempSize >>= 1;
            }

            if (!convertLevel(mipW, mipH, tempSize))
                return {};
        }
        while (mipH > 1 || mipW > 1);
    }

    return result;
}

bool TemplateTXMP::convertData(Format toFmt)
{
    // The Win alpha 6 format is the same as PC 1.0
    if (toFmt == curFormat_ || toFmt == Format::WinAlpha6)
        return true;

    // This would require converting the PC-format pixel data to the PS2 palette-based format which is not supported at this time
    if (toFmt == Format::PS2)
    {
        cerr << "Advisory: Texture conversion to PS2 format not supported at this time.\n";
        return false;
    }

    if (toFmt == Format::MacBeta4 || toFmt == Format::PC1_1)
    {
        cerr << "Advisory: Texture conversion to Mac format not supported at this time.\n";
        return false;
    }

    if (toFmt == Format::PC1_0)
    {
        // Even when the originating data is Mac- or 1.1-format, OniSplit's .oni file uses the raw data address field to point to the aux data,
        // not the separate data address field
        if (origFormat_ == Format::MacBeta4 || origFormat_ == Format::PC1_1)
        {
            pixelOffsetRaw.val() = pixelOffsetSep.val();
            pixelOffsetSep.val() = 0;
        }
        else if (origFormat_ == Format::PS2)
        {
            // Determine the equivalent PC format for this PS2 texture
            int targetFmt;
            int srcFmtCode = texFormat.code();
            if (srcFmtCode == texFmtRGB888PS2)
                targetFmt = texFmtRGB888;
            else if (srcFmtCode == texFmtARGB8888PS2)
                targetFmt = texFmtARGB8888;
            else
            {
                cerr << "Error: Unsupported PS2 texture format for conversion on instance " << quoted(name_) << ".\n";
                return false;
            }

            // De-palettize the indexed pixel data into PC-format pixel data
            vector<char> convertedPixels = convertPS2PixelsToPC(targetFmt);
            if (convertedPixels.empty())
                return false;

            // PS2 pixel data may be in either raw or separate file; PC 1.0 always uses the raw data address field
            uint32_t auxOff = pixelOffsetRaw.val() ? pixelOffsetRaw.val() : pixelOffsetSep.val();
            pixelOffsetRaw.val() = auxOff;
            pixelBlob.val() = std::move(convertedPixels);
            auxDataSize_ = static_cast<uint32_t>(pixelBlob.val().size());

            // Clear separate and palette fields that are no longer valid for PC format
            pixelOffsetSep.val() = 0;
            paletteNum.val() = 0;
            paletteData.val() = {};
            hasPaletteData_ = false;

            // Update the texture format code to the PC equivalent
            texFormat.val() = (targetFmt == texFmtRGB888) ? 8 : 7;
        }
        // else Format::WinAlpha6, so fall through to "return true" because we have nothing to do
    }

    curFormat_ = toFmt;

    return true;
}

size_t TemplateTXMP::auxOffset()
{
    if (pixelOffsetRaw.val())
        return pixelOffsetRaw.val();
    // else
    return pixelOffsetSep.val();
}

size_t TemplateTXMP::auxFieldsBaseOffset()
{
    return auxOffset();
}

optional<reference_wrapper<span<char>>> TemplateTXMP::palData()
{
    return ref(paletteData.val());
}

bool TemplateTXMP::hasSepData()
{
    return (pixelOffsetRaw.val() == 0);
}

// Convert pixel data to RGBA (4 bytes per pixel). Returns an empty vector and prints an error on failure.
vector<uint8_t> TemplateTXMP::convertPixelsToRGBA(const vector<char> & pixelData, uint16_t w, uint16_t h, int fmt)
{
    size_t pixelCount = static_cast<size_t>(w) * static_cast<size_t>(h);
    vector<uint8_t> rgba;

    auto checkSize = [&](size_t expected) -> bool
    {
        if (pixelData.size() < expected)
        {
            cerr << "Error: Pixel data too small for instance " << quoted(name_) << ": expected " << expected << " bytes, got "
                 << pixelData.size() << ".\n";
            return false;
        }
        return true;
    };

    switch (fmt)
    {
        case texFmtARGB4444:
        {
            size_t expectedSize = pixelCount * 2; // 2 bytes per pixel
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                uint8_t lo = static_cast<uint8_t>(pixelData[i * 2]);
                uint8_t hi = static_cast<uint8_t>(pixelData[(i * 2) + 1]);
                uint16_t px = static_cast<uint16_t>(lo | (static_cast<uint16_t>(hi) << 8));
                // Bits [15:12]=A, [11:8]=R, [7:4]=G, [3:0]=B; all 4-bit channels
                // Expand 4-bit channel to 8-bit by replicating into low nibble: (val << 4) | val
                uint8_t a = ((px >> 12) & 0xF); a = static_cast<uint8_t>((a << 4) | a);
                uint8_t r = ((px >>  8) & 0xF); r = static_cast<uint8_t>((r << 4) | r);
                uint8_t g = ((px >>  4) & 0xF); g = static_cast<uint8_t>((g << 4) | g);
                uint8_t b = ( px        & 0xF); b = static_cast<uint8_t>((b << 4) | b);
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(a);
            }
            break;
        }
        case texFmtRGB555:
        {
            size_t expectedSize = pixelCount * 2; // 2 bytes per pixel
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                uint8_t lo = static_cast<uint8_t>(pixelData[i * 2]);
                uint8_t hi = static_cast<uint8_t>(pixelData[(i * 2) + 1]);
                uint16_t px = static_cast<uint16_t>(lo | (static_cast<uint16_t>(hi) << 8));
                // Bits [14:10]=R, [9:5]=G, [4:0]=B; bit 15 is always 0
                // Expand 5-bit channel to 8-bit by replicating high bits into low bits
                uint8_t r = static_cast<uint8_t>((((px >> 10) & 0x1F) << 3) | (((px >> 10) & 0x1F) >> 2));
                uint8_t g = static_cast<uint8_t>((((px >>  5) & 0x1F) << 3) | (((px >>  5) & 0x1F) >> 2));
                uint8_t b = static_cast<uint8_t>((( px        & 0x1F) << 3) | (( px        & 0x1F) >> 2));
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(0xFF); // fully opaque
            }
            break;
        }
        case texFmtARGB1555:
        {
            size_t expectedSize = pixelCount * 2; // 2 bytes per pixel
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                uint8_t lo = static_cast<uint8_t>(pixelData[i * 2]);
                uint8_t hi = static_cast<uint8_t>(pixelData[(i * 2) + 1]);
                uint16_t px = static_cast<uint16_t>(lo | (static_cast<uint16_t>(hi) << 8));
                // Bit 15=A, bits [14:10]=R, [9:5]=G, [4:0]=B; same channel layout as texFmtRGB555 but with a 1-bit alpha
                uint8_t r = static_cast<uint8_t>((((px >> 10) & 0x1F) << 3) | (((px >> 10) & 0x1F) >> 2));
                uint8_t g = static_cast<uint8_t>((((px >>  5) & 0x1F) << 3) | (((px >>  5) & 0x1F) >> 2));
                uint8_t b = static_cast<uint8_t>((( px        & 0x1F) << 3) | (( px        & 0x1F) >> 2));
                uint8_t a = (px >> 15) ? 0xFF : 0x00; // 1-bit alpha: expand to fully opaque or fully transparent
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(a);
            }
            break;
        }
        case texFmtI8: // not used in vanilla game data and thus this code has not been tested
        {
            size_t expectedSize = pixelCount; // 1 byte per pixel
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                uint8_t intensity = static_cast<uint8_t>(pixelData[i]);
                rgba.push_back(intensity);
                rgba.push_back(intensity);
                rgba.push_back(intensity);
                rgba.push_back(0xFF);
            }
            break;
        }
        case texFmtI1: // not used in vanilla game data and thus this code has not been tested
        {
            size_t expectedSize = (pixelCount + 7) / 8; // 1 bit per pixel, rounded up to whole bytes
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                // MSB first: bit 7 of byte 0 is pixel 0
                uint8_t byte = static_cast<uint8_t>(pixelData[i / 8]);
                uint8_t intensity = ((byte >> (7 - (i % 8))) & 1) ? 0xFF : 0x00;
                rgba.push_back(intensity);
                rgba.push_back(intensity);
                rgba.push_back(intensity);
                rgba.push_back(0xFF);
            }
            break;
        }
        case texFmtA8: // not used in vanilla game data and thus this code has not been tested
        {
            size_t expectedSize = pixelCount; // 1 byte per pixel
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                uint8_t a = static_cast<uint8_t>(pixelData[i]);
                rgba.push_back(0xFF); // white with alpha mask
                rgba.push_back(0xFF);
                rgba.push_back(0xFF);
                rgba.push_back(a);
            }
            break;
        }
        case texFmtA4I4: // not used in vanilla game data and thus this code has not been tested
        {
            size_t expectedSize = pixelCount; // 1 byte per pixel
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                uint8_t byte = static_cast<uint8_t>(pixelData[i]);
                // High nibble = alpha, low nibble = intensity; expand 4-bit to 8-bit via (val << 4) | val
                uint8_t a = (byte >> 4) & 0xF; a = static_cast<uint8_t>((a << 4) | a);
                uint8_t intensity = byte & 0xF;  intensity = static_cast<uint8_t>((intensity << 4) | intensity);
                rgba.push_back(intensity);
                rgba.push_back(intensity);
                rgba.push_back(intensity);
                rgba.push_back(a);
            }
            break;
        }
        case texFmtARGB8888: // not used in vanilla game data and thus this code has not been tested
        {
            size_t expectedSize = pixelCount * 4; // 4 bytes per pixel: B, G, R, A (BGRA in memory, per DirectX convention)
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                // Bytes are B, G, R, A; same channel order as texFmtRGB888 but with a real alpha byte instead of 0x00 padding
                uint8_t b = static_cast<uint8_t>(pixelData[i * 4]);
                uint8_t g = static_cast<uint8_t>(pixelData[(i * 4) + 1]);
                uint8_t r = static_cast<uint8_t>(pixelData[(i * 4) + 2]);
                uint8_t a = static_cast<uint8_t>(pixelData[(i * 4) + 3]);
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(a);
            }
            break;
        }
        case texFmtRGB888:
        {
            size_t expectedSize = pixelCount * 4; // 4 bytes per pixel: B, G, R, 0x00 padding
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                // Bytes are B, G, R, 0x00 (padding); fourth byte is discarded
                uint8_t b = static_cast<uint8_t>(pixelData[i * 4]);
                uint8_t g = static_cast<uint8_t>(pixelData[(i * 4) + 1]);
                uint8_t r = static_cast<uint8_t>(pixelData[(i * 4) + 2]);
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(0xFF); // fully opaque
            }
            break;
        }
        case texFmtDXT1:
        {
            // BC1 (DXT1): 4x4 pixel blocks, 8 bytes per block; two RGB565 endpoint colors and a 2-bit-per-pixel lookup table
            uint16_t bw = (w + 3) / 4; // number of blocks wide
            uint16_t bh = (h + 3) / 4; // number of blocks tall
            size_t expectedSize = static_cast<size_t>(bw) * bh * 8;
            if (!checkSize(expectedSize))
                return {};
            rgba.resize(static_cast<size_t>(w) * h * 4, 0);
            for (uint16_t by = 0; by < bh; ++by)
            {
                for (uint16_t bx = 0; bx < bw; ++bx)
                {
                    size_t bo = (static_cast<size_t>(by) * bw + bx) * 8; // block offset in pixelData
                    // Read two RGB565 endpoint colors (little-endian)
                    uint16_t c0 = static_cast<uint16_t>(
                                  static_cast<uint16_t>(static_cast<uint8_t>(pixelData[bo])) |
                                  (static_cast<uint16_t>(static_cast<uint8_t>(pixelData[bo + 1])) << 8));
                    uint16_t c1 = static_cast<uint16_t>(
                                  static_cast<uint16_t>(static_cast<uint8_t>(pixelData[bo + 2])) |
                                  (static_cast<uint16_t>(static_cast<uint8_t>(pixelData[bo + 3])) << 8));
                    // Read 2-bit-per-pixel index lookup table (little-endian)
                    uint32_t lookup = static_cast<uint32_t>(static_cast<uint8_t>(pixelData[bo + 4])) |
                                     (static_cast<uint32_t>(static_cast<uint8_t>(pixelData[bo + 5])) << 8) |
                                     (static_cast<uint32_t>(static_cast<uint8_t>(pixelData[bo + 6])) << 16) |
                                     (static_cast<uint32_t>(static_cast<uint8_t>(pixelData[bo + 7])) << 24);
                    // Decode RGB565 to RGB888
                    auto decodeColor = [](uint16_t c) -> array<uint8_t, 3> {
                        uint8_t r = (c >> 11) & 0x1F; r = static_cast<uint8_t>((r << 3) | (r >> 2));
                        uint8_t g = (c >> 5) & 0x3F;  g = static_cast<uint8_t>((g << 2) | (g >> 4));
                        uint8_t b = c & 0x1F;          b = static_cast<uint8_t>((b << 3) | (b >> 2));
                        return {r, g, b};
                    };
                    auto [r0, g0, b0] = decodeColor(c0);
                    auto [r1, g1, b1] = decodeColor(c1);
                    // Build 4-entry RGBA color table
                    array<uint8_t, 16> colors; // 4 entries x 4 channels
                    colors[0] = r0; colors[1] = g0; colors[2] = b0; colors[3] = 0xFF;
                    colors[4] = r1; colors[5] = g1; colors[6] = b1; colors[7] = 0xFF;
                    if (c0 > c1)
                    {
                        // 4-color mode: interpolate two additional colors
                        colors[8]  = static_cast<uint8_t>((2 * r0 + r1 + 1) / 3);
                        colors[9]  = static_cast<uint8_t>((2 * g0 + g1 + 1) / 3);
                        colors[10] = static_cast<uint8_t>((2 * b0 + b1 + 1) / 3);
                        colors[11] = 0xFF;
                        colors[12] = static_cast<uint8_t>((r0 + 2 * r1 + 1) / 3);
                        colors[13] = static_cast<uint8_t>((g0 + 2 * g1 + 1) / 3);
                        colors[14] = static_cast<uint8_t>((b0 + 2 * b1 + 1) / 3);
                        colors[15] = 0xFF;
                    }
                    else
                    {
                        // 3-color + transparent mode: interpolate one midpoint; index 3 = transparent
                        colors[8]  = static_cast<uint8_t>((r0 + r1) / 2);
                        colors[9]  = static_cast<uint8_t>((g0 + g1) / 2);
                        colors[10] = static_cast<uint8_t>((b0 + b1) / 2);
                        colors[11] = 0xFF;
                        colors[12] = 0; colors[13] = 0; colors[14] = 0; colors[15] = 0; // transparent
                    }
                    // Write pixels, clamping to image bounds for partial edge blocks
                    for (uint16_t py = 0; py < 4 && (by * 4 + py) < h; ++py)
                    {
                        for (uint16_t px = 0; px < 4 && (bx * 4 + px) < w; ++px)
                        {
                            uint8_t idx = (lookup >> ((py * 4 + px) * 2)) & 0x3;
                            size_t outOffset = (static_cast<size_t>((by * 4) + py) * w + (bx * 4 + px)) * 4;
                            rgba[outOffset]     = colors[static_cast<size_t>(idx) * 4];
                            rgba[outOffset + 1] = colors[(idx * 4) + 1];
                            rgba[outOffset + 2] = colors[(idx * 4) + 2];
                            rgba[outOffset + 3] = colors[(idx * 4) + 3];
                        }
                    }
                }
            }
            break;
        }
        case texFmtRGB_Bytes: // not used in vanilla game data and thus this code has not been tested
        {
            size_t expectedSize = pixelCount * 3; // 3 bytes per pixel: B, G, R (packed, no padding)
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                // Bytes are B, G, R (packed); byte order matches texFmtRGB888 but without the 0x00 padding byte
                uint8_t b = static_cast<uint8_t>(pixelData[i * 3]);
                uint8_t g = static_cast<uint8_t>(pixelData[(i * 3) + 1]);
                uint8_t r = static_cast<uint8_t>(pixelData[(i * 3) + 2]);
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(0xFF); // fully opaque
            }
            break;
        }
        case texFmtRGBA_Bytes: // not used in vanilla game data and thus this code has not been tested
        {
            size_t expectedSize = pixelCount * 4; // 4 bytes per pixel: B, G, R, A (assumed BGRA in memory, consistent with other 32-bit formats)
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                // Bytes assumed to be B, G, R, A; consistent with texFmtARGB8888 actual layout
                uint8_t b = static_cast<uint8_t>(pixelData[i * 4]);
                uint8_t g = static_cast<uint8_t>(pixelData[(i * 4) + 1]);
                uint8_t r = static_cast<uint8_t>(pixelData[(i * 4) + 2]);
                uint8_t a = static_cast<uint8_t>(pixelData[(i * 4) + 3]);
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(a);
            }
            break;
        }
        case texFmtRGBA5551: // not used in vanilla game data and thus this code has not been tested
        {
            size_t expectedSize = pixelCount * 2; // 2 bytes per pixel
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                uint8_t lo = static_cast<uint8_t>(pixelData[i * 2]);
                uint8_t hi = static_cast<uint8_t>(pixelData[(i * 2) + 1]);
                uint16_t px = static_cast<uint16_t>(lo | (static_cast<uint16_t>(hi) << 8));
                // Bits [15:11]=R (5-bit), [10:6]=G (5-bit), [5:1]=B (5-bit), [0]=A (1-bit)
                uint8_t r = static_cast<uint8_t>((((px >> 11) & 0x1F) << 3) | (((px >> 11) & 0x1F) >> 2));
                uint8_t g = static_cast<uint8_t>((((px >>  6) & 0x1F) << 3) | (((px >>  6) & 0x1F) >> 2));
                uint8_t b = static_cast<uint8_t>((((px >>  1) & 0x1F) << 3) | (((px >>  1) & 0x1F) >> 2));
                uint8_t a = (px & 0x1) ? 0xFF : 0x00; // 1-bit alpha: expand to fully opaque or fully transparent
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(a);
            }
            break;
        }
        case texFmtRGBA4444: // not used in vanilla game data and thus this code has not been tested
        {
            size_t expectedSize = pixelCount * 2; // 2 bytes per pixel
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                uint8_t lo = static_cast<uint8_t>(pixelData[i * 2]);
                uint8_t hi = static_cast<uint8_t>(pixelData[(i * 2) + 1]);
                uint16_t px = static_cast<uint16_t>(lo | (static_cast<uint16_t>(hi) << 8));
                // Bits [15:12]=R, [11:8]=G, [7:4]=B, [3:0]=A; all 4-bit channels
                // Expand 4-bit channel to 8-bit by replicating into low nibble: (val << 4) | val
                uint8_t r = ((px >> 12) & 0xF); r = static_cast<uint8_t>((r << 4) | r);
                uint8_t g = ((px >>  8) & 0xF); g = static_cast<uint8_t>((g << 4) | g);
                uint8_t b = ((px >>  4) & 0xF); b = static_cast<uint8_t>((b << 4) | b);
                uint8_t a = ( px        & 0xF); a = static_cast<uint8_t>((a << 4) | a);
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(a);
            }
            break;
        }
        case texFmtRGB565: // not used in vanilla game data and thus this code has not been tested
        {
            size_t expectedSize = pixelCount * 2; // 2 bytes per pixel
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                uint8_t lo = static_cast<uint8_t>(pixelData[i * 2]);
                uint8_t hi = static_cast<uint8_t>(pixelData[(i * 2) + 1]);
                uint16_t px = static_cast<uint16_t>(lo | (static_cast<uint16_t>(hi) << 8));
                // Bits [15:11]=R (5-bit), [10:5]=G (6-bit), [4:0]=B (5-bit); no alpha
                // 5-bit channels expand via high-bit replication: (val << 3) | (val >> 2)
                // 6-bit green expands via: (val << 2) | (val >> 4)
                uint8_t r = static_cast<uint8_t>((((px >> 11) & 0x1F) << 3) | (((px >> 11) & 0x1F) >> 2));
                uint8_t g = static_cast<uint8_t>((((px >>  5) & 0x3F) << 2) | (((px >>  5) & 0x3F) >> 4));
                uint8_t b = static_cast<uint8_t>((( px        & 0x1F) << 3) | (( px        & 0x1F) >> 2));
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(0xFF); // fully opaque
            }
            break;
        }
        case texFmtABGR1555: // not used in vanilla game data and thus this code has not been tested
        {
            size_t expectedSize = pixelCount * 2; // 2 bytes per pixel
            if (!checkSize(expectedSize))
                return {};
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                uint8_t lo = static_cast<uint8_t>(pixelData[i * 2]);
                uint8_t hi = static_cast<uint8_t>(pixelData[(i * 2) + 1]);
                uint16_t px = static_cast<uint16_t>(lo | (static_cast<uint16_t>(hi) << 8));
                // Bit 15=A, bits [14:10]=B, [9:5]=G, [4:0]=R; same as texFmtARGB1555 but with R and B channels swapped
                uint8_t r = static_cast<uint8_t>((( px        & 0x1F) << 3) | (( px        & 0x1F) >> 2));
                uint8_t g = static_cast<uint8_t>((((px >>  5) & 0x1F) << 3) | (((px >>  5) & 0x1F) >> 2));
                uint8_t b = static_cast<uint8_t>((((px >> 10) & 0x1F) << 3) | (((px >> 10) & 0x1F) >> 2));
                uint8_t a = (px >> 15) ? 0xFF : 0x00; // 1-bit alpha: expand to fully opaque or fully transparent
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(a);
            }
            break;
        }
        case texFmtRGB888PS2:
        {
            size_t expectedSize = pixelCount; // 1 byte per pixel: palette index
            if (!checkSize(expectedSize))
                return {};
            span<char> & palette = paletteData.val();
            if (palette.size() < kPS2PaletteSize)
            {
                cerr << "Error: Palette data missing or too small for instance " << quoted(name_) << ".\n";
                return {};
            }
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                uint8_t idx = static_cast<uint8_t>(pixelData[i]);
                // De-swizzle PS2 CLUT: the GS hardware stores palette entries with entries 8-15 and 16-23 swapped
                // within each 32-entry block. Undo this by XOR-ing the low 5 bits with 0x18 for entries 8-23.
                uint8_t sub = idx & 0x1F;
                if (sub >= 8 && sub < 24)
                    idx = (idx & 0xE0) | (sub ^ 0x18);
                // Palette entry: R, G, B, 0x80 (4 bytes per entry; 4th byte is 0x80 padding, ignored)
                uint8_t r = static_cast<uint8_t>(palette[static_cast<size_t>(idx) * 4]);
                uint8_t g = static_cast<uint8_t>(palette[(idx * 4) + 1]);
                uint8_t b = static_cast<uint8_t>(palette[(idx * 4) + 2]);
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(0xFF); // fully opaque
            }
            break;
        }
        case texFmtARGB8888PS2:
        {
            size_t expectedSize = pixelCount; // 1 byte per pixel: palette index
            if (!checkSize(expectedSize))
                return {};
            span<char> & palette = paletteData.val();
            if (palette.size() < kPS2PaletteSize)
            {
                cerr << "Error: Palette data missing or too small for instance " << quoted(name_) << ".\n";
                return {};
            }
            rgba.reserve(pixelCount * 4);
            for (size_t i = 0; i < pixelCount; ++i)
            {
                uint8_t idx = static_cast<uint8_t>(pixelData[i]);
                // De-swizzle PS2 CLUT: the GS hardware stores palette entries with entries 8-15 and 16-23 swapped
                // within each 32-entry block. Undo this by XOR-ing the low 5 bits with 0x18 for entries 8-23.
                uint8_t sub = idx & 0x1F;
                if (sub >= 8 && sub < 24)
                    idx = (idx & 0xE0) | (sub ^ 0x18);
                // Palette entry: R, G, B, A (4 bytes per entry; PS2 alpha range is 0x00-0x80 where 0x80 = fully opaque)
                uint8_t r = static_cast<uint8_t>(palette[static_cast<size_t>(idx) * 4]);
                uint8_t g = static_cast<uint8_t>(palette[(idx * 4) + 1]);
                uint8_t b = static_cast<uint8_t>(palette[(idx * 4) + 2]);
                uint8_t a = static_cast<uint8_t>(palette[(idx * 4) + 3]);
                a = (a >= 0x80) ? 0xFF : static_cast<uint8_t>(a << 1); // scale PS2 alpha (0x00-0x80) to 8-bit (0x00-0xFF)
                rgba.push_back(r);
                rgba.push_back(g);
                rgba.push_back(b);
                rgba.push_back(a);
            }
            break;
        }
        default:
        cerr << "Error: Unknown texture format " << fmt << " found for instance " << quoted(name_) << ".\n";
        return {};
    }

    return rgba;
}

void TemplateTXMP::displayViaTerminal(TerminalImageSupport termSupport, int displayScale,
                                      const vector<unique_ptr<Template>> & instances)
{
    int effectiveScale = (displayScale > 1) ? displayScale : 1;

    // If this TXMP is the first frame of a TXAN animation, gather all frames and display as an animated image
    if (termSupport == TerminalImageSupport::Kitty && !instances.empty() && linkTXAN.val() != 0)
    {
        uint32_t txanIdx = linkTXAN.val();
        if (txanIdx < instances.size() && instances[txanIdx])
        {
            TemplateTXAN * txan = dynamic_cast<TemplateTXAN *>(instances[txanIdx].get());
            if (txan)
            {
                vector<TemplateTXMP *> additionalFrames = txan->getAdditionalFrames(instances);
                if (!additionalFrames.empty())
                {
                    size_t outW = static_cast<size_t>(texWidth.val())  * static_cast<size_t>(effectiveScale);
                    size_t outH = static_cast<size_t>(texHeight.val()) * static_cast<size_t>(effectiveScale);
                    int gapMs = txan->frameDelayMs();

                    vector<TemplateTXMP *> allFrames;
                    allFrames.reserve(1 + additionalFrames.size());
                    allFrames.push_back(this);
                    allFrames.insert(allFrames.end(), additionalFrames.begin(), additionalFrames.end());
                    TemplateTXAN::sendKittyAnimatedFrames(allFrames, effectiveScale, outW, outH, gapMs, name_);
                    return;
                }
            }
        }
    }

    // If this TXMP is the first frame of a TXAN animation, display as an animated PNG via wezterm imgcat
    if (termSupport == TerminalImageSupport::WezTerm && !instances.empty() && linkTXAN.val() != 0)
    {
        uint32_t txanIdx = linkTXAN.val();
        if (txanIdx < instances.size() && instances[txanIdx])
        {
            TemplateTXAN * txan = dynamic_cast<TemplateTXAN *>(instances[txanIdx].get());
            if (txan)
            {
                vector<TemplateTXMP *> additionalFrames = txan->getAdditionalFrames(instances);
                if (!additionalFrames.empty())
                {
                    size_t outW = static_cast<size_t>(texWidth.val())  * static_cast<size_t>(effectiveScale);
                    size_t outH = static_cast<size_t>(texHeight.val()) * static_cast<size_t>(effectiveScale);
                    uint16_t delayMs = uint16_t(txan->frameDelayMs());

                    vector<TemplateTXMP *> allFrames;
                    allFrames.reserve(1 + additionalFrames.size());
                    allFrames.push_back(this);
                    allFrames.insert(allFrames.end(), additionalFrames.begin(), additionalFrames.end());
                    vector<vector<uint8_t>> rgbaFrames;
                    if (TemplateTXAN::collectRGBAFrames(allFrames, effectiveScale, name_, rgbaFrames)
                        && TemplateTXAN::displayViaWezTermAPNG(rgbaFrames, outW, outH, delayMs, name_))
                        return;
                }
            }
        }
    }

    // Terminal does not support inline image display; if this is an animated texture, write an APNG and an HTML
    // wrapper to disk and open the HTML in the default web browser so the animation can be viewed
    if (termSupport == TerminalImageSupport::None && !instances.empty() && linkTXAN.val() != 0)
    {
        uint32_t txanIdx = linkTXAN.val();
        if (txanIdx < instances.size() && instances[txanIdx])
        {
            TemplateTXAN * txan = dynamic_cast<TemplateTXAN *>(instances[txanIdx].get());
            if (txan)
            {
                vector<TemplateTXMP *> additionalFrames = txan->getAdditionalFrames(instances);
                if (!additionalFrames.empty())
                {
                    size_t outW = static_cast<size_t>(texWidth.val()) * static_cast<size_t>(effectiveScale);
                    size_t outH = static_cast<size_t>(texHeight.val()) * static_cast<size_t>(effectiveScale);
                    uint16_t delayMs = uint16_t(txan->frameDelayMs());

                    vector<TemplateTXMP *> allFrames;
                    allFrames.reserve(1 + additionalFrames.size());
                    allFrames.push_back(this);
                    allFrames.insert(allFrames.end(), additionalFrames.begin(), additionalFrames.end());
                    vector<vector<uint8_t>> rgbaFrames;
                    if (TemplateTXAN::collectRGBAFrames(allFrames, effectiveScale, name_, rgbaFrames)
                        && TemplateTXAN::displayViaBrowserAPNG(rgbaFrames, outW, outH, delayMs, name_))
                        return;
                }
            }
        }
    }

    const vector<char> & pixelData = pixelBlob.val();
    if (pixelData.empty())
    {
        cerr << "Error: No pixel data found for instance " << quoted(name_) << ".\n";
        return;
    }

    uint16_t w = texWidth.val();
    uint16_t h = texHeight.val();

    // Convert pixels to RGBA; returns an empty vector and prints an error if the format is unsupported
    vector<uint8_t> nativeRgba = convertPixelsToRGBA(pixelData, w, h, static_cast<int>(texFormat.val()));
    if (nativeRgba.empty())
        return;

    TemplateDisplay::displayStaticRGBA(nativeRgba, size_t(w), size_t(h), termSupport, effectiveScale, name_);
}

bool TemplateTXMP::exportToPNG(const string & dir, const string & stem,
                                const vector<unique_ptr<Template>> & instances)
{
    // If this TXMP is the first frame of an animation, gather all frames and export as an APNG
    if (!instances.empty() && linkTXAN.val() != 0)
    {
        uint32_t txanIdx = linkTXAN.val();
        if (txanIdx < instances.size() && instances[txanIdx])
        {
            TemplateTXAN * txan = dynamic_cast<TemplateTXAN *>(instances[txanIdx].get());
            if (txan)
            {
                vector<TemplateTXMP *> additionalFrames = txan->getAdditionalFrames(instances);
                if (!additionalFrames.empty())
                {
                    size_t outW = static_cast<size_t>(texWidth.val());
                    size_t outH = static_cast<size_t>(texHeight.val());
                    uint16_t delayMs = uint16_t(txan->frameDelayMs());

                    vector<TemplateTXMP *> allFrames;
                    allFrames.reserve(1 + additionalFrames.size());
                    allFrames.push_back(this);
                    allFrames.insert(allFrames.end(), additionalFrames.begin(), additionalFrames.end());

                    vector<vector<uint8_t>> rgbaFrames;
                    if (!TemplateTXAN::collectRGBAFrames(allFrames, 1, name_, rgbaFrames))
                        return false;

                    vector<uint8_t> png = TemplateDisplay::buildAnimatedPNG(rgbaFrames, outW, outH, delayMs, 1000);
                    if (png.empty())
                    {
                        cerr << "Error: Failed to build APNG data for instance " << quoted(name_) << ".\n";
                        return false;
                    }
                    return DiskItem(dir, stem, "png", ReadingMode::None, ReportingMode::ErrorsOnly).write(png) == WriteResult::Written;
                }
            }
        }
    }

    // Export as a single-frame PNG
    const vector<char> & pixelData = pixelBlob.val();
    if (pixelData.empty())
    {
        cerr << "Error: No pixel data found for instance " << quoted(name_) << ".\n";
        return false;
    }

    uint16_t w = texWidth.val();
    uint16_t h = texHeight.val();

    vector<uint8_t> rgba = convertPixelsToRGBA(pixelData, w, h, static_cast<int>(texFormat.val()));
    if (rgba.empty())
        return false;

    vector<vector<uint8_t>> singleFrame {rgba};
    vector<uint8_t> png = TemplateDisplay::buildAnimatedPNG(singleFrame, size_t(w), size_t(h), 0, 1);
    if (png.empty())
    {
        cerr << "Error: Failed to build PNG data for instance " << quoted(name_) << ".\n";
        return false;
    }
    // DiskItem sanitizes the file name and enforces the program-wide overwrite policy
    return DiskItem(dir, stem, "png", ReadingMode::None, ReportingMode::ErrorsOnly).write(png) == WriteResult::Written;
}

uint32_t TemplateTXMP::txanLinkIdx()
{
    return linkTXAN.val();
}

uint16_t TemplateTXMP::width()
{
    return texWidth.val();
}

uint16_t TemplateTXMP::height()
{
    return texHeight.val();
}

// Returns RGBA pixel data scaled up by the given factor. Returns an empty vector and prints an error on failure.
vector<uint8_t> TemplateTXMP::getScaledRGBA(int scale)
{
    int effectiveScale = (scale > 1) ? scale : 1;

    const vector<char> * pixelData = &pixelBlob.val();
    if (pixelData->empty())
    {
        cerr << "Error: No pixel data found for instance " << quoted(name_) << ".\n";
        return {};
    }

    uint16_t w = texWidth.val();
    uint16_t h = texHeight.val();

    vector<uint8_t> nativeRgba = convertPixelsToRGBA(*pixelData, w, h, static_cast<int>(texFormat.val()));
    if (nativeRgba.empty())
        return {};

    size_t outW = static_cast<size_t>(w) * static_cast<size_t>(effectiveScale);
    size_t outH = static_cast<size_t>(h) * static_cast<size_t>(effectiveScale);
    vector<uint8_t> scaled;
    scaled.reserve(outW * outH * 4);
    for (size_t y = 0; y < h; ++y)
    {
        for (int ry = 0; ry < effectiveScale; ++ry)
        {
            for (size_t x = 0; x < w; ++x)
            {
                size_t src = ((y * w) + x) * 4;
                for (int rx = 0; rx < effectiveScale; ++rx)
                {
                    scaled.push_back(nativeRgba[src]);
                    scaled.push_back(nativeRgba[src + 1]);
                    scaled.push_back(nativeRgba[src + 2]);
                    scaled.push_back(nativeRgba[src + 3]);
                }
            }
        }
    }
    return scaled;
}

/**************************** TemplateVCRA ****************************/
TemplateVCRA::TemplateVCRA(string instName, Format dataFormat)
            : Template("VCRA", std::move(instName), dataFormat),
              padding("padding",        2, true, false),
              arraySize("vector count", 3)
{
    certified_ = true;

    fwvlaSizeOffset_ = {0x1C, 16};

    fields_.insert(fields_.end(), {&padding, &arraySize});

    padding.setFixedSize(20);
}

unique_ptr<Template> TemplateVCRA::create(const string & instName, Format dataFormat)
{
    return make_unique<TemplateVCRA>(instName, dataFormat);
}

void TemplateVCRA::createFWVarArray(int32_t n)
{
    const size_t sz = static_cast<size_t>(n);
    coordX.reserve(sz);
    coordY.reserve(sz);
    coordZ.reserve(sz);

    int s = static_cast<int>(fields_.size()) + 1;
    int nf = 3; // number of fields per element: x, y, z
    for (int32_t i = 0; i < n; ++i)
    {
        coordX.emplace_back("x coordinate [" + to_string(i) + "]", s + (nf * i) + 0);
        coordY.emplace_back("y coordinate [" + to_string(i) + "]", s + (nf * i) + 1);
        coordZ.emplace_back("z coordinate [" + to_string(i) + "]", s + (nf * i) + 2);
    }

    for (size_t i = 0; i < sz; ++i)
        fields_.insert(fields_.end(), {&coordX[i], &coordY[i], &coordZ[i]});
}

/************************** TemplateCatchAll **************************/
TemplateCatchAll::TemplateCatchAll(string tag, string instName, Format dataFormat)
                : Template(std::move(tag), std::move(instName), dataFormat),
                  dataBlob("data blob", 2)
{
    fields_.insert(fields_.end(), {&dataBlob});
}

// This method is never called from anywhere; a pointer to a new instance of this class is created directly from GameData::makeInstance()
unique_ptr<Template> TemplateCatchAll::create(const string &, Format)
{
    return nullptr;
}

// This catch-all subclass needs to process the data differently from class Template
void TemplateCatchAll::processData(span<char> dataPacket)
{
    // Can't really happen but silences a warning from analysis tools about the subtraction of "kInstHeaderSize" from the data packet size
    if (dataPacket.size() < static_cast<size_t>(kInstHeaderSize))
    {
        cerr << "Error: Data packet received for processing is smaller (" << dataPacket.size() << ") than the instance header size.\n";
        return;
    }
    dataBlob.setReservedSize(static_cast<uint32_t>(dataPacket.size() - kInstHeaderSize));

    sortFieldsFor(origFormat_);

    DataIO::ReadData(index_.var(), dataPacket, index_.offset());
    DataIO::ReadData(level_.var(), dataPacket, level_.offset());
    DataIO::ReadData(dataBlob.var(), dataPacket, dataBlob.offset(), dataBlob.fixedSize());

    index_.val() >>= 8;
    level_.val() >>= 25;
}