bun-memory 1.1.21 → 1.1.22

package/README.md

@@ -1,171 +1,119 @@
 # 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');
-
-// Get the loaded client.dll…
-const client = cs2.modules['client.dll'];
+const array = cs2.f32Array(0x12345678n, 4); // Float32Array of length 4
+cs2.i32Array(0x12345678n, new Int32Array([1, 2, 3, 4]));
+```
 
-// 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);
+## Example: Using Scratches (Recommended)
 
-// 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.22",
   "main": "./index.ts",
   "keywords": [
     "bun",