bun-memory 1.1.12 → 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
 
@@ -24,7 +25,7 @@ bun add bun-memory
 
 ## Usage
 
-See [example/trigger-bot.ts](example/trigger-bot.ts) for a real-world example.
+See [example/trigger-bot.ts](example/trigger-bot.ts) for a real-world example for Counter-Strike 2.
 
 ### Basic Example
 
@@ -32,42 +33,95 @@ See [example/trigger-bot.ts](example/trigger-bot.ts) for a real-world example.
 import Memory from 'bun-memory';
 
 // Attach to process by name…
-const memory = new Memory('notepad.exe');
-// …or PID
-const memory = new Memory(1234);
+const memory = new Memory('cs2.exe');
+// …or PID…
+const memory = new Memory(1_234);
 
-// Access loaded modules
+// 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`);
 
-// Read a 32-bit integer
-const value = memory.i32(0x12345678n);
+const client = modules['client.dll'];
 
-// Write a float
-memory.f32(0x12345678n, 3.14159);
+console.log(`Base address: 0x${client.base.toString(16)}`);
+console.log(`Size: ${client.size} bytes`);
 
-// Clean up
+// Read a 32-bit integer…
+const value = memory.i32(client.base + 0x12345678n);
+
+// Write a float…
+memory.f32(client.base + 0x12345678n, 3.14159);
+
+// Clean up…
 memory.close();
 ```
 
-### Pattern Scanning
+### 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 offset = memory.findPattern('aa??bbccdd??ff', mainModule.modBaseAddr, mainModule.modBaseSize);
-const value = memory.bool(offset + 0x1234n);
-memory.close();
-```
+const handles = new Uint32Array(0x100);
 
-### Efficient Buffer Reads
+while (true) {
+  try {
+    memory.read(myAddress, handles); // Updated handles, no allocations…
+
+    // Do something with your handles…
+    for (const handle of handles) {
+      // …
+    }
+  } finally {
+    continue;
+  }
+}
+```
 
 ```ts
-const scratch = Buffer.allocUnsafe(0xf000);
-const view = new BigUint64Array(scratch.buffer, scratch.byteOffset, 0xf000 / 8);
+const buffer = Buffer.allocUnsafe(0xf000); // Use buffer as a scratch…
+const pointers = new BigUint64Array(scratchBuffer.buffer, scratchBuffer.byteOffset, 0xf000 / 8);
 
 while (true) {
-  memory.read(myAddress, scratch); // Updates scratch and view, no allocations
+  try {
+    memory.read(myAddress, buffer); // Updates buffer and pointers, no allocations…
+
+    // Do something with your pointers…
+    for (const pointer of pointers) {
+      // Read a 32 length string at pointer…
+      const myString = memory.cString(pointer, 32).toString();
+
+      // …
+    }
+  } finally {
+    continue;
+  }
 }
 ```
 
@@ -76,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/example/trigger-bot.ts

@@ -11,15 +11,6 @@ import OffsetsJSON from './offsets/offsets.json';
 
 const { random } = Math;
 
-// !
-const buffer = Buffer.from('Hello world!');
-const bufferPtr = ptr(buffer);
-
-const cString = new CString(bufferPtr);
-
-console.log(cString.byteLength, cString.byteOffset); // undefined undefined
-// !
-
 const Delay = 2.5;
 
 // Load user32.dll…
@@ -54,14 +45,24 @@ if (ClientPtr === undefined) {
 }
 // !
 
-console.time('Read test');
+const dec = new TextDecoder('utf-8');
 
-for (let i = 0; i < 10_000_000; i++) {
-  // new Uint8Array((random() * 256 + 1) >> 0);
-  Buffer.allocUnsafe((random() * 256 + 1) >> 0);
+const buffer = Buffer.allocUnsafe(32);
+const pointers = [4749947025128n, 4749937696488n, 4749757372648n, 4745786211048n, 4745800086248n, 4748263960808n, 4748274490088n, 4748287459048n, 4747096900328n, 4747107757288n];
+
+console.time('test');
+
+while (true) {
+  for (const pointer of pointers) {
+    const cString = cs2.cString(pointer, 32).toString();
+
+    if (cString.length > 32) {
+      console.log(cString);
+    }
+  }
 }
 
-console.timeEnd('Read test');
+console.timeEnd('test');
 
 // !
 

package/package.json

@@ -22,7 +22,7 @@
     "url": "git://github.com/obscuritysrl/bun-memory.git"
   },
   "type": "module",
-  "version": "1.1.12",
+  "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,6 +167,18 @@ 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');
+
   /**
    * Handle to the target process.
    */
@@ -185,7 +196,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('notepad.exe');
    * const modules = memory.modules;
    *
    * // Access a specific module
@@ -211,7 +221,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('notepad.exe');
    * const regions = memory.regions(0x10000000n, 0x1000n);
    *
    * regions.forEach(region => {
@@ -265,7 +274,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('notepad.exe');
    * const buffer = new Uint8Array(4);
    * memory.read(0x12345678n, buffer);
    * ```
@@ -295,7 +303,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('notepad.exe');
    * const buffer = new Uint8Array([0x41, 0x42, 0x43, 0x44]);
    * memory.write(0x12345678n, buffer);
    * ```
@@ -342,8 +349,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('notepad.exe');
-   *
    * // Initial modules
    * console.log('Initial modules:', Object.keys(memory.modules));
    *
@@ -401,8 +406,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read a boolean value
    * const isAlive = memory.bool(0x12345678n);
    * console.log('Player is alive:', isAlive);
@@ -444,14 +447,14 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read up to 64 bytes and interpret as a C string
    * const playerName = memory.cString(0x12345678n, 64);
    * console.log('Player name:', playerName.toString());
    *
    * // Write a C string (NUL-terminated)
-   * const value = new CString('PlayerOne');
+   * const valueBuffer = Buffer.from('PlayerOne\0');
+   * const valuePtr = ptr(valueBuffer);
+   * const value = new CString(valuePtr);
    * memory.cString(0x12345678n, value);
    * ```
    */
@@ -482,8 +485,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read a float value
    * const playerHealth = memory.f32(0x12345678n);
    * console.log('Player health:', playerHealth);
@@ -517,8 +518,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read an array of 10 float values
    * const coordinates = memory.f32Array(0x12345678n, 10);
    * console.log('Coordinates:', coordinates);
@@ -556,8 +555,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('scientific_app.exe');
-   *
    * // Read a double precision value
    * const preciseValue = memory.f64(0x12345678n);
    * console.log('Precise value:', preciseValue);
@@ -591,8 +588,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('scientific_app.exe');
-   *
    * // Read an array of 5 double precision values
    * const preciseData = memory.f64Array(0x12345678n, 5);
    * console.log('Precise data:', preciseData);
@@ -630,8 +625,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read a signed 16-bit integer
    * const temperature = memory.i16(0x12345678n);
    * console.log('Temperature:', temperature);
@@ -665,8 +658,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('audio_app.exe');
-   *
    * // Read an array of audio samples
    * const samples = memory.i16Array(0x12345678n, 1024);
    * console.log('Audio samples:', samples);
@@ -704,8 +695,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read a player's score
    * const score = memory.i32(0x12345678n);
    * console.log('Player score:', score);
@@ -739,8 +728,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read inventory item counts
    * const inventory = memory.i32Array(0x12345678n, 20);
    * console.log('Inventory:', inventory);
@@ -778,8 +765,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('database.exe');
-   *
    * // Read a large number (timestamp, file size, etc.)
    * const timestamp = memory.i64(0x12345678n);
    * console.log('Timestamp:', timestamp);
@@ -813,8 +798,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('database.exe');
-   *
    * // Read an array of large numbers
    * const largeNumbers = memory.i64Array(0x12345678n, 10);
    * console.log('Large numbers:', largeNumbers);
@@ -852,8 +835,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read a small signed value (e.g., direction, state)
    * const direction = memory.i8(0x12345678n);
    * console.log('Direction:', direction);
@@ -887,8 +868,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read an array of small signed values
    * const directions = memory.i8Array(0x12345678n, 8);
    * console.log('Movement directions:', directions);
@@ -917,6 +896,117 @@ class Memory {
     return this;
   }
 
+  /**
+   * Reads a 3×3 matrix from memory or writes a 3×3 matrix to memory.
+   *
+   * The matrix is represented as 9 contiguous 32-bit floating-point values (`Float32Array`).
+   * No transposition or stride is applied—values are copied exactly as stored in memory.
+   *
+   * @param address - Memory address to read from or write to
+   * @param values - Optional `Float32Array` of length 9 to write. If omitted, performs a read operation
+   * @returns `Float32Array` of length 9 when reading, or this `Memory` instance when writing
+   * @throws {RangeError} When `values.length` is not exactly 9
+   *
+   * @example
+   * ```typescript
+   * // Read a 3×3 matrix
+   * const matrix = memory.matrix3x3(0x12345678n); // Float32Array(9)
+   *
+   * // Write a 3×3 matrix (length must be 9)
+   * const next = new Float32Array([
+   *   1, 0, 0,
+   *   0, 1, 0,
+   *   0, 0, 1
+   * ]);
+   * memory.matrix3x3(0x12345678n, next);
+   * ```
+   */
+  public matrix3x3(address: bigint): Float32Array;
+  public matrix3x3(address: bigint, values: Float32Array): this;
+  public matrix3x3(address: bigint, values?: Float32Array): Float32Array | this {
+    if (values === undefined) {
+      const scratch = new Float32Array(0x09);
+
+      this.read(address, scratch);
+
+      return scratch;
+    }
+
+    if (values.length !== 0x09) {
+      throw new RangeError('values.length must be 9.');
+    }
+
+    this.write(address, values);
+
+    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.
+   *
+   * The matrix is represented as 16 contiguous 32-bit floating-point values (`Float32Array`).
+   * No transposition or stride is applied—values are copied exactly as stored in memory.
+   *
+   * @param address - Memory address to read from or write to
+   * @param values - Optional `Float32Array` of length 16 to write. If omitted, performs a read operation
+   * @returns `Float32Array` of length 16 when reading, or this `Memory` instance when writing
+   * @throws {RangeError} When `values.length` is not exactly 16
+   *
+   * @example
+   * ```typescript
+   * // Read a 4×4 matrix
+   * const matrix = memory.matrix4x4(0x12345678n); // Float32Array(16)
+   *
+   * // Write a 4×4 matrix (length must be 16)
+   * const next = new Float32Array([
+   *   1, 0, 0, 0,
+   *   0, 1, 0, 0,
+   *   0, 0, 1, 0,
+   *   0, 0, 0, 1
+   * ]);
+   * memory.matrix4x4(0x12345678n, next);
+   * ```
+   */
+  public matrix4x4(address: bigint): Float32Array;
+  public matrix4x4(address: bigint, values: Float32Array): this;
+  public matrix4x4(address: bigint, values?: Float32Array): Float32Array | this {
+    if (values === undefined) {
+      const scratch = new Float32Array(0x10);
+
+      this.read(address, scratch);
+
+      return scratch;
+    }
+
+    if (values.length !== 0x10) {
+      throw new RangeError('values.length must be 16.');
+    }
+
+    this.write(address, values);
+
+    return this;
+  }
+
   /**
    * Reads a `NetworkUtlVector` (`Uint32Array`) from memory or writes a `NetworkUtlVector` to memory.
    *
@@ -936,8 +1026,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('network_app.exe');
-   *
    * // Read the current vector
    * const ids = memory.networkUtlVector(0x12345678n);
    * console.log('IDs:', Array.from(ids));
@@ -969,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.
@@ -979,8 +1164,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read player rotation
    * const rotation = memory.quaternion(0x12345678n);
    * console.log('Player rotation:', rotation);
@@ -1022,8 +1205,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read bone rotations for skeletal animation
    * const boneRotations = memory.quaternionArray(0x12345678n, 50);
    * console.log('Bone rotations:', boneRotations);
@@ -1082,8 +1263,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read a port number or small positive value
    * const port = memory.u16(0x12345678n);
    * console.log('Network port:', port);
@@ -1117,8 +1296,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('network_app.exe');
-   *
    * // Read an array of port numbers
    * const ports = memory.u16Array(0x12345678n, 10);
    * console.log('Active ports:', ports);
@@ -1156,8 +1333,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read player's money (always positive)
    * const money = memory.u32(0x12345678n);
    * console.log('Player money:', money);
@@ -1191,8 +1366,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read resource amounts
    * const resources = memory.u32Array(0x12345678n, 6);
    * console.log('Resources:', resources);
@@ -1230,8 +1403,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('database.exe');
-   *
    * // Read a very large positive number
    * const recordId = memory.u64(0x12345678n);
    * console.log('Record ID:', recordId);
@@ -1265,8 +1436,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('database.exe');
-   *
    * // Read an array of record IDs
    * const recordIds = memory.u64Array(0x12345678n, 100);
    * console.log('Record IDs:', recordIds);
@@ -1304,8 +1473,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read a byte value (0-255)
    * const opacity = memory.u8(0x12345678n);
    * console.log('UI opacity:', opacity);
@@ -1339,8 +1506,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('image_editor.exe');
-   *
    * // Read pixel data
    * const pixels = memory.u8Array(0x12345678n, 1024);
    * console.log('Pixel data:', pixels);
@@ -1379,8 +1544,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read player position
    * const position = memory.vector2(0x12345678n);
    * console.log('Player position:', position);
@@ -1418,8 +1581,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read waypoints for AI pathfinding
    * const waypoints = memory.vector2Array(0x12345678n, 20);
    * console.log('AI waypoints:', waypoints);
@@ -1479,8 +1640,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read player 3D position
    * const position = memory.vector3(0x12345678n);
    * console.log('Player 3D position:', position);
@@ -1520,8 +1679,6 @@ class Memory {
    *
    * @example
    * ```typescript
-   * const memory = new Memory('game.exe');
-   *
    * // Read vertex positions for 3D model
    * const vertices = memory.vector3Array(0x12345678n, 500);
    * console.log('3D vertices:', vertices);
@@ -1572,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;
+};