samp.directory
← Scripts y librerías

qxlies/satk-gta

San Andreas ToolKit: GTA San Andreas modding, reverse-engineering and debugging toolkit for humans and AI agents (CLI + MCP)

Herramienta★ 2actualizado hace 12 díasMITPython
Abrir en GitHub

README.md

satk — San Andreas ToolKit

Русская версия

Status: public preview (0.4.0). satk works and its checks pass, but commands, answers and file layouts may still change before 1.0. Bug reports and ideas are welcome on the Issues page.

satk is a toolkit for GTA San Andreas (PC) modders, reverse engineers and people who debug the game. It indexes your game and lets you, or an AI assistant, find and inspect models, textures, map placements and crash addresses, build texture and model mods, register add-on cars, peds and weapons, tune handling, write CLEO scripts, generate collision, shrink textures, check mods for errors and conflicts, and convert maps. New in 0.4.0: asset authoring through design, form, composition, detail, surface and finish gates, with rounded form tools, an inventory of required parts, close-up previews and checks backed by independent review beside vanilla peers. The AI asset pipeline explains how to repeat the method with your own agents. It is one Python package with one command, satk, and one MCP server, also satk: both run the same operations and give the same answers.

Security and privacy

  • Your game is only read. The game folder, the clean copy and the source clones are write-protected; satk writes only into its own work folder (indexes, caches, pictures, exports, logs).
  • No network, no telemetry. satk opens no internet connections by itself; downloads happen only in commands you run on purpose (dependency setup, satk engine setup, satk dev release). satk doctor shows it as a check.
  • Bug reports stay local: satk bug-report writes a redacted file on your computer and sends nothing.
  • With a cloud AI assistant, what satk answers goes to that assistant's provider as part of the conversation; a fully local setup sends nothing. Details: docs/en/ai.md.

Works without AI

Every operation is a terminal command with readable tables: satk asset find, satk texture image, satk crash analyze, satk mod conflicts, and so on. satk help shows the main tasks, satk help --all every command, and satk catalog build makes an offline web page of all models, textures and zones. An AI assistant is an option on top: satk mcp config --client <name> connects Claude Code, Codex, Cursor, VS Code, LM Studio and others.

Install in three steps

You need 64-bit Windows 10/11 and any GTA San Andreas (PC) folder: 1.0 US, Steam, with or without mods.

  1. Get satk. The portable zip satk-<version>-win64.zip from the Releases page needs no Python and no admin rights: unpack it into your own folder and double-click Start satk.cmd. From a git checkout: clone github.com/qxlies/satk-gta into a folder named tools and run scripts\bootstrap.ps1 -Deps, which creates a Python 3.12+ venv. The Releases page also has the wheel satk_gta-<version>-py3-none-any.whl (not on PyPI yet) and SHA256SUMS.txt to check the downloads.
  2. Point it at your game: satk init finds the game itself (registry, Steam libraries, usual folders) or takes --game <folder>, and writes satk.toml.
  3. Index the game: satk index build, then try satk asset find infernus or satk help.
git clone https://github.com/qxlies/satk-gta.git tools
powershell -ExecutionPolicy Bypass -File tools\scripts\bootstrap.ps1 -Deps
tools\satk.cmd init --game "<folder with gta_sa.exe>"
tools\satk.cmd index build

Everything about installing (zip, git, Python package, where work lives, Windows blocking unsigned files): docs/en/install.md. From zero to the first screenshot: docs/en/quickstart.md.

What is inside

CommandsWhat they doPage
satk gameverify, protect and reproduce a clean game copygame.md
satk formatsparsers of IMG, DFF, TXD, COL, IDE, IPL, IFP, ZON, DATformats.md
satk index, asset, worldSQLite index of all assets and placements: search, references, SQLindex.md
satk texture, map image, modeltexture sheets, the top-down map, GPU-free model previews, export to glTF/OBJmedia.md, models.md
satk texture pack, rw, col, imgtexture mods, DFF/COL/IMG writing without Blendertexmod.md, rw.md
satk asset lint, mod, idmod checks, what a mod changes, Mod Loader conflicts, free model idslint.md, modinspect.md, idmgr.md
satk mod add, dataadd-on vehicles, peds, weapons and objects as Mod Loader folders; handling and weapon data: read, explain, patchaddon.md
satk col gen, fx2dcollision generated from models, collision checks; 2dEffect lights, particles and entry points as JSONcolgen.md, fx2d.md
satk texture optimize, audit, budgetsmaller TXDs, a texture audit, the streaming memory budgettxdopt.md
satk script, kb mta, kb nativeCLEO and SCM scripts: disassemble, assemble, check, templates; MTA Lua and SA-MP Pawn API lookupscript.md, scriptapi.md
satk batch, recipeone operation over many files, saved multi-step checksbatch.md
satk animIFP animations: list, edit as JSON, write, merge into ped.ifp, check against a skeleton, to and from Blenderanim.md
satk gxt, zone, water, timecycgame text, zones, water, the time cycle, population and radar tiles: read, edit, write as Mod Loader foldersworldfiles.md
satk limits planthe engine limits your game and mods need, with limit adjuster settingslimits.md
satk pack.saepak content containers, derived-asset cache files, the texture dedup censuspack.md, saepak.md, dac.md
satk mta, shaderMTA:SA resources: Lua lint with the server's own messages, starter resources, model packs, logs; shaders for world texturesmta.md, shader.md
satk map convert, ipl, pathsSA-MP/MTA/IPL map conversion, binary IPL, vehicle and ped pathsmapconv.md, paths.md
satk crash, re, kbcrash dumps and logs, gta_sa.exe addresses to functions, engine knowledge basecrash.md, re.md, kb.md
satk view, saapa viewer with a camera, frames with numbered objects, "what is this object"viewer.md
satk view place, vehicle, pedyour own models, vehicles and peds next to the map in the viewer, reloaded when the files changeviewscene.md
satk ingamea mod in the real game on the MTA fork: test spots, behaviour checks against vanilla with frames, hot reloadingame.md
satk spsatk_sp.asi: camera, screenshots and picking in the single-player gamespbridge.md
satk blender, engineheadless Blender import/render/export to MTA; build of the MTA forkblender.md, engine.md
satk style, asset checkSan Andreas style guidance and class references; model and texture defects, coverage and strict completionstyle.md, sa-style.md
satk blender session, kit, blender previewnew cars, props, buildings and other assets in a live Blender session: templates, blanks, generators, a game-like preview, exportauthoring.md, studio.md, kit.md, look.md
satk asset convert, texliba third-party model brought to San Andreas scale, detail and textures; procedural SA-style texturesconvert.md, texlib.md
satk status, doctor, help, mcpoverview, diagnostics with fixes, help, the MCP servermcp.md, ai.md

Every page, by task: docs/en/README.md.

Some parts need tools that are not in the release zip: the viewer (an Ariane fork) for satk view, Blender 5.1 for the Blender and authoring commands, the MTA fork for satk ingame and satk mta server-check (its client needs a one-time administrator setup), and the Visual Studio C++ build tools to build satk_sp.asi. Everything else works with the zip and your game folder.

Documentation

Development

How to work on satk (setup, one worktree per task, tests, rules): CLAUDE.md, the contributor guide for people and AI agents. The acceptance check before a merge is satk dev gate; the tests alone: python -m pytest -q -p no:cacheprovider in the venv.

Acknowledgements

A special thank-you to Dryxio. His open projects are the foundation of a large part of satk and of our research into the game and its engine: the satk viewer is a fork of his Ariane, satk paths runs his gta-flow core, satk describe imports the gta-scout model descriptions, satk kb reads his plugin-sdk-sa and cleo-ai, and his MTA Neon fork is where we learned how the engine works. Thank you! His GTA projects:

  • ariane: a modern map editor for GTA III, Vice City and San Andreas; the viewer of satk view is a local fork of it.
  • mtasa-neon: an experimental MTA:SA engine fork with larger worlds, raised limits and new Lua features; studied in depth, the donor of our engine fork.
  • gta-scout: GTA-style models and scenes with AI and Blender; satk describe import imports its model descriptions.
  • gta-flow: traffic routes with AI and Blender; its core is vendored for satk paths.
  • plugin-sdk-sa: the Plugin SDK with extra layout fixes; read by satk kb and satk re.
  • cleo-ai: CLEO modding with AI; its opcode reference feeds satk kb opcode.
  • reagent: AI reconstruction and validation of C/C++ code from binaries; studied when we designed satk re.
  • ghidra-bridge: AI access to Ghidra's analysis; the model for the agent-facing design of satk re.
  • samp-source: a byte-for-byte rebuild of SA-MP 0.3.7 R5; studied for our multiplayer research.
  • samp-r5-rebuild: the earlier from-scratch rebuild of the SA-MP 0.3.7-R5 client DLL.
  • wiki.mtasa-neon.com: the Neon documentation, based on the MTA wiki.
  • skygfx: his SkyGfx fork, the source of the MTA bridge that Neon builds.
  • gta-reversed: his fork of the gta_sa.exe reimplementation.
  • mtasa-blue: his fork of Multi Theft Auto (he also sends fixes upstream).
  • library: his fork of the Sanny Builder Library.
  • fastman92_limit_adjuster: his fork of the fastman92 Limit Adjuster source.
  • GTA-GPS-Redux: his fork of a GPS mod for San Andreas.
  • Radar-in-style-GTA-SA-The-Definitive-Edition: his fork of a Definitive Edition style radar.
  • dryxio: his profile with the list of projects.
  • gtastuff.com: 40+ browser tools for GTA modding, and Ariane's home page.

His other public projects are not about GTA: DockDrop, tamago-life, openclaw-lullabully and ppp-rescue.

Thanks also to the projects satk builds on or learned from:

Licence notices of the code and data satk ships: NOTICE.md. Every source we used, grouped by topic and with notes: docs/en/credits.md.

License

MIT (LICENSE). The exception is the Blender add-on blender/satk_blender (GPL-3.0-or-later, its own LICENSE). Third-party components and their notices: NOTICE.md.

ai-agentsgamedev-toolsgta-sagta-san-andreasmcpmcp-servermoddingmta-sapythonrenderwarereverse-engineeringsa-mp

Esta página se genera con lo que GitHub publica sobre el repositorio. samp.directory no aloja el código. Informar de un problema con esta ficha