Merge pull request #663 from markus-wa/various-fixes

Various fixes: correctness, new events/getters, and doc corrections

Author: markus-wa

docs/game-events.md

@@ -18,6 +18,35 @@ parser.RegisterEventHandler(func(event events.GenericGameEvent) {
 
 ✅ = Available, ❌ = Not available, ? = Not sure, need to be tested
 
+> **Provenance**
+> This table was originally authored against **CS:GO** demos (Jan 2023) and is not generated. Most
+> rows have never been re-measured for CS2. The rows verified against CS2 broadcast-GOTV so far are
+> the item-lifecycle / per-action corrections noted below (`item_remove`, `player_falldamage`,
+> `player_ping`/`player_ping_stop`, `defuser_*`, and the per-action cohort); treat the remaining rows
+> as CS:GO-era carry-over pending re-measurement, and the POV column as untested for CS2.
+
+> **Note (CS2 broadcast-GOTV vs match-server SourceTV)**
+> The GOTV column can differ between the two GOTV flavors. In CS2 **broadcast-GOTV** (e.g. HLTV)
+> demos a family of item-lifecycle / per-action events does not fire even when otherwise available:
+> `item_remove`, `defuser_dropped`, `defuser_pickup` and `player_falldamage` never fire, and
+> `bomb_beginplant` / `bomb_begindefuse` fire only in match-server SourceTV recordings (marked ✅
+> above), not in broadcast-GOTV. Drop / pickup / ownership are still recoverable from the
+> entity-property layer — weapon `m_hOwnerEntity` and pawn `m_bPawnHasDefuser` transitions fire
+> abundantly. Conversely `player_ping` / `player_ping_stop` appear in broadcast-GOTV but are
+> **absent on match-server SourceTV** (advertised in the event list, never emitted) - the reverse of
+> the rest of the family, so a consumer validating on a match-server demo would wrongly conclude
+> pings don't exist in CS2.
+
+> **Note (per-action event cohort in broadcast-GOTV)**
+> Broadcast-GOTV carries aggregate/director events (`player_sound`, `entity_killed`, `player_ping`,
+> `hltv_*`) but drops the raw per-action cohort (`player_footstep`, `player_jump`, `weapon_reload`,
+> `item_equip`, `weapon_zoom`, `player_blind`, `bomb_beginplant`). This is not governed by a `tv_*`
+> ConVar — `tv_transmitall` controls entity transmission, not the game-event stream, and is already
+> `1` in demos where the cohort is still absent; the cohort's absence is a property of the
+> game-event networking layer, so it cannot be re-enabled server-side for broadcast-GOTV. Most of
+> the signal is still recoverable from the entity/net-prop layer. Server ConVars themselves are
+> readable via the `events.ConVarsUpdated` event and `GameState.ConVars()`.
+
 | Event name                      | GOTV | POV |
 | ------------------------------- | ---- | --- |
 | ammo_pickup                     | ❌   | ✅  |
@@ -43,6 +72,8 @@ parser.RegisterEventHandler(func(event events.GenericGameEvent) {
 | cs_win_panel_round              | ✅   | ✅  |
 | decoy_detonate                  | ✅   | ✅  |
 | decoy_started                   | ✅   | ✅  |
+| defuser_dropped                  | ❌   | ?   |
+| defuser_pickup                   | ❌   | ?   |
 | endmatch_cmm_start_reveal_items | ✅   | ❌  |
 | enter_bombzone                  | ❌   | ✅  |
 | enter_buyzone                   | ❌   | ✅  |
@@ -68,22 +99,22 @@ parser.RegisterEventHandler(func(event events.GenericGameEvent) {
 | item_equip                      | ✅   | ❌  |
 | item_pickup                     | ✅   | ❌  |
 | item_pickup_slerp               | ❌   | ✅  |
-| item_remove                     | ✅   | ❌  |
+| item_remove                     | ❌   | ❌  |
 | jointeam_failed                 | ❌   | ✅  |
 | other_death                     | ✅   | ✅  |
 | player_blind                    | ✅   | ❌  |
 | player_connect                  | ✅   | ✅  |
 | player_connect_full             | ✅   | ✅  |
 | player_death                    | ✅   | ✅  |
 | player_disconnect               | ✅   | ✅  |
-| player_falldamage               | ✅   | ❌  |
+| player_falldamage               | ❌   | ❌  |
 | player_footstep                 | ✅   | ❌  |
 | player_given_c4                 | ❌   | ✅  |
 | player_hurt                     | ✅   | ✅  |
 | player_jump                     | ✅   | ❌  |
 | player_changename               | ✅   | ✅  |
-| player_ping                     | ❌   | ✅  |
-| player_ping_stop                | ❌   | ✅  |
+| player_ping                     | ✅   | ✅  |
+| player_ping_stop                | ✅   | ✅  |
 | player_spawn                    | ✅   | ✅  |
 | player_spawned                  | ❌   | ✅  |
 | player_team                     | ✅   | ✅  |

examples/mocking/README.md

@@ -56,7 +56,7 @@ func TestCollectKills(t *testing.T) {
 }
 
 func kill(wep common.EquipmentElement) events.Kill {
-	eq := common.NewEquipment(wep)
+	eq := common.NewEquipment(wep, 1)
 	return events.Kill{
 		Killer: new(common.Player),
 		Weapon: &eq,

examples/mocking/mocking_test.go

@@ -29,7 +29,7 @@ func TestCollectKills(t *testing.T) {
 }
 
 func kill(wep common.EquipmentType) events.Kill {
-	eq := common.NewEquipment(wep)
+	eq := common.NewEquipment(wep, 1)
 	return events.Kill{
 		Killer: new(common.Player),
 		Weapon: eq,

pkg/demoinfocs/common/common.go

@@ -3,7 +3,6 @@ package common
 
 import (
 	"fmt"
-	"math/rand"
 	"strconv"
 	"strings"
 	"time"
@@ -53,6 +52,10 @@ func getVelocityComponent(entity st.Entity, component string) (float32, bool) {
 
 // Velocity returns the projectile's velocity.
 // Returns a zero vector if the velocity is not networked.
+//
+// Note: on CS2 broadcast/GOTV demos the m_vecVelocity property is not present on grenade
+// projectile entities and this returns a zero vector. The throw kinematics are instead captured
+// at entity creation via m_vInitialVelocity / m_vInitialPosition; use those for release velocity.
 func (g *GrenadeProjectile) Velocity() r3.Vector {
 	x, okX := getVelocityComponent(g.Entity, "m_vecX")
 	y, okY := getVelocityComponent(g.Entity, "m_vecY")
@@ -70,17 +73,24 @@ func (g *GrenadeProjectile) Velocity() r3.Vector {
 }
 
 // UniqueID returns the unique id of the grenade.
-// The unique id is a random int generated internally by this library and can be used to differentiate
-// grenades from each other. This is needed because demo-files reuse entity ids.
+// The id is generated internally by this library and can be used to differentiate grenades from
+// each other. This is needed because demo-files reuse entity ids.
+//
+// The id is unique within the Parser instance that created the grenade; ids from different Parser
+// instances (e.g. concurrently or sequentially parsed demos) may collide, so don't key data
+// across demos by it.
 func (g *GrenadeProjectile) UniqueID() int64 {
 	return g.uniqueID
 }
 
 // NewGrenadeProjectile creates a grenade projectile and sets the Unique-ID.
 //
+// The id must come from the creating Parser's unique-id source so that it is unique within that
+// parse and reproducible across parses of the same demo.
+//
 // Intended for internal use only.
-func NewGrenadeProjectile() *GrenadeProjectile {
-	return &GrenadeProjectile{uniqueID: rand.Int63()} //nolint:gosec
+func NewGrenadeProjectile(id int64) *GrenadeProjectile {
+	return &GrenadeProjectile{uniqueID: id}
 }
 
 // Bomb tracks the bomb's position, and the player carrying it, if any.

pkg/demoinfocs/common/common_test.go

@@ -12,7 +12,7 @@ import (
 )
 
 func TestGrenadeProjectileUniqueID(t *testing.T) {
-	assert.NotEqual(t, NewGrenadeProjectile().UniqueID(), NewGrenadeProjectile().UniqueID(), "UniqueIDs of different grenade projectiles should be different")
+	assert.NotEqual(t, NewGrenadeProjectile(1).UniqueID(), NewGrenadeProjectile(2).UniqueID(), "UniqueIDs of different grenade projectiles should be different")
 }
 
 func TestGrenadeProjectile_Velocity(t *testing.T) {

pkg/demoinfocs/common/equipment.go

@@ -1,6 +1,7 @@
 package common
 
 import (
+	"encoding/binary"
 	"strings"
 
 	"github.com/oklog/ulid/v2"
@@ -340,7 +341,8 @@ func (e *Equipment) Class() EquipmentClass {
 // UniqueID2 returns a unique id of the equipment element that can be sorted efficiently.
 // UniqueID2 is a value generated internally by this library and can be used to differentiate
 // equipment from each other. This is needed because demo-files reuse entity ids.
-// Unlike UniqueID, UniqueID2 is guaranteed to be unique.
+// The id is unique within the Parser instance that created the equipment; ids from different
+// Parser instances may collide, so don't key data across demos by it.
 func (e *Equipment) UniqueID2() ulid.ULID {
 	return e.uniqueID2
 }
@@ -395,9 +397,15 @@ func (e *Equipment) ZoomLevel() ZoomLevel {
 	return ZoomLevel(value.Int())
 }
 
-// AmmoReserve returns the ammo left available for reloading.
+// AmmoReserve returns the reserve ammo available for reloading.
 // Returns CWeaponCSBase.m_iPrimaryReserveAmmoCount for most weapons and 'Owner.AmmoLeft[AmmoType] - 1' for grenades.
 // Use AmmoInMagazine() + AmmoReserve() to quickly get the amount of grenades a player owns.
+//
+// Note: the unit is era-dependent. The March 2026 CS2 reload patch
+// (https://steamcommunity.com/games/CSGO/announcements/detail/532126482488623354) changed reserve
+// ammo to reserve magazines, so on post-patch demos this is a magazine count (e.g. AK-47 = 3,
+// MP9 = 2) rather than a round count; pre-patch demos still report rounds. The value itself is
+// correct for both - only the interpretation differs by demo era.
 func (e *Equipment) AmmoReserve() int {
 	if e.Entity == nil {
 		return 0
@@ -444,9 +452,17 @@ func (e *Equipment) Silenced() bool {
 
 // NewEquipment creates a new Equipment and sets the UniqueID.
 //
+// The id must come from the creating Parser's unique-id source. It is encoded into the ULID, which
+// keeps UniqueID2 unique within the parse, lexicographically sortable (in creation order) and
+// reproducible across parses of the same demo - unlike ulid.Make(), which embeds wall-clock time
+// plus entropy and changes every parse.
+//
 // Intended for internal use only.
-func NewEquipment(wep EquipmentType) *Equipment {
-	return &Equipment{Type: wep, uniqueID2: ulid.Make()}
+func NewEquipment(wep EquipmentType, id int64) *Equipment {
+	var uid ulid.ULID
+	binary.BigEndian.PutUint64(uid[:8], uint64(id))
+
+	return &Equipment{Type: wep, uniqueID2: uid}
 }
 
 var equipmentToAlternative = map[EquipmentType]EquipmentType{

pkg/demoinfocs/common/equipment_test.go

@@ -38,14 +38,14 @@ func TestWeirdCS2Values(t *testing.T) {
 }
 
 func TestEquipment_Class(t *testing.T) {
-	assert.Equal(t, EqClassUnknown, NewEquipment(EqUnknown).Class(), "EqUnknown should have the class EqClassUnknown")
-	assert.Equal(t, EqClassPistols, NewEquipment(EqP2000).Class(), "EqP2000 should have the class EqClassPistols")
-	assert.Equal(t, EqClassPistols, NewEquipment(EqRevolver).Class(), "EqRevolver should have the class EqClassPistols")
-	assert.Equal(t, EqClassRifle, NewEquipment(EqG3SG1).Class(), "EqG3SG1 should have the class EqClassRifle")
+	assert.Equal(t, EqClassUnknown, NewEquipment(EqUnknown, 1).Class(), "EqUnknown should have the class EqClassUnknown")
+	assert.Equal(t, EqClassPistols, NewEquipment(EqP2000, 1).Class(), "EqP2000 should have the class EqClassPistols")
+	assert.Equal(t, EqClassPistols, NewEquipment(EqRevolver, 1).Class(), "EqRevolver should have the class EqClassPistols")
+	assert.Equal(t, EqClassRifle, NewEquipment(EqG3SG1, 1).Class(), "EqG3SG1 should have the class EqClassRifle")
 }
 
 func TestEquipment_UniqueID(t *testing.T) {
-	assert.NotEqual(t, NewEquipment(EqAK47).UniqueID2(), NewEquipment(EqAK47).UniqueID2(), "UniqueIDs of different equipment instances should be different")
+	assert.NotEqual(t, NewEquipment(EqAK47, 1).UniqueID2(), NewEquipment(EqAK47, 2).UniqueID2(), "UniqueIDs of different equipment instances should be different")
 }
 
 func TestEquipment_AmmoInMagazine(t *testing.T) {

pkg/demoinfocs/common/inferno.go

@@ -2,7 +2,6 @@ package common
 
 import (
 	"fmt"
-	"math/rand"
 	"sort"
 
 	"github.com/golang/geo/r2"
@@ -39,8 +38,11 @@ type Fires struct {
 }
 
 // UniqueID returns the unique id of the inferno.
-// The unique id is a random int generated internally by this library and can be used to differentiate
-// infernos from each other. This is needed because demo-files reuse entity ids.
+// The id is generated internally by this library and can be used to differentiate infernos from
+// each other. This is needed because demo-files reuse entity ids.
+//
+// The id is unique within the Parser instance that created the inferno; ids from different Parser
+// instances may collide, so don't key data across demos by it.
 func (inf *Inferno) UniqueID() int64 {
 	return inf.uniqueID
 }
@@ -62,6 +64,9 @@ func (inf *Inferno) Thrower() *Player {
 func (inf *Inferno) Fires() Fires {
 	entity := inf.Entity
 	origin := entity.Position()
+	// m_fireCount is the total number of fire positions ever spawned for this inferno, not the number
+	// currently burning - it only ever increases and never returns to 0. Use Fires().Active() (gated
+	// on m_bFireIsBurning) for the fires burning right now.
 	nFires := entity.PropertyValueMust("m_fireCount").Int()
 	fires := make([]Fire, 0, nFires)
 	iFormat := "%04d"
@@ -204,11 +209,14 @@ func convexHull(pointCloud []r3.Vector) quickhull.ConvexHull {
 
 // NewInferno creates a inferno and sets the Unique-ID.
 //
+// The id must come from the creating Parser's unique-id source so that it is unique within that
+// parse and reproducible across parses of the same demo.
+//
 // Intended for internal use only.
-func NewInferno(demoInfoProvider demoInfoProvider, entity st.Entity, thrower *Player) *Inferno {
+func NewInferno(demoInfoProvider demoInfoProvider, entity st.Entity, thrower *Player, id int64) *Inferno {
 	return &Inferno{
 		Entity:           entity,
-		uniqueID:         rand.Int63(), //nolint:gosec
+		uniqueID:         id,
 		demoInfoProvider: demoInfoProvider,
 		thrower:          thrower,
 	}

pkg/demoinfocs/common/inferno_test.go

@@ -13,7 +13,7 @@ import (
 
 func TestInferno_UniqueID(t *testing.T) {
 	entity := new(stfake.Entity)
-	assert.NotEqual(t, NewInferno(nil, entity, nil).UniqueID(), NewInferno(nil, entity, nil).UniqueID(), "UniqueIDs of different infernos should be different")
+	assert.NotEqual(t, NewInferno(nil, entity, nil, 1).UniqueID(), NewInferno(nil, entity, nil, 2).UniqueID(), "UniqueIDs of different infernos should be different")
 }
 
 func TestFires_Active(t *testing.T) {
@@ -119,7 +119,7 @@ func TestInferno_Thrower(t *testing.T) {
 		playersByHandle: map[uint64]*Player{1: player},
 	}
 
-	assert.Equal(t, player, NewInferno(provider, entity, nil).Thrower())
+	assert.Equal(t, player, NewInferno(provider, entity, nil, 1).Thrower())
 }
 
 func TestInferno_List(t *testing.T) {

pkg/demoinfocs/common/player.go

@@ -20,7 +20,7 @@ type Player struct {
 	Inventory           map[int]*Equipment // All weapons / equipment the player is currently carrying. See also Weapons().
 	EntityID            int                // Usually the same as Entity.ID() but may be different between player death and re-spawn.
 	Entity              st.Entity          // May be nil between player-death and re-spawn
-	FlashDuration       float32            // Blindness duration from the flashbang currently affecting the player (seconds)
+	FlashDuration       float32            // Effective blindness duration from the flashbang currently affecting the player (seconds). The engine's flash-affected window (e.g. for assist attribution) runs ~1.4x longer; there is no continuous remaining-intensity netprop.
 	FlashTick           int                // In-game tick at which the player was last flashed
 	TeamState           *TeamState         // When keeping the reference make sure you notice when the player changes teams
 	Team                Team               // Team identifier for the player (e.g. TeamTerrorists or TeamCounterTerrorists).
@@ -408,8 +408,11 @@ func (p *Player) ViewDirectionY() float32 {
 	return 0
 }
 
-// Velocity returns the player's velocity in game units per second.
-// Note: available only with demos after the AnimGraph 2 update! Otherwise this returns a zero vector.
+// Velocity returns the player's velocity in units per second.
+//
+// Note: on CS2 GOTV demos - both broadcast-GOTV and match-server SourceTV - the m_vecVelocity
+// property is not networked on player pawns and this returns a zero vector; it is populated only on
+// POV / match-making demos. For GOTV, derive velocity from the position delta between ticks instead.
 func (p *Player) Velocity() r3.Vector {
 	pawnEntity := p.PlayerPawnEntity()
 	if pawnEntity == nil {