update readme

README.md

@@ -1,23 +1,27 @@
 # Ray-Trace
 
-**Shared ray tracing interface for Metamod:Source & CounterStrikeSharp plugins**
+**Shared ray tracing interface for Metamod:Source & CounterStrikeSharp
+plugins**
 
 ------------------------------------------------------------------------
 
 ## Overview
 
-`Ray-Trace` is a lightweight **Metamod interface module** for  
+`Ray-Trace` is a lightweight **Metamod interface module** for\
 **Counter-Strike 2** servers.
 
-It exposes a shared interface: `CRayTraceInterface001` which can be consumed from:
+It exposes a shared interface: `CRayTraceInterface001` which can be
+consumed from:
 
 -   Native **Metamod C++ plugins**
 -   Managed **CounterStrikeSharp C# plugins**
 
 The interface is implemented as a **C++ virtual class** and is accessed
-from C# by calling its **vtable functions directly** using a native handle.
+from C# by calling its **vtable functions directly** using a native
+handle.
 
-The goal is to provide a **single tracing backend** usable from both worlds  
+The goal is to provide a **single tracing backend** usable from both
+worlds\
 without duplicating engine detours.
 
 ------------------------------------------------------------------------
@@ -69,13 +73,14 @@ public:
     ) = 0;
 };
 ```
-**Return value:**
+
-- true → trace hit something, TraceResult is valid
+**Return value:** - true → trace hit something, TraceResult is valid\
 - false → no hit
 
 ------------------------------------------------------------------------
 
 ## Getting the interface
+
 **C++ (Metamod plugin)**
 
 ``` cpp
@@ -102,6 +107,7 @@ bool LoadRayTrace()
 ```
 
 **C# (CounterStrikeSharp plugin)**
+
 ``` csharp
 private nint g_pRayTraceHandle = nint.Zero;
 private bool g_bRayTraceLoaded = false;
@@ -119,12 +125,16 @@ public override void Load(bool hotReload)
     g_bRayTraceLoaded = true;
 }
 ```
-The returned handle is a pointer to the native CRayTraceInterface object.
+
+The returned handle is a pointer to the native CRayTraceInterface
+object.
 
 ------------------------------------------------------------------------
 
 ## Calling methods from C++ (Metamod)
+
 **TraceShape example**
+
 ``` cpp
 Vector vecOrigin{};
 QAngle angView{};
@@ -156,6 +166,7 @@ if (g_pRayTrace && g_bRayTraceLoaded)
 ```
 
 **TraceEndShape example**
+
 ``` cpp
 TraceResult traceResult{};
 
@@ -169,6 +180,7 @@ bool bHit = g_pRayTrace->TraceEndShape(
 ```
 
 **TraceShapeEx (low-level)**
+
 ``` cpp
 Ray_t ray{};
 CTraceFilter filter(
@@ -191,6 +203,7 @@ bool bHit = g_pRayTrace->TraceShapeEx(
 ------------------------------------------------------------------------
 
 ## Calling methods from C# (CounterStrikeSharp plugin)
+
 ``` csharp
 private delegate bool TraceShapeFn(
     nint pThis,
@@ -235,11 +248,79 @@ public bool TraceShape(
 
 ------------------------------------------------------------------------
 
+## Memory allocation from C# (Important)
+
+When calling `TraceShape` or `TraceEndShape` from C#, the plugin **must
+allocate native memory** for the following structures:
+
+-   `TraceOptions`
+-   `TraceResult`
+
+These parameters are native pointers in C++ (`TraceOptions*` and
+`TraceResult*`) and must remain valid for the duration of the call.
+
+The recommended and safest approach is using **stackalloc** (or unsafe
+stack variables) to provide native memory on the stack.
+
+Failing to allocate valid memory for these parameters will result in
+crashes or undefined behavior.
+
+### Example (C# stackalloc)
+
+``` csharp
+[StructLayout(LayoutKind.Sequential, Pack = 8)]
+public struct TraceOptions
+{
+    public ulong InteractsWith;
+    public ulong InteractsExclude;
+    public int DrawBeam;
+}
+
+[StructLayout(LayoutKind.Sequential, Pack = 8)]
+public struct TraceResult
+{
+    public Vector EndPos;
+    public nint HitEntity;
+    public float Fraction;
+    public int AllSolid;
+    public Vector Normal;
+}
+
+unsafe
+{
+    Vector origin = player.Position;
+    QAngle angles = player.ViewAngles;
+
+    TraceOptions* opts = stackalloc TraceOptions[1];
+    opts->InteractsWith = (ulong)MASK_SHOT_FULL;
+    opts->InteractsExclude = 0;
+    opts->DrawBeam = 0;
+
+    TraceResult* result = stackalloc TraceResult[1];
+
+    bool hit = _traceShape!(
+        g_pRayTraceHandle,
+        (nint)&origin,
+        (nint)&angles,
+        nint.Zero,
+        (nint)opts,
+        (nint)result
+    );
+
+    if (hit)
+    {
+        Console.WriteLine($"Hit at: {result->EndPos}");
+    }
+}
+```
+
+------------------------------------------------------------------------
+
 ## Low-level usage from C# (Ray_t & CTraceFilter)
 
-When using the low-level method `TraceShapeEx` from a C# plugin, the plugin
+When using the low-level method `TraceShapeEx` from a C# plugin, the
-must provide its own native-compatible implementations of the following
+plugin must provide its own native-compatible implementations of the
-engine structures:
+following engine structures:
 
 -   `Ray_t`
 -   `CTraceFilter`
@@ -249,8 +330,8 @@ must be recreated in managed code with correct memory layout.
 
 ### Ray_t (C#)
 
-The C# plugin must define a struct that matches the native `Ray_t` layout
+The C# plugin must define a struct that matches the native `Ray_t`
-used by the engine.
+layout used by the engine.
 
 Example (simplified):
 
@@ -264,18 +345,20 @@ public struct Ray_t
     public byte m_IsSwept;
 }
 ```
-(Exact layout depends on the engine version and must match native memory.)
 
-**CTraceFilter (C#)**
+(Exact layout depends on the engine version and must match native
+memory.)
+
+**CTraceFilter (C#)**\
 For `CTraceFilter`, the plugin must:
+
 -   Define a managed struct matching the native layout.
 -   Resolve the CTraceFilter vtable pointer using a signature scan.
-- Assign the resolved vtable to the struct before calling TraceShapeEx.
+-   Assign the resolved vtable to the struct before calling
-
+    TraceShapeEx.
-This is required because CTraceFilter is a polymorphic C++ class and its
-virtual table is not directly exposed to managed code.
 
 Example concept:
+
 ``` csharp
 [StructLayout(LayoutKind.Sequential)]
 public unsafe struct CTraceFilter
@@ -285,19 +368,18 @@ public unsafe struct CTraceFilter
     public T ...;
 }
 ```
-The vtable pointer must be resolved at runtime using a signature scan
-against the game binary.
 
-**Important notes**
+**Important notes** - This setup is only required when using the
-- This setup is only required when using the low-level API:
+low-level API: - TraceShapeEx(...) - High-level functions (TraceShape,
-- TraceShapeEx(...)
+TraceEndShape) do not require custom Ray_t or CTraceFilter handling from
-- High-level functions (TraceShape, TraceEndShape) do not require custom Ray_t or CTraceFilter handling from C#.
+C#. - Incorrect structure layout or invalid vtable resolution will
-- Incorrect structure layout or invalid vtable resolution will result in crashes or undefined behavior.
+result in crashes or undefined behavior. - This is considered an
-- This is considered an advanced use case intended for engine-level plugins.
+advanced use case intended for engine-level plugins.
 
 ------------------------------------------------------------------------
 
 ## Notes about ABI & Destructor
+
 -   CRayTraceInterface has a virtual destructor.
 -   The object is owned by the Ray-Trace Metamod module.
 -   Plugins must never call delete on the interface pointer.
@@ -305,10 +387,13 @@ against the game binary.
 -   All parameters are passed as native pointers (nint).
 
 # Build
+
 ## Requirements
+
 -   HL2SDK-CS2
 -   Metamod:Source
 -   CMake
+
 ``` bash
 git clone https://github.com/FUNPLAY-pro-CS2/Ray-Trace.git
 cd Ray-Trace
@@ -319,9 +404,11 @@ docker compose -f docker/docker-compose.yml up
 ------------------------------------------------------------------------
 
 ## License
-GPLv3  
+
+GPLv3\
 https://www.gnu.org/licenses/gpl-3.0.en.html
 
 ## Author
-**Michal "Slynx" Přikryl**  
+
+**Michal "Slynx" Přikryl**\
 https://slynxdev.cz