Files
totk-pc-recomp/tools/make_romfs_patches.py
T
mrtink125792andClaude Opus 5.5 bb85bc8a80 Add an Xbox prompts button layout: Switch positions with the A/B and X/Y prompts swapped to the Xbox labels
With pad_layout = nintendo on an Xbox pad the right button does Switch A but is labelled B, the bottom one does B but is
labelled A, and the game's prompts still name the Switch buttons. A fourth Button layout choice, Xbox prompts (A right)
(pad_layout = xbox_prompts), maps the buttons as nintendo and swaps the prompts to the labels, so each prompt names the
button to press. Automatic, Nintendo and Xbox are unchanged and keep the game's own prompts. The buttons change at once;
the prompts at the next start, as the game reads its UI archive and fonts at boot (the menu says so).

At start, xbox_prompts loads romfs-patches-xbox in place of romfs-patches (runtime/romfs.c overlay_init).
tools/make_romfs_patches.py --xbox-prompts writes it from the player's own RomFS, with the 60 fps patches; nothing from
the game or a mod is added to the repository. It swaps A with B and X with Y in:
- the letter images Nt_KeyTexA/B/X/Y_00 of the action prompt (DoCommand_00), in the Common archive's __Combined.bntx
  (same format, size and tiling, so the image data trades places);
- the action prompt's diamond of the other face buttons: one-letter text panes the game fills from
  LayoutMsg/DoCommand_00.msbt in each language's Mals archive (both the messages and the layout's own text);
- the button glyphs U+E040 to U+E043 of scft/External.bfotf in each Font/Font*.bfarc, which every other prompt uses
  (CFF outlines and metrics in the deobfuscated OpenType font, then its checksums).
The diamond's shape shows the button's position and stays. The setup writes both folders; the menu notes when the Xbox
prompt files are missing and when the prompts in use differ from the choice until a restart.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-10-31 07:51:03 +03:00

403 lines
21 KiB
Python

# Adapted from MacNativeGames games/totk/scripts/make_romfs_patches.py @ ebe621d (MIT, Copyright (c) 2026
# MacNativeGames contributors).
"""Build the 60 fps RomFS overlay for TotK 1.2.1 or 1.4.3 (runtime/romfs.c, TOTK_ROMFS_PATCHES).
UI/LayoutArchive/Common.Product.<110 or 140>.Nin_NX_NVN.blarc.zs: the weapon / shield / material quick menus capture the game
picture for their background when the panes C_CaptureBG_00, C_CaptureClearBG_00 and P_CaptureClearBG_00 become
visible at animation frame 1.0 (anim/ShortCutBG_00_In.bflan), AutoBuilder the same with C_CaptureBG_00
(anim/AutoBuilder_00_In.bflan). UI animations advance 0.5 frames per game frame at 60 fps, so the capture lands after
the world stopped drawing and the background can be black. The visibility keys move to frame 0.0: the live world is
captured at once (upstream checked weapon, shield, material and ability wheel at 60 fps, and 30 fps).
The game-over flow fix of the same upstream script is 1.0.0 only (1.2.1 and 1.4.3 run DmF_SY_GameOver.110) and is
left out.
--xbox-prompts: the same overlay with the A and B, and the X and Y button prompts swapped, for pad_layout = xbox_prompts
(runtime/romfs.c overlay_init loads romfs-patches-xbox in place of romfs-patches). That layout plays an Xbox pad by
position, as nintendo does: the button that does Switch A is labelled B, and the prompts then name the label. Built from
the game's own images and glyphs, nothing added:
- the action prompt (blyt/DoCommand_00.bflyt) draws the letter images Nt_KeyTexA/B/X/Y_00 of timg/__Combined.bntx in
the Common archive: their image data is swapped (same format, size and tiling). Around it, a diamond names the
other face buttons with one-letter text panes (T_B_00, T_X_00, ...). The game fills them from the messages of the
same name in LayoutMsg/DoCommand_00.msbt of each Mals/<language> archive, over the layout's own text: both have
their letters swapped the same way. The diamond's shape (Nt_KeyBtnSubBase*) shows the button's position, which
stays right.
- every other prompt is text: the button glyphs U+E040 A, U+E041 B, U+E042 X, U+E043 Y of scft/External.bfotf, the
same font in each Font/Font*.Nin_NX_NVN.bfarc.zs. Their CFF outlines and horizontal metrics are swapped.
Input: build/extracted/<version>/romfs (romfs.bin and index.json, verified by tools/extract.py). Output:
build/<version>/romfs-patches/<path> by default (romfs-patches-xbox with --xbox-prompts), and <out>/manifest.tsv (path, size, SHA-256 of the overlay, SHA-256 of the original). Run with .venv-py314.
"""
import argparse
import compression.zstd as zstd
import hashlib
import json
import re
import struct
from pathlib import Path
root = Path(__file__).resolve().parents[1]
ap = argparse.ArgumentParser(description=__doc__.splitlines()[0])
ap.add_argument('--version', choices=('v121', 'v143'), default='v121')
ap.add_argument('--romfs', type=Path, help='default build/extracted/<version>/romfs')
ap.add_argument('--out', type=Path,
help='default build/<version>/romfs-patches (romfs-patches-xbox with --xbox-prompts)')
ap.add_argument('--xbox-prompts', action='store_true', help='swap the A/B and X/Y button prompts as well')
args = ap.parse_args()
args.romfs = args.romfs or root / 'build/extracted' / args.version / 'romfs'
args.out = args.out or root / 'build' / args.version / ('romfs-patches-xbox' if args.xbox_prompts else 'romfs-patches')
index = json.loads((args.romfs / 'index.json').read_text())
assert index['status'] == 'pass'
files = {f['path']: f for f in index['files']}
def sarc_nodes(data):
"""(name, node offset, absolute start, end) of every SARC member, in SFAT order."""
assert data[:4] == b'SARC' and data[6:8] == b'\xff\xfe'
header, size, start = struct.unpack_from('<HxxII', data, 4)
assert size == len(data) and data[header:header + 4] == b'SFAT'
count = struct.unpack_from('<H', data, header + 6)[0]
names = header + 12 + count * 16
assert data[names:names + 4] == b'SFNT'
names += 8
out = []
for i in range(count):
node = header + 12 + i * 16
_, attribute, lo, hi = struct.unpack_from('<4I', data, node)
offset = names + (attribute & 0xffffff) * 4
out.append((data[offset:data.index(0, offset, start)].decode(), node, start + lo, start + hi))
return out
def sarc_members(data):
"""name -> (absolute start, end) of every SARC member."""
return {name: (lo, hi) for name, _, lo, hi in sarc_nodes(data)}
def flvi_keys(data, base):
"""(pane name, absolute key offset, keys) of every FLVI (visibility) step track in the BFLAN at data[base:]."""
assert data[base:base + 4] == b'FLAN' and data[base + 4:base + 6] == b'\xff\xfe'
pos, out = base + 0x14, []
for _ in range(struct.unpack_from('<H', data, base + 0x10)[0]):
magic, size = data[pos:pos + 4], struct.unpack_from('<I', data, pos + 4)[0]
if magic == b'pai1':
count, table = struct.unpack_from('<H', data, pos + 14)[0], pos + struct.unpack_from('<I', data, pos + 16)[0]
for e in range(count):
eo = pos + struct.unpack_from('<I', data, table + 4 * e)[0]
name = data[eo:eo + 28].split(b'\0')[0].decode()
for t in range(data[eo + 28]):
to = eo + struct.unpack_from('<I', data, eo + 32 + 4 * t)[0]
if data[to:to + 4] != b'FLVI':
continue
for g in range(data[to + 4]):
go = to + struct.unpack_from('<I', data, to + 8 + 4 * g)[0]
assert data[go + 2] == 1, 'visibility tracks are step curves'
ko = go + struct.unpack_from('<I', data, go + 8)[0]
keys = [struct.unpack_from('<fH', data, ko + 8 * k)
for k in range(struct.unpack_from('<H', data, go + 4)[0])]
out.append((name, ko, keys))
pos += size
return out
def bntx_swap(data, base, pairs):
"""Swap the image data of each (name, name) pair of textures in the BNTX at data[base:] (names without the ^
suffix). Both of a pair must have the same header from flags to layout (format, size, tiling, mips) and image
size, so the bytes of one are a valid image of the other."""
assert data[base:base + 4] == b'BNTX' and data[base + 0x20:base + 0x24] == b'NX '
count, table = struct.unpack_from('<IQ', data, base + 0x24)
found = {}
for k in range(count):
info = base + struct.unpack_from('<Q', data, base + table + 8 * k)[0]
assert data[info:info + 4] == b'BRTI'
name = base + struct.unpack_from('<Q', data, info + 0x60)[0]
name = data[name + 2:name + 2 + struct.unpack_from('<H', data, name)[0]].decode().split('^')[0]
mips = base + struct.unpack_from('<Q', data, info + 0x70)[0]
shape = bytes(data[info + 0x10:info + 0x3c]) + bytes(data[info + 0x50:info + 0x54])
start, size = base + struct.unpack_from('<Q', data, mips)[0], struct.unpack_from('<I', data, info + 0x50)[0]
found[name] = (shape, start, size)
for a, b in pairs:
assert a in found and b in found, f'{a} or {b} missing from the texture list'
(shape_a, at_a, size), (shape_b, at_b, _) = found[a], found[b]
assert shape_a == shape_b, f'{a} and {b} differ in format, size or tiling'
data[at_a:at_a + size], data[at_b:at_b + size] = data[at_b:at_b + size], data[at_a:at_a + size]
def bflyt_letters(data, base, end, swap):
"""Swap the text of the one-letter text panes T_<letter>_<n> (A, B, X or Y) in the BFLYT at data[base:end] by
swap (letter -> letter); the names of the panes changed. Same length (one UTF-16 letter and its terminator)."""
assert data[base:base + 4] == b'FLYT'
pos, changed = base + struct.unpack_from('<H', data, base + 6)[0], []
while pos + 8 <= end:
magic, size = data[pos:pos + 4], struct.unpack_from('<I', data, pos + 4)[0]
if magic == b'txt1':
name = data[pos + 12:pos + 36].split(b'\0')[0].decode()
length = struct.unpack_from('<H', data, pos + 0x56)[0]
at = pos + struct.unpack_from('<I', data, pos + 0x64)[0]
letter = data[at:at + 2].decode('utf-16-le') if length == 4 and at > pos else ''
if letter in swap and re.fullmatch(r'T_[ABXY]_\d+', name):
data[at:at + 2] = swap[letter].encode('utf-16-le')
changed.append(name)
if not size:
break
pos += size
return changed
def msbt_letters(data, swap):
"""Swap the one-letter messages labelled T_<letter>_<n> (A, B, X or Y) in the UTF-16 MSBT data (a bytearray) by
swap; the labels changed. The game sets a layout's text panes from the messages of the same name in
Mals/<language>/LayoutMsg/<layout>.msbt, over the text stored in the layout."""
assert data[:8] == b'MsgStdBn' and data[0x0c] == 1, 'not a UTF-16 MSBT'
sections, pos = {}, 0x20
for _ in range(struct.unpack_from('<H', data, 0x0e)[0]):
size = struct.unpack_from('<I', data, pos + 4)[0]
sections[bytes(data[pos:pos + 4])] = (pos + 16, size)
pos = (pos + 16 + size + 15) & ~15
labels, (base, _) = {}, sections[b'LBL1']
for g in range(struct.unpack_from('<I', data, base)[0]):
count, at = struct.unpack_from('<II', data, base + 4 + 8 * g)
at += base
for _ in range(count):
length = data[at]
labels[struct.unpack_from('<I', data, at + 1 + length)[0]] = data[at + 1:at + 1 + length].decode()
at += 1 + length + 4
(base, size), changed = sections[b'TXT2'], []
count = struct.unpack_from('<I', data, base)[0]
offsets = list(struct.unpack_from(f'<{count}I', data, base + 4)) + [size]
for i in range(count):
at, length = base + offsets[i], offsets[i + 1] - offsets[i]
letter = data[at:at + 2].decode('utf-16-le') if length == 4 else ''
if letter in swap and re.fullmatch(r'T_[ABXY]_\d+', labels.get(i, '')):
data[at:at + 2] = swap[letter].encode('utf-16-le')
changed.append(labels[i])
return changed
def cff_index(data, pos):
"""([(start, end)] of every item, offSize, end) of the CFF INDEX at data[pos:]."""
count = struct.unpack_from('>H', data, pos)[0]
if not count:
return [], 0, pos + 2
size = data[pos + 2]
offsets = [int.from_bytes(data[pos + 3 + i * size:pos + 3 + (i + 1) * size], 'big') for i in range(count + 1)]
first = pos + 2 + (count + 1) * size
return [(first + offsets[i], first + offsets[i + 1]) for i in range(count)], size, first + offsets[-1]
def cff_charstrings(data, cff):
"""The offset (from the CFF table) of the CharStrings INDEX: operator 17 of the Top DICT. CID-keyed fonts (ROS,
operator 12 30) are refused: their glyphs can use different private dictionaries."""
_, _, pos = cff_index(data, cff + data[cff + 2]) # Name INDEX after the header
top, _, _ = cff_index(data, pos)
(pos, end), operands, found = top[0], [], None
while pos < end:
b = data[pos]
if b <= 21:
op = (12, data[pos + 1]) if b == 12 else b
pos += 2 if b == 12 else 1
assert op != (12, 30), 'CID-keyed CFF'
if op == 17:
found = operands[-1]
operands = []
elif b == 28:
operands.append(struct.unpack_from('>h', data, pos + 1)[0]); pos += 3
elif b == 29:
operands.append(struct.unpack_from('>i', data, pos + 1)[0]); pos += 5
elif b == 30: # real number: nibbles up to an 0xf
pos += 1
while data[pos] & 0x0f != 0x0f and data[pos] & 0xf0 != 0xf0:
pos += 1
pos += 1
operands.append(0)
elif b <= 246:
operands.append(b - 139); pos += 1
elif b <= 250:
operands.append((b - 247) * 256 + data[pos + 1] + 108); pos += 2
else:
operands.append(-(b - 251) * 256 - data[pos + 1] - 108); pos += 2
assert found is not None, 'no CharStrings in the Top DICT'
return found
def otf_glyph(data, cmap, code):
"""The glyph id of a code point in the format 4 (platform 3 encoding 1) subtable of the cmap at data[cmap:]."""
for k in range(struct.unpack_from('>H', data, cmap + 2)[0]):
platform, encoding, offset = struct.unpack_from('>HHI', data, cmap + 4 + 8 * k)
p = cmap + offset
if (platform, encoding) != (3, 1) or struct.unpack_from('>H', data, p)[0] != 4:
continue
seg = struct.unpack_from('>H', data, p + 6)[0] // 2
for s in range(seg):
end = struct.unpack_from('>H', data, p + 14 + 2 * s)[0]
start = struct.unpack_from('>H', data, p + 16 + 2 * seg + 2 * s)[0]
if not start <= code <= end:
continue
delta = struct.unpack_from('>h', data, p + 16 + 4 * seg + 2 * s)[0]
at = p + 16 + 6 * seg + 2 * s
ro = struct.unpack_from('>H', data, at)[0]
glyph = code if not ro else struct.unpack_from('>H', data, at + ro + 2 * (code - start))[0]
return (glyph + delta) & 0xffff if glyph else 0
raise AssertionError(f'U+{code:04X} is not in the font')
def otf_checksum(data):
data = bytes(data) + bytes(-len(data) % 4)
return sum(struct.unpack(f'>{len(data) // 4}I', data)) & 0xffffffff
def bfotf_swap(data, pairs):
"""The BFOTF data with the glyphs of each (code point, code point) pair swapped: CFF outlines and horizontal
metrics, then the table checksums. A BFOTF is an OpenType font after an 8-byte header; from offset 4 on, every
4-byte word is XORed with one key, which the size field gives away (it holds the font's length)."""
key = bytes(x ^ y for x, y in zip(data[4:8], struct.pack('>I', len(data) - 8)))
plain = bytearray(data[:4]) + bytearray(x ^ key[i % 4] for i, x in enumerate(data[4:]))
font = plain[8:]
assert font[:4] == b'OTTO', 'not a CFF OpenType font'
tables = {}
for k in range(struct.unpack_from('>H', font, 4)[0]):
tag, _, offset, length = struct.unpack_from('>4sIII', font, 12 + 16 * k)
tables[tag] = (12 + 16 * k, offset, length)
cff = tables[b'CFF '][1]
strings, size, end = cff_index(font, cff + cff_charstrings(font, cff))
hmtx, metrics = tables[b'hmtx'][1], struct.unpack_from('>H', font, tables[b'hhea'][1] + 34)[0]
order = list(range(len(strings)))
for a, b in pairs:
ga, gb = otf_glyph(font, tables[b'cmap'][1], a), otf_glyph(font, tables[b'cmap'][1], b)
assert 0 < ga < len(strings) and 0 < gb < len(strings) and ga < metrics and gb < metrics, (a, b, ga, gb)
order[ga], order[gb] = order[gb], order[ga]
ma, mb = hmtx + 4 * ga, hmtx + 4 * gb
font[ma:ma + 4], font[mb:mb + 4] = font[mb:mb + 4], font[ma:ma + 4]
# The CharStrings INDEX again with the items in the new order: the same length, so nothing after it moves.
body = b''.join(bytes(font[slice(*strings[g])]) for g in order)
first = strings[0][0]
assert first + len(body) == end
font[first:end] = body
at, base = first - (len(strings) + 1) * size, 1 # the offset array ends where the first item starts
for i, g in enumerate(order + [None]):
font[at + i * size:at + (i + 1) * size] = base.to_bytes(size, 'big')
if g is not None:
base += strings[g][1] - strings[g][0]
head = tables[b'head'][1]
struct.pack_into('>I', font, head + 8, 0)
for entry, offset, length in tables.values():
struct.pack_into('>I', font, entry + 4, otf_checksum(font[offset:offset + length]))
struct.pack_into('>I', font, head + 8, (0xb1b0afba - otf_checksum(font)) & 0xffffffff)
plain[8:] = font
return bytes(plain[:4]) + bytes(x ^ key[i % 4] for i, x in enumerate(plain[4:]))
def sarc_replace(data, new):
"""The SARC data with the members named in new (name -> bytes) replaced. The header, SFAT and SFNT stay; the
members are laid out again in their old order, each at an offset with at least the alignment its old one had."""
start = struct.unpack_from('<I', data, 12)[0]
out = bytearray(data[:start])
for name, node, lo, hi in sorted(sarc_nodes(data), key=lambda n: n[2]):
align = min(lo & -lo, 0x2000) if lo else 0x2000
out += bytes(-len(out) % align)
body = new.get(name, data[lo:hi])
struct.pack_into('<II', out, node + 8, len(out) - start, len(out) - start + len(body))
out += body
struct.pack_into('<I', out, 8, len(out))
return bytes(out)
COMMON = {'v121': '110', 'v143': '140'} # the version in the name of each game's Common archive
ARCHIVE = f'UI/LayoutArchive/Common.Product.{COMMON[args.version]}.Nin_NX_NVN.blarc.zs'
MEMBERS = {
'anim/ShortCutBG_00_In.bflan': ('C_CaptureBG_00', 'C_CaptureClearBG_00', 'P_CaptureClearBG_00'),
'anim/AutoBuilder_00_In.bflan': ('C_CaptureBG_00',),
}
KEY_TEXTURES = (('Nt_KeyTexA_00', 'Nt_KeyTexB_00'), ('Nt_KeyTexX_00', 'Nt_KeyTexY_00'))
KEY_GLYPHS = ((0xE040, 0xE041), (0xE042, 0xE043)) # A B, X Y in scft/External.bfotf
KEY_LETTERS = {'A': 'B', 'B': 'A', 'X': 'Y', 'Y': 'X'} # the face-button diamond around the action prompt
FONTS = sorted(p for p in files if re.fullmatch(r'Font/Font(_\w+)?\.Nin_NX_NVN\.bfarc\.zs', p))
# The message archive of each language: the newest version in the RomFS (Mals/USen.Product.121.sarc.zs on 1.2.1).
MALS = {}
for p in files:
m = re.fullmatch(r'Mals/(\w+)\.Product\.(\d+)\.sarc\.zs', p)
if m and int(m[2]) > MALS.get(m[1], (0, ''))[0]:
MALS[m[1]] = (int(m[2]), p)
MALS = sorted(p for _, p in MALS.values())
LAYOUT_MSG = 'LayoutMsg/DoCommand_00.msbt'
with (args.romfs / 'romfs.bin').open('rb') as image:
def read(path):
f = files[path]
image.seek(f['offset'])
b = image.read(f['size'])
assert len(b) == f['size']
return b
dictionaries = {}
pack = zstd.decompress(read('Pack/ZsDic.pack.zs'))
for name, (lo, hi) in sarc_members(pack).items():
d = zstd.ZstdDict(pack[lo:hi])
dictionaries[d.dict_id] = d
originals = {path: read(path) for path in [ARCHIVE] + (FONTS + MALS if args.xbox_prompts else [])}
raw = originals[ARCHIVE]
info = zstd.get_frame_info(raw)
dictionary = dictionaries[info.dictionary_id]
original = zstd.decompress(raw, zstd_dict=dictionary)
blarc = bytearray(original)
assert len(blarc) == info.decompressed_size
members = sarc_members(blarc)
patched = {}
for member, panes in MEMBERS.items():
lo, hi = members[member]
changed = []
for name, ko, keys in flvi_keys(blarc, lo):
if name not in panes:
continue
assert [(f, v) for f, v in keys] == [(0.0, 0), (1.0, 1)], (member, name, keys)
struct.pack_into('<f', blarc, ko + 8, 0.0)
changed.append(name)
assert sorted(changed) == sorted(panes), (member, changed)
patched[member] = changed
diff = [i for i in range(len(original)) if original[i] != blarc[i]]
assert diff and all(any(lo <= i < hi for lo, hi in (members[m] for m in MEMBERS)) for i in diff), diff
outputs = {ARCHIVE: bytes(blarc)} # RomFS path -> new contents (before compression)
if args.xbox_prompts:
bntx_swap(blarc, members['timg/__Combined.bntx'][0], KEY_TEXTURES)
letters = {}
for member, (lo, hi) in members.items():
if member.endswith('.bflyt'):
changed = bflyt_letters(blarc, lo, hi, KEY_LETTERS)
if changed:
letters[member] = changed
assert 'blyt/DoCommand_00.bflyt' in letters, 'no letter panes in blyt/DoCommand_00.bflyt'
outputs[ARCHIVE] = bytes(blarc)
assert FONTS, 'no Font/Font*.Nin_NX_NVN.bfarc.zs in the RomFS'
for path in FONTS:
frame = zstd.get_frame_info(originals[path])
bfarc = zstd.decompress(originals[path], zstd_dict=dictionaries.get(frame.dictionary_id))
lo, hi = sarc_members(bfarc)['scft/External.bfotf']
outputs[path] = sarc_replace(bfarc, {'scft/External.bfotf': bfotf_swap(bfarc[lo:hi], KEY_GLYPHS)})
assert MALS, 'no Mals/<language>.Product.<version>.sarc.zs in the RomFS'
messages = {}
for path in MALS:
frame = zstd.get_frame_info(originals[path])
mals = bytearray(zstd.decompress(originals[path], zstd_dict=dictionaries.get(frame.dictionary_id)))
lo, hi = sarc_members(mals)[LAYOUT_MSG]
msbt = bytearray(mals[lo:hi])
changed = msbt_letters(msbt, KEY_LETTERS)
assert len(changed) == sum(len(v) for v in letters.values()), (path, changed)
mals[lo:hi] = msbt
outputs[path] = bytes(mals)
messages[path] = len(changed)
lines = []
for path, contents in outputs.items():
raw = originals[path]
dictionary = dictionaries.get(zstd.get_frame_info(raw).dictionary_id)
data = zstd.compress(contents, level=19, zstd_dict=dictionary)
assert zstd.decompress(data, zstd_dict=dictionary) == contents
assert zstd.get_frame_info(data).dictionary_id == zstd.get_frame_info(raw).dictionary_id
target = args.out / path
target.parent.mkdir(parents=True, exist_ok=True)
target.write_bytes(data)
lines.append('\t'.join([path, str(len(data)), hashlib.sha256(data).hexdigest(), hashlib.sha256(raw).hexdigest()]))
(args.out / 'manifest.tsv').write_text('# path\tsize\tsha256\toriginal_sha256 (tools/make_romfs_patches.py)\n'
+ ''.join(line + '\n' for line in lines))
print(json.dumps(dict(status='pass', path=ARCHIVE, members=patched, changed_bytes=len(diff),
xbox_prompts=dict(textures=KEY_TEXTURES, letters=letters, messages=messages, fonts=FONTS)
if args.xbox_prompts else None)))