AnimSnapshot.hpp File Reference

PR-27 — per-entity animation state snapshot, decoupled from CharacterAnimator. More...

#include <algorithm>
#include <array>
#include <cmath>
#include <cstddef>
#include <cstdint>

Include dependency graph for AnimSnapshot.hpp:

This graph shows which files directly or indirectly include this file:

Go to the source code of this file.

Classes
struct	AnimSlot
	One slot in an entity's blend stack. More...
struct	AnimSnapshot
	Snapshot of an entity's full animation state at one instant. More...
struct	PendingShotIntent
	PR-27: transient component placed on the shooter entity for the duration of one runWeapon invocation when the matching SHOT_INTENT packet was received from that client. More...

Namespaces
namespace	anim_snapshot

Functions
float	anim_snapshot::delta (const AnimSnapshot &a, const AnimSnapshot &b)
	PR-27 animation-state delta.
void	anim_snapshot::pack (const AnimSlot &s, std::uint8_t out[4])
	Pack one AnimSlot into 4 bytes for wire transmission.
AnimSlot	anim_snapshot::unpack (const std::uint8_t in[4])
void	anim_snapshot::packSnapshot (const AnimSnapshot &snap, std::uint8_t out[k_wireSize])
AnimSnapshot	anim_snapshot::unpackSnapshot (const std::uint8_t in[k_wireSize])

Variables
constexpr std::size_t	anim_snapshot::k_wireSize = AnimSnapshot::k_numSlots * 4
	Total wire size of an AnimSnapshot (5 slots × 4 bytes).

Detailed Description

PR-27 — per-entity animation state snapshot, decoupled from CharacterAnimator.

Both client and server run the same CharacterAnimator state machine; at any instant, an entity's animation is fully described by 5 sampler slots (ClipSampler[5] in client/animation/CharacterAnimator.hpp). AnimSnapshot is the wire-friendly + ECS-friendly mirror of those 5 slots — an uint8_t clip ID + two floats per slot.

Two consumers:

1. Server-side history: HitboxHistorySystem extracts an AnimSnapshot from each entity's animator each tick, stores it alongside the historical capsules. When a shot is rewound, the server can compare its historical snapshot to the client's claimed snapshot to decide whether to accept the client's view of the target's animation pose.
2. Wire format: SHOT_INTENT packet carries the client's AnimSnapshot of the target it was shooting at. 20-byte packed payload (4 bytes per slot × 5 slots).

Per-slot delta semantics:

• different active/inactive flags → 0.5 penalty (transition slop)
• different clip IDs (both active) → 1.0 penalty (irreconcilable)
• same clip, different timeRatio → |Δt| × max(weight) (weighted)
• same clip, different weight → |Δw| × 0.5 (softer)

The total delta is dimensionless and uniform across body parts — 0.05 timeRatio drift in a fully-active slot is the same number regardless of which bone moves how far in those 0.05 of clip time. That uniformity is the whole reason this metric beats capsule- position-distance for "is the animation pose close enough?".

Note

Avoids depending on client/animation/AnimationLibrary.hpp (which carries ozz transitively): we store clipIdRaw as a raw uint8_t cast of the ClipId enum, so this header compiles into any TU including the bot which links no animation code.