Working advanced tracking code
Build / Build source distribution (push) Failing after 13s
Build / Execute unit tests (push) Failing after 8s
Build / Verify generated game data is current (push) Failing after 7s
Build / Upload Release Asset (push) Has been skipped
Build / upload_pypi (push) Has been skipped

This commit is contained in:
2026-10-13 09:08:38 -06:00
parent f3114b076a
commit 7279b3c207
23 changed files with 336893 additions and 7521 deletions
+172 -2
View File
@@ -9,12 +9,15 @@ PHOTON_GAME_CODE = 1
# Current opcodes (albion-lens numbering, verified against captured traffic)
EVENT_LEAVE = 1
EVENT_HEALTH_UPDATE = 6
EVENT_BATCHED_HEALTH_UPDATE = 7
EVENT_EFFECT_STACK_UPDATE = 22
EVENT_NEW_CHARACTER = 29
EVENT_ITEM_GAINED = 32
EVENT_TAKE_SILVER = 62
EVENT_UPDATE_FAME = 82
EVENT_CHARACTER_EQUIPMENT_CHANGED = 90
EVENT_REGENERATION_HEALTH_CHANGED = 91
EVENT_MOB_SPAWNED = 123
EVENT_KNOCKED_DOWN = 166
EVENT_PARTY_INVITATION = 229
EVENT_PARTY_JOIN_REQUEST = 230
@@ -75,6 +78,24 @@ def _as_int_list(value) -> List[int]:
return []
def _as_byte_list(value) -> List[int]:
"""Unpack a Photon byte array into ints.
Batched health-update params arrive either as ``bytes`` or as a dict with a
``bytes_hex`` field (which is how the discovery log serialises them), and
occasionally as an already-decoded list. All three shapes occur for the
same parameter, so accept each of them.
"""
if isinstance(value, (bytes, bytearray)):
return list(value)
if isinstance(value, dict):
raw = value.get('bytes_hex')
if isinstance(raw, str):
return [int(raw[i:i + 2], 16) for i in range(0, len(raw) - 1, 2)]
return []
return _as_int_list(value)
@dataclass
class GameMessage:
name: str
@@ -85,6 +106,17 @@ class GameMessage:
return self.params.get(key)
@dataclass(frozen=True)
class EffectApplication:
"""One entry of a victim's active effect list.
``applier`` is the entity that put the effect on the target; the game
sends it explicitly rather than leaving it to be inferred.
"""
applier: int
effect_id: int
def into_game_message(message: PhotonMessage) -> Optional[GameMessage]:
if message.code != PHOTON_GAME_CODE:
return None
@@ -113,12 +145,15 @@ def into_game_message(message: PhotonMessage) -> Optional[GameMessage]:
EVENT_NAMES = {
EVENT_LEAVE: 'Leave',
EVENT_HEALTH_UPDATE: 'HealthUpdate',
EVENT_BATCHED_HEALTH_UPDATE: 'BatchedHealthUpdate',
EVENT_EFFECT_STACK_UPDATE: 'EffectStackUpdate',
EVENT_NEW_CHARACTER: 'NewCharacter',
EVENT_ITEM_GAINED: 'ItemGained',
EVENT_TAKE_SILVER: 'TakeSilver',
EVENT_UPDATE_FAME: 'UpdateFame',
EVENT_CHARACTER_EQUIPMENT_CHANGED: 'CharacterEquipmentChanged',
EVENT_REGENERATION_HEALTH_CHANGED: 'RegenerationHealthChanged',
EVENT_MOB_SPAWNED: 'MobSpawned',
EVENT_KNOCKED_DOWN: 'KnockedDown',
EVENT_PARTY_INVITATION: 'PartyInvitation',
EVENT_PARTY_JOIN_REQUEST: 'PartyJoinRequest',
@@ -137,7 +172,18 @@ OPERATION_NAMES = {
# Parameter accessors used by the world state machine. Field names follow
# aoaddons' messages.json layouts, with the current opcode space from albion-lens.
def msg_source(msg: GameMessage) -> int:
#
# Naming note: the older messages.json labelled HealthUpdate params as
# ``source@0`` / ``target@6``, but the capture data shows the opposite of what
# those names suggest -- param 0 is the entity whose health changed (the victim)
# and param 6 is the entity that caused it (the attacker). The accessors below
# are named for what the wire actually carries.
def msg_subject_id(msg: GameMessage) -> int:
"""Param 0: the entity the event is about.
For most events that is simply the subject (the character that joined, left,
or changed equipment). For HealthUpdate it is the *victim*.
"""
v = _int(msg.params.get(0))
return v if v is not None else 0
@@ -156,16 +202,140 @@ def msg_map_index(msg: GameMessage) -> Optional[str]:
return _string(msg.params.get(8))
def msg_target(msg: GameMessage) -> int:
def msg_attacker_id(msg: GameMessage) -> int:
"""Param 6: the entity responsible for a health change (attacker or healer)."""
v = _int(msg.params.get(6))
return v if v is not None else 0
def msg_value(msg: GameMessage) -> float:
"""Param 2: the signed health delta. Negative is damage, positive is healing."""
v = _float(msg.params.get(2))
return v if v is not None else 0.0
def msg_health_after(msg: GameMessage) -> Optional[float]:
"""Param 3: the victim's health once the hit has been applied."""
return _float(msg.params.get(3))
def msg_hit_type(msg: GameMessage) -> Optional[int]:
"""Param 5: hit-type enum.
Observed values split into two groups. ``0`` and ``1`` accompany basic
attacks (median damage ~45) and always carry ``-1`` for param 7; ``2``, ``3``,
``5`` and ``6`` accompany ability hits (median ~164-242). The exact meaning
of each value is not yet known, so it is carried through untranslated.
"""
return _int(msg.params.get(5))
def msg_batched_victim_id(msg: GameMessage) -> int:
"""Param 0 of a batched health update: the entity every hit landed on."""
return msg_subject_id(msg)
def msg_batched_ticks(msg: GameMessage) -> List[int]:
"""Param 1: one tick counter per hit."""
return _as_int_list(msg.params.get(1))
def msg_batched_values(msg: GameMessage) -> List[float]:
"""Param 2: one signed health delta per hit."""
v = msg.params.get(2)
if not isinstance(v, list):
return []
out = []
for item in v:
f = _float(item)
if f is not None:
out.append(f)
return out
def msg_batched_health_after(msg: GameMessage) -> List[float]:
"""Param 3: one resulting-health value per hit."""
v = msg.params.get(3)
if not isinstance(v, list):
return []
out = []
for item in v:
f = _float(item)
if f is not None:
out.append(f)
return out
def msg_batched_hit_types(msg: GameMessage) -> List[int]:
"""Param 5: one hit-type enum per hit.
These arrive as a raw byte array rather than a decoded list, so they need
unpacking rather than the usual int coercion.
"""
return _as_byte_list(msg.params.get(5))
def msg_batched_attacker_ids(msg: GameMessage) -> List[int]:
"""Param 6: one attacker entity id per hit.
Also a raw byte array. Unlike param 2/3/5 the decoder sometimes produces a
plain list here instead, so both shapes are accepted.
"""
return _as_byte_list(msg.params.get(6))
def msg_effect_stack_appliers(msg: GameMessage) -> List[int]:
"""Param 1: the entity responsible for each effect on the victim.
Index-aligned with ``msg_effect_stack_ids``. The game sends the applier
outright, so attribution does not have to infer who applied a debuff from
the attacker's weapon -- which is what the original plan assumed.
"""
return _as_int_list(msg.params.get(1))
def msg_effect_stack_ids(msg: GameMessage) -> List[int]:
"""Param 2: one effect id per entry in the victim's active effect list.
These are runtime-assigned ids. They are stable for the life of a session
and usually unique to one (spell, caster) pair, but they are not the spell
ids used by the game data files, so they cannot be looked up statically.
"""
return _as_int_list(msg.params.get(2))
def msg_effect_stack_applications(msg: GameMessage) -> List[EffectApplication]:
"""Pair up the applier and effect id lists.
The two arrays are index-aligned and the same length on every observed
message. If a capture ever produced a ragged pair the mismatched tail is
dropped rather than guessed at.
"""
appliers = msg_effect_stack_appliers(msg)
effects = msg_effect_stack_ids(msg)
return [EffectApplication(applier, effect)
for applier, effect in zip(appliers, effects)]
def msg_mob_template_id(msg: GameMessage) -> Optional[int]:
"""Param 1: the numeric mob template this entity spawned from.
Template ids are the enumeration index of the mob table. They are a
different id space from item ids -- 454 is the Giant Snake as a mob but a
gathering skillbook as an item -- so this must never be resolved through
the item table.
"""
return _int(msg.params.get(1))
def msg_mob_hitpoints_max(msg: GameMessage) -> Optional[float]:
"""Param 13: the mob's maximum hit points at spawn.
Doubles as a cross-check on the template id: the two must agree.
"""
return _float(msg.params.get(13))
def msg_items(msg: GameMessage) -> List[int]:
return _as_int_list(msg.params.get(2))
+74 -22
View File
@@ -171,6 +171,8 @@ class World:
return self._on_leave(message)
if message.name == 'HealthUpdate':
return self._on_health_update(message)
if message.name == 'BatchedHealthUpdate':
return self._on_batched_health_update(message)
if message.name == 'RegenerationHealthChanged':
return self._on_regeneration(message)
if message.name == 'KnockedDown':
@@ -206,7 +208,7 @@ class World:
def _on_new_character(self, msg: GameMessage) -> List[dict]:
name = translate.msg_new_character_name(msg)
dynamic_id = _dyn(translate.msg_source(msg))
dynamic_id = _dyn(translate.msg_subject_id(msg))
if not name:
return []
self.cache.save(dynamic_id, name)
@@ -231,7 +233,7 @@ class World:
def _on_join(self, msg: GameMessage) -> List[dict]:
name = translate.msg_character_name(msg)
dynamic_id = _dyn(translate.msg_source(msg))
dynamic_id = _dyn(translate.msg_subject_id(msg))
if not name:
return []
self.cache.save(dynamic_id, name)
@@ -265,7 +267,7 @@ class World:
return [{'name': 'ZoneChange'}]
def _on_leave(self, msg: GameMessage) -> List[dict]:
dynamic_id = _dyn(translate.msg_source(msg))
dynamic_id = _dyn(translate.msg_subject_id(msg))
static_id = self.cache.get_static_id(dynamic_id)
if static_id is None:
return []
@@ -278,35 +280,85 @@ class World:
return []
def _on_health_update(self, msg: GameMessage) -> List[dict]:
# params: [0]=target (entity whose health changed), [2]=signed delta,
# [6]=source (attacker/healer). aoaddons emits Damage{source: params[6],
# target: params[0]} which the app attributes to the dealer/healer.
# Params: [0]=victim (entity whose health changed), [2]=signed delta,
# [3]=victim health after the hit, [5]=hit type, [6]=attacker/healer.
value = translate.msg_value(msg)
if value == 0.0:
return []
actor_id = _dyn(translate.msg_target(msg)) # param 6
victim_id = _dyn(translate.msg_source(msg)) # param 0
actor_static = self.cache.get_static_id(actor_id)
victim_id = _dyn(translate.msg_subject_id(msg))
attacker_id = _dyn(translate.msg_attacker_id(msg))
hit_type = translate.msg_hit_type(msg)
health_after = translate.msg_health_after(msg)
return self._health_events(
attacker_id=attacker_id,
victim_id=victim_id,
value=value,
hit_type=hit_type,
health_after=health_after)
def _on_batched_health_update(self, msg: GameMessage) -> List[dict]:
# Batched form of HealthUpdate: one victim, several hits delivered in a
# single packet, with parallel arrays indexed per hit. Verified against
# captures to be additional damage rather than a repeat of the scalar
# form -- see PLAN.md F2.
values = translate.msg_batched_values(msg)
if not values:
return []
victim_id = _dyn(translate.msg_batched_victim_id(msg))
health_after = translate.msg_batched_health_after(msg)
hit_types = translate.msg_batched_hit_types(msg)
attackers = translate.msg_batched_attacker_ids(msg)
events: List[dict] = []
for index, value in enumerate(values):
if value == 0.0:
continue
attacker = attackers[index] if index < len(attackers) else None
hit_type = hit_types[index] if index < len(hit_types) else None
after = health_after[index] if index < len(health_after) else None
events.extend(self._health_events(
attacker_id=_dyn(attacker) if attacker is not None else None,
victim_id=victim_id,
value=value,
hit_type=hit_type,
health_after=after))
return events
def _health_events(self, attacker_id: Optional[int], victim_id: int,
value: float, hit_type: Optional[int],
health_after: Optional[float]) -> List[dict]:
"""Build the damage/heal events for a single health change.
``DamageDone`` and ``DamageTaken`` are emitted independently so a hit
from an unknown attacker (a mob, say) still registers against a tracked
victim, and a hit on an untracked victim still registers for a tracked
attacker.
"""
attacker_static = (self.cache.get_static_id(attacker_id)
if attacker_id is not None else None)
victim_static = self.cache.get_static_id(victim_id)
events = []
if actor_static is not None:
event_name = 'DamageDone' if value < 0.0 else 'HealthReceived'
if attacker_static is not None:
payload = {'source': attacker_static,
'target': victim_static,
'value': float(abs(value)),
'hit_type': hit_type,
'health_after': health_after}
events.append({
'name': event_name,
'value': {'source': actor_static,
'target': victim_static,
'value': float(abs(value))},
'name': 'DamageDone' if value < 0.0 else 'HealthReceived',
'value': payload,
})
if value < 0.0 and victim_static is not None:
events.append({
'name': 'DamageTaken',
'value': {'source': victim_static,
'value': float(abs(value))},
'value': float(abs(value)),
'hit_type': hit_type},
})
return events
def _on_regeneration(self, msg: GameMessage) -> List[dict]:
dynamic_id = _dyn(translate.msg_source(msg))
dynamic_id = _dyn(translate.msg_subject_id(msg))
static_id = self.cache.get_static_id(dynamic_id)
if static_id is None:
return []
@@ -318,7 +370,7 @@ class World:
return [{'name': event_name, 'value': {'id': static_id, 'name': name}}]
def _on_knocked_down(self, msg: GameMessage) -> List[dict]:
dynamic_id = _dyn(translate.msg_source(msg))
dynamic_id = _dyn(translate.msg_subject_id(msg))
static_id = self.cache.get_static_id(dynamic_id)
if static_id is None:
return []
@@ -328,7 +380,7 @@ class World:
return [{'name': 'LeaveCombat', 'value': {'id': static_id, 'name': name}}]
def _on_update_fame(self, msg: GameMessage) -> List[dict]:
dynamic_id = _dyn(translate.msg_source(msg))
dynamic_id = _dyn(translate.msg_subject_id(msg))
static_id = self.cache.get_static_id(dynamic_id)
if static_id is None:
return []
@@ -358,7 +410,7 @@ class World:
def _on_item_gained(self, msg: GameMessage) -> List[dict]:
if not self._main_player_joined:
return []
source_id = _dyn(translate.msg_source(msg))
source_id = _dyn(translate.msg_subject_id(msg))
item_id = translate.msg_collected_item_id(msg)
quantity = translate.msg_collected_item_quantity(msg)
if item_id is None or quantity is None or quantity <= 0:
@@ -381,7 +433,7 @@ class World:
def _on_take_silver(self, msg: GameMessage) -> List[dict]:
if not self._main_player_joined:
return []
dynamic_id = _dyn(translate.msg_source(msg))
dynamic_id = _dyn(translate.msg_subject_id(msg))
static_id = self.cache.get_static_id(dynamic_id)
if static_id is None or static_id != self.main_player_id:
return []
@@ -400,7 +452,7 @@ class World:
}}]
def _on_character_equipment_changed(self, msg: GameMessage) -> List[dict]:
dynamic_id = _dyn(translate.msg_source(msg))
dynamic_id = _dyn(translate.msg_subject_id(msg))
static_id = self.cache.get_static_id(dynamic_id)
if static_id is None:
self.unconsumed_messages.add(dynamic_id, msg)