common: add Player.PositionEyes() func + fix Player.Position() docs (#295)

see #236

Author: markus-wa

pkg/demoinfocs/common/player.go

@@ -285,7 +285,8 @@ func (p *Player) ViewDirectionY() float32 {
 }
 
 // Position returns the in-game coordinates.
-// Like the ones you get from cl_showpos 1.
+// Note: the Z value is not on the player's eye height but instead at his feet.
+// See also PositionEyes().
 func (p *Player) Position() r3.Vector {
 	if p.Entity == nil {
 		return r3.Vector{}
@@ -294,6 +295,20 @@ func (p *Player) Position() r3.Vector {
 	return p.Entity.Position()
 }
 
+// PositionEyes returns the player's position with the Z value at eye height.
+// This is what you get from cl_showpos 1.
+// See lso Position().
+func (p *Player) PositionEyes() r3.Vector {
+	if p.Entity == nil {
+		return r3.Vector{}
+	}
+
+	pos := p.Position()
+	pos.Z += float64(p.Entity.PropertyValueMust("localdata.m_vecViewOffset[2]").FloatVal)
+
+	return pos
+}
+
 // Velocity returns the player's velocity.
 func (p *Player) Velocity() r3.Vector {
 	if p.Entity == nil {

pkg/demoinfocs/common/player_test.go

@@ -353,6 +353,23 @@ func TestPlayer_Position_EntityNil(t *testing.T) {
 	assert.Empty(t, pl.Position())
 }
 
+func TestPlayer_PositionEyes(t *testing.T) {
+	entity := entityWithProperty("localdata.m_vecViewOffset[2]", st.PropertyValue{FloatVal: 2})
+	pos := r3.Vector{X: 1, Y: 2, Z: 3}
+
+	entity.On("Position").Return(pos)
+
+	pl := &Player{Entity: entity}
+
+	assert.Equal(t, r3.Vector{X: 1, Y: 2, Z: 5}, pl.PositionEyes())
+}
+
+func TestPlayer_PositionEyes_EntityNil(t *testing.T) {
+	pl := new(Player)
+
+	assert.Empty(t, pl.PositionEyes())
+}
+
 func TestPlayer_Velocity(t *testing.T) {
 	entity := new(stfake.Entity)
 	entity.On("PropertyValueMust", "localdata.m_vecVelocity[0]").Return(st.PropertyValue{FloatVal: 1})