Torch doesn't support TLUTs that are in a different file and share offsets

[louist103]

OOT support added the key external_tlut and external_tlut_offset but neither seem to be used anywhere.
Ship doesn't technically need these since it never needs to combine files that use these into a normal rgba image but it is still a feature ZAPD had that Torch doesn't yet.

[inspectredc]

This should be supported by using external_files in the files config

[louist103]

There is probably a cleaner way to do it, but this will work.

 auto externalTlutFile = pf.node["external_tlut"];
 auto externalTlutOffset = pf.node["external_tlut_offset"];
 auto externalSeg = Companion::Instance->GetFileSegmentNumber(externalTlutFile.as<std::string>());
 tlutData = Companion::Instance->GetParseDataByAddr(externalSeg << 24 | externalTlutOffset.as<uint32_t>());```

[inspectredc]

Not sure what's wrong with using external files though?

[louist103]

This is using external files. When the external file is parsed the offset and segment are added to the address list. This gets the segment of the external file and then uses the address in the YML.

[inspectredc]

What I'm saying is that it shouldn't require new fields and from my memory is already supported by using the regular tlut/tlut_offset fields

[briaguya0]

to clarify, the zapd_to_torch script (from https://github.com/briaguya0/zapd-to-torch-test-harness) preserved external_tlut and external_tlut_offset from the xml, but (as mentioned in the original comment) nothing in torch reads those.

[briaguya0]

Note

🤖 Generated with Claude Code

On whether the regular tlut field already covers this — it can't for the skybox cases, because tlut is a file-relative offset and the whole premise of an external TLUT is that the palette lives in a different file. Concrete example from the current yml:

pal_mq_dbg/textures/vr_fine0_static.yml

gSunriseSkybox1Tex:
  type: TEXTURE
  offset: 0x0          # <- the texture itself sits at 0x0
  format: CI8
  width: 128
  height: 64
  external_tlut: vr_fine0_pal_static
  external_tlut_offset: 0x000

pal_mq_dbg/textures/vr_fine0_pal_static.yml

gSunriseSkyboxTLUT:
  type: TEXTURE
  offset: 0x0          # <- the palette also sits at 0x0, in a different file
  format: RGBA16
  width: 16
  height: 8

Rewrite that as tlut: 0x0 and GetParseDataByAddr(0x0) (src/Companion.cpp:2291) searches the current file first:

if (CONTAINS(this->gParseResults, this->gCurrentFile)) {
    for (auto& result : this->gParseResults[this->gCurrentFile]) {
        if (result.data.has_value() && result.GetOffset() == addr) {
            return result;          // returns gSunriseSkybox1Tex — itself
        }
    }
}
for (auto& file : this->gCurrentExternalFiles) { ... }   // never reached

It returns the CI8 texture as its own palette and never reaches the external-file loop. TextureModdingExporter::Export (TextureFactory.cpp:263) then feeds those 128x64 CI8 bytes to convert_raw_to_ci8 as if they were an RGBA16 palette. palette.has_value() is true, so nothing throws — you just get a wrong PNG. Same for gSunriseSkybox2Tex through 5Tex, which all point at the same palette.

74 of the 993 external_tlut entries in pal_mq_dbg have an external_tlut_offset that collides with an offset declared in the same file like this.

tlut_symbol looks like it sidesteps the whole problem without new fields: GetParseDataBySymbol (src/Companion.cpp:2316) searches current file -> declared externals -> global fallback, matching on symbol, so current-file-first ordering can't mis-bind it. tlut_symbol: gSunriseSkyboxTLUT should just work. I haven't tested that yet, just read the code.

[louist103]

🧠 Generated with Carbon Based Brain
tlut_symbol fixes part of the issue. The rest of the issue is that split_tlut was never brought over from ZAPD's XMLs. Some skyboxes read from index 128-255. ZAPD fixed this by starting the TLUT at 128. We can probably get the same result by subtracting the TLUT index by 128. I tested this for 1 skybox and it worked. I am working on a different issue which I should be done with today. Then I will add split_tlut