VoidChecksum/pcx-ai-toolkit

## 问题所在 LLM 不懂 Enma。它们不了解 Perception.cx API。让它们编写 PCX 脚本，它们会臆造函数名、发明参数，并生成无法编译的代码。 ## 解决方案 为 AI 提供 **34,000 多行真实文档**以及 **12 条编码规则**，以防止最常见的错误。AI 会在编写代码前阅读实际文档，遵循真实的 API 签名，并生成可运行的脚本。 ``` Before: "Write me an ESP overlay" AI: *invents draw_esp(), uses int for addresses, forgets null checks* Result: Doesn't compile. Wrong types. Silent crashes. After: "Write me an ESP overlay" (with pcx-ai-toolkit loaded) AI: *reads render-api.md, uses draw_rect + draw_text, uint64 addresses, validates pointers* Result: Compiles. Runs. Correct API calls. ``` ## 快速开始 ``` # 1. Clone git clone --recursive https://github.com/VoidChecksum/pcx-ai-toolkit.git cd pcx-ai-toolkit # 2. Install (构建 LSPs, 安装 Claude Code skills) ./setup.sh # 3. 添加到你的项目 cp rules/CLAUDE.md /path/to/your/pcx-project/ ``` 大功告成。AI 现在会在编写代码前阅读文档。 ## 内部包含内容

### 文档 107 页，34,000 多行 - 完整的 Enma 语言规范 - 全部 18 个标准库 addon - 完整的 C++ SDK 嵌入指南 - 每个 PCX API (Enma, AngelScript, Lua) - IDE、Extensions、Analyzer 文档	### AI Skills 2 个 Claude Code / OMC skills - **game-hacking-pcx** — 文档索引，API 规则 - **game-cheat-guidelines** — 12 条行为规则 在处理 `.em`/`.as` 文件及 PCX 相关话题时自动触发
### 知识库 4 个参考文件，865 行 - Enma 语言速查表 - PCX API 速查表 - 实用代码模式（13 个方案） - 偏移量查找方法论	### 工具 MCP + LSP + 规则 - Perception MCP 配置（42+ 工具） - Enma LSP（语法、补全、悬停提示） - AngelScript+PCX LSP - 开箱即用的 CLAUDE.md / AGENTS.md

## Perception IDE — 内置脚本编辑器和 AI 助手 ## 目录结构 ``` pcx-ai-toolkit/ │ ├── docs/ 107 pages of documentation │ ├── enma/ ── Enma language, addons, SDK (50 files) │ │ ├── llms-language.md Complete language reference (2,861 lines) │ │ ├── llms-sdk.md Complete SDK reference (832 lines) │ │ ├── lang-*.md Language guide (10 files) │ │ ├── addon-*.md 18 standard library addons │ │ └── sdk-*.md SDK embedding guide (17 files) │ │ │ └── perception/ ── Perception.cx platform APIs │ ├── *.md Enma APIs (17 files) │ ├── angelscript/ AngelScript APIs (23 files) │ └── lua/ Lua APIs (17 files) │ ├── .claude/skills/ ── AI Skills │ ├── game-hacking-pcx/ Doc index + coding rules │ └── game-cheat-guidelines/ 12 behavioral guidelines │ ├── knowledge/ ── Quick References │ ├── enma-cheatsheet.md Language quick-ref card │ ├── pcx-api-cheatsheet.md All APIs at a glance │ ├── common-patterns.md 13 working code recipes │ └── offset-methodology.md Sig scanning methodology │ ├── rules/ ── Project Rules │ ├── CLAUDE.md Drop-in for Claude Code │ └── AGENTS.md 5 agent role definitions │ ├── mcp/ ── MCP Configs │ ├── perception-mcp-config.json 42+ tool definitions │ ├── claude-code-setup.md Claude Code guide │ └── cursor-setup.md Cursor guide │ ├── lsp/ ── Language Servers (submodules) │ ├── enma-lsp/ Enma: completion + diagnostics │ └── angel-lsp-pcx/ AngelScript: completion + diagnostics │ ├── signatures/source-engine/ ── Signature Examples │ ├── setup.sh One-command install ├── CONTRIBUTING.md Contribution guide └── LICENSE MIT ``` ## 文档覆盖率

语料库	文件	行数	覆盖范围
Enma 语言	50	13,518	每种类型、运算符、控制流、函数、指针、结构体、类、模板、协程、异常、FFI、注解、模块、预处理器 + 全部 18 个 addon + 完整的 SDK
PCX Enma API	17	3,915	Proc, Render, GUI, Input, CPU, Zydis, Unicorn, Net, Win, Filesystem, Sound, Lifecycle, MCP, IDE, Extensions, Analyzer
PCX AngelScript API	23	10,820	上述所有内容 + Intrinsics, Zydis Encoder, Bit Reinterpret, Mutex, Atomic Types, CS2 Extended
PCX Lua API	17	5,779	采用 Lua 语法的所有核心 API
总计	107	34,032

### Enma 语言文档细分

语言指南 — 10 个文件，3,150 行（点击展开）

| 文件 | 行数 | 主题 | |------|------:|--------| | `lang-basics.md` | 267 | 类型、变量、常量、运算符、控制流 | | `lang-functions.md` | 247 | 参数、默认值、引用、out、可变参数、lambda、闭包 | | `lang-pointers.md` | 357 | 堆指针、取地址、成员访问、空指针、按引用返回 | | `lang-structs-and-classes.md` | 912 | 值/引用类型、继承、虚表 (vtable)、接口、mixin、运算符 | | `lang-templates.md` | 173 | 泛型结构体和函数、单态化 | | `lang-advanced.md` | 562 | 委托、命名空间、协程、异常、智能指针、FFI | | `lang-annotations.md` | 209 | packed, align, reflect, serialize, export, dll, custom | | `lang-modules.md` | 100 | Import 系统、别名导入、.emb、多模块链接 | | `lang-pre-processor.md` | 77 | #define, #ifdef, #include, #pragma | | `lang-semantics-and-limits.md` | 181 | 语义保证、编译时拒绝、不存在的特性 |

标准库 Addon — 18 个文件，2,528 行（点击展开）

| Addon | 行数 | 关键类型 / 函数 | |-------|------:|----------------------| | Core | 42 | `print`, `println` | | Strings | 165 | `format`, `to_int`, `split`, `replace`, `substr`, 插值 | | Arrays | 119 | `T[]`, `push`, `pop`, `sort`, `contains`, `slice` | | Maps | 200 | `map`, `imap`, `get`, `set`, 迭代 | | Math | 137 | `sin`, `cos`, `atan2`, `sqrt`, `clamp`, `lerp`, `random` | | SIMD | 128 | SSE2: `f32x4`, `i32x4` 向量运算 | | Vectors | 135 | `vec2`, `vec3`, `vec4` | | 3D Math | 182 | `quat`, `mat4` | | Variant | 130 | 类型擦除的值容器 | | Atomic | 94 | `aint32`, `aint64` 原子操作 | | Bits | 117 | `popcount`, `clz`, `ctz`, `bswap`, `rotl` | | Time | 95 | `time_ms`, `time_us`, ISO 8601, `sleep` | | Regex | 61 | `match`, `find`, `replace`, `split`, 捕获 | | File | 125 | 沙盒文件 I/O（受权限控制） | | Thread | 120 | `mutex`, `lock_guard`, `condition_variable` | | Hash Set | 89 | `hash_set` | | Sorted Map | 89 | `sorted_map` 有序迭代 | | List | 192 | 双端 O(1) push/pop | | JSON | 108 | `json_parse`, `json_stringify`, `json_value` |

SDK 嵌入指南 — 17 个文件，3,795 行（点击展开）

| 文件 | 行数 | 主题 | |------|------:|-------| | `sdk-quick-start.md` | 126 | 最小化嵌入示例 | | `sdk-engine-lifecycle.md` | 166 | 创建、配置、销毁 | | `sdk-compilation.md` | 65 | 从源代码/文件编译 | | `sdk-execution.md` | 103 | 上下文、执行、读取返回值 | | `sdk-calling-functions.md` | 82 | 从宿主传递参数 | | `sdk-globals.md` | 79 | 读写脚本全局变量 | | `sdk-type-registration.md` | 862 | type_builder — 暴露原生类型 | | `sdk-native-functions.md` | 446 | 注册可由宿主调用的函数 | | `sdk-hot-reload.md` | 64 | 运行时替换代码 | | `sdk-serialization-and-linking.md` | 97 | .emb 二进制文件、多模块 | | `sdk-introspection.md` | 317 | 列出函数、注解、IR 导出 | | `sdk-lifecycle.md` | 227 | 确定性 RAII，无 GC | | `sdk-debug-and-gc.md` | 202 | 调试钩子、预算、堆状态 | | `sdk-error-handling.md` | 116 | 编译/运行时错误报告 | | `sdk-safety.md` | 121 | 故障捕获、沙盒、权限 | | `sdk-custom-addons.md` | 576 | 构建你自己的 addon | | `sdk-api-reference.md` | 411 | 完整的函数列表 |

## AI Skills ### `game-hacking-pcx` — 文档路由器 强制 AI 在编写任何 PCX API 调用之前，先阅读正确的文档文件。 ``` User: "Write me a render overlay" AI: → reads docs/perception/render-api.md (264 lines) → reads docs/perception/lifecycle-and-routines.md (134 lines) → writes code using real function signatures ``` 包含：全部 107 份文档的逐文件索引、关键的 Enma 类型规则、地址类型要求、RAII 注意事项。 ### `game-cheat-guidelines` — 12 条行为规则

#	规则	所能防止的问题
1	为每个偏移量提供依据	因使用旧版 SDK 的陈旧偏移量而浪费数小时
2	所有地址均使用 uint64	高用户态地址上的符号扩展损坏
3	验证每个指针	静默的空读取返回看似合理的垃圾数据
4	将更新与渲染分离	当内存读取阻塞绘制路径时导致覆盖层卡顿
5	优先使用特征码而非硬编码	每次游戏更新补丁都会导致脚本失效
6	一个功能，一个文件	2000 行的庞然大物无法进行热重载
7	每帧构造颜色/向量	为 4 字节的栈分配结构体使用无意义的全局变量
8	float32 加上 f 后缀	顶点缓冲区中静默的 float64 向 float32 截断
9	最小化内存写入	不必要的被检测风险面
10	只进行一次正确的 W2S	摄像机背后的坐标镜像，错误的矩阵布局
11	所有可调参数均使用 GUI	为了更改距离阈值而重新编译
12	使用二进制文件进行验证	盲目相信陈旧的缓存偏移量而忽略实时现状

每条规则都包含使用真实 Perception.cx API 的错误/正确代码示例。 ## 知识库

### Enma 速查表 每种原生类型及其大小、所有转换规则、控制流、函数、结构体与类、模板、数组、map、、指针、协程、异常、模块、预处理器、注解。 ### PCX API 速查表 全部 13 个 Perception.cx API 中的每个函数签名：Proc, Render, GUI, Input, CPU, Zydis, Unicorn, Net, Win, Filesystem, Sound, Lifecycle, MCP。

### 常见模式 13 个完整的可用示例： - 进程附加 + 模块解析 - 特征码扫描 + RIP 解析 - 带有空值保护的实体列表 - 世界坐标到屏幕坐标 (4x4 矩阵) - 方框覆盖层 + 血条 - 透视线、距离文本 - 角度计算、平滑插值 - GUI 菜单、配置保存/加载 - 带旋转的小地图 / 雷达 - 完整的脚本骨架 ### 偏移量方法论 特征码扫描、通配符策略、RIP 相对解析表、指针链遍历、struct_dump 发现、IDA/Ghidra 交叉引用、偏移量表格式、补丁稳定性分析。

## MCP 集成 ### Perception MCP Server

完整工具列表（点击展开）

**进程内存** `read_memory` · `read_typed_value` · `find_pattern` · `read_pointer_chain` · `read_string` · `memory_write` **分析** `disassemble` · `struct_dump` · `find_xrefs` · `find_string_refs` · `find_function_bounds` · `analyze_function` · `trace_register` · `analyze_vtable` · `read_rtti` · `generate_signature` · `build_call_graph` **扫描** `scan_string` · `scan_wstring` · `scan_pointer_to` · `scan_value` · `scan_changed` · `diff_memory` **进程信息** `list_processes` · `get_process_info` · `get_module_exports` · `get_module_imports` **文件与脚本** `read_file` · `write_file` · `edit_file` · `search_text` · `find_references` · `check_script` · `validate_script` · `execute_script` · `get_script_api` · `web_search`

配置：[`mcp/perception-mcp-config.json`](mcp/perception-mcp-config.json) ### 支持的 AI 工具 | 工具 | 方式 | 指南 | |:-----|:----|:------| | **Claude Code** | Skills + CLAUDE.md + MCP | [`claude-code-setup.md`](mcp/claude-code-setup.md) | | **Cursor** | .cursorrules + MCP + 文档 | [`cursor-setup.md`](mcp/cursor-setup.md) | | **Cline** | MCP 配置 + system prompt | 使用 MCP 配置，粘贴 CLAUDE.md | | **Perception IDE** | 原生 — 内置 AI 聊天 | 将 `docs/` 添加为工作区文件夹 | | **任何兼容 OpenAI 的工具** | System prompt + 文档 | 将 `rules/CLAUDE.md` 粘贴到提示词中 | ## LSP 语言服务器 | 服务器 | 语言 | 特性 | |:-------|:---------|:---------| | [enma-lsp](https://github.com/sinnafuls/enma-lsp) | Enma (`.em`) | 语法高亮、补全、悬停文档、诊断、Perception API 表面 | | [angel-lsp-pcx](https://github.com/sinnafuls/angel-lsp-pcx) | AngelScript (`.as`) | 语法高亮、补全、悬停文档、诊断、Perception API 表面 | 由 `setup.sh` 自动构建。编辑器配置： ``` Enma: node lsp/enma-lsp/server/dist/server.js --stdio AngelScript: node lsp/angel-lsp-pcx/server/out/server.js --stdio ``` ## 项目规则 ### `rules/CLAUDE.md` — 开箱即用的项目配置 复制到任何 PCX 脚本项目中。涵盖： - 语言和 API 声明 - 文档路径 - 编码标准（地址类型、浮点数后缀、RAII、转换） - 以单行形式呈现的 12 条指南 - 推荐的文件结构 ### `rules/AGENTS.md` — 多 Agent 角色定义 用于编排工作流的五个专家角色： | Agent | 职责 | |:------|:---------------| | **reverse-engineer** | 二进制分析、特征码生成、偏移量发现 | | **script-writer** | 遵循所有规则的 Enma/AngelScript 实现 | | **offset-maintainer** | 补丁后的偏移量表更新和验证 | | **feature-builder** | 使用常见模式实现功能 | | **reviewer** | 正确性、风格和检测风险面审查 | ## 贡献 详情请参阅 [CONTRIBUTING.md](CONTRIBUTING.md)。 1. 使用 `--recursive` Fork 并 clone 2. 添加或改进：文档、模式、模板、特征码、知识文件 3. 在全新的 clone 上使用 `./setup.sh` 进行测试 4. 发起 PR 特别欢迎新的实用模式和文档改进。

标签：AI开发工具, DLL 劫持, LSP, MCP, rizin, 大语言模型, 游戏作弊, 游戏辅助, 游戏逆向工程, 脚本开发