bun-memory 1.1.34 → 1.1.36

package/README.md

@@ -52,7 +52,8 @@ cs2.close();
 ## API Highlights
 
 - `follow(address, offsets)` — Follow a pointer chain
-- `pattern(needle, address, length)` — Find a byte pattern in memory (supports wildcards)
+- `indexOf(needle, address, length, [all])` — Search for a buffer or array in memory (returns all matches if all=true)
+- `pattern(needle, address, length, [all])` — Find a byte pattern in memory (supports wildcards, returns all matches if all=true)
 - `read(address, scratch)` — Read memory into a scratch (no allocations)
 - `write(address, scratch)` — Write a scratch to memory
 - Module map: `memory.modules['client.dll']`
@@ -83,10 +84,16 @@ void cs2.read(0x12345678n, array); // Fills array in-place
 const needle = 'deadbeef';
 // const needle = 'de**beef';
 // const needle = 'de????ef';
+// Find first match
 const address = cs2.pattern(needle, 0x10000000n, 0x1000);
 if (address !== -1n) {
   console.log(`Found at 0x${address.toString(16)}`);
 }
+// Find all matches
+const allAddresses = cs2.pattern(needle, 0x10000000n, 0x1000, true);
+for (const addr of allAddresses) {
+  console.log(`Found at 0x${addr.toString(16)}`);
+}
 ```
 
 ## Example: Pointer Chains
@@ -103,11 +110,16 @@ const address = cs2.follow(0x10000000n, [0x10n, 0x20n]);
 const needle = Buffer.from([0x01, 0x02, 0x03]);
 // const needle = new Uint8Array([0x01, 0x02, 0x03]);
 // const needle = new Uint32Array([0x012345, 0x123456, 0x234567]);
-// …etc…
+// Find first match
 const address = cs2.indexOf(needle, 0x10000000n, 0x1000);
 if (address !== -1n) {
   console.log(`Found at 0x${address.toString(16)}`);
 }
+// Find all matches
+const allAddresses = cs2.indexOf(needle, 0x10000000n, 0x1000, true);
+for (const addr of allAddresses) {
+  console.log(`Found at 0x${addr.toString(16)}`);
+}
 ```
 
 ## Example: Typed Arrays
@@ -117,7 +129,6 @@ if (address !== -1n) {
 const array = cs2.f32Array(0x12345678n, 4); // Float32Array of length 4
 // const array = cs2.u64Array(0x12345678n, 4);
 // const array = cs2.vector3Array(0x12345678n, 4);
-// …etc…
 cs2.i32Array(0x12345678n, new Int32Array([1, 2, 3, 4]));
 cs2.u64Array(0x12345678n, new BigUint64Array([1, 2, 3, 4]));
 cs2.vector3Array(0x12345678n, [{ x: 1, y: 2, z: 3 }]);

package/example/benchmark.ts

@@ -10,6 +10,8 @@ import Memory from 'bun-memory';
 import ClientDLLJSON from './offsets/client_dll.json';
 import OffsetsJSON from './offsets/offsets.json';
 
+const Iterations = 1e6;
+
 // Load the needed offsets as bigints… It's ugly but… IntelliSense! 🫠…
 const Client = {
   ...Object.fromEntries(Object.entries(ClientDLLJSON['client.dll'].classes).map(([class_, { fields }]) => [class_, Object.fromEntries(Object.entries(fields).map(([field, value]) => [field, BigInt(value)]))])),
@@ -32,11 +34,12 @@ if (ClientPtr === undefined) {
 // Warmup…
 console.log('Warming up…');
 
-for (let i = 0; i < 1e6; i++) {
+for (let i = 0; i < Iterations; i++) {
   const GlobalVarsPtr = cs2.u64(ClientPtr + Client.Other.dwGlobalVars);
   /* */ const CurTime = cs2.f32(GlobalVarsPtr + 0x30n);
 
   const lPlayerControllerPtr = cs2.u64(ClientPtr + Client.Other.dwLocalPlayerController);
+  /* */ const lPlayerName = cs2.string(lPlayerControllerPtr + Client.CBasePlayerController.m_iszPlayerName, 32);
 
   const lPlayerPawnPtr = cs2.u64(ClientPtr + Client.Other.dwLocalPlayerPawn);
   /* */ const lHealth = cs2.u32(lPlayerPawnPtr + Client.C_BaseEntity.m_iHealth);
@@ -52,75 +55,92 @@ const EntityListScratch = new BigUint64Array(0x200 / 0x08);
 const EntityClassInfoNames = new Map<bigint, string>();
 
 // Start the test…
-console.log('Starting the test…');
+for (let i = 0; i < 10; i++) {
+  console.log('Starting the test…');
 
-const performance1 = performance.now();
+  const start = performance.now();
 
-const EntityListPtr = cs2.u64(ClientPtr + Client.Other.dwEntityList);
+  const EntityListPtr = cs2.u64(ClientPtr + Client.Other.dwEntityList);
 
-for (let i = 0; i < 1e6; i++) {
-  try {
-    // Traverse the entity list and store it in `BaseEntityPtrs`…
-    cs2.read(EntityListPtr + 0x10n, EntityListScratch);
+  for (let j = 0; j < Iterations; j++) {
+    try {
+      // Traverse the entity list and store it in `BaseEntityPtrs`…
+      void cs2.read(EntityListPtr + 0x10n, EntityListScratch);
 
-    // Traverse each of the potential 64 entity chunks…
-    for (let i = 0; i < 0x40; i++) {
-      const EntityChunkPtr = EntityListScratch[i];
+      // Traverse each of the potential 64 entity chunks…
+      for (let k = 0; k < 0x40; k++) {
+        const EntityChunkPtr = EntityListScratch[k];
 
-      if (EntityChunkPtr === 0n) {
-        continue;
-      }
+        if (EntityChunkPtr === 0n) {
+          continue;
+        }
 
-      cs2.read(EntityChunkPtr, EntityChunkScratch);
+        void cs2.read(EntityChunkPtr, EntityChunkScratch);
 
-      // Traverse each of the potential 512 entities within this chunk…
-      // for (let j = 0, l = 0; j < 0x200; j++, l += 0x0f) {
-      for (let l = 0; l < 0x1e00; l += 0x0f) {
-        const BaseEntityPtr = EntityChunkScratch[l];
+        // Traverse each of the potential 512 entities within this chunk…
+        for (let l = 0; l < 0x1e00; l += 0x0f) {
+          const BaseEntityPtr = EntityChunkScratch[l];
 
-        if (BaseEntityPtr === 0n) {
-          continue;
-        }
+          if (BaseEntityPtr === 0n) {
+            continue;
+          }
 
-        const EntityClassInfoPtr = EntityChunkScratch[l + 0x01];
+          const EntityClassInfoPtr = EntityChunkScratch[l + 0x01];
 
-        let Name = EntityClassInfoNames.get(EntityClassInfoPtr);
+          let Name = EntityClassInfoNames.get(EntityClassInfoPtr);
 
-        if (Name === undefined) {
-          const SchemaClassInfoDataPtr = cs2.u64(EntityClassInfoPtr + 0x30n);
-          /* */ const NamePtr = cs2.u64(SchemaClassInfoDataPtr + 0x08n);
-          /*       */ Name = cs2.buffer(NamePtr, 0x20).toString();
+          if (Name === undefined) {
+            const SchemaClassInfoDataPtr = cs2.u64(EntityClassInfoPtr + 0x30n);
+            /* */ const NamePtr = cs2.u64(SchemaClassInfoDataPtr + 0x08n);
+            // /*       */ Name = cs2.buffer(NamePtr, 0x20).toString();
+            /*       */ Name = cs2.string(NamePtr, 0x40);
 
-          EntityClassInfoNames.set(EntityClassInfoPtr, Name);
-        }
+            EntityClassInfoNames.set(EntityClassInfoPtr, Name);
+          }
 
-        let BaseEntityPtrs_ = BaseEntityPtrs.get(Name);
+          let BaseEntityPtrs_ = BaseEntityPtrs.get(Name);
 
-        if (BaseEntityPtrs_ === undefined) {
-          BaseEntityPtrs_ = [];
+          if (BaseEntityPtrs_ === undefined) {
+            BaseEntityPtrs_ = [];
 
-          BaseEntityPtrs.set(Name, BaseEntityPtrs_);
-        }
+            BaseEntityPtrs.set(Name, BaseEntityPtrs_);
+          }
 
-        BaseEntityPtrs_.push(BaseEntityPtr);
+          BaseEntityPtrs_.push(BaseEntityPtr);
+        }
       }
-    }
 
-    // ! —————————————————————————————————————————————————————————————————————————————————————————————
-    // ! YOUR CODE GOES HERE…
-    // ! —————————————————————————————————————————————————————————————————————————————————————————————
-
-    // ! —————————————————————————————————————————————————————————————————————————————————————————————
-    // ! YOUR CODE ENDS HERE…
-    // ! —————————————————————————————————————————————————————————————————————————————————————————————
-  } finally {
-    // Clear the entity list…
-    for (const BaseEntityPtrs_ of BaseEntityPtrs.values()) {
-      BaseEntityPtrs_.length = 0;
+      // ! —————————————————————————————————————————————————————————————————————————————————————————————
+      // ! YOUR CODE GOES HERE…
+      // ! —————————————————————————————————————————————————————————————————————————————————————————————
+
+      // // Log our entities…
+      // console.log(
+      //   'Entities found this tick: %O',
+      //   Object.fromEntries([...BaseEntityPtrs.entries()].map(([Name, { length }]) => [Name, length])) //
+      // );
+
+      // ! —————————————————————————————————————————————————————————————————————————————————————————————
+      // ! YOUR CODE ENDS HERE…
+      // ! —————————————————————————————————————————————————————————————————————————————————————————————
+    } finally {
+      // Clear the entity list…
+      for (const BaseEntityPtrs_ of BaseEntityPtrs.values()) {
+        BaseEntityPtrs_.length = 0;
+      }
     }
   }
-}
 
-const performance2 = performance.now();
+  const end = performance.now();
+
+  const total = end - start;
+  const average = total / Iterations;
 
-console.log('Test completed in %fms…', (performance2 - performance1).toFixed(2));
+  console.log(
+    'Completed %d iterations in %ss, averaging %sms (%sµs) each…', //
+    Iterations,
+    (total / 1_000).toFixed(2),
+    average.toFixed(2),
+    (average * 1_000).toFixed(2)
+  );
+}

package/example/trigger-bot.ts

@@ -1,4 +1,4 @@
-import { FFIType, dlopen } from 'bun:ffi';
+import { FFIType, dlopen, ptr } from 'bun:ffi';
 import { sleep } from 'bun';
 
 import Memory from 'bun-memory';
@@ -32,28 +32,13 @@ const Client = {
 const cs2 = new Memory('cs2.exe');
 
 // Get the base for client.dll…
-const ClientPtr = cs2.modules['client.dll']?.base;
-
-if (ClientPtr === undefined) {
-  throw new TypeError('ClientPtr must not be undefined.');
-}
-
-// Get client.dll…
 const client = cs2.modules['client.dll'];
 
 if (client === undefined) {
-  throw new Error('client must not be undefined…');
+  throw new TypeError('client must not be undefined.');
 }
 
-// Byte pattern for AddNametag
-const needle = '40555356488dac24????????4881ec????????488bda488bf14885c9';
-
-// Find a byte pattern in memory (supports wildcards: ** and ??)…
-const addNametag = cs2.pattern(needle, client.base, client.size);
-
-if (addNametag !== -1n) {
-  console.log(`Found at 0x${addNametag.toString(16)}`); // Found at 0x7ffc8964e490
-}
+const ClientPtr = client.base;
 
 // Create a cache for class name strings… 🫠…
 const Cache_Names = new Map<bigint, string>();
@@ -114,7 +99,7 @@ async function tick(ClientPtr: bigint) {
     if (Name === undefined) {
       const SchemaClassInfoDataPtr = cs2.u64(EntityClassInfoPtr + 0x30n);
       /* */ const NamePtr = cs2.u64(SchemaClassInfoDataPtr + 0x08n);
-      /*       */ Name = cs2.cString(NamePtr, 0x80).toString();
+      /*       */ Name = cs2.string(NamePtr, 0x80);
 
       Cache_Names.set(EntityClassInfoPtr, Name);
     }

package/package.json

@@ -22,7 +22,7 @@
     "url": "git://github.com/obscuritysrl/bun-memory.git"
   },
   "type": "module",
-  "version": "1.1.34",
+  "version": "1.1.36",
   "main": "./index.ts",
   "keywords": [
     "bun",

package/structs/Memory.ts

@@ -7,7 +7,10 @@ const {
   symbols: { CloseHandle, CreateToolhelp32Snapshot, GetLastError, Module32FirstW, Module32NextW, OpenProcess, Process32FirstW, Process32NextW, ReadProcessMemory, VirtualQueryEx, WriteProcessMemory },
 } = dlopen('kernel32.dll', {
   CloseHandle: { args: [FFIType.u64], returns: FFIType.bool },
+  CreateRemoteThread: { args: [FFIType.u64, FFIType.u64, FFIType.u64, FFIType.u64, FFIType.u64, FFIType.u32, FFIType.ptr], returns: FFIType.u64 },
   CreateToolhelp32Snapshot: { args: [FFIType.u32, FFIType.u32], returns: FFIType.u64 },
+  GetCurrentProcess: { args: [], returns: FFIType.ptr },
+  GetExitCodeThread: { args: [FFIType.u64, FFIType.ptr], returns: FFIType.bool },
   GetLastError: { returns: FFIType.u32 },
   IsWow64Process2: { args: [FFIType.u64, FFIType.ptr, FFIType.ptr], returns: FFIType.bool },
   Module32FirstW: { args: [FFIType.u64, FFIType.ptr], returns: FFIType.bool },
@@ -16,8 +19,11 @@ const {
   Process32FirstW: { args: [FFIType.u64, FFIType.ptr], returns: FFIType.bool },
   Process32NextW: { args: [FFIType.u64, FFIType.ptr], returns: FFIType.bool },
   ReadProcessMemory: { args: [FFIType.u64, FFIType.u64, FFIType.ptr, FFIType.u64_fast, FFIType.ptr], returns: FFIType.bool },
+  VirtualAllocEx: { args: [FFIType.u64, FFIType.u64, FFIType.u64, FFIType.u32, FFIType.u32], returns: FFIType.u64 },
+  VirtualFreeEx: { args: [FFIType.u64, FFIType.u64, FFIType.u64, FFIType.u32], returns: FFIType.bool },
   VirtualProtectEx: { args: [FFIType.u64, FFIType.u64, FFIType.u64, FFIType.u32, FFIType.ptr], returns: FFIType.bool },
   VirtualQueryEx: { args: [FFIType.u64, FFIType.u64, FFIType.ptr, FFIType.u64], returns: FFIType.u64 },
+  WaitForSingleObject: { args: [FFIType.u64, FFIType.u32], returns: FFIType.u32 },
   WriteProcessMemory: { args: [FFIType.u64, FFIType.u64, FFIType.ptr, FFIType.u64_fast, FFIType.ptr], returns: FFIType.bool },
 });
 
@@ -28,6 +34,7 @@ const {
  *
  * Many scalar reads utilize `TypedArray` scratches to avoid a second FFI hop, such as calling `bun:ffi.read.*`.
  *
+ * @todo Add call method for calling functions in remote process.
  * @todo Add support for 32 or 64-bit processes using IsWow64Process2 (Windows 10+).
  * @todo When adding 32-bit support, several u64 will need changed to u64_fast.
  *
@@ -109,6 +116,8 @@ class Memory {
     throw new Error(`Process not found: ${identifier}…`);
   }
 
+  // public call(address: bigint, args: { type: FFIType, value: any }[] = [], timeout: number = 5_000): bigint {}
+
   /**
    * Memory protection flags for safe and unsafe regions.
    * Used to filter readable/writable memory areas.
@@ -124,7 +133,8 @@ class Memory {
    */
   private static readonly Patterns = {
     MatchAll: /(?:[0-9A-Fa-f]{2})+/g,
-    Test: /^(?:\*{2}|[0-9A-Fa-f]{2}|\?{2})+$/,
+    Test: /^(?=.*[0-9A-Fa-f]{2})(?:\*{2}|\?{2}|[0-9A-Fa-f]{2})+$/,
+    // Test: /^(?:\*{2}|[0-9A-Fa-f]{2}|\?{2})+$/,
   };
 
   /**
@@ -170,9 +180,10 @@ class Memory {
   private readonly ScratchMemoryBasicInformation = Buffer.allocUnsafe(0x30 /* sizeof(MEMORY_BASIC_INFORMATION) */);
   private readonly ScratchModuleEntry32W = Buffer.allocUnsafe(0x438 /* sizeof(MODULEENTRY32W) */);
 
-  private static TextDecoderUTF16 = new TextDecoder('utf-16');
   private static TextDecoderUTF8 = new TextDecoder('utf-8');
 
+  private static TextEncoderUTF8 = new TextEncoder('utf-8');
+
   private readonly hProcess: bigint;
   private readonly th32ProcessID: number;
 
@@ -189,43 +200,6 @@ class Memory {
     return this._modules;
   }
 
-  /**
-   * Returns memory regions in a given address range.
-   * @param address Start address.
-   * @param length Number of bytes to scan.
-   * @returns Array of memory regions.
-   */
-  private regions(address: bigint, length: bigint | number): Region[] {
-    const dwLength = 0x30; /* sizeof(MEMORY_BASIC_INFORMATION) */
-    let   lpAddress = BigInt(address); // prettier-ignore
-    const lpBuffer = this.ScratchMemoryBasicInformation;
-
-    const bVirtualQueryEx = !!VirtualQueryEx(this.hProcess, lpAddress, lpBuffer, dwLength);
-
-    if (!bVirtualQueryEx) {
-      throw new Win32Error('VirtualQueryEx', GetLastError());
-    }
-
-    const end = lpAddress + BigInt(length);
-    const result: Region[] = [];
-
-    do {
-      const baseAddress = lpBuffer.readBigUInt64LE();
-      const protect = lpBuffer.readUInt32LE(36);
-      const regionSize = lpBuffer.readBigUInt64LE(24);
-      const state = lpBuffer.readUInt32LE(32);
-      const type = lpBuffer.readUInt32LE(40);
-
-      if ((protect & Memory.MemoryProtections.Safe) !== 0 && (protect & Memory.MemoryProtections.Unsafe) === 0 && state === 0x1000 /* MEM_COMMIT */) {
-        result.push({ base: baseAddress, protect, size: regionSize, state, type });
-      }
-
-      lpAddress = baseAddress + regionSize;
-    } while (lpAddress < end && !!VirtualQueryEx(this.hProcess, lpAddress, lpBuffer, dwLength));
-
-    return result;
-  }
-
   /**
    * Closes the process handle.
    * @example
@@ -316,100 +290,6 @@ class Memory {
     return;
   }
 
-  /**
-   * Follows a pointer chain with offsets.
-   * @param address Base address.
-   * @param offsets Array of pointer offsets.
-   * @returns Final address after following the chain, or -1n if any pointer is null.
-   * @example
-   * ```ts
-   * const cs2 = new Memory('cs2.exe');
-   * const myAddress = cs2.follow(0x10000000n, [0x10n, 0x20n]);
-   * ```
-   */
-  public follow(address: bigint, offsets: readonly bigint[]): bigint {
-    const last = offsets.length - 1;
-
-    for (let i = 0; i < last; i++) {
-      address = this.u64(address + offsets[i]);
-
-      if (address === 0n) {
-        return -1n;
-      }
-    }
-
-    return address + (offsets[last] ?? 0n);
-  }
-
-  /**
-   * Finds the address of a byte pattern in memory. `**` and `??` match any byte.
-   * @param needle Hex string pattern to search for (e.g., 'deadbeed', 'dead**ef', 'dead??ef').
-   * @param address Start address to search.
-   * @param length Number of bytes to search.
-   * @returns Address of the pattern if found, or -1n.
-   * @example
-   * ```ts
-   * const cs2 = new Memory('cs2.exe');
-   * const addr = cs2.pattern('dead**ef', 0x10000000n, 0x1000);
-   * ```
-   */
-  public pattern(needle: string, address: bigint, length: number): bigint {
-    const test = Memory.Patterns.Test.test(needle);
-
-    if (!test) {
-      return -1n;
-    }
-
-    const tokens = [...needle.matchAll(Memory.Patterns.MatchAll)]
-      .map((match) => ({ buffer: Buffer.from(match[0], 'hex'), index: match.index >>> 1, length: match[0].length >>> 1 })) //
-      .sort(({ length: a }, { length: b }) => b - a);
-
-    if (tokens.length === 0) {
-      return needle.length >>> 1 <= length ? address : -1n;
-    }
-
-    const anchor = tokens.shift()!;
-
-    const haystack = this.buffer(address, length);
-
-    const end = length - (needle.length >>> 1);
-    let   start = haystack.indexOf(anchor.buffer); // prettier-ignore
-
-    if (start === -1) {
-      return -1n;
-    }
-
-    outer: do {
-      const base = start - anchor.index;
-
-      if (base < 0) {
-        continue;
-      } else if (base > end) {
-        return -1n;
-      }
-
-      for (const { buffer, index, length } of tokens) {
-        const sourceEnd = base + index + length,
-          sourceStart = base + index,
-          target = buffer,
-          targetEnd = length,
-          targetStart = 0;
-
-        const compare = haystack.compare(target, targetStart, targetEnd, sourceStart, sourceEnd);
-
-        if (compare !== 0) {
-          continue outer;
-        }
-      }
-
-      return address + BigInt(base);
-
-      // Finish…
-    } while ((start = haystack.indexOf(anchor.buffer, start + 0x01)) !== -1);
-
-    return -1n;
-  }
-
   /**
    * Reads memory into a buffer.
    * @param address Address to read from.
@@ -540,7 +420,13 @@ class Memory {
     if (typeof lengthOrValue === 'number') {
       const scratch = new Uint8Array(lengthOrValue);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
+
+      const indexOf = scratch.indexOf(0x00);
+
+      if (indexOf === -1) {
+        scratch[lengthOrValue - 1] = 0x00;
+      }
 
       return new CString(scratch.ptr);
     }
@@ -599,7 +485,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new Float32Array(length);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -658,7 +544,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new Float64Array(length);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -717,7 +603,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new Int16Array(length);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -776,7 +662,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new Int32Array(length);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -835,7 +721,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new BigInt64Array(length);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -894,7 +780,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new Int8Array(length);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -924,7 +810,7 @@ class Memory {
     if (values === undefined) {
       const scratch = new Float32Array(0x09);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -956,7 +842,7 @@ class Memory {
     if (values === undefined) {
       const scratch = new Float32Array(0x0c);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -988,7 +874,7 @@ class Memory {
     if (values === undefined) {
       const scratch = new Float32Array(0x10);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -1024,7 +910,7 @@ class Memory {
 
       const scratch = new Uint32Array(size);
 
-      this.read(elementsPtr, scratch);
+      void this.read(elementsPtr, scratch);
 
       return scratch;
     }
@@ -1054,7 +940,7 @@ class Memory {
     const Scratch8Float32Array = this.Scratch8Float32Array;
 
     if (value === undefined) {
-      this.read(address, Scratch8Float32Array);
+      void this.read(address, Scratch8Float32Array);
 
       const x = Scratch8Float32Array[0x00],
             y = Scratch8Float32Array[0x01]; // prettier-ignore
@@ -1089,7 +975,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new Float32Array(length * 2);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       const result = new Array<Vector2>(length);
 
@@ -1152,7 +1038,7 @@ class Memory {
     const Scratch12Float32Array = this.Scratch12Float32Array;
 
     if (value === undefined) {
-      this.read(address, Scratch12Float32Array);
+      void this.read(address, Scratch12Float32Array);
 
       const pitch = Scratch12Float32Array[0x00],
             roll  = Scratch12Float32Array[0x02],
@@ -1189,7 +1075,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new Float32Array(length * 0x03);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       const result = new Array<QAngle>(length);
 
@@ -1266,7 +1152,7 @@ class Memory {
     const Scratch16Float32Array = this.Scratch16Float32Array;
 
     if (value === undefined) {
-      this.read(address, Scratch16Float32Array);
+      void this.read(address, Scratch16Float32Array);
 
       const w = Scratch16Float32Array[0x03],
             x = Scratch16Float32Array[0x00],
@@ -1305,7 +1191,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new Float32Array(length * 0x04); // 4 * f32 per Quaternion
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       const result = new Array<Quaternion>(length);
 
@@ -1384,7 +1270,7 @@ class Memory {
     const Scratch3 = this.Scratch3;
 
     if (value === undefined) {
-      this.read(address, Scratch3);
+      void this.read(address, Scratch3);
 
       const r = Scratch3[0x00],
             g = Scratch3[0x01],
@@ -1446,7 +1332,7 @@ class Memory {
     const Scratch4 = this.Scratch4;
 
     if (value === undefined) {
-      this.read(address, Scratch4);
+      void this.read(address, Scratch4);
 
       const r = Scratch4[0x00],
             g = Scratch4[0x01],
@@ -1492,6 +1378,43 @@ class Memory {
     return this;
   }
 
+  /**
+   * Reads or writes a UTF-8 string.
+   * @param address Address to access.
+   * @param lengthOrValue Length to read or string to write.
+   * @returns The string at address, or this instance if writing.
+   * @notice When writing, remember to null-terminate your string (e.g., 'hello\0').
+   * @example
+   * ```ts
+   * const cs2 = new Memory('cs2.exe');
+   * const myString = cs2.string(0x12345678n, 16);
+   * cs2.string(0x12345678n, 'hello\0');
+   * ```
+   */
+  public string(address: bigint, length: number): string;
+  public string(address: bigint, value: string): this;
+  public string(address: bigint, lengthOrValue: number | string): string | this {
+    if (typeof lengthOrValue === 'number') {
+      const scratch = new Uint8Array(lengthOrValue);
+
+      void this.read(address, scratch);
+
+      const indexOf = scratch.indexOf(0x00);
+
+      return Memory.TextDecoderUTF8.decode(
+        scratch.subarray(0, indexOf !== -1 ? indexOf : lengthOrValue) //
+      );
+
+      // return new CString(scratch.ptr).valueOf();
+    }
+
+    const scratch = Memory.TextEncoderUTF8.encode(lengthOrValue);
+
+    this.write(address, scratch);
+
+    return this;
+  }
+
   /**
    * Reads or writes a 16-bit unsigned integer.
    * @param address Address to access.
@@ -1539,7 +1462,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new Uint16Array(length);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -1598,7 +1521,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new Uint32Array(length);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -1657,7 +1580,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new BigUint64Array(length);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -1716,7 +1639,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new Uint8Array(length);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       return scratch;
     }
@@ -1854,7 +1777,7 @@ class Memory {
     const Scratch12Float32Array = this.Scratch12Float32Array;
 
     if (value === undefined) {
-      this.read(address, Scratch12Float32Array);
+      void this.read(address, Scratch12Float32Array);
 
       const x = Scratch12Float32Array[0x00],
             y = Scratch12Float32Array[0x01],
@@ -1891,7 +1814,7 @@ class Memory {
       const length = lengthOrValues;
       const scratch = new Float32Array(length * 0x03);
 
-      this.read(address, scratch);
+      void this.read(address, scratch);
 
       const result = new Array<Vector3>(length);
 
@@ -2002,30 +1925,190 @@ class Memory {
 
   // Public utility methods…
 
+  /**
+   * Follows a pointer chain with offsets.
+   * @param address Base address.
+   * @param offsets Array of pointer offsets.
+   * @returns Final address after following the chain, or -1n if any pointer is null.
+   * @example
+   * ```ts
+   * const cs2 = new Memory('cs2.exe');
+   * const myAddress = cs2.follow(0x10000000n, [0x10n, 0x20n]);
+   * ```
+   */
+  public follow(address: bigint, offsets: readonly bigint[]): bigint {
+    const last = offsets.length - 1;
+
+    for (let i = 0; i < last; i++) {
+      address = this.u64(address + offsets[i]);
+
+      if (address === 0n) {
+        return -1n;
+      }
+    }
+
+    return address + (offsets[last] ?? 0n);
+  }
+
   /**
    * Finds the address of a buffer within a memory region.
-   * @param needle Buffer to search for.
+   * @param needle Buffer or typed array to search for.
    * @param address Start address.
    * @param length Number of bytes to search.
-   * @returns Address of the buffer if found, or -1n.
+   * @param all If true, returns all matches as an array. If false or omitted, returns the first match or -1n.
+   * @returns Address of the buffer if found, or -1n. If all is true, returns an array of addresses.
    * @example
    * ```ts
    * const cs2 = new Memory('cs2.exe');
-   * const myAddress = cs2.indexOf(new Uint8Array([1,2,3]), 0x10000000n, 100);
+   * const needle = Buffer.from('Hello world!');
+   * // const needle = Buffer.from([0x01, 0x02, 0x03]);
+   * // const needle = new Uint8Array([0x01, 0x02, 0x03]);
+   * // const needle = new Float32Array([0x01, 0x02, 0x03]);
+   * // Find first match
+   * const address = cs2.indexOf(needle, 0x10000000n, 100);
+   * // Find all matches
+   * const allAddressess = cs2.indexOf(needle, 0x10000000n, 100, true);
    * ```
    */
-  public indexOf(needle: Scratch, address: bigint, length: number): bigint {
+  public indexOf(needle: Scratch, address: bigint, length: number): bigint;
+  public indexOf(needle: Scratch, address: bigint, length: number, all: false): bigint;
+  public indexOf(needle: Scratch, address: bigint, length: number, all: true): bigint[];
+  public indexOf(needle: Scratch, address: bigint, length: number, all: boolean = false): bigint | bigint[] {
     const haystack = Buffer.allocUnsafe(length);
 
-    this.read(address, haystack);
-
     const needleBuffer = ArrayBuffer.isView(needle) //
       ? Buffer.from(needle.buffer, needle.byteOffset, needle.byteLength)
       : Buffer.from(needle);
 
-    const indexOf = haystack.indexOf(needleBuffer);
+    void this.read(address, haystack);
+
+    if (!all) {
+      const indexOf = haystack.indexOf(needleBuffer);
+
+      return indexOf !== -1 ? BigInt(indexOf) + address : -1n;
+    }
+
+    const results: bigint[] = [];
+
+    let start = haystack.indexOf(needleBuffer);
+
+    if (start === -1) {
+      return results;
+    }
+
+    do {
+      results.push(address + BigInt(start));
+    } while ((start = haystack.indexOf(needleBuffer, start + 0x01)) !== -1);
+
+    return results;
+  }
+
+  /**
+   * Finds the address of a byte pattern in memory. `**` and `??` match any byte.
+   * @param needle Hex string pattern to search for (e.g., 'deadbeed', 'dead**ef', 'dead??ef').
+   * @param address Start address to search.
+   * @param length Number of bytes to search.
+   * @param all If true, returns all matches as an array. If false or omitted, returns the first match or -1n.
+   * @returns Address of the pattern if found, or -1n. If all is true, returns an array of addresses.
+   * @example
+   * ```ts
+   * const cs2 = new Memory('cs2.exe');
+   * // Find first match
+   * const address = cs2.pattern('dead**ef', 0x10000000n, 0x1000);
+   * // Find all matches
+   * const allAddresses = cs2.pattern('dead**ef', 0x10000000n, 0x1000, true);
+   * ```
+   */
+  public pattern(needle: string, address: bigint, length: number): bigint;
+  public pattern(needle: string, address: bigint, length: number, all: false): bigint;
+  public pattern(needle: string, address: bigint, length: number, all: true): bigint[];
+  public pattern(needle: string, address: bigint, length: number, all: boolean = false): bigint | bigint[] {
+    const test = Memory.Patterns.Test.test(needle);
+
+    if (!test) {
+      return !all ? -1n : [];
+    }
+
+    // The RegExp test ensures that we have at least one token…
+
+    const tokens = [...needle.matchAll(Memory.Patterns.MatchAll)]
+      .map((match) => ({ buffer: Buffer.from(match[0], 'hex'), index: match.index >>> 1, length: match[0].length >>> 1 })) //
+      .sort(({ length: a }, { length: b }) => b - a);
+
+    const anchor = tokens.shift()!;
+
+    const haystack = this.buffer(address, length);
+
+    const end = length - (needle.length >>> 1);
+    let   start = haystack.indexOf(anchor.buffer); // prettier-ignore
+
+    if (start === -1) {
+      return !all ? -1n : [];
+    }
+
+    if (!all) {
+      outer: do {
+        const base = start - anchor.index;
+
+        if (base < 0) {
+          continue;
+        }
+
+        if (base > end) {
+          return -1n;
+        }
+
+        for (const { buffer, index, length } of tokens) {
+          const sourceEnd = base + index + length,
+                sourceStart = base + index,
+                target = buffer,
+                targetEnd = length,
+                targetStart = 0; // prettier-ignore
+
+          const compare = haystack.compare(target, targetStart, targetEnd, sourceStart, sourceEnd);
+
+          if (compare !== 0) {
+            continue outer;
+          }
+        }
+
+        return address + BigInt(base);
+      } while ((start = haystack.indexOf(anchor.buffer, start + 0x01)) !== -1);
+
+      return -1n;
+    }
+
+    const results: bigint[] = [];
+
+    outer: do {
+      const base = start - anchor.index;
+
+      if (base < 0) {
+        continue;
+      }
+
+      if (base > end) {
+        return results;
+      }
+
+      for (const { buffer, index, length } of tokens) {
+        const sourceEnd = base + index + length,
+              sourceStart = base + index,
+              target = buffer,
+              targetEnd = length,
+              targetStart = 0; // prettier-ignore
+
+        const compare = haystack.compare(target, targetStart, targetEnd, sourceStart, sourceEnd);
+
+        if (compare !== 0) {
+          continue outer;
+        }
+      }
+
+      results.push(address + BigInt(base));
+    } while ((start = haystack.indexOf(anchor.buffer, start + 0x01)) !== -1);
 
-    return indexOf !== -1 ? BigInt(indexOf) + address : -1n;
+    return results;
   }
 }