|
1 | | -> ⚠️ **WARNING:** |
2 | | -> This package relies heavily on **Bun's native FFI (`bun:ffi`)** for performance and interacting with system APIs. |
3 | | -> Furthermore, it interacts directly with the Windows API and is therefore **only compatible with Windows**. |
4 | | -> |
5 | | -> Currently, Bun does not provide a polyfill for `bun:ffi` when building for Node.js (`target: 'node'`). Therefore, this package is **only compatible with the Bun runtime** and **will not work** if run directly with Node.js. |
6 | | -> |
7 | | -> While Bun intends to add polyfills for `bun:*` modules in the future to improve Node.js compatibility for bundled code (see [Bundler Docs](https://bun.sh/docs/bundler#target)), this is not yet implemented for `bun:ffi`. |
8 | | -> |
9 | | -> **Requirements:** |
10 | | -> * Bun v1.2.9 or later (required to run the code) |
11 | | -
|
12 | | ---- |
13 | | - |
14 | 1 | <p align="center"> |
15 | 2 | <img alt="Banner" src="assets/banner.png"> |
16 | 3 | <br> |
|
32 | 19 | </a> |
33 | 20 | </p> |
34 | 21 |
|
35 | | -## Current Status |
36 | | - |
37 | | -This package is currently under active development. The following core functions are implemented and available for use: |
38 | | - |
39 | | -* `openProcess(processIdentifier: string | number): ProcessObject`: Opens a process by its name or ID. |
40 | | -* `closeProcess(handle: number): void`: Closes an opened process handle. |
41 | | -* `readMemory(handle: number, address: number, dataType: MemoryDataType): number`: Reads memory from a specific address in the target process. **Note:** Currently returns `number` for all types, including strings (returning the address). String content reading is planned. |
42 | | -* `writeMemory(handle: number, address: number, value: MemoryValueType, dataType: MemoryDataType): void`: Writes memory to a specific address in the target process. |
43 | | - |
44 | | -The `ProcessObject` object returned by `openProcess` contains information about the opened process: |
45 | | - |
46 | | -```typescript |
47 | | -interface ProcessObject { |
48 | | - dwSize: number; // Size of the structure, in bytes |
49 | | - th32ProcessID: number; // Process identifier (PID) |
50 | | - cntThreads: number; // Number of execution threads started by the process |
51 | | - th32ParentProcessID: number; // PID of the parent process |
52 | | - pcPriClassBase: number; // Base priority of threads created by this process |
53 | | - szExeFile: string; // Path to the executable file |
54 | | - handle: number; // Process handle (for read/write operations) |
55 | | - modBaseAddr: number; // Base address of the process's primary module |
56 | | -} |
57 | | -``` |
58 | | - |
59 | | -More functions are planned for future releases to expand the capabilities of this library. |
60 | | - |
61 | | -## Data Types |
62 | | - |
63 | | -The `dataType` parameter in `readMemory` and `writeMemory` specifies the type of data to be read or written. It accepts a specific set of string literals defined by the `MemoryDataType` type in TypeScript. The `value` parameter for `writeMemory` should correspond to this type, as defined by `MemoryValueType` (number, string, or boolean). |
64 | | - |
65 | | -### Supported Data Type Strings |
66 | | - |
67 | | -The following data type strings (and their aliases) are supported: |
68 | | - |
69 | | -* **8-bit Signed:** `byte`, `int8`, `char` |
70 | | -* **8-bit Unsigned:** `ubyte`, `uint8`, `uchar` |
71 | | -* **16-bit Signed:** `short`, `int16` |
72 | | -* **16-bit Unsigned:** `ushort`, `uint16`, `word` |
73 | | -* **32-bit Signed:** `int`, `int32`, `long` |
74 | | -* **32-bit Unsigned:** `uint`, `uint32`, `ulong`, `dword` |
75 | | -* **64-bit Signed:** `longlong`, `int64` (uses BigInt) |
76 | | -* **64-bit Unsigned:** `ulonglong`, `uint64` (uses BigInt) |
77 | | -* **Floating Point:** `float` (4 bytes), `double` (8 bytes) |
78 | | -* **Boolean:** `bool` (1 byte, 0 or 1) |
79 | | -* **String:** `string`, `str` (Null-terminated UTF-8) |
80 | | - |
81 | | -### TypeScript Type Definitions |
82 | | - |
83 | | -```typescript |
84 | | -/** Represents the valid data types for memory operations. */ |
85 | | -export type MemoryDataType = |
86 | | - | "byte" | "int8" | "char" // 8-bit signed |
87 | | - | "ubyte" | "uint8" | "uchar" // 8-bit unsigned |
88 | | - | "short" | "int16" // 16-bit signed |
89 | | - | "ushort" | "uint16" | "word" // 16-bit unsigned |
90 | | - | "int" | "int32" | "long" // 32-bit signed |
91 | | - | "uint" | "uint32" | "ulong" | "dword" // 32-bit unsigned |
92 | | - | "float" // 32-bit float |
93 | | - | "double" // 64-bit float |
94 | | - | "longlong" | "int64" // 64-bit signed (Note: JS Number limitations apply) |
95 | | - | "ulonglong" | "uint64" // 64-bit unsigned (Note: JS Number limitations apply) |
96 | | - | "bool" |
97 | | - | "string" | "str"; // Null-terminated string |
98 | | - |
99 | | -/** Represents the possible value types corresponding to MemoryDataType. */ |
100 | | -export type MemoryValueType = number | string | boolean; |
| 22 | +--- |
| 23 | + |
| 24 | +## 📖 API References (`src`) |
| 25 | + |
| 26 | +### Main Functions |
| 27 | + |
| 28 | +- **openProcess(processIdentifier: string | number, callback?): Process** |
| 29 | + Opens a process by name or ID. Returns the process handle or undefined if not found. |
| 30 | + |
| 31 | +- **closeHandle(handle: number): boolean** |
| 32 | + Closes a process handle. |
| 33 | + |
| 34 | +- **getProcesses(callback?): Process[]** |
| 35 | + Returns the list of running processes. |
| 36 | + |
| 37 | +- **findModule(moduleName: string, processId: number, callback?): Module | undefined** |
| 38 | + Finds a module by name in a process. |
| 39 | + |
| 40 | +- **getModules(processId: number, callback?): Module[]** |
| 41 | + Returns the modules loaded by a process. |
| 42 | + |
| 43 | +- **readMemory<T extends DataType>(handle: number, address: number, dataType: T, callback?): MemoryData<T> | undefined** |
| 44 | + Reads a value from a process's memory. |
| 45 | + |
| 46 | +- **writeMemory(handle: number, address: number, value: any, dataType: DataType): boolean** |
| 47 | + Writes a value to a process's memory. |
| 48 | + |
| 49 | +- **findPattern(...)** |
| 50 | + Scans memory patterns (multiple overloads). |
| 51 | + |
| 52 | +- **callFunction(handle: number, args: any[], returnType: number, address: number, callback?): any** |
| 53 | + Calls a function in the process's memory. |
| 54 | + |
| 55 | +- **Debugger** |
| 56 | + Utility class for process debugging. Main methods: `attach`, `detach`, `setHardwareBreakpoint`, `removeHardwareBreakpoint`, `monitor`. |
| 57 | + |
| 58 | +- **virtualAllocEx, virtualProtectEx, getRegions, virtualQueryEx, injectDll, unloadDll, openFileMapping, mapViewOfFile** |
| 59 | + Advanced memory and DLL manipulation functions. |
| 60 | + |
| 61 | +### Main Types and Constants (`types.ts`) |
| 62 | + |
| 63 | +- **type DataType** |
| 64 | + Supported data types for memory read/write: `'byte'`, `'int32'`, `'float'`, `'string'`, `'vector3'`, etc. |
| 65 | + |
| 66 | +- **type MemoryData<T extends DataType>** |
| 67 | + Maps a `DataType` to its corresponding JS type (`number`, `bigint`, `string`, `{x,y,z}`...) |
| 68 | + |
| 69 | +- **interface Process** |
| 70 | + Information about an opened process (PID, handle, etc). |
| 71 | + |
| 72 | +- **interface Module** |
| 73 | + Information about a module loaded in a process. |
| 74 | + |
| 75 | +- **type Protection, PageProtection, AllocationType, BreakpointTriggerType** |
| 76 | + Auxiliary types for memory flags and protection. |
| 77 | + |
| 78 | +- **const FunctionTypes, SignatureTypes, MemoryAccessFlags, MemoryPageFlags, HardwareDebugRegisters, BreakpointTriggerTypes** |
| 79 | + Constants for flags and function types. |
| 80 | + |
| 81 | +--- |
| 82 | + |
| 83 | +> See the [`src`](./src) folder for full details and comments on each function/type. |
0 commit comments