bun-memory 1.1.13 → 1.1.14

package/README.md

@@ -1,6 +1,7 @@
 # bun-memory
 
-High-performance Windows process memory utilities for [Bun](https://bun.sh) using `bun:ffi` and Win32 APIs.
+High-performance Windows process memory utilities for [Bun](https://bun.sh) using `bun:ffi` and
+Win32 APIs.
 
 ## Features
 
@@ -32,40 +33,59 @@ See [example/trigger-bot.ts](example/trigger-bot.ts) for a real-world example fo
 import Memory from 'bun-memory';
 
 // Attach to process by name…
-const memory = new Memory('notepad.exe');
+const memory = new Memory('cs2.exe');
 // …or PID…
 const memory = new Memory(1_234);
 
 // Access loaded modules…
 const modules = memory.modules;
-const mainModule = modules['notepad.exe'];
-console.log(`Base address: 0x${mainModule.modBaseAddr.toString(16)}`);
-console.log(`Size: ${mainModule.modBaseSize} bytes`);
+
+const client = modules['client.dll'];
+
+console.log(`Base address: 0x${client.base.toString(16)}`);
+console.log(`Size: ${client.size} bytes`);
 
 // Read a 32-bit integer…
-const value = memory.i32(0x12345678n);
+const value = memory.i32(client.base + 0x12345678n);
 
 // Write a float…
-memory.f32(0x12345678n, 3.14159);
+memory.f32(client.base + 0x12345678n, 3.14159);
 
 // Clean up…
 memory.close();
 ```
 
-### Pattern Scanning
-
-Pattern scanning is temporarily disabled but will return shortly.
-
-```ts
-const offset = memory.findPattern('aa??bbccdd??ff', mainModule.modBaseAddr, mainModule.modBaseSize);
-const value = memory.bool(offset + 0x1234n);
-memory.close();
-```
-
-### Efficient Buffer Reads
-
-There are many ways to use `scratch`es. Scratches are great for avoiding allocation costs by reusing a
-preexisting array, buffer, string, etc.
+### API — Typed Reads / Writes
+
+A `Memory` instance exposes typed helpers for reading and writing process memory. Pairs indicate
+scalar and array variants; entries without a pair are scalar-only or array-only.
+
+- bool
+- cString
+- f32 / f32Array
+- f64 / f64Array
+- i16 / i16Array
+- i32 / i32Array
+- i64 / i64Array
+- i8 / i8Array
+- matrix3x3
+- matrix3x4
+- matrix4x4
+- networkUtlVector
+- qAngle / qAngleArray
+- quaternion / quaternionArray
+- u16 / u16Array
+- u32 / u32Array
+- u64 / u64Array
+- u8 / u8Array
+- vector2 / vector2Array
+- vector3 / vector3Array
+- vector4 / vector4Array
+
+### Efficient Reads / Writes Using Scratches
+
+There are many ways to use `scratch`es. Scratches are great for avoiding allocation costs by reusing
+a preexisting array, buffer, string, etc.
 
 ```ts
 const handles = new Uint32Array(0x100);
@@ -110,6 +130,21 @@ const scratch = Buffer.allocUnsafe(0x100);
 memory.read(myAddress, scratch);
 ```
 
+```ts
+const scratch = new Uint32Array(0x10);
+memory.read(myAddress, scratch);
+```
+
+### Pattern Scanning
+
+Pattern scanning is temporarily disabled but will return shortly.
+
+```ts
+const offset = memory.findPattern('aa??bbccdd??ff', mainModule.modBaseAddr, mainModule.modBaseSize);
+const value = memory.bool(offset + 0x1234n);
+memory.close();
+```
+
 ## Notes
 
 - Only works with Bun and Windows.

package/package.json

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

package/structs/Memory.ts

@@ -1,10 +1,6 @@
-// TODO: Reintroduce findPattern(…)…
-// TODO: Reintroduce indexOf(…)…
-// TODO: String methods…
-
 import { CString, FFIType, dlopen, read } from 'bun:ffi';
 
-import type { Module, NetworkUtlVector, Quaternion, Region, Scratch, Vector2, Vector3 } from '../types/Memory';
+import type { Module, NetworkUtlVector, QAngle, Quaternion, Region, Scratch, Vector2, Vector3, Vector4 } from '../types/Memory';
 import Win32Error from './Win32Error';
 
 const { f32, f64, i16, i32, i64, i8, u16, u32, u64, u8 } = read;
@@ -33,6 +29,9 @@ const { symbols: Kernel32 } = dlopen('kernel32.dll', {
  * This class allows reading from and writing to memory addresses in external processes,
  * supporting various data types including primitives, arrays, and custom structures like vectors and quaternions.
  *
+ * @todo Reimplement `findPattern(…)`.
+ * @todo Reimplement `indexOf(…)`.
+ *
  * @example
  * ```typescript
  * // Connect to a process by name
@@ -168,7 +167,16 @@ class Memory {
   private readonly ScratchMemoryBasicInformation = Buffer.allocUnsafe(0x30 /* sizeof(MEMORY_BASIC_INFORMATION) */);
   private readonly ScratchModuleEntry32W = Buffer.allocUnsafe(0x438 /* sizeof(MODULEENTRY32W) */);
 
+  /**
+   * Reusable UTF-16 decoder for interpreting raw process memory as UTF-16 text.
+   * Kept as a singleton to avoid repeated allocations in hot paths.
+   */
   private static readonly TextDecoderUTF16 = new TextDecoder('utf-16');
+
+  /**
+   * Reusable UTF-8 decoder for interpreting raw process memory as UTF-8 text.
+   * Kept as a singleton to avoid repeated allocations in hot paths.
+   */
   private static readonly TextDecoderUTF8 = new TextDecoder('utf-8');
 
   /**
@@ -933,6 +941,26 @@ class Memory {
     return this;
   }
 
+  public matrix3x4(address: bigint): Float32Array;
+  public matrix3x4(address: bigint, values: Float32Array): this;
+  public matrix3x4(address: bigint, values?: Float32Array): Float32Array | this {
+    if (values === undefined) {
+      const scratch = new Float32Array(0x0c);
+
+      this.read(address, scratch);
+
+      return scratch;
+    }
+
+    if (values.length !== 0x0c) {
+      throw new RangeError('values.length must be 12.');
+    }
+
+    this.write(address, values);
+
+    return this;
+  }
+
   /**
    * Reads a 4×4 matrix from memory or writes a 4×4 matrix to memory.
    *
@@ -1029,6 +1057,103 @@ class Memory {
     return this;
   }
 
+  /**
+   * Reads a set of Euler angles from memory or writes a set of Euler angles to memory.
+   *
+   * Angles are stored as three 32-bit floats in the order **pitch, yaw, roll**.
+   *
+   * @param address - Memory address to read from or write to
+   * @param value - Optional `QAngle` to write. If omitted, performs a read operation
+   * @returns The `QAngle` value when reading, or this `Memory` instance when writing
+   *
+   * @example
+   * ```typescript
+   * // Read current view angles
+   * const view = memory.qAngle(0x12345678n);
+   *
+   * // Write new view angles (e.g., level the roll)
+   * memory.qAngle(0x12345678n, { ...view, roll: 0 });
+   * ```
+   */
+
+  public qAngle(address: bigint): QAngle;
+  public qAngle(address: bigint, value: QAngle): this;
+  public qAngle(address: bigint, value?: QAngle): QAngle | this {
+    if (value === undefined) {
+      this.read(address, this.Scratch12);
+
+      const pitch = f32(this.Scratch12.ptr);
+      const roll = f32(this.Scratch12.ptr, 0x08);
+      const yaw = f32(this.Scratch12.ptr, 0x04);
+
+      return { pitch, roll, yaw };
+    }
+
+    this.Scratch12Buffer.writeFloatLE(value.pitch);
+    this.Scratch12Buffer.writeFloatLE(value.roll, 0x08);
+    this.Scratch12Buffer.writeFloatLE(value.yaw, 0x04);
+
+    this.write(address, this.Scratch12);
+
+    return this;
+  }
+
+  /**
+   * Reads an array of Euler angles from memory or writes an array of Euler angles to memory.
+   *
+   * Each element is three 32-bit floats in the order **pitch, yaw, roll**.
+   *
+   * @param address - Memory address to read from or write to
+   * @param lengthOrValues - Length of array to read, or array of `QAngle` values to write
+   * @returns `QAngle[]` when reading, or this `Memory` instance when writing
+   *
+   * @example
+   * ```typescript
+   * // Read bone aim offsets
+   * const bones = memory.qAngleArray(0x12345678n, 64);
+   *
+   * // Write new bone angles (e.g., reset all roll to zero)
+   * bones.forEach(b => (b.roll = 0));
+   * memory.qAngleArray(0x12345678n, bones);
+   * ```
+   */
+  public qAngleArray(address: bigint, length: number): QAngle[];
+  public qAngleArray(address: bigint, values: QAngle[]): this;
+  public qAngleArray(address: bigint, lengthOrValues: QAngle[] | number): QAngle[] | this {
+    if (typeof lengthOrValues === 'number') {
+      const length = lengthOrValues;
+      const scratch = new Float32Array(length * 0x03);
+
+      this.read(address, scratch);
+
+      const result = new Array<QAngle>(length);
+
+      for (let i = 0, j = 0; i < length; i++, j += 0x03) {
+        const pitch = scratch[j];
+        const yaw = scratch[j + 0x01];
+        const roll = scratch[j + 0x02];
+        result[i] = { pitch, yaw, roll };
+      }
+
+      return result;
+    }
+
+    const values = lengthOrValues;
+    const scratch = new Float32Array(values.length * 0x03);
+
+    for (let i = 0, j = 0; i < values.length; i++, j += 0x03) {
+      const qAngle = values[i];
+
+      scratch[j] = qAngle.pitch;
+      scratch[j + 0x02] = qAngle.roll;
+      scratch[j + 0x01] = qAngle.yaw;
+    }
+
+    this.write(address, scratch);
+
+    return this;
+  }
+
   /**
    * Reads a quaternion (4D rotation) from memory or writes a quaternion to memory.
    * Quaternions are stored as four 32-bit floats: x, y, z, w.
@@ -1604,6 +1729,67 @@ class Memory {
 
     return this;
   }
+
+  /**
+   * Reads a 4D vector from memory or writes a 4D vector to memory.
+   *
+   * Uses the same 16-byte layout as {@link Memory.quaternion}: four 32-bit floats
+   * stored in the order **x, y, z, w**. Returned objects are shaped as `{ w, x, y, z }`.
+   *
+   * @param address - Memory address to read from or write to
+   * @param value - Optional `Vector4` to write. If omitted, performs a read operation
+   * @returns The `Vector4` value when reading, or this `Memory` instance when writing
+   *
+   * @example
+   * ```typescript
+   * // Read directional data in projective space
+   * const value = memory.vector4(0x12345678n);
+   *
+   * // Write a vector4 value (e.g., identity quaternion)
+   * memory.vector4(0x12345678n, { x: 0, y: 0, z: 0, w: 1 });
+   * ```
+   */
+  public vector4(address: bigint): Vector4;
+  public vector4(address: bigint, value: Vector4): this;
+  public vector4(address: bigint, value?: Vector4): Vector4 | this {
+    // TypeScript is funny sometimes, isn't it?… 🫠…
+    if (value === undefined) {
+      return this.quaternion(address);
+    }
+
+    return this.quaternion(address, value);
+  }
+
+  /**
+   * Reads an array of 4D vectors from memory or writes an array of 4D vectors to memory.
+   *
+   * Each element uses the same 16-byte layout as {@link Memory.quaternionArray}:
+   * four 32-bit floats stored in the order **x, y, z, w**.
+   *
+   * @param address - Memory address to read from or write to
+   * @param lengthOrValues - Length of array to read, or array of `Vector4` values to write
+   * @returns `Vector4[]` when reading, or this `Memory` instance when writing
+   *
+   * @example
+   * ```typescript
+   * // Read per-vertex tangent vectors (xyzw)
+   * const tangents = memory.vector4Array(0x12345678n, 1024);
+   *
+   * // Write tangent vectors (eg. normalize w to 1.0)
+   * tangents.forEach(v => (v.w = 1.0));
+   * memory.vector4Array(0x12345678n, tangents);
+   * ```
+   */
+  public vector4Array(address: bigint, length: number): Vector4[];
+  public vector4Array(address: bigint, values: Vector4[]): this;
+  public vector4Array(address: bigint, lengthOrValues: Vector4[] | number): Vector4[] | this {
+    // TypeScript is funny sometimes, isn't it?… 🫠…
+    if (typeof lengthOrValues === 'number') {
+      return this.quaternionArray(address, lengthOrValues);
+    }
+
+    return this.quaternionArray(address, lengthOrValues);
+  }
 }
 
 export default Memory;

package/types/Memory.ts

@@ -319,6 +319,68 @@ export type Quaternion = {
   z: number;
 };
 
+/**
+ * Represents an orientation using Euler angles.
+ *
+ * `QAngle` stores three 32-bit floating-point angles that describe rotation
+ * in degrees around the principal axes: `pitch` (X), `yaw` (Y), and `roll` (Z).
+ * This format is common in Source-engine-style telemetry and many gameplay
+ * camera systems. For quaternions, see {@link Quaternion}.
+ *
+ * Typical uses include:
+ * - Camera/view rotations
+ * - Bone/attachment orientations
+ * - Aim and recoil calculations
+ *
+ * @example
+ * ```typescript
+ * // Read and tweak view angles
+ * const view: QAngle = memory.qAngle(0x12345678n);
+ * const leveled: QAngle = { pitch: 0, yaw: view.yaw, roll: 0 };
+ * memory.qAngle(0x12345678n, leveled);
+ * ```
+ */
+export interface QAngle {
+  /**
+   * Rotation around the X axis, in degrees.
+   *
+   * Positive values pitch the nose downward in many right-handed game
+   * coordinate systems; verify the target engine’s convention before writing.
+   *
+   * @example
+   * ```typescript
+   * const aimDown: QAngle = { pitch: 10, yaw: 0, roll: 0 };
+   * ```
+   */
+  pitch: number;
+
+  /**
+   * Rotation around the Z axis, in degrees.
+   *
+   * Often used for banking/tilt effects. Some engines clamp or ignore roll for
+   * first-person cameras.
+   *
+   * @example
+   * ```typescript
+   * const slightBank: QAngle = { pitch: 0, yaw: 0, roll: 5 };
+   * ```
+   */
+  roll: number;
+
+  /**
+   * Rotation around the Y axis, in degrees.
+   *
+   * Positive values typically turn to the right (clockwise when viewed from
+   * above) in right-handed systems.
+   *
+   * @example
+   * ```typescript
+   * const turnRight: QAngle = { pitch: 0, yaw: 90, roll: 0 };
+   * ```
+   */
+  yaw: number;
+}
+
 /**
  * Represents a memory region with its properties and protection flags.
  *
@@ -791,3 +853,32 @@ export type Vector3 = {
    */
   z: number;
 };
+
+/**
+ * Represents a 4D vector with w, x, y, z components.
+ *
+ * Common use cases:
+ * - Homogeneous coordinates (w ≠ 0)
+ * - Colors with alpha (x = R, y = G, z = B, w = A)
+ * - Packed attributes and shader parameters
+ * - As a quaternion carrier when interoperating with APIs expecting {x,y,z,w}
+ *
+ * Memory layout used by {@link Memory.vector4} is four 32-bit floats stored in
+ * the order **x, y, z, w**, while this type exposes `{ w, x, y, z }` for
+ * consistency with {@link Quaternion}.
+ *
+ * @example
+ * ```typescript
+ * // RGBA color
+ * const red: Vector4 = { x: 255, y: 0, z: 0, w: 255 };
+ *
+ * // Homogeneous point (x, y, z, w)
+ * const p: Vector4 = { x: 10, y: 20, z: 30, w: 1 };
+ * ```
+ */
+export type Vector4 = {
+  w: number;
+  x: number;
+  y: number;
+  z: number;
+};