pcx-ai-toolkit

Source-grounded AI infrastructure for Perception.cx scripting — AngelScript, Lua, and Enma

Make LLMs write Perception.cx scripts from verified AngelScript, Lua, and Enma sources, not guessed APIs.

llms.txt bundles · source-backed API oracle · MCP server · code validators · hallucination evals · templates · native RE helpers

Install · AI workflow · Validation · MCP · Coverage · Safety

---

The point

LLMs are good at syntax shape and terrible at knowing which Perception APIs actually exist. pcx-ai-toolkit gives them a grounded contract:

flowchart LR
    P[Prompt] --> C[Context plan]
    C --> D[Source docs + llms bundles]
    D --> A[API lookup]
    A --> G[Generate script]
    G --> V[Validate code / answer / project]
    V -->|findings| R[Repair with citations]
    R --> V
    V -->|ok| S[Ship script]

Loading

Built for Perception.cx AngelScript, Lua, and Enma scripting AI agents that need small, precise context MCP clients that need lookup and validation tools Reverse-engineering workflows that need evidence discipline Users who want copy-paste setup and predictable checks

Not built for Invented helper APIs like draw_esp() Mixing syntax or APIs across script modes, or unregistered historical bindings Offset dumps without source evidence Malware, credential theft, or unauthorized targets Guessing when docs are silent

Install

npm / Bun

npm install -g pcx-ai-toolkit
# or
bun add -g pcx-ai-toolkit

pcx doctor
pcx ai-smoke

Python

python -m pip install pcx-ai-toolkit
pcx doctor
pcx ai-smoke

Source checkout

git clone --recursive https://github.com/VoidChecksum/pcx-ai-toolkit.git
cd pcx-ai-toolkit
./setup.sh
pcx doctor

Windows PowerShell

git clone --recursive https://github.com/VoidChecksum/pcx-ai-toolkit.git
cd pcx-ai-toolkit
powershell -ExecutionPolicy Bypass -File setup.ps1
pcx doctor

Requirements: Git, Python 3.10+, Node.js 18+. Rust/Cargo enables native RE binaries. Submodules are required for LSP and VSIX packaging.

Update later with one command:

pcx update
npm install -g pcx-ai-toolkit@latest
python -m pip install --upgrade pcx-ai-toolkit

Release publishing uses PyPI Trusted Publisher and npm Trusted Publisher where configured. Workflow filename: release.yml.

First command by job

Job	Command / file	Result
Need model instructions	pcx prompt --model claude	Copy-paste anti-hallucination prompt
Need setup targets	pcx agent-install --dry-run	Shows client install plan
Need API proof	pcx api draw_text	Exact signatures and source URLs
Need script validation	pcx verify file.em	Lint + symbol checks
Need project validation	pcx verify-project ./project	Project hygiene + evidence gates
Need answer validation	pcx check-answer answer.md	Checks fenced code blocks
Need all docs gates	pcx docs-check	Regeneration, drift, eval, focused tests
Need MCP workflow	mcp/pcx-knowledge-mcp/	Search, fetch, lookup, validate, scaffold
Need persistent agent memory	pcx prism	Optional Prism setup plan for PCX workflows

Task guides: validate Enma, AngelScript quickstart, Lua quickstart, use the knowledge MCP, create a scaffold, run live Perception MCP checks, use Prism memory.

Language contract

Three Perception.cx script modes — AngelScript (.as) and Lua (.lua) as current production targets, Enma (.em) as the future AOT transition target. Never mix syntax or APIs between modes. The registry in knowledge/language-modes.json is the source of truth for modes, extensions, and context packs; angelscript is the default.

Concern	AngelScript .as	Lua .lua	Enma .em
Status	Current production	Current production	Future AOT transition
Entry point	int main()	function main()	int64 main()
Repeating work	register_callback(fn, interval_ms, data_index)	register_callback(...) or on_frame()	register_routine(cast<int64>(fn), data)
Logging	log(...)	log(...)	println(...)
Arrays / maps	array<T> / dictionary	tables	T[] / map<K,V>, imap<V>
Render shapes	scalar x, y and RGBA args unless the AS page says otherwise	scalar x, y and RGBA args unless the Lua page says otherwise	vec2(...), color(r,g,b,a)
Validation	pcx verify file.as	pcx verify file.lua	pcx verify file.em

Validation rule: if the docs/API index do not prove it, do not use it. C++ helper syntax, JavaScript await, ImGui::*, invented game helpers, and cross-mode syntax mixing are rejected or flagged by validators.

AI workflow

Docs	Doc Lines	API Docs Indexed	API Functions	API Methods	Skills	Templates	MCP Tools	Native Tools
135	22,642	53	828	377	32	18	59	13

Minimal context load

1. Read docs/AI_AGENT_OPERATING_MANUAL.md
2. Read docs/perception/llm-routing.md
3. Load the pack for the target language:
   angelscript -> docs/llms-perception-angelscript.md (default)
   lua         -> docs/llms-perception-lua.md
   enma        -> docs/llms-perception-enma.md
4. Verify every API name with pcx api or MCP api_lookup
5. Validate final code with pcx verify, validate_code, or validate_answer

Copy-paste model instruction

You are writing Perception.cx scripts in one language mode at a time.
Confirm the target language first (angelscript | lua | enma); default to angelscript.
Before code, load docs/AI_AGENT_OPERATING_MANUAL.md and docs/perception/llm-routing.md.
Use the matching docs/llms-perception-<language>.md as the primary context pack.
Never mix syntax or APIs between modes. Do not use ImGui, C++ templates, or invented game helpers.
Verify every Perception host API and add-on symbol with pcx api <symbol> --lang <language> or MCP api_lookup.
Run validation before final answer. If the API index does not prove a symbol exists, say it is unverified instead of guessing.

Choose a context surface

Surface	Path	Best when
Entry index	docs/llms.txt	Tool auto-fetches llms.txt
AngelScript pack	docs/llms-perception-angelscript.md	Current-production AngelScript session
Lua pack	docs/llms-perception-lua.md	Current-production Lua session
Enma pack	docs/llms-perception-enma.md	Enma migration/AOT session
Full pack	docs/llms-full.txt	Tool accepts one large file
Skills pack	docs/llms-skills.md	Agent needs operating rules
Knowledge pack	docs/llms-knowledge.md	Agent needs patterns and RE context
API oracle	knowledge/pcx-api-index.json	Exact symbol/signature lookup
Dynamic MCP	mcp/pcx-knowledge-mcp	Long sessions and lazy retrieval

Validation pipeline

flowchart TD
    Q[Question or generated answer] --> L{Contains code?}
    L -->|No| C[Use docs + citations]
    L -->|Yes| E["Extract code blocks (em/as/lua)"]
    E --> S[Symbol lookup]
    S --> M[Import + lifecycle checks]
    M --> P[Permission and sentinel checks]
    P --> H[Hallucination regression patterns]
    H --> O{ok?}
    O -->|No| F[Return finding code + minimal repair]
    O -->|Yes| K[Safe to hand off]

Loading

Failure mode	Gate
Invented API names	pcx api, knowledge/pcx-api-index.json, MCP api_lookup
Wrong lifecycle	validate_code, symbol-check, routine-shape checks
Missing imports	Enma: module hints for vec, color, math, json, and others
Wrong argument shape	argument-count and rough constructor-shape validation
Permission-sensitive APIs	permission metadata and knowledge/permission-rules.json
Bad Markdown answer	pcx check-answer answer.md or MCP validate_answer
Regressed validator	tools/hallucination-eval.py expected-finding corpus
Generated docs drift	pcx docs-check

Coverage

Coverage truth is generated from committed artifacts. Do not hand-count these numbers.

Metric	Current
API families indexed	12
API pages indexed	20
Symbols indexed	216
Symbols with signatures	213
Hallucination eval cases	150
Drift-checkable sources	67

See docs/COVERAGE.md and docs/COVERAGE.json for generated target status.

MCP

pcx-knowledge-mcp exposes the repo as a tool surface for AI clients.

pip install -e mcp/pcx-knowledge-mcp/
pcx-knowledge-mcp --help

Recommended MCP call order:

overview()
recommend_context(task, "<language>")
generate_script_plan(task, "<language>")
scaffold_project(..., dry_run=true)
get_skill(name)
get_file(path)
api_lookup(symbol, "<language>")
validate_code(code, "<language>")
validate_answer(markdown)
validate_project(path)

<language> is angelscript (default), lua, or enma, per knowledge/language-modes.json.

Tool family	Purpose
Search/fetch	Find and load docs, knowledge, templates, and skills
Planning	Recommend minimal context and deterministic script plans
Grounding	Exact API lookup with source URLs
Validation	Check snippets, answers, and full projects
Scaffolding	Preview or create AngelScript, Lua, or Enma project templates

Client guides:

Client	Guide
Claude Code	mcp/claude-code-setup.md
Cursor	mcp/cursor-setup.md
Cline	mcp/pcx-knowledge-mcp/README.md
Continue	mcp/continue-setup.md
Zed	mcp/zed-setup.md
Aider	mcp/aider-setup.md

CLI map

Command	Purpose
pcx doctor	Check local install health
pcx prompt --model claude	Print model-specific operating prompt
pcx agent-install --dry-run	Preview agent/client config writes
pcx api <symbol> --lang <language>	Source-backed symbol lookup
pcx symbol-check script.as	Script-level symbol validation (also .lua, .em)
pcx verify script.as	Lint and symbol-check one script (also .lua, .em)
pcx verify-project ./project	Validate project layout, placeholders, symbols, evidence
pcx check-answer answer.md	Validate fenced code blocks in Markdown
pcx create --wizard	Interactive script project scaffold (em/as/lua)
pcx ai-smoke	Fast validator smoke test
pcx docs-check	One pre-ship docs/eval/test gate

Pre-ship gate:

pcx docs-check

Runs API index check, LLM bundle check, coverage dashboard check, internal links, doc drift, hallucination eval, and focused pytest suites.

Templates

pcx create --wizard
pcx create --name "PCX Enma Script" --language enma --kind cheat --target game.exe --output ./pcx-enma-script
pcx create --name "PCX AS Overlay" --language angelscript --kind overlay --target game.exe --output ./pcx-as-overlay
pcx verify-project ./pcx-enma-script --allow-placeholders --allow-unverified

Template	Use
hello-world	Minimal lifecycle sanity check
cheat-skeleton-em	Modular ESP, aim, menu, radar, triggerbot scaffold
full-project	Multi-file Enma project layout
overlay-basic	Focused render overlay example
minimap	Map/radar example
aimbot-skeleton	Aiming architecture skeleton
angelscript-overlay	Single-file AngelScript overlay/proc starter (--language angelscript)
lua-overlay	Single-file Lua overlay/proc starter (--language lua)

Native RE toolchain

The high-volume binary-analysis path is Rust-first with Python compatibility wrappers. Setup and CI build native binaries into tools/bin/; Python wrappers keep existing agent commands stable.

cargo build --release --manifest-path tools/pe-parser/Cargo.toml

Native tool	Wrapper	Use
pcx-rs	tools/pcx	Native command router and MCP helpers
api-lookup	tools/api-lookup.py	Source-backed API lookup
pattern-format-converter	tools/pattern-format-converter.py	Convert IDA/Ghidra/x64dbg/CE/Enma patterns
anti-debug-scanner	tools/anti-debug-scanner.py	Anti-debug imports, byte patterns, timing, strings
identify-protector	tools/identify-protector.py	Protector and packer heuristics
pe-section-analyzer	tools/pe-section-analyzer.py	Entropy, flags, overlays, section anomalies
analyze-vmprotect	tools/analyze-vmprotect.py	VMProtect section and entry-stub workflow
dump-strings-xor	tools/dump-strings-xor.py	Single-byte XOR string extraction
module-export-mapper	tools/module-export-mapper.py	Export listing and named consumer mapping
sig-uniqueness-checker	tools/sig-uniqueness-checker.py	Signature uniqueness and near-miss checks
binary-diff-summary	tools/binary-diff-summary.py	Patch-day section survival summary
offset-diff	tools/offset-diff.py	Direct and RIP-relative offset movement report

Editor packages

Package	Path	Language
Enma VS Code extension	lsp/enma-lsp/enma-language-1.1.22.vsix	.em, .em.predefined, .emb
Visual Studio extension	visualstudio/	Windows + MSBuild

Build locally:

./tools/package-vsix.sh

Manual VS Code packaging:

cd lsp/enma-lsp
npm install
npm run compile
npm run package

Visual Studio package:

msbuild visualstudio\EnmaVS\EnmaVS.csproj /p:Configuration=Release /restore

Repository map

pcx-ai-toolkit/
├── docs/                  Generated LLM bundles + local docs mirror
├── docs/perception/       Perception Enma API docs
├── docs/enma/             Enma language and SDK references
├── knowledge/             API index, metadata, patterns, forum insights
├── evals/                 Hallucination regression and model scorecards
├── templates/             Script scaffolds (em/as/lua)
├── tools/                 CLI, validators, builders, RE helpers
├── tools/pe-parser/       Rust-native parser, signature, diff, offset tools
├── mcp/                   Knowledge MCP and Perception MCP setup
├── rules/                 Drop-in agent instruction files
├── .claude/skills/        Agent skills for PCX work
├── signatures/            Engine and protector reversal signature packs
├── lsp/                   Enma VS Code extension submodule
└── visualstudio/          Visual Studio extension projects

Maintainer commands

python3 tools/build-counts.py
python3 tools/build-api-index.py --check
python3 tools/build-llms-index.py --check
python3 tools/build-coverage-dashboard.py --check
python3 tools/check-internal-links.py
python3 tools/check-doc-drift.py
python3 tools/hallucination-eval.py
pcx docs-check

Generated files include docs/llms*.txt, docs/COVERAGE.*, docs/COUNTS.json, and knowledge/pcx-api-index.json.

Safety

This toolkit is for authorized Perception.cx scripting, reverse engineering, security research, single-player modding, and defensive analysis. Only analyze software you own or are explicitly authorized to test.

The repository does not provide malware, stolen offsets, credential material, or binary payloads. Keep offset claims evidence-backed and mark placeholders until verified.

See SECURITY.md, CODE_OF_CONDUCT.md, and CONTRIBUTING.md.

License

MIT. See LICENSE.