bun-memory 1.1.27 → 1.1.29

package/README.md

@@ -11,6 +11,7 @@ Blazing fast, high-performance Windows process memory manipulation for Bun.
 - Attach to processes by name or PID
 - Efficient, allocation-free operations using user-provided buffers (scratches)
 - Module enumeration and pointer chain resolution
+- Pattern search with wildcards (`**` and `??`)
 - Read and write all primitive types, arrays, buffers, and common structures
 - Typed helpers for vectors, matrices, colors, and more
 
@@ -27,6 +28,8 @@ bun add bun-memory
 
 ## Quick Start
 
+❗ **Important**: [Example: Using Scratches (Recommended)](#example-using-scratches-recommended)
+
 ```ts
 import Memory from 'bun-memory';
 
@@ -59,26 +62,43 @@ See the code and type definitions for full details. All methods are documented w
 ## Example: Efficient Scratch Reuse
 
 ```ts
+// Reuse buffers and arrays for fast, allocation-free memory operations
 const buffer = Buffer.allocUnsafe(256);
-cs2.read(0x12345678n, buffer); // Fills buffer in-place
+void cs2.read(0x12345678n, buffer); // Fills buffer in-place
 // …use buffer…
 ```
 
 ```ts
+// Typed arrays work the same way
 const array = new Float32Array(32);
-cs2.read(0x12345678n, array); // Fills array in-place
+void cs2.read(0x12345678n, array); // Fills array in-place
 // …use buffer…
 ```
 
+## Example: Pattern Search
+
+```ts
+// Find a byte pattern in memory (supports wildcards: ** and ??)
+const needle = 'deadbeef';
+// const needle = 'de**beef';
+// const needle = 'de????ef';
+const address = cs2.pattern(needle, 0x10000000n, 0x1000);
+if (address !== -1n) {
+  console.log(`Found at 0x${address.toString(16)}`);
+}
+```
+
 ## Example: Pointer Chains
 
 ```ts
+// Follow a pointer chain to resolve nested addresses
 const address = cs2.follow(0x10000000n, [0x10n, 0x20n]);
 ```
 
 ## Example: Searching Memory
 
 ```ts
+// Search for a buffer or array in memory
 const needle = Buffer.from([0x01, 0x02, 0x03]);
 // const needle = new Uint8Array([0x01, 0x02, 0x03]);
 // const needle = new Uint32Array([0x012345, 0x123456, 0x234567]);
@@ -92,6 +112,7 @@ if (address !== -1n) {
 ## Example: Typed Arrays
 
 ```ts
+// Read or write arrays of numbers and structures
 const array = cs2.f32Array(0x12345678n, 4); // Float32Array of length 4
 // const array = cs2.u64Array(0x12345678n, 4);
 // const array = cs2.vector3Array(0x12345678n, 4);
@@ -103,9 +124,9 @@ cs2.vector3Array(0x12345678n, [{ x: 1, y: 2, z: 3 }]);
 
 ## Example: Using Scratches (Recommended)
 
-Scratches let you reuse buffers and typed arrays for repeated memory operations, avoiding unnecessary allocations and maximizing performance. This is the most efficient way to read or write large or frequent data.
-
 ```ts
+// Scratches let you reuse buffers and arrays for repeated memory operations
+// This avoids allocations and maximizes performance
 const array = new BigUint64Array(0xf000 / 0x08);
 
 while (true) {
@@ -121,7 +142,7 @@ const buffer = Buffer.allocUnsafe(256);
 const array = new Uint64Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 8);
 
 while (true) {
-  cs2.read(0x10000000n, buffer); // Updates array & buffer without allocations
+  cs2.read(0x10000000n, buffer); // Updates both array & buffer without allocations
   for (const element of array) {
     // …use element…
   }

package/example/benchmark.ts

@@ -35,14 +35,22 @@ console.log('Warming up…');
 for (let i = 0; i < 1e6; i++) {
   const GlobalVarsPtr = cs2.u64(ClientPtr + Client.Other.dwGlobalVars);
   /* */ const CurTime = cs2.f32(GlobalVarsPtr + 0x30n);
+
+  const lPlayerControllerPtr = cs2.u64(ClientPtr + Client.Other.dwLocalPlayerController);
+
+  const lPlayerPawnPtr = cs2.u64(ClientPtr + Client.Other.dwLocalPlayerPawn);
+  /* */ const lHealth = cs2.u32(lPlayerPawnPtr + Client.C_BaseEntity.m_iHealth);
+  /* */ const lTeamNum = cs2.u8(lPlayerPawnPtr + Client.C_BaseEntity.m_iTeamNum);
 }
 
 // Create caches and scratches to optimize performance…
-const Cache_Names = new Map<bigint, string>();
+const BaseEntityPtrs = new Map<string, bigint[]>();
 
 const EntityChunkScratch = new BigUint64Array(0xf000 / 0x08);
 const EntityListScratch = new BigUint64Array(0x200 / 0x08);
 
+const EntityClassInfoNames = new Map<bigint, string>();
+
 // Start the test…
 console.log('Starting the test…');
 
@@ -51,53 +59,64 @@ const performance1 = performance.now();
 const EntityListPtr = cs2.u64(ClientPtr + Client.Other.dwEntityList);
 
 for (let i = 0; i < 1e6; i++) {
-  const EntityClassInfoNames = new Map<string, bigint[]>();
-  const EntityClassInfoPtrs = new Map<bigint, bigint[]>();
+  try {
+    // Traverse the entity list and store it in `BaseEntityPtrs`…
+    cs2.read(EntityListPtr + 0x10n, EntityListScratch);
 
-  // Traverse the entity list…
-  cs2.read(EntityListPtr + 0x10n, EntityListScratch);
+    // Traverse each of the potential 64 entity chunks…
+    for (let i = 0; i < 0x40; i++) {
+      const EntityChunkPtr = EntityListScratch[i];
 
-  for (let i = 0; i < 0x40; i++) {
-    const EntityChunkPtr = EntityListScratch[i];
-
-    if (EntityChunkPtr === 0n) {
-      continue;
-    }
+      if (EntityChunkPtr === 0n) {
+        continue;
+      }
 
-    cs2.read(EntityChunkPtr, EntityChunkScratch);
+      cs2.read(EntityChunkPtr, EntityChunkScratch);
 
-    for (let j = 0, l = 0; j < 0x200; j++, l += 0x0f) {
-      const BaseEntityPtr = EntityChunkScratch[l];
+      // 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];
 
-      if (BaseEntityPtr === 0n) {
-        continue;
-      }
+        if (BaseEntityPtr === 0n) {
+          continue;
+        }
 
-      const EntityClassInfoPtr = EntityChunkScratch[l + 0x01];
+        const EntityClassInfoPtr = EntityChunkScratch[l + 0x01];
 
-      let BaseEntityPtrs = EntityClassInfoPtrs.get(EntityClassInfoPtr);
+        let Name = EntityClassInfoNames.get(EntityClassInfoPtr);
 
-      if (BaseEntityPtrs === undefined) {
-        BaseEntityPtrs = [];
+        if (Name === undefined) {
+          const SchemaClassInfoDataPtr = cs2.u64(EntityClassInfoPtr + 0x30n);
+          /* */ const NamePtr = cs2.u64(SchemaClassInfoDataPtr + 0x08n);
+          /*       */ Name = cs2.buffer(NamePtr, 0x20).toString();
 
-        EntityClassInfoPtrs.set(EntityClassInfoPtr, BaseEntityPtrs);
-      }
+          EntityClassInfoNames.set(EntityClassInfoPtr, Name);
+        }
 
-      BaseEntityPtrs.push(BaseEntityPtr);
-    }
+        let BaseEntityPtrs_ = BaseEntityPtrs.get(Name);
 
-    for (const [EntityClassInfoPtr, BaseEntityPtrs] of EntityClassInfoPtrs) {
-      let Name = Cache_Names.get(EntityClassInfoPtr);
+        if (BaseEntityPtrs_ === undefined) {
+          BaseEntityPtrs_ = [];
 
-      if (Name === undefined) {
-        const SchemaClassInfoDataPtr = cs2.u64(EntityClassInfoPtr + 0x30n);
-        /* */ const NamePtr = cs2.u64(SchemaClassInfoDataPtr + 0x08n);
-        /*       */ Name = cs2.cString(NamePtr, 0x2a).toString();
+          BaseEntityPtrs.set(Name, BaseEntityPtrs_);
+        }
 
-        Cache_Names.set(EntityClassInfoPtr, Name);
+        BaseEntityPtrs_.push(BaseEntityPtr);
       }
+    }
 
-      EntityClassInfoNames.set(Name, BaseEntityPtrs);
+    // ! —————————————————————————————————————————————————————————————————————————————————————————————
+    // ! YOUR CODE GOES HERE…
+    // ! —————————————————————————————————————————————————————————————————————————————————————————————
+
+    // ! —————————————————————————————————————————————————————————————————————————————————————————————
+    // ! YOUR CODE ENDS HERE…
+    // ! —————————————————————————————————————————————————————————————————————————————————————————————
+  } finally {
+    // Clear the entity list…
+    for (const BaseEntityPtrs_ of BaseEntityPtrs.values()) {
+      BaseEntityPtrs_.length = 0;
     }
   }
 }

package/package.json

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

package/runtime/extensions.ts

@@ -182,7 +182,7 @@ declare global {
 /**
  * Installs the `ptr` property on all supported binary view prototypes.
  *
- * The property is non-enumerable and configurable. The getter calls `ptr(this)`.
+ * The property is non-enumerable and non-configurable. The getter calls `ptr(this)`.
  */
 const constructors = [ArrayBuffer, BigInt64Array, BigUint64Array, Buffer, DataView, Float32Array, Float64Array, Int16Array, Int32Array, Int8Array, SharedArrayBuffer, Uint16Array, Uint32Array, Uint8Array, Uint8ClampedArray] as const;
 

package/structs/Memory.ts

@@ -109,11 +109,24 @@ class Memory {
     throw new Error(`Process not found: ${identifier}…`);
   }
 
+  /**
+   * Memory protection flags for safe and unsafe regions.
+   * Used to filter readable/writable memory areas.
+   */
   private static readonly MemoryProtections = {
     Safe: 0x10 /* PAGE_EXECUTE */ | 0x20 /* PAGE_EXECUTE_READ */ | 0x40 /* PAGE_EXECUTE_READWRITE */ | 0x80 /* PAGE_EXECUTE_WRITECOPY */ | 0x02 /* PAGE_READONLY */ | 0x04 /* PAGE_READWRITE */ | 0x08 /* PAGE_WRITECOPY */,
     Unsafe: 0x100 /* PAGE_GUARD */ | 0x01 /* PAGE_NOACCESS */,
   };
 
+  /**
+   * Regex patterns for matching hex strings and wildcards in memory scans.
+   * Used by the pattern method.
+   */
+  private static readonly Patterns = {
+    MatchAll: /(?:[0-9A-Fa-f]{2})+/g,
+    Test: /^(?:\*{2}|[0-9A-Fa-f]{2}|\?{2})+$/,
+  };
+
   /**
    * Map of loaded modules in the process, keyed by module name.
    * @example
@@ -124,6 +137,10 @@ class Memory {
    */
   private _modules: { [key: string]: Module };
 
+  /**
+   * Scratch buffers and typed views for temporary FFI reads/writes.
+   * Used internally for efficient memory access and conversions.
+   */
   private readonly Scratch1 = new Uint8Array(0x01);
   private readonly Scratch1Int8Array = new Int8Array(this.Scratch1.buffer, this.Scratch1.byteOffset, 0x01);
 
@@ -324,6 +341,75 @@ class Memory {
     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.