diff --git a/bindings/cs/.gitignore b/bindings/cs/.gitignore index bf52c2b..8480e2d 100644 --- a/bindings/cs/.gitignore +++ b/bindings/cs/.gitignore @@ -484,4 +484,7 @@ $RECYCLE.BIN/ *.swp # JetBrains Rider -.idea/ \ No newline at end of file +.idea/ + +# libhat_c binaries should only exist locally +libhat_c.* \ No newline at end of file diff --git a/bindings/cs/README.md b/bindings/cs/README.md new file mode 100644 index 0000000..aeef433 --- /dev/null +++ b/bindings/cs/README.md @@ -0,0 +1,50 @@ +# libhat-sharp +C# bindings for libhat, a high-performance game hacking library. + +## Notes +- Currently only includes the pattern scanning functionality of libhat (libhat_c only implements pattern scanning) +- Supports Windows only, x86 and x64 +- Requires .NET 8, support for .NET Standard 2.0 will be added later +- Linux support will be added in the future + +## Installation +The library is available on NuGet: https://www.nuget.org/packages/libhat-sharp/ + +You can install it using the following command: +`dotnet add package libhat-sharp` + +## Usage +```csharp +using Hat; + +// Parse a pattern's string representation to an array of bytes at runtime +Pattern pattern = new Pattern("48 8D 05 ? ? ? ? E8"); + +// Create a scanner object for a section in a specific module +Process process = /* ... */; +Scanner scanner = new Scanner(process.MainModule, ".text"); + +// ...or for a specific memory region +nint start = /* the start of the memory region you want to scan */; +uint size = /* ... */; +Scanner scanner = new Scanner(start, size); + +// A span can also be used +Span buffer = /* ... */; +Scanner scanner = new Scanner(buffer); + +// Scan for this pattern using your CPU's vectorization features +ScanResult? result = scanner.FindPattern(pattern); + +// Get the address pointed at by the pattern +nint address = result!.Address; + +// Resolve an RIP relative address at a given offset +// +// | signature matches here +// | | relative address located at +3 +// v v +// 48 8D 05 BE 53 23 01 lea rax, [rip+0x12353be] +// +nint relativeAddress = result!.Relative(3); +``` diff --git a/bindings/cs/libhat-sharp/ScanResult.cs b/bindings/cs/libhat-sharp/ScanResult.cs new file mode 100644 index 0000000..141d20e --- /dev/null +++ b/bindings/cs/libhat-sharp/ScanResult.cs @@ -0,0 +1,41 @@ +namespace Hat; + +/// +/// Represents the result of a pattern scan. +/// +public unsafe class ScanResult +{ + /// + /// The resulting address from the pattern scan. + /// + public nint Address { get; } + + internal ScanResult(nint address) + { + Address = address; + } + + /// + /// Reads a value of type located at a given offset. + /// + /// The offset of the value. Defaults to 0. + public T Read(int offset = 0) where T : unmanaged + { + return *(T*)(Address + offset); + } + + /// + /// Resolves a RIP relative address located at a given offset. + /// + /// The offset of the relative address. + /// The amount of bytes remaining after the relative address. + /// + /// In some cases, the instruction pointed at by the result does not end with the relative address. + /// To prevent incorrect results caused by the remaining bytes, the parameter + /// should be used to specify the amount of bytes remaining in the instruction. + /// + public nint Relative(int offset, int remaining = 0) + { + return Address + Read(offset) + offset + sizeof(int) + remaining; + } +} \ No newline at end of file diff --git a/bindings/cs/libhat-sharp/Scanner.cs b/bindings/cs/libhat-sharp/Scanner.cs index 6638cd0..9b6525c 100644 --- a/bindings/cs/libhat-sharp/Scanner.cs +++ b/bindings/cs/libhat-sharp/Scanner.cs @@ -57,22 +57,30 @@ public Scanner(Span buffer) _size = (uint)buffer.Length; } + /// + /// Creates a scanner for a of bytes. + /// + /// The buffer to scan in. + public Scanner(Memory buffer) : this(buffer.Span) { } + /// /// Scans for a pattern. /// /// The pattern to scan for. /// The byte alignment of the result. - /// The address of the pattern if found, otherwise, 0. - public nint FindPattern(Pattern pattern, ScanAlignment alignment = ScanAlignment.X1) + /// A containing the result of the scan if found, otherwise null. + public ScanResult? FindPattern(Pattern pattern, ScanAlignment alignment = ScanAlignment.X1) { if (_buffer is not null && _size is not null) { - return Functions.libhat_find_pattern(pattern.Signature, _buffer.Value, _size.Value, alignment); + var result = Functions.libhat_find_pattern(pattern.Signature, _buffer.Value, _size.Value, alignment); + return result == 0 ? null : new ScanResult(result); } if (_section is not null && _module is not null) { - return Functions.libhat_find_pattern_mod(pattern.Signature, _module.Value, _section, alignment); + var result = Functions.libhat_find_pattern_mod(pattern.Signature, _module.Value, _section, alignment); + return result == 0 ? null : new ScanResult(result); } throw new InvalidOperationException("Scanner is not initialized."); diff --git a/bindings/cs/libhat-sharp/libhat-sharp.csproj b/bindings/cs/libhat-sharp/libhat-sharp.csproj index 70547df..2ee3fb7 100644 --- a/bindings/cs/libhat-sharp/libhat-sharp.csproj +++ b/bindings/cs/libhat-sharp/libhat-sharp.csproj @@ -6,6 +6,34 @@ enable enable true + 0.2.0 + 0.2.0.1 + + + libhat-sharp + 0.2.0 + phase + true + libhat-sharp + + C# bindings for libhat, a high-performance game hacking library. + Currently only includes the pattern scanner, which uses CPU vectorization features to quickly find patterns. + + https://github.com/BasedInc/libhat + MIT + README.md + https://github.com/phasephasephase/libhat + git + libhat;vectorized;game-hacking;modding;pattern-scanning + + - Updated to latest libhat release + - Added missing summary for ScanResult class + + + + + + diff --git a/bindings/cs/libhat-sharp/runtimes/win-x64/native/.placeholder b/bindings/cs/libhat-sharp/runtimes/win-x64/native/.placeholder new file mode 100644 index 0000000..1513c59 --- /dev/null +++ b/bindings/cs/libhat-sharp/runtimes/win-x64/native/.placeholder @@ -0,0 +1 @@ +When building, place your compiled libhat_c binary here. \ No newline at end of file diff --git a/bindings/cs/libhat-sharp/runtimes/win-x86/native/.placeholder b/bindings/cs/libhat-sharp/runtimes/win-x86/native/.placeholder new file mode 100644 index 0000000..2264f89 --- /dev/null +++ b/bindings/cs/libhat-sharp/runtimes/win-x86/native/.placeholder @@ -0,0 +1 @@ +When building, place your compiled libhat_c binary here. \ No newline at end of file diff --git a/bindings/cs/libhat-tests/Program.cs b/bindings/cs/libhat-tests/Program.cs index f35af7e..7933271 100644 --- a/bindings/cs/libhat-tests/Program.cs +++ b/bindings/cs/libhat-tests/Program.cs @@ -11,9 +11,9 @@ var pattern = randomBytes.AsSpan().Slice(0x1000, 0x10).ToArray().AsPattern(); var scanner = new Scanner(Marshal.UnsafeAddrOfPinnedArrayElement(randomBytes, 0), (uint)randomBytes.Length); -var address = scanner.FindPattern(pattern); +var result = scanner.FindPattern(pattern); -Console.WriteLine($"found pattern at 0x{address:X}"); +if (result != null) Console.WriteLine($"found pattern at 0x{result.Address:X}"); Console.WriteLine("\nscanning in module:"); @@ -21,6 +21,6 @@ var module = Process.GetCurrentProcess().MainModule!; var moduleScanner = new Scanner(module); -var moduleAddress = moduleScanner.FindPattern(modulePattern); +var moduleResult = moduleScanner.FindPattern(modulePattern); -Console.WriteLine($"found pattern at 0x{moduleAddress:X}"); \ No newline at end of file +if (moduleResult != null) Console.WriteLine($"found pattern at 0x{moduleResult.Address:X}"); \ No newline at end of file diff --git a/bindings/cs/libhat-tests/libhat-tests.csproj b/bindings/cs/libhat-tests/libhat-tests.csproj index 6f53a12..c3ba1cc 100644 --- a/bindings/cs/libhat-tests/libhat-tests.csproj +++ b/bindings/cs/libhat-tests/libhat-tests.csproj @@ -6,10 +6,12 @@ Hat.Tests enable enable + Debug;Release + AnyCPU - +