"""Helpers for analysing captured discovery logs. Captures are large (tens of MB) and live outside the repository, so tests that use them skip themselves when none are available. Set ``AOSTATS_CAPTURE_GLOB`` to point at a different location, e.g.:: AOSTATS_CAPTURE_GLOB='/tmp/aostats-in-party*.jsonl' pytest tests Records are read from the ``photon_message`` stream rather than the decoder's ``game_message`` stream. That matters for opcode research: ``game_message`` only contains opcodes that ``src/decode/translate.py`` currently knows about, which is exactly the set we are trying to extend. """ import glob import json import os from dataclasses import dataclass from typing import Any, Dict, Iterator, List, Optional CAPTURE_GLOB_ENV = 'AOSTATS_CAPTURE_GLOB' DEFAULT_CAPTURE_GLOB = '/tmp/aostats-in-party-with-items-and-silver*.jsonl' # Opcodes under investigation, by Photon parameter id. EVENT_PARAM = 252 OPCODE_HEALTH_UPDATE = 6 OPCODE_DAMAGE_BATCH = 7 OPCODE_ENTITY_STATS = 18 @dataclass(frozen=True) class DecodedMessage: """A Photon message as captured, before opcode translation.""" timestamp: str kind: str opcode: Optional[int] params: Dict[str, Any] @dataclass(frozen=True) class DamageHit: """One damage or healing tick against a victim. ``opcode`` is retained so a hit can be attributed to either the scalar (``OPCODE_HEALTH_UPDATE``) or batched (``OPCODE_DAMAGE_BATCH``) encoding. """ timestamp: str opcode: int victim: Any attacker: Any delta: float health_after: Optional[float] def capture_glob() -> str: return os.getenv(CAPTURE_GLOB_ENV) or DEFAULT_CAPTURE_GLOB def capture_paths() -> List[str]: return sorted(path for path in glob.glob(capture_glob()) if not path.endswith('.app.log')) def captures_available() -> bool: return bool(capture_paths()) def param(params: Dict[str, Any], key: int, default: Any = None) -> Any: """Read a Photon parameter by numeric id (JSON keys are strings).""" return params.get(str(key), default) def byte_list(value: Any) -> List[int]: """Normalise a parameter that may arrive as raw bytes or a decoded list.""" if isinstance(value, dict) and 'bytes_hex' in value: raw = value['bytes_hex'] return [int(raw[i:i + 2], 16) for i in range(0, len(raw), 2)] if isinstance(value, list): return [v for v in value if isinstance(v, int)] return [] def iter_messages(path: str) -> Iterator[DecodedMessage]: """Yield every captured Photon message in ``path`` in arrival order.""" with open(path, encoding='utf-8', errors='replace') as log: for line in log: if '"photon_message"' not in line: continue try: record = json.loads(line) except json.JSONDecodeError: continue message = record.get('message') or {} params = message.get('params') or {} kind = message.get('kind') if kind == 'Event': opcode = param(params, EVENT_PARAM) elif kind in ('Request', 'Response'): opcode = param(params, 253) else: opcode = None yield DecodedMessage( timestamp=record.get('timestamp') or '', kind=kind, opcode=opcode if isinstance(opcode, int) else None, params=params, ) def damage_hits(path: str) -> Iterator[DamageHit]: """Yield every damage/healing tick from both health-update encodings.""" for message in iter_messages(path): if message.kind != 'Event': continue if message.opcode == OPCODE_HEALTH_UPDATE: delta = param(message.params, 2) health_after = param(message.params, 3) if not isinstance(delta, (int, float)): continue yield DamageHit( timestamp=message.timestamp, opcode=OPCODE_HEALTH_UPDATE, victim=param(message.params, 0), attacker=param(message.params, 6), delta=float(delta), health_after=health_after if isinstance(health_after, (int, float)) else None, ) elif message.opcode == OPCODE_DAMAGE_BATCH: deltas = param(message.params, 2) or [] health_afters = param(message.params, 3) or [] attackers = byte_list(param(message.params, 6)) for index, delta in enumerate(deltas): if not isinstance(delta, (int, float)): continue attacker = attackers[index] if index < len(attackers) else None health_after = health_afters[index] if index < len(health_afters) else None yield DamageHit( timestamp=message.timestamp, opcode=OPCODE_DAMAGE_BATCH, victim=param(message.params, 0), attacker=attacker, delta=float(delta), health_after=health_after if isinstance(health_after, (int, float)) else None, ) def entity_multipliers(path: str) -> Iterator[tuple]: """Yield ``(timestamp, entity, multiplier)`` from the entity-stats opcode.""" for message in iter_messages(path): if message.kind != 'Event' or message.opcode != OPCODE_ENTITY_STATS: continue multiplier = param(message.params, 6) if isinstance(multiplier, (int, float)): yield message.timestamp, param(message.params, 0), float(multiplier) def damage_type(message: DecodedMessage) -> Any: """Param 5 of a health update: an ability/hit category enum.""" return param(message.params, 5) def perfect_scalar_chains(path: str, min_steps: int = 5) -> List[List[DamageHit]]: """Victims whose scalar-opcode health chain is perfectly consistent. These are the calibration set for the duplicate test: a stream that merely repeats known hits cannot survive being injected into an already-exact chain, so the damage a stream adds to this set is genuine. """ by_victim: Dict[Any, List[DamageHit]] = {} for hit in damage_hits(path): by_victim.setdefault(hit.victim, []).append(hit) perfect = [] for victim_hits in by_victim.values(): scalar = check_chain(victim_hits, include_batched=False) if scalar.steps >= min_steps and scalar.breaks == 0: perfect.append(victim_hits) return perfect @dataclass class ChainReport: """Whether each victim's reported health can be explained by observed hits. Every health update reports the health the victim was left at. Walking a victim's hits in time order and applying each delta to the running total should land exactly on the next reported value: previous.health_after + delta == health_after When it does not, something moved the victim's health that we did not observe -- regeneration, food, an offline update, or simply a hit missing from this stream. Those are ``breaks``. The decisive property: a stream that is a *duplicate* of another adds no information while perturbing the running total, so it can only increase breaks. The correct encoding therefore has the fewest breaks. """ steps: int = 0 breaks: int = 0 @property def break_rate(self) -> float: return self.breaks / self.steps if self.steps else 0.0 def merge(self, other: 'ChainReport') -> 'ChainReport': return ChainReport(self.steps + other.steps, self.breaks + other.breaks) def check_chain(hits: List[DamageHit], include_batched: bool) -> ChainReport: """Walk each victim's health chain using one encoding or both. Healing is included in the walk (it is a real health change) but a step is only counted when both endpoints reported their resulting health. """ by_victim: Dict[Any, List[DamageHit]] = {} for hit in hits: if not include_batched and hit.opcode == OPCODE_DAMAGE_BATCH: continue by_victim.setdefault(hit.victim, []).append(hit) report = ChainReport() for victim_hits in by_victim.values(): ordered = sorted(victim_hits, key=lambda h: (h.timestamp, h.opcode)) previous = ordered[0] if previous.health_after is None: continue running = previous.health_after for current in ordered[1:]: if current.health_after is None: previous = current continue report.steps += 1 if abs(running + current.delta - current.health_after) > 0.01: report.breaks += 1 # Trust the server's reported value; re-anchor after any break. running = current.health_after previous = current return report