update readme
This commit is contained in:
SlynxCZ
parent
923edbbba0
commit
8e0e61acd1
1 changed files with 149 additions and 62 deletions
145
README.md
145
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
|
||||
must provide its own native-compatible implementations of the following
|
||||
engine structures:
|
||||
When using the low-level method `TraceShapeEx` from a C# plugin, the
|
||||
plugin must provide its own native-compatible implementations of the
|
||||
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
|
||||
used by the engine.
|
||||
The C# plugin must define a struct that matches the native `Ray_t`
|
||||
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.
|
||||
|
||||
This is required because CTraceFilter is a polymorphic C++ class and its
|
||||
virtual table is not directly exposed to managed code.
|
||||
- Assign the resolved vtable to the struct before calling
|
||||
TraceShapeEx.
|
||||
|
||||
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**
|
||||
- This setup is only required when using the low-level API:
|
||||
- TraceShapeEx(...)
|
||||
- High-level functions (TraceShape, TraceEndShape) do not require custom Ray_t or CTraceFilter handling from C#.
|
||||
- Incorrect structure layout or invalid vtable resolution will result in crashes or undefined behavior.
|
||||
- This is considered an advanced use case intended for engine-level plugins.
|
||||
**Important notes** - This setup is only required when using the
|
||||
low-level API: - TraceShapeEx(...) - High-level functions (TraceShape,
|
||||
TraceEndShape) do not require custom Ray_t or CTraceFilter handling from
|
||||
C#. - Incorrect structure layout or invalid vtable resolution will
|
||||
result in crashes or undefined behavior. - This is considered an
|
||||
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
|
||||
Loading…
Add table
Add a link
Reference in a new issue