Adding UniqueID2 for Equipment (#360)

The prior uniqueID for equipment wasn't guaranteed to be unique.

This is
- guaranteed to be unique
- produced in a sortable order
- easily marshallable
- requires few extra dependencies

Author: David-Durst

go.mod

@@ -18,6 +18,7 @@ require (
 require (
 	github.com/davecgh/go-spew v1.1.1 // indirect
 	github.com/golang/freetype v0.0.0-20170609003504-e2365dfdc4a0 // indirect
+	github.com/oklog/ulid/v2 v2.1.0 // indirect
 	github.com/pmezard/go-difflib v1.0.0 // indirect
 	github.com/stretchr/objx v0.4.0 // indirect
 	golang.org/x/image v0.0.0-20220617043117-41969df76e82 // indirect

go.sum

@@ -29,6 +29,9 @@ github.com/markus-wa/ice-cipher-go v0.0.0-20220126215401-a6adadccc817 h1:VB4ANo0
 github.com/markus-wa/ice-cipher-go v0.0.0-20220126215401-a6adadccc817/go.mod h1:JIsht5Oa9P50VnGJTvH2a6nkOqDFJbUeU1YRZYvdplw=
 github.com/markus-wa/quickhull-go/v2 v2.1.0 h1:DA2pzEzH0k5CEnlUsouRqNdD+jzNFb4DBhrX4Hpa5So=
 github.com/markus-wa/quickhull-go/v2 v2.1.0/go.mod h1:bOlBUpIzGSMMhHX0f9N8CQs0VZD4nnPeta0OocH7m4o=
+github.com/oklog/ulid/v2 v2.1.0 h1:+9lhoxAP56we25tyYETBBY1YLA2SaoLvUFgrP2miPJU=
+github.com/oklog/ulid/v2 v2.1.0/go.mod h1:rcEKHmBBKfef9DhnvX7y1HZBYxjXb0cP5ExxNsTT1QQ=
+github.com/pborman/getopt v0.0.0-20170112200414-7148bc3a4c30/go.mod h1:85jBQOZwpVEaDAr341tbn15RS4fCAsIst0qp7i8ex1o=
 github.com/pkg/errors v0.9.1 h1:FEBLx1zS214owpjy7qsBeixbURkuhQAwrK5UwLGTwt4=
 github.com/pkg/errors v0.9.1/go.mod h1:bwawxfHBFNV+L2hUp1rHADufV3IMtnDRdf1r5NINEl0=
 github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=

pkg/demoinfocs/common/equipment.go

@@ -4,6 +4,8 @@ import (
 	"math/rand"
 	"strings"
 
+	"github.com/oklog/ulid/v2"
+
 	st "github.com/markus-wa/demoinfocs-golang/v3/pkg/demoinfocs/sendtables"
 )
 
@@ -288,7 +290,8 @@ type Equipment struct {
 	Owner          *Player       // The player carrying the equipment, not necessarily the buyer.
 	OriginalString string        // E.g. 'models/weapons/w_rif_m4a1_s.mdl'. Used internally to differentiate alternative weapons (M4A4 / M4A1-S etc.).
 
-	uniqueID int64
+	uniqueID  int64 // Deprecated, use uniqueID2, see UniqueID() for why
+	uniqueID2 ulid.ULID
 }
 
 // String returns a human readable name for the equipment.
@@ -303,13 +306,23 @@ func (e *Equipment) Class() EquipmentClass {
 	return e.Type.Class()
 }
 
-// UniqueID returns the unique id of the equipment element.
+// UniqueID returns a randomly generated unique id of the equipment element.
 // The unique id is a random int generated internally by this library and can be used to differentiate
 // equipment from each other. This is needed because demo-files reuse entity ids.
+// Deprecated: Use UniqueID2 instead. Since UniqueID is randomly generated, duplicate IDs are possible.
+// See the birthday problem for why repeatedly generating random 64 bit integers is likely to produce a collision.
 func (e *Equipment) UniqueID() int64 {
 	return e.uniqueID
 }
 
+// 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.
+func (e *Equipment) UniqueID2() ulid.ULID {
+	return e.uniqueID2
+}
+
 // AmmoInMagazine returns the ammo left in the magazine.
 // Returns CWeaponCSBase.m_iClip1 for most weapons and 1 for grenades.
 func (e *Equipment) AmmoInMagazine() int {
@@ -375,7 +388,7 @@ func (e *Equipment) AmmoReserve() int {
 //
 // Intended for internal use only.
 func NewEquipment(wep EquipmentType) *Equipment {
-	return &Equipment{Type: wep, uniqueID: rand.Int63()} //nolint:gosec
+	return &Equipment{Type: wep, uniqueID: rand.Int63(), uniqueID2: ulid.Make()} //nolint:gosec
 }
 
 var equipmentToAlternative = map[EquipmentType]EquipmentType{