From c54eda19679aa2db23db62881af9c7be47e1cf6f Mon Sep 17 00:00:00 2001 From: Roflmuffin Date: Thu, 2 Nov 2023 20:51:21 +1000 Subject: [PATCH] feat: add `GetPlayerFrom` utility methods --- .../docs/reference/referencing-players.md | 9 ++++---- managed/CounterStrikeSharp.API/Utilities.cs | 22 ++++++++++++++++++- 2 files changed, 25 insertions(+), 6 deletions(-) diff --git a/docs/src/content/docs/reference/referencing-players.md b/docs/src/content/docs/reference/referencing-players.md index f05567f73..2853567f8 100644 --- a/docs/src/content/docs/reference/referencing-players.md +++ b/docs/src/content/docs/reference/referencing-players.md @@ -36,13 +36,12 @@ Userids are similar to a slot, and they are what show in the console when you ty All entity instances have an entity index (similar to CSGO), which means both the player controller and the player pawn both have different indexes. The Player Controller has a reserved entity index (because of the slot system 0-MAXPLAYERS(64)), but a player pawn does not, so it is common to retrieve a player pawn with an index in the hundreds. ### Entity Pointers & Handles -All "entity objects" you interact with in CounterStrikeSharp are actually wrappers around a __pointer__ on the server, which can be accessed by retrieving the `.Handle` property. Which means to go from a CPlayerSlot, UserID or Index value, you must first convert to an index, and then supply this to a native method which can convert the index to an entity pointer. At time of writing this is `NativeAPI.GetEntityFromIndex()` but will likely change in the future. Examples: +All "entity objects" you interact with in CounterStrikeSharp are actually wrappers around a __pointer__ on the server, which can be accessed by retrieving the `.Handle` property. Which means to go from a CPlayerSlot, UserID or Index value, you must use the matching utility method to fetch the entity pointer. There are three utility methods to get an instance of a player using these identifiers: ```csharp -var entity = new CCSPlayerController(NativeAPI.GetEntityFromIndex(slot + 1)); // Slot -> Index -> Pointer -var entity = new CCSPlayerController(NativeAPI.GetEntityFromIndex(index)); // Index -> Pointer -var entity = new CCSPlayerController(NativeAPI.GetEntityFromIndex((userid & 0xFF) + 1)); // Userid -> Index -> Pointer -var entity = new CCSPlayerController(NativeAPI.GetEntityFromIndex(pointer); // IntPtr directly +var player = Utilities.GetPlayerFromUserid(userid); +var player = Utilities.GetPlayerFromIndex(index); +var player = Utilities.GetPlayerFromSlot(slot); ``` :::note[Entity Safety] diff --git a/managed/CounterStrikeSharp.API/Utilities.cs b/managed/CounterStrikeSharp.API/Utilities.cs index 0bdf02cf6..49f28267e 100644 --- a/managed/CounterStrikeSharp.API/Utilities.cs +++ b/managed/CounterStrikeSharp.API/Utilities.cs @@ -38,6 +38,26 @@ public static IEnumerable FlagsToList(this T flags) where T : Enum .Where(x => flags.HasFlag(x)).AsEnumerable(); } + public static T GetEntityFromIndex(int index) where T : CEntityInstance + { + return (T)Activator.CreateInstance(typeof(T), NativeAPI.GetEntityFromIndex(index))!; + } + + public static CCSPlayerController GetPlayerFromIndex(int index) + { + return Utilities.GetEntityFromIndex(index); + } + + public static CCSPlayerController GetPlayerFromSlot(int slot) + { + return Utilities.GetEntityFromIndex(slot + 1); + } + + public static CCSPlayerController GetPlayerFromUserid(int userid) + { + return Utilities.GetEntityFromIndex((userid & 0xFF) + 1); + } + public static IEnumerable FindAllEntitiesByDesignerName(string designerName) where T : CEntityInstance { var pEntity = new CEntityIdentity(NativeAPI.GetFirstActiveEntity()); @@ -84,4 +104,4 @@ public static unsafe string ReadStringUtf8(IntPtr ptr) } } } -} +} \ No newline at end of file