bun-memory 1.1.21 → 1.1.23

package/README.md

@@ -1,171 +1,121 @@
 # bun-memory
 
-High-performance Windows process memory utilities for [Bun](https://bun.sh) using `bun:ffi` and
-Win32 APIs.
+Blazing fast, high-performance Windows process memory manipulation for Bun.
 
-## Features
+## Overview
+
+`bun-memory` provides fast, allocation-conscious tools for reading and writing memory in external Windows processes. Designed for Bun and Windows 10/11, it exposes a single class, `Memory`, with a clear, type-safe API for all common memory operations.
 
-- Built for Bun runtime and Windows 10/11
-- Efficient buffer management for high-speed operations
-- Pattern scanning for offsets \*
-- Read and write memory of Windows processes
+## Features
 
-\* — Feature temporarily disabled
+- Attach to processes by name or PID
+- Read and write all primitive types, arrays, buffers, and common structures
+- Efficient, allocation-free operations using user-provided buffers (scratches)
+- Module enumeration and pointer chain resolution
+- Typed helpers for vectors, matrices, colors, and more
 
 ## Requirements
 
-- **Bun** (uses `bun:ffi`)
-- **Windows 10/11** (uses `kernel32.dll`)
+- Bun runtime
+- Windows 10 or later
 
 ## Installation
 
-```bash
+```sh
 bun add bun-memory
 ```
 
-## Usage
-
-See [example/trigger-bot.ts](example/trigger-bot.ts) for a real-world example for Counter-Strike 2.
-
-### Basic Example
+## Quick Start
 
 ```ts
 import Memory from 'bun-memory';
 
-// Attach to process by name…
-const memory = new Memory('cs2.exe');
-// …or PID…
-const memory = new Memory(1_234);
+// Attach to a process by name
+const cs2 = new Memory('cs2.exe');
 
-// Access loaded modules…
-const modules = memory.modules;
+// Read a float
+const myFloat = cs2.f32(0x12345678n);
 
-const client = modules['client.dll'];
+// Write an int
+cs2.i32(0x12345678n, 42);
+
+// Access loaded modules
+const client = cs2.modules['client.dll'];
+
+// Clean up
+cs2.close();
+```
 
-console.log(`Base: 0x%s — Size: %d bytes…`, client.base.toString(16), client.size);
+## API Highlights
 
-const address = memory.follow(client.base + 0x12345678n, [0x10n, 0x20n, 0x30n]);
+- `follow(address, offsets)` — Follow a pointer chain
+- `read(address, scratch)` — Read memory into a scratch (no allocations)
+- `write(address, scratch)` — Write a scratch to memory
+- Module map: `memory.modules['client.dll']`
+- Typed accessors: `bool`, `f32`, `i32`, `matrix4x4`, `u8`, `u64Array`, `vector3`, etc.
 
-// Read a 32-bit integer…
-const value = memory.i32(address);
+See the code and type definitions for full details. All methods are documented with concise examples.
 
-// Write a float…
-memory.f32(address, 3.14159);
+## Example: Efficient Buffer Reuse
 
-// Clean up…
-memory.close();
+```ts
+const buffer = Buffer.allocUnsafe(256);
+cs2.read(0x12345678n, buffer); // Fills buffer in-place
+// …use buffer…
 ```
 
-### API — Follow / Read / Write
-
-Low-level helpers for pointer resolution and raw, allocation-free memory transfers. Use these when you need maximum control or want to reuse your own scratches.
-
-- follow
-- read
-- write
-
-### 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
-- buffer
-- 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.
+## Example: Pointer Chains
 
 ```ts
-const handles = new Uint32Array(0x100);
+const address = cs2.follow(0x10000000n, [0x10n, 0x20n]);
+```
 
-while (true) {
-  try {
-    memory.read(myAddress, handles); // Updated handles, no allocations…
-
-    // Do something with your handles…
-    for (const handle of handles) {
-      // …
-    }
-  } finally {
-    continue;
-  }
+## Example: Searching Memory
+
+```ts
+const needle = Buffer.from([0x48, 0x8b, 0x05]);
+const address = cs2.indexOf(needle, 0x10000000n, 0x1000);
+if (address !== -1n) {
+  console.log(`Found at 0x${address.toString(16)}`);
 }
 ```
 
 ```ts
-const buffer = Buffer.allocUnsafe(0xf000); // Use buffer as a scratch…
-const pointers = new BigUint64Array(scratchBuffer.buffer, scratchBuffer.byteOffset, 0xf000 / 8);
-
-while (true) {
-  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;
-  }
+const needle = new Uint32Array([0x01, 0x02, 0x03]);
+const address = cs2.indexOf(needle, 0x10000000n, 0x1000);
+if (address !== -1n) {
+  console.log(`Found at 0x${address.toString(16)}`);
 }
 ```
 
-### Searching Memory
-
-#### `findPattern`
-
-Pattern scanning is temporarily disabled but will return shortly.
-
-#### `indexOf`
-
-Find the first occurrence of a byte sequence within a memory range and return the absolute address (`bigint`) of the first match, or `-1n` when not found. Accepts any Scratch-compatible input (`Buffer`, `TypedArray`, `DataView`, `ArrayBuffer`, or `SharedArrayBuffer`). No region or protection checking is performed; ensure the range is readable before calling.
+## Example: Typed Arrays
 
 ```ts
-// Attach…
-const memory = new Memory('cs2.exe');
+const array = cs2.f32Array(0x12345678n, 4); // Float32Array of length 4
+cs2.i32Array(0x12345678n, new Int32Array([1, 2, 3, 4]));
+```
 
-// Get the loaded client.dll…
-const client = cs2.modules['client.dll'];
+## Example: Using Scratches (Recommended)
 
-// Choose any Scratch type for the needle (bytes are matched exactly as laid out in memory).
-const needle = Buffer.from([0x48, 0x8b, 0x05, 0x00, 0x00, 0x00, 0x00]);
-// const needle = new Uint8Array([0x48, 0x8B, 0x05, 0x00, 0x00, 0x00, 0x00]);
-// const needle = new Uint32Array([0xDEADBEEF, 0x11223344]);
-// const needle = new DataView(Uint8Array.from([0xde, 0xad, 0xbe, 0xef]).buffer);
+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.
 
-// Search client.dll for the byte sequence…
-const addeess = memory.indexOf(needle, client.base, client.size);
+```ts
+const buffer = Buffer.allocUnsafe(256);
+const array = new Uint64Array(buffer.buffer, buffer.byteOffset, buffer.byteLength / 8);
 
-if (address !== -1n) {
-  console.log(`Found at 0x${address.toString(16)}`);
+while (true) {
+  cs2.read(0x10000000n, buffer); // Updates array & buffer without allocations
+  for (const element of array) {
+    // …use element…
+  }
 }
 ```
 
 ## Notes
 
-- Only works with Bun and Windows.
+- Pattern scanning is temporarily disabled.
+- Windows only. Bun runtime required.
+
+---
+
+For real-world usage, see [example/trigger-bot.ts](example/trigger-bot.ts).

package/example/trigger-bot.ts

@@ -34,6 +34,10 @@ const { dwEntityList, dwGlobalVars, dwLocalPlayerController, dwLocalPlayerPawn }
   [K in keyof (typeof OffsetsJSON)['client.dll']]: bigint;
 };
 
+const a: bigint[] = [1n];
+
+console.log(typeof a);
+
 // Open a handle to cs2.exe…
 const cs2 = new Memory('cs2.exe');
 

package/package.json

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