HRiggs/KnoxBuildWorksViewpoint
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Intial Commit

Browse Source
This commit is contained in:
Hudson Riggs
2026-10-27 17:12:43 -04:00
parent b29ea9faf3
commit 288ce560f3
75 changed files with 120505 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files
tools/Match-KnoxViewpoint.py
+582
View File
@@ -0,0 +1,582 @@
"""Build a private local Viewpoint compatibility pack and an evidence-based catalogue audit.
Python 3.10+ and Pillow. Never changes Workshop files, saves, recipes or sprite IDs.
"""
from __future__ import annotations
import argparse
import collections
import copy
import hashlib
import io
import json
import re
import shutil
import struct
from pathlib import Path
from PIL import Image
MOD_ID = 'KnoxBuildworksViewpointCrates' # Retain the ID of the previously installed patch.
HERE = Path(__file__).resolve().parent
REPO_ROOT = HERE.parent
VERSION_FOLDER = '42.20'
SPRITE = re.compile(r'^[A-Za-z][A-Za-z0-9_-]*_\d+$')
SEMANTICS = ('CustomName', 'GroupName', 'MoveType', 'container', 'WindowShape')
SHAPES = re.compile(r'\b(box|polygon|cylinder)\s*\{')
def read_json(path):
return json.loads(Path(path).read_text(encoding='utf-8-sig'))
def write_json(path, value):
path.parent.mkdir(parents=True, exist_ok=True)
path.write_text(json.dumps(value, indent=2, ensure_ascii=False)+'\n', encoding='utf-8')
def family(sprite):
return sprite.removeprefix('kbw_').rsplit('_', 1)[0]
def merge(parent, child):
if isinstance(parent, dict) and isinstance(child, dict):
out = copy.deepcopy(parent)
for key, value in child.items():
out[key] = merge(out.get(key), value)
return out
return copy.deepcopy(child)
def tile_properties(path):
"""Read the installed game's tdef v1 format, including custom tiles and patches."""
out = {}
with path.open('rb') as stream:
def integer():
return struct.unpack('<i', stream.read(4))[0]
def string():
return stream.readline().decode('latin1').strip()
if stream.read(4) != b'tdef' or integer() != 1:
raise ValueError(f'Unsupported tile format: {path}')
count = integer()
if not 0 <= count <= 10000:
raise ValueError('Invalid tileset count')
for _ in range(count):
name, _image = string(), string()
width, height, number = integer(), integer(), integer()
for index in range(integer()):
properties = {}
for _ in range(integer()):
key, value = string(), string()
properties[key] = value
out[f'{name}_{index}'] = properties
if stream.read():
raise ValueError(f'Unparsed tile data: {path}')
return out
def geometry(path):
text = path.read_text(encoding='utf-8-sig')
# Canonical comments identify tiles; do not mistake a properties-only block for geometry.
blocks = {}
for m in re.finditer(r'/\*\s*(\w+_\d+)\s*\*/\s*tile\s*\{(.*?)(?=/\*|\Z)', text, re.S):
if SHAPES.search(m[2]):
body = re.sub(r'properties\s*\{[^{}]*\}', '', m[2])
body = re.sub(r'xy\s*=\s*[^,]+,', '', body)
# Remove closing tileset/root braces from the final tile in a sheet.
body = body[:body.rfind('}')].strip()
blocks[m[1]] = re.sub(r'\s+', '', body).rstrip('}')
return blocks
def load_bindings(workshop):
mod = workshop/'3810302175/mods/PZVoxelStudioViewpoint'
root = mod/'common/media/voxel-studio'
registration = (mod/'common/media/lua/client/PZVoxelStudioViewpoint.lua').read_text(encoding='utf-8-sig')
manifests = re.findall(r'"media/voxel-studio/([^"\r\n]+\.properties)"', registration)
if not manifests:
raise ValueError('No registered model manifests found')
bindings = {}
for name in manifests:
entries = {}
for line in (root/name).read_text(encoding='utf-8-sig').splitlines():
if line.strip() and not line.lstrip().startswith('#') and '=' in line:
key, value = line.split('=', 1)
entries[key.strip()] = value.strip()
models = {k[6:]:v for k,v in entries.items() if k.startswith('model.')}
for key, value in entries.items():
if not key.startswith('bind.'):
continue
fields = value.split(',')
if len(fields) != 6 or fields[0] not in models:
raise ValueError(f'Invalid binding {key} in {name}')
[float(v) for v in fields[1:]]
bindings[key[5:]] = dict(value=value, model=fields[0], path=models[fields[0]], manifest=name)
return root, bindings
def load_catalogue(workshop):
templates, raw, sources, patches = {}, {}, {}, {}
for folder in ('KnoxBuildworks', 'KnoxBuildworks_Vanilla_Expanded'):
root = workshop/'3772269882/mods'/folder/'42'
manifest = read_json(root/'media/KnoxBuildworks/manifest.json')
for relative in manifest['definitions']:
data = read_json(root/relative)
templates.update(data.get('templates', {}))
for key, value in data.get('patches', {}).items():
patches[key] = merge(patches.get(key,{}), value)
for item in data.get('buildables', []):
raw[item['id']] = item
sources[item['id']] = f'{folder}/{relative}'
def resolve(value, seen=()):
parent = value.get('extends')
if not parent:
return copy.deepcopy(value)
if parent in seen or parent not in templates:
raise ValueError(f'Unknown or cyclic template: {parent}')
return merge(resolve(templates[parent], (*seen, parent)), value)
out = []
for key,value in raw.items():
item = resolve(value)
item = merge(item, patches.get(key,{}))
for stage in item.get('stages',[]):
if stage.get('sprites'):
continue
directional = stage.get('directionalSprites',item.get('directionalSprites'))
if directional:
stage['sprites'] = copy.deepcopy(directional)
continue
pattern = stage.get('spritePattern',item.get('spritePattern'))
if pattern:
prefix = pattern.get('prefix',item.get('spritePrefix',''))
suffix = pattern.get('suffix',item.get('spriteSuffix',''))
expanded={d:prefix+str(token)+suffix for d,token in pattern.get('directions',{}).items()}
if 'start' in pattern:
directions=stage.get('rotations',item.get('rotations',['W','N','E','S']))
expanded.update({d:prefix+str(pattern['start']+i*pattern.get('step',1))+suffix for i,d in enumerate(directions)})
stage['sprites']=expanded
item['_source'] = sources[key]
out.append(item)
return out
def sprite_strings(value):
if isinstance(value, str) and SPRITE.fullmatch(value):
yield value
elif isinstance(value, dict):
for key, child in value.items():
if key in ('id','name','displayName','translationKey','tooltipKey','requirements','construction','tags'):
continue
yield from sprite_strings(child)
elif isinstance(value, list):
for child in value:
yield from sprite_strings(child)
def braced_body(text, start):
depth=1
for index in range(start,len(text)):
if text[index]=='{': depth+=1
elif text[index]=='}':
depth-=1
if depth==0: return text[start:index]
raise ValueError('Unbalanced entity script block')
def load_entity_sprites(game, workshop):
entities={}
roots=[game/'scripts', workshop/'3772269882/mods/KnoxBuildworks/common/media/scripts',
workshop/'3772269882/mods/KnoxBuildworks/42/media/scripts']
for root in roots:
if not root.exists(): continue
for path in sorted(root.rglob('*.txt')):
text=path.read_text(encoding='utf-8-sig',errors='replace')
if not re.search(r'\bentity\s+',text): continue
text=re.sub(r'/\*.*?\*/|//[^\n]*','',text,flags=re.S)
module=re.search(r'\bmodule\s+([\w.]+)\s*\{',text)
if not module: continue
for match in re.finditer(r'\bentity\s+([\w.]+)\s*\{',text):
body=braced_body(text,match.end())
entities[f'{module[1]}.{match[1]}']=set()
sprite_config=re.search(r'\bcomponent\s+SpriteConfig\s*\{',body)
if sprite_config:
config=braced_body(body,sprite_config.end())
sprites=set()
for row in re.findall(r'\brow\s*=\s*([^,\n]+)',config):
sprites.update(s for s in row.split() if SPRITE.fullmatch(s))
entities[f'{module[1]}.{match[1]}']=sprites
return entities
def entity_references(value):
if isinstance(value,dict):
ref=value.get('entityCompat')
if isinstance(ref,dict) and ref.get('entity'):
yield ref.get('module','Base')+'.'+ref['entity']
for child in value.values(): yield from entity_references(child)
elif isinstance(value,list):
for child in value: yield from entity_references(child)
class Textures:
"""Read pack metadata without loading the game; keep at most two atlas pages in memory."""
def __init__(self, paths):
self.index = {}
self.pages = collections.OrderedDict()
for path in paths:
with path.open('rb') as stream:
def integer(): return struct.unpack('<I', stream.read(4))[0]
def string(): return stream.read(integer()).decode('latin1')
if stream.read(4) != b'PZPK' or integer() != 1:
raise ValueError(f'Unsupported texture pack: {path}')
for _ in range(integer()):
page, count, alpha = string(), integer(), integer()
subs = []
for _ in range(count):
name = string()
subs.append((name, struct.unpack('<8i', stream.read(32))))
length = integer()
position = stream.tell()
stream.seek(length, 1)
for name, rect in subs:
self.index[name] = dict(file=path, position=position, length=length, rect=rect)
if stream.read():
raise ValueError(f'Unparsed texture data: {path}')
def sprite(self, name):
row = self.index[name]
key = row['file'], row['position']
if key not in self.pages:
with row['file'].open('rb') as stream:
stream.seek(row['position'])
self.pages[key] = Image.open(io.BytesIO(stream.read(row['length']))).convert('RGBA')
while len(self.pages) > 2:
self.pages.popitem(last=False)
self.pages.move_to_end(key)
x,y,w,h,*_ = row['rect']
return self.pages[key].crop((x,y,x+w,y+h))
def fingerprints(self, names):
groups = collections.defaultdict(list)
out = {}
for name in set(names) & self.index.keys():
row = self.index[name]
groups[(row['file'], row['position'])].append(name)
for group in groups.values():
for name in group:
image = self.sprite(name)
box = image.getbbox()
if not box:
continue
image = image.crop(box)
# Ignore invisible RGB bytes, while retaining alpha and object anchor.
clean = Image.new('RGBA', image.size)
clean.paste(image, mask=image.getchannel('A').point(lambda a: 255 if a else 0))
x,y,w,h,ox,oy,fx,fy = self.index[name]['rect']
out[name] = (image.size, ox+box[0], oy+box[1], fx, fy, hashlib.sha256(clean.tobytes()).hexdigest())
return out
def semantic_conflict(a, b):
return any(a.get(k) and b.get(k) and a[k] != b[k] for k in SEMANTICS)
def alias_matches(sprite, bindings, properties):
if not sprite.startswith('kbw_'):
return None
source = sprite[4:]
if source not in bindings:
return None
a,b = properties.get(sprite,{}), properties.get(source,{})
# Same index is not sufficient. In particular Knox white crates reuse vanilla sign indices.
if semantic_conflict(a,b):
return None
if not a.get('CustomName') or a.get('CustomName') != b.get('CustomName'):
return None
if a.get('container') != b.get('container'):
return None
return source
def native_route(sprite, properties, shapes):
p = properties.get(sprite,{})
if 'solidfloor' in p:
return 'native-floor', 'Game solidfloor flag; Viewpoint floor renderer'
if sprite.startswith(('roofs_', 'roofs_accents_')):
return 'native-roof-candidate', 'Roof tile family; uses Viewpoint roof system rather than a furniture binding; visual check needed'
if sprite in shapes:
return 'native-geometry', 'Installed tileGeometry.txt contains box/polygon/cylinder geometry'
if any(k in p for k in ('FloorOverlay','attachedFloor')):
return 'native-floor-overlay', 'Game floor overlay metadata; Viewpoint floor/decal renderer'
edge_flags = ('cutN','cutW','collideN','collideW','HoppableN','HoppableW','TallHoppableN','TallHoppableW',
'transparentN','transparentW','WallN','WallW','WallNW','WallNTrans','WallWTrans','WallNWTrans',
'DoorWallN','DoorWallW','WindowN','WindowW','doorN','doorW','windowN','windowW')
if any(k in p for k in edge_flags):
return 'native-edge', 'Game wall/door/window/fence edge flags; keep Viewpoint edge rendering'
return None
def candidates(sprite, bindings, properties, shapes):
p = properties.get(sprite,{})
out = []
for source, binding in bindings.items():
q = properties.get(source,{})
same_family = family(sprite) == family(source)
named = p.get('CustomName') and p.get('CustomName') == q.get('CustomName')
if not (same_family or named) or semantic_conflict(p,q):
continue
reasons, score = [],0
if same_family: score += 20; reasons.append('same tile family')
if named: score += 25; reasons.append('same CustomName')
if p.get('GroupName') and p.get('GroupName') == q.get('GroupName'):
score += 20; reasons.append('same GroupName')
if p.get('Facing') and p.get('Facing') == q.get('Facing'):
score += 10; reasons.append('same facing')
if p.get('MaterialType') and p.get('MaterialType') == q.get('MaterialType'):
score += 5; reasons.append('same material')
if sprite in shapes and shapes.get(sprite) == shapes.get(source):
score += 20; reasons.append('same native geometry')
if score >= 25:
out.append(dict(source=source, score=score, reasons=reasons))
# This deliberately ranks suggestions rather than applying shape/color guesses.
return sorted(out, key=lambda r:(-r['score'],r['source']))[:3]
def tint_texture(image, color):
"""Set the dominant painted surface to the requested RGB; preserve relative luminance and alpha."""
if not re.fullmatch(r'#[0-9a-fA-F]{6}',color):
raise ValueError(f'Invalid texture tint: {color}')
target=tuple(int(color[i:i+2],16) for i in (1,3,5))
image=image.convert('RGBA')
colors=collections.Counter()
raw=image.tobytes()
for pixel,count in collections.Counter(raw[i:i+4] for i in range(0,len(raw),4)).items():
r,g,b,a=pixel
if a>=128 and g>r and g>b and max(r,g,b)>25:
colors[(r,g,b)]+=count
if not colors:
raise ValueError('The requested green source atlas has no painted green surface')
base=colors.most_common(1)[0][0]
reference=Image.new('RGB',(1,1),base).convert('L').getpixel((0,0))
luminance=image.convert('L')
channels=[luminance.point([min(255,round(channel*value/reference)) for value in range(256)]) for channel in target]
return Image.merge('RGBA',(*channels,image.getchannel('A')))
def copy_asset(source_root, binding, media, white=False, tint=None):
source = (source_root/binding['path']).resolve()
source.relative_to(source_root.resolve())
tag = ('white-' if white else ('tint-'+tint[1:].lower()+'-' if tint else '')) + hashlib.sha256(str(source).encode()).hexdigest()[:16]
target = media/'knox-crates-assets'/tag/source.name
target.parent.mkdir(parents=True, exist_ok=True)
shutil.copy2(source,target)
for line in source.read_text(encoding='utf-8-sig').splitlines():
if not line.startswith('mtllib '):
continue
name = line.split(None,1)[1].strip()
material = (source.parent/name).resolve()
material.relative_to(source_root.resolve())
destination = target.parent/name
destination.parent.mkdir(parents=True,exist_ok=True)
shutil.copy2(material,destination)
for ml in material.read_text(encoding='utf-8-sig').splitlines():
if re.match(r'^map_\w+\s+',ml):
texture_name = ml.split(None,1)[1].strip()
texture = (material.parent/texture_name).resolve()
texture.relative_to(source_root.resolve())
texture_out = destination.parent/texture_name
texture_out.parent.mkdir(parents=True,exist_ok=True)
if tint:
tint_texture(Image.open(texture),tint).save(texture_out)
elif white:
# Reviewed white crate adaptation: reuse crate geometry and UVs, retain atlas alpha/detail.
image = Image.open(texture).convert('RGBA')
alpha = image.getchannel('A')
luminance = image.convert('L').point(lambda v: min(245, int(115 + v*0.65)))
Image.merge('RGBA',(luminance,luminance,luminance,alpha)).save(texture_out)
else:
shutil.copy2(texture,texture_out)
return target.relative_to(media).as_posix(), tag
def build_pack(output, source_root, bindings, assignments):
media=output/'common/media'
media.mkdir(parents=True,exist_ok=True)
lines=['id=knox-buildworks-viewpoint-crates','name=Knox Buildworks - Viewpoint Compatibility','version=2']
models={}
for target, assignment in sorted(assignments.items()):
binding=bindings[assignment['source']]
white=assignment.get('adaptation')=='white-crate'
tint=assignment.get('tint')
key=(binding['path'],white,tint)
if key not in models:
relative,tag=copy_asset(source_root,binding,media,white,tint)
model='kbw-'+tag
models[key]=model
lines.append(f'model.{model}={relative}')
_,*transform=binding['value'].split(',')
lines.append(f"bind.{target}={models[key]},{','.join(transform)}")
(media/'knox-viewpoint-crates.properties').write_text('\n'.join(lines)+'\n',encoding='utf-8')
info='\n'.join(['name=Knox Buildworks - Viewpoint Compatibility',f'id={MOD_ID}','author=Local compatibility patch',
'modversion=2.1.0','description=Green, gray-green (#626763) and white military crates. Gray crates use retextured green crate meshes.',
'require=KnoxBuildworks,Viewpoint,PZVoxelStudioViewpoint','loadAfter=KnoxBuildworks,PZVoxelStudioViewpoint,Viewpoint','versionMin=42.0',''])
(output/VERSION_FOLDER).mkdir(parents=True,exist_ok=True)
(output/VERSION_FOLDER/'mod.info').write_text(info,encoding='utf-8')
(output/'mod.info').write_text(info,encoding='utf-8')
lua='''-- Render bindings only. No recipe, object, inventory or save changes.
local registered = false
local warned = false
local function register()
if registered or not Viewpoint or not Viewpoint.ModelPacks then return end
local ok, result = pcall(Viewpoint.ModelPacks.register,
"KnoxBuildworksViewpointCrates", "media/knox-viewpoint-crates.properties")
if ok and result then
registered = true
print("[Knox Viewpoint Crates] Registered %COUNT% reviewed compatibility sprite bindings.")
elseif not warned then
warned = true
print("[Knox Viewpoint Crates] Model pack registration failed: " .. tostring(result))
end
end
Events.OnGameBoot.Add(register)
Events.OnGameStart.Add(register)
register()
'''.replace('%COUNT%',str(len(assignments)))
(media/'lua/client').mkdir(parents=True,exist_ok=True)
(media/'lua/client/ZZ_KnoxViewpointCrates.lua').write_text(lua,encoding='utf-8')
return len(models)
def main():
parser=argparse.ArgumentParser(description=__doc__)
parser.add_argument('--workshop-root',type=Path,default=Path('D:/SteamLibrary/steamapps/workshop/content/108600'))
parser.add_argument('--game-directory',type=Path,default=Path('D:/SteamLibrary/steamapps/common/ProjectZomboid'))
parser.add_argument('--output-directory',type=Path,default=REPO_ROOT)
parser.add_argument('--reports-directory',type=Path,default=REPO_ROOT/'reports')
parser.add_argument('--install',action='store_true')
parser.add_argument('--local-mods-directory',type=Path,default=Path.home()/'Zomboid/mods')
args=parser.parse_args()
game=args.game_directory/'media'
source_root,bindings=load_bindings(args.workshop_root)
catalogue=load_catalogue(args.workshop_root)
entities=load_entity_sprites(game,args.workshop_root)
properties={}
for path in [game/'newtiledefinitions.tiles',game/'tiledefinitions_erosion.tiles',game/'tiledefinitions_noiseworks.patch.tiles',
args.workshop_root/'3772269882/mods/KnoxBuildworks/common/media/knox_buildworks_pack.tiles']:
for name,p in tile_properties(path).items(): properties.setdefault(name,{}).update(p)
shapes=geometry(game/'tileGeometry.txt')
shapes.update(geometry(args.workshop_root/'3772269882/mods/KnoxBuildworks/common/media/tileGeometry.txt'))
all_sprites=set()
object_sprites={}
unresolved_entities={}
for item in catalogue:
# Include geometry/states/finishes/variants/materials inherited from templates; exclude mere icons.
relevant={k:item[k] for k in ('stages','geometry','sprites','finishes','variants','materials') if k in item}
object_sprites[item['id']]=set(sprite_strings(relevant))
for entity in set(entity_references(item)):
if entity in entities:
object_sprites[item['id']].update(entities[entity])
else:
unresolved_entities.setdefault(item['id'],[]).append(entity)
all_sprites.update(object_sprites[item['id']])
textures=Textures([game/'texturepacks/Tiles2x.pack',game/'texturepacks/Tiles2x.floor.pack',
args.workshop_root/'3772269882/mods/KnoxBuildworks/common/media/texturepacks/knox_buildworks_pack.pack'])
print(f'Read {len(catalogue)} catalogue entries, {len(all_sprites)} sprites and {len(bindings)} authored bindings.',flush=True)
fingerprints=textures.fingerprints(all_sprites | bindings.keys())
exact=collections.defaultdict(list)
for name in bindings:
if name in fingerprints: exact[fingerprints[name]].append(name)
assignments={}
decisions={}
manual=read_json(HERE/'reviewed-matches.json')
for name in sorted(all_sprites):
p=properties.get(name,{})
if name in bindings:
decisions[name]=dict(status='already-bound',source=name,evidence='Exact authored sprite binding')
continue
# Explicit reviewed choices override generic matching (including user-requested recolors).
alias=alias_matches(name,bindings,properties) if name not in manual['matches'] else None
if alias:
assignments[name]=dict(source=alias,method='automatic-alias')
decisions[name]=dict(status='automatic-match',source=alias,evidence='Prefix alias with matching object/container semantics')
continue
identical=[s for s in exact.get(fingerprints.get(name),[]) if not semantic_conflict(p,properties.get(s,{})) and family(name)==family(s)]
identities={(bindings[s]['path'],bindings[s]['value'].split(',',1)[1]) for s in identical}
if identical and len(identities)==1 and name not in manual['matches']:
source=sorted(identical)[0]
assignments[name]=dict(source=source,method='automatic-identical-art')
decisions[name]=dict(status='automatic-match',source=source,evidence='Identical anchored RGBA artwork, same tile family and compatible metadata')
continue
if name in manual['matches']:
review=manual['matches'][name]
if review['source'] not in bindings:
raise ValueError(f"Reviewed source disappeared: {review['source']}")
# Abort when either target/source meaning changes after a Workshop update.
expected=review.get('expectedTargetCustomName')
if expected and p.get('CustomName')!=expected:
raise ValueError(f'Reviewed target changed: {name}')
expected_source=review.get('expectedSourceCustomName')
if expected_source and properties.get(review['source'],{}).get('CustomName')!=expected_source:
raise ValueError(f'Reviewed source changed: {name}')
assignments[name]=dict(source=review['source'],method='manual-adaptation',adaptation=review.get('adaptation'),tint=review.get('tint'))
decisions[name]=dict(status='manual-adaptation',**review)
continue
native=native_route(name,properties,shapes)
if native:
decisions[name]=dict(status=native[0],evidence=native[1])
continue
suggestions=candidates(name,bindings,properties,shapes)
rule=next((r for r in manual['unmatchedReviews'] if re.fullmatch(r['pattern'],name)),None)
decisions[name]=dict(status='no-compatible-authored-model',candidates=suggestions,
evidence=rule['reason'] if rule else 'No exact or reviewed compatible asset; do not force a different object model',
reviewed=bool(rule))
# Include custom stacked sprites which are managed by the game's stack system, not just recipes.
for name,review in manual.get('extraSprites',{}).items():
if name not in properties: raise ValueError(f'Missing reviewed stack sprite: {name}')
if review['source'] not in bindings: raise ValueError(f'Missing reviewed stack model: {review["source"]}')
if properties[name].get('CustomName') != 'Crate' or properties.get(review['source'],{}).get('CustomName') != 'Crate':
raise ValueError(f'Reviewed stack meaning changed: {name}')
assignments[name]=dict(source=review['source'],method=review['method'],adaptation=review.get('adaptation'),tint=review.get('tint'))
decisions[name]=dict(status=review['method'],**review)
model_count=build_pack(args.output_directory,source_root,bindings,assignments)
counts=dict(collections.Counter(d['status'] for d in decisions.values()))
objects=[]
for item in catalogue:
sprites=sorted(object_sprites[item['id']])
counts_for_object=collections.Counter(decisions[s]['status'] for s in sprites)
if not sprites: counts_for_object['no-static-sprite-reference']=1
objects.append(dict(id=item['id'],name=item.get('displayName',item['id']),category=item.get('category',''),
source=item['_source'],statuses=dict(counts_for_object),sprites=sprites,
unresolvedEntityReferences=unresolved_entities.get(item['id'],[])))
summary=dict(catalogueEntries=len(catalogue),entriesWithResolvedSprites=sum(bool(o['sprites']) for o in objects),uniqueSprites=len(decisions),
authoredPackBindings=len(bindings),patchBindings=len(assignments),copiedModels=model_count,statusCounts=counts,
note='Native routes describe installed geometry/metadata, not verified in-game appearance. Roof family matches require visual checks. No-compatible-model entries have no accepted model assignment.')
summary['unresolvedEntityReferences']=unresolved_entities
gap_objects=[o for o in objects if o['statuses'].get('no-compatible-authored-model',0)]
summary['buildablesWithReviewedModelGaps']=len(gap_objects)
summary['unreviewedGapSprites']=sum(d['status']=='no-compatible-authored-model' and not d.get('reviewed') for d in decisions.values())
write_json(args.reports_directory/'summary.json',summary)
write_json(args.reports_directory/'sprite-decisions.json',decisions)
write_json(args.reports_directory/'buildable-coverage.json',objects)
write_json(args.reports_directory/'applied-matches.json',assignments)
lines=['# Matching results','',f"Scanned {len(catalogue)} catalogue entries; added {len(assignments)} sprite bindings.",'',
'Native geometry is recorded separately from authored model matches. File analysis is not an in-game visual test.','',
'## Applied matches','']
for target,a in sorted(assignments.items()): lines.append(f"- `{target}` -> `{a['source']}` ({a['method']}{'; '+a['adaptation'] if a.get('adaptation') else ''})")
lines+=['','## Buildables still without a complete authored model match','',
'The reasons below identify native rendering routes and reviewed gaps. A native route is not an invisible object.','']
for item in sorted(objects,key=lambda a:(a['name'],a['id'])):
if not item['sprites']:
lines.append(f"- **{item['name']}** — `{item['id']}`: no static sprite reference; game action/runtime entity; not assigned a model")
continue
other=[s for s in item['sprites'] if decisions[s]['status'] not in ('already-bound','automatic-match','manual-adaptation')]
if not other: continue
statuses=collections.Counter(decisions[s]['status'] for s in other)
lines.append(f"- **{item['name']}** — `{item['id']}`: "+', '.join(f'{k}: {v}' for k,v in sorted(statuses.items())))
for sprite in other:
if decisions[sprite]['status']=='no-compatible-authored-model':
lines.append(f" - `{sprite}`: {decisions[sprite]['evidence']}")
(args.reports_directory/'results.md').write_text('\n'.join(lines)+'\n',encoding='utf-8')
gaps=['# Buildables without a complete accepted authored model match','',
f'{len(gap_objects)} buildables have one or more unresolved authored-model parts. These are reviewed gaps, not confirmed invisible objects. Native edge/depth/overlay rendering may still display them.','',
'The earlier audit counted ordinary native walls/floors/roofs as unmatched; those native routes are now recorded separately in results.md.','']
for item in sorted(gap_objects,key=lambda o:(o['name'],o['id'])):
gaps.append(f"## {item['name']}")
gaps.extend(['',f"`{item['id']}`",''])
for sprite in item['sprites']:
if decisions[sprite]['status']=='no-compatible-authored-model':
gaps.append(f"- `{sprite}`: {decisions[sprite]['evidence']}")
gaps.append('')
(args.reports_directory/'unmatched.md').write_text('\n'.join(gaps)+'\n',encoding='utf-8')
write_json(args.output_directory/'match-summary.json',summary)
if args.install:
destination=args.local_mods_directory/MOD_ID
if args.output_directory.resolve()!=destination.resolve():
# The output can be a Git repository. Install runtime files only, never .git/tools/reports.
destination.mkdir(parents=True,exist_ok=True)
for directory in ('common',VERSION_FOLDER):
shutil.copytree(args.output_directory/directory,destination/directory,dirs_exist_ok=True)
for filename in ('mod.info','match-summary.json'):
shutil.copy2(args.output_directory/filename,destination/filename)
print(f'Installed {destination}',flush=True)
print(json.dumps(summary,indent=2),flush=True)
if __name__=='__main__':
main()