"""Shared content identities and item presentation used by runtime and assets.""" import json import math import re from pathlib import Path PATH = Path(__file__).resolve().parents[2] / "catalog" / "content.json" SPECS = PATH.parent / "specs.json" FAMILIES = {"trainable", "gun", "turret", "vertical", "static", "truck", "light"} CLASSES = {"drone", "jet", "cruise", "supersonic", "ballistic"} MUZZLES = {"none", "patriot", "pantsir", "grid", "rails", "cells"} ENGINES = {"prop": {"type", "back", "size"}, "jet": {"type", "up", "back", "size"}, "rocket": {"type", "back", "size"}} MODEL = r"airdef:[a-z0-9_]+" def load(): data = json.loads(PATH.read_text(encoding="utf-8")) items = data["items"] ids = [item["id"] for item in items] if len(ids) != len(set(ids)): raise ValueError("duplicate item ID in content catalog") referenced = [] for group in (data["aircraft"], data["units"]): kinds = [entry["kind"] for entry in group] if len(kinds) != len(set(kinds)): raise ValueError("duplicate kind in content catalog") referenced.extend(entry["item"] for entry in group if entry["item"] is not None) if len(referenced) != len(set(referenced)) or not set(referenced) <= set(ids): raise ValueError("duplicate or unregistered content item") for item in items: if len(item["color"]) != 3 or any(not isinstance(c, int) or not 0 <= c <= 255 for c in item["color"]): raise ValueError(f"invalid icon color for {item['id']}") return data def load_sounds(): """Load stable event IDs and engine attenuation metadata.""" entries = json.loads((PATH.parent / "sounds.json").read_text(encoding="utf-8")) seen = set() for entry in entries: event, distance, far = entry["event"], entry["distance"], entry["far"] if not re.fullmatch(r"[a-z0-9_]+\.[a-z0-9_]+", event) or event in seen: raise ValueError(f"invalid or duplicate sound event {event!r}") if type(distance) is not int or distance <= 0 or type(far) is not bool: raise ValueError(f"invalid sound metadata for {event}") seen.add(event) names = [entry["event"].replace(".", "_") for entry in entries] if len(names) != len(set(names)): raise ValueError("sound event IDs collide as resource names") registered = [name for entry in entries for name in ([entry["event"], entry["event"] + "_far"] if entry["far"] else [entry["event"]])] if len(registered) != len(set(registered)): raise ValueError("sound event IDs collide with far variants") return entries def _exact(entry, keys, where): if not isinstance(entry, dict) or set(entry) != set(keys): got = sorted(entry) if isinstance(entry, dict) else type(entry).__name__ raise ValueError(f"{where}: expected keys {sorted(keys)}, got {got}") def _number(value, where, minimum=None): if isinstance(value, bool) or not isinstance(value, (int, float)) or not math.isfinite(value): raise ValueError(f"{where}: expected a finite number, got {value!r}") if minimum is not None and value < minimum: raise ValueError(f"{where}: {value!r} is below {minimum}") return value def _integer(value, where, minimum=0): if isinstance(value, bool) or not isinstance(value, int) or value < minimum: raise ValueError(f"{where}: expected an integer >= {minimum}, got {value!r}") return value def _text(value, where, pattern=None): if not isinstance(value, str) or not value: raise ValueError(f"{where}: expected a non-empty string") if pattern and not re.fullmatch(pattern, value): raise ValueError(f"{where}: {value!r} does not match {pattern}") return value def _sound(value, where, events): _text(value, where, r"[a-z0-9_]+\.[a-z0-9_]+") if value not in events: raise ValueError(f"{where}: sound event {value!r} is not registered in sounds.json") def _named_ref(value, where, named, kind): _exact(value, {"ref"}, where) name = value["ref"] if name not in named or named[name]["kind"] != kind: raise ValueError(f"{where}: unknown {kind} reference {name!r}") return name def _model_ref(value, where, named, kind): return f"NAMED_{_named_ref(value, where, named, kind).upper()}" def _parts(entry, where, named): _exact(entry, {"body", "launcher", "pack", "dish", "fixed", "spinner"}, where) _text(entry["body"], f"{where}.body", MODEL) for slot in ("launcher", "pack"): if entry[slot] is not None: _text(entry[slot], f"{where}.{slot}", MODEL) dish = entry["dish"] if dish is not None: if not isinstance(dish, list) or len(dish) != 4: raise ValueError(f"{where}.dish: expected [model, height, forward, tilt]") _text(dish[0], f"{where}.dish.model", MODEL) for i, v in enumerate(dish[1:], 1): _number(v, f"{where}.dish[{i}]") fixed = entry["fixed"] if isinstance(fixed, dict): _named_ref(fixed, f"{where}.fixed", named, "fixed") elif not isinstance(fixed, list): raise ValueError(f"{where}.fixed: expected a list or a named reference") else: for i, piece in enumerate(fixed): if not isinstance(piece, list) or len(piece) != 3: raise ValueError(f"{where}.fixed[{i}]: expected [model, height, back]") _text(piece[0], f"{where}.fixed[{i}].model", MODEL) _number(piece[1], f"{where}.fixed[{i}].height") _number(piece[2], f"{where}.fixed[{i}].back") spinner = entry["spinner"] if isinstance(spinner, dict): _named_ref(spinner, f"{where}.spinner", named, "spinner") elif spinner is not None: if not isinstance(spinner, list) or len(spinner) != 5: raise ValueError(f"{where}.spinner: expected [model, height, back, size, tilt]") _text(spinner[0], f"{where}.spinner.model", MODEL) for i, v in enumerate(spinner[1:], 1): _number(v, f"{where}.spinner[{i}]") def _muzzle(entry, where): if not isinstance(entry, dict) or entry.get("type") not in MUZZLES: raise ValueError(f"{where}: expected one of {sorted(MUZZLES)}") kind = entry["type"] keys = {"grid": {"type", "cols", "rows", "size"}, "rails": {"type", "xs"}}.get(kind, {"type"}) _exact(entry, keys, where) if kind == "grid": _integer(entry["cols"], f"{where}.cols", 1) _integer(entry["rows"], f"{where}.rows", 1) _number(entry["size"], f"{where}.size", 0) elif kind == "rails": xs = entry["xs"] if not isinstance(xs, list) or not xs: raise ValueError(f"{where}.xs: expected a non-empty list") for i, v in enumerate(xs): _number(v, f"{where}.xs[{i}]") def _rest_pitch(entry, where): if isinstance(entry, dict): _exact(entry, {"half_pi"}, where) _number(entry["half_pi"], f"{where}.half_pi") else: _number(entry, where) def load_specs(): """Load the numeric profiles shared by Rust and Python, validating every reference.""" return validate_specs(json.loads(SPECS.read_text(encoding="utf-8")), load(), {entry["event"] for entry in load_sounds()}) def validate_specs(data, content, events): """Check a specs document against the content identities and registered sound events. Nothing here names a unit or aircraft kind: a new type only needs its catalog entry. """ _exact(data, {"shared", "drones", "units", "missiles", "named"}, "specs.json") shared = data["shared"] _exact(shared, {"mobility", "flight", "logistics"}, "shared") _exact(shared["mobility"], {"drive_scale", "drive_ramp", "trainable", "vertical", "other"}, "shared.mobility") _number(shared["mobility"]["drive_scale"], "shared.mobility.drive_scale", 0) _number(shared["mobility"]["drive_ramp"], "shared.mobility.drive_ramp", 0) for family in ("trainable", "vertical", "other"): axes = shared["mobility"][family] if not isinstance(axes, list) or len(axes) != 2: raise ValueError(f"shared.mobility.{family}: expected [yaw, pitch]") for i, v in enumerate(axes): _number(v, f"shared.mobility.{family}[{i}]") _exact(shared["flight"], {"gravity", "block_split"}, "shared.flight") _number(shared["flight"]["gravity"], "shared.flight.gravity", 0) _number(shared["flight"]["block_split"], "shared.flight.block_split", 0) _exact(shared["logistics"], {"depot_reach", "handover", "truck_load", "stock_limit"}, "shared.logistics") _number(shared["logistics"]["depot_reach"], "shared.logistics.depot_reach", 0) _number(shared["logistics"]["handover"], "shared.logistics.handover", 0) _integer(shared["logistics"]["truck_load"], "shared.logistics.truck_load", 1) _integer(shared["logistics"]["stock_limit"], "shared.logistics.stock_limit", 1) named = data["named"] if not isinstance(named, dict): raise ValueError("named: expected an object") referenced = set() for name, entry in named.items(): where = f"named.{name}" _exact(entry, {"kind", "value"}, where) value = entry["value"] if not isinstance(value, list): raise ValueError(f"{where}.value: expected a list") if entry["kind"] == "fixed": for i, piece in enumerate(value): if not isinstance(piece, list) or len(piece) != 3: raise ValueError(f"{where}.value[{i}]: expected [model, height, back]") _text(piece[0], f"{where}.value[{i}].model", MODEL) _number(piece[1], f"{where}.value[{i}].height") _number(piece[2], f"{where}.value[{i}].back") elif entry["kind"] == "spinner": if len(value) != 5: raise ValueError(f"{where}: expected [model, height, back, size, tilt]") _text(value[0], f"{where}.model", MODEL) for i, v in enumerate(value[1:], 1): _number(v, f"{where}[{i}]") elif entry["kind"] == "pivot": if len(value) != 3: raise ValueError(f"{where}: expected [x, y, z]") for i, v in enumerate(value): _number(v, f"{where}[{i}]") else: raise ValueError(f"{where}.kind: expected fixed, spinner or pivot") missile_kinds = set() for i, entry in enumerate(data["missiles"]): where = f"missiles[{i}]" _exact(entry, {"kind", "model", "speed", "accel", "turn", "boost", "cold", "eject", "eject_drag", "pk", "fuse", "life", "scale", "flame", "rear", "seeker", "launch_sound", "voice"}, where) kind = _text(entry["kind"], f"{where}.kind", r"[A-Z][A-Za-z0-9]*") if kind in missile_kinds: raise ValueError(f"{where}: duplicate missile kind {kind}") missile_kinds.add(kind) _text(entry["model"], f"{where}.model", MODEL) for field in ("speed", "accel", "turn", "pk", "fuse", "scale", "flame", "rear", "seeker"): _number(entry[field], f"{where}.{field}", 0) _integer(entry["boost"], f"{where}.boost") _integer(entry["cold"], f"{where}.cold") _number(entry["eject"], f"{where}.eject", 0) _number(entry["eject_drag"], f"{where}.eject_drag", 0) _integer(entry["life"], f"{where}.life", 1) _sound(entry["launch_sound"], f"{where}.launch_sound", events) _exact(entry["voice"], {"event", "gain", "pitch"}, f"{where}.voice") _sound(entry["voice"]["event"], f"{where}.voice.event", events) _number(entry["voice"]["gain"], f"{where}.voice.gain", 0) _number(entry["voice"]["pitch"], f"{where}.voice.pitch", 0) drone_kinds = [] keys = set() for i, entry in enumerate(data["drones"]): where = f"drones[{i}]" _exact(entry, {"kind", "key", "name", "model", "speed", "turn", "cruise", "clearance", "dive", "warhead", "scale", "engine", "decoy", "stealth", "sound", "class", "ballistic", "rcs", "launch_sound"}, where) kind = _text(entry["kind"], f"{where}.kind", r"[A-Z][A-Za-z0-9]*") drone_kinds.append(kind) key = _text(entry["key"], f"{where}.key", r"[a-z0-9_]+") if key in keys: raise ValueError(f"{where}: duplicate key {key}") keys.add(key) _text(entry["name"], f"{where}.name") _text(entry["model"], f"{where}.model", MODEL) for field in ("speed", "turn", "cruise", "clearance", "dive", "scale", "stealth", "rcs"): _number(entry[field], f"{where}.{field}", 0) _integer(entry["warhead"], f"{where}.warhead") if not isinstance(entry["decoy"], bool): raise ValueError(f"{where}.decoy: expected a boolean") engine = entry["engine"] if not isinstance(engine, dict) or engine.get("type") not in ENGINES: raise ValueError(f"{where}.engine: expected one of {sorted(ENGINES)}") _exact(engine, ENGINES[engine["type"]], f"{where}.engine") for field in ENGINES[engine["type"]] - {"type"}: _number(engine[field], f"{where}.engine.{field}") _exact(entry["sound"], {"event", "pitch", "interval"}, f"{where}.sound") _sound(entry["sound"]["event"], f"{where}.sound.event", events) _number(entry["sound"]["pitch"], f"{where}.sound.pitch", 0) _integer(entry["sound"]["interval"], f"{where}.sound.interval", 1) if entry["class"] not in CLASSES: raise ValueError(f"{where}.class: expected one of {sorted(CLASSES)}") if entry["ballistic"] is not None: _number(entry["ballistic"], f"{where}.ballistic", 0) _sound(entry["launch_sound"], f"{where}.launch_sound", events) unit_kinds = [] used_missiles = set() for i, entry in enumerate(data["units"]): where = f"units[{i}]" _exact(entry, {"kind", "key", "name", "missile", "gun", "reload", "scale", "rest_pitch", "roles", "family", "parts", "mount", "pivot", "muzzle", "sensor", "mast"}, where) kind = _text(entry["kind"], f"{where}.kind", r"[A-Z][A-Za-z0-9]*") unit_kinds.append(kind) key = _text(entry["key"], f"{where}.key", r"[a-z0-9_]+") if key in keys: raise ValueError(f"{where}: duplicate key {key}") keys.add(key) _text(entry["name"], f"{where}.name") _integer(entry["reload"], f"{where}.reload") _number(entry["scale"], f"{where}.scale", 0) _rest_pitch(entry["rest_pitch"], f"{where}.rest_pitch") _integer(entry["roles"], f"{where}.roles") if entry["roles"] > 0x1F: raise ValueError(f"{where}.roles: mask out of range") if entry["family"] not in FAMILIES: raise ValueError(f"{where}.family: expected one of {sorted(FAMILIES)}") _parts(entry["parts"], f"{where}.parts", named) if not isinstance(entry["mount"], list) or len(entry["mount"]) != 2: raise ValueError(f"{where}.mount: expected [up, forward]") for j, v in enumerate(entry["mount"]): _number(v, f"{where}.mount[{j}]") pivot = entry["pivot"] if isinstance(pivot, dict): _model_ref(pivot, f"{where}.pivot", named, "pivot") elif not isinstance(pivot, list) or len(pivot) != 3: raise ValueError(f"{where}.pivot: expected [x, y, z] or a named reference") else: for j, v in enumerate(pivot): _number(v, f"{where}.pivot[{j}]") _muzzle(entry["muzzle"], f"{where}.muzzle") _number(entry["sensor"], f"{where}.sensor", 0) _number(entry["mast"], f"{where}.mast", 0) missile = entry["missile"] if missile is not None: _exact(missile, {"kind", "magazine", "min", "max", "interval"}, f"{where}.missile") used_missiles.add(_text(missile["kind"], f"{where}.missile.kind", r"[A-Z][A-Za-z0-9]*")) _integer(missile["magazine"], f"{where}.missile.magazine", 1) _number(missile["min"], f"{where}.missile.min", 0) _number(missile["max"], f"{where}.missile.max", 0) _integer(missile["interval"], f"{where}.missile.interval", 1) gun = entry["gun"] if gun is not None: _exact(gun, {"range", "track", "p", "bursts", "shell", "slew"}, f"{where}.gun") for field in ("range", "track", "p", "shell"): _number(gun[field], f"{where}.gun.{field}", 0) _integer(gun["bursts"], f"{where}.gun.bursts", 1) if not isinstance(gun["slew"], list) or len(gun["slew"]) != 2: raise ValueError(f"{where}.gun.slew: expected [yaw, pitch]") for j, v in enumerate(gun["slew"]): _number(v, f"{where}.gun.slew[{j}]", 0) if set(drone_kinds) != {entry["kind"] for entry in content["aircraft"]}: raise ValueError("specs.json drones and content.json aircraft disagree") if len(drone_kinds) != len(content["aircraft"]): raise ValueError("specs.json drones and content.json aircraft differ in count") if set(unit_kinds) != {entry["kind"] for entry in content["units"]}: raise ValueError("specs.json units and content.json units disagree") if len(unit_kinds) != len(content["units"]): raise ValueError("specs.json units and content.json units differ in count") missing = used_missiles - missile_kinds if missing: raise ValueError(f"units reference missiles without a profile: {sorted(missing)}") unused = missile_kinds - used_missiles if unused: raise ValueError(f"missile profiles are not carried by any unit: {sorted(unused)}") for entry in data["units"]: parts = entry["parts"] for slot in ("fixed", "spinner"): if isinstance(parts[slot], dict): referenced.add(parts[slot]["ref"]) if isinstance(entry["pivot"], dict): referenced.add(entry["pivot"]["ref"]) idle = set(named) - referenced if idle: raise ValueError(f"named part profiles are not referenced: {sorted(idle)}") return data def sound_events(entries): """Build the Minecraft sound event registry without generating audio.""" events = {} for entry in entries: event, distance = entry["event"], entry["distance"] name = event.replace(".", "_") events[event] = {"sounds": [{"name": f"airdef:{name}", "attenuation_distance": distance}]} if entry["far"]: events[event + "_far"] = {"sounds": [{"name": f"airdef:{name}_far", "attenuation_distance": int(distance * 1.6)}]} return events