pyloaderv

Developer kit for PyloaderV, the mod that lets you write GTA V mods in real Python (CPython 3.12 embedded in the game through ScriptHookV).

pip install pyloaderv

That one command gives you:

• Autocomplete and type checking for import gta in VS Code (Pylance), PyCharm, mypy... The whole API is covered: gta.player, gta.world, gta.ped, gta.vehicle, gta.entity, gta.ui, gta.math, and all 6649 natives in gta.natives.<namespace>. Nothing to configure: no stubs folder to copy, no pyrightconfig.json.
• The pyloaderv command to create, pack and install mods.

This package is for writing mods. Players do not need it: they only install the PyloaderV mod in their game folder. The real gta module exists only inside the game.

Quick start

pyloaderv new MyMod

Open the MyMod folder in VS Code (select the Python interpreter where you installed pyloaderv), edit main.py, then try it in game:

pyloaderv install MyMod/main.py --game "C:\Program Files\Rockstar Games\Grand Theft Auto V"

Press F9 in game to reload scripts after a change.

Commands

Set the PYLOADERV_GAME environment variable to your GTA V folder to skip --game. pyloaderv pip downloads Windows x64 wheels for CPython 3.12 whatever Python you run it with; packages that only exist as source archives cannot be installed this way.

Writing a script

import gta
from gta import player, world, ui

INTERVAL_MS = 500  # on_tick cadence in ms (0 = every frame)

def on_start():
    ui.notify("~g~hello ~w~from python")

def on_tick():
    me = player.current()
    gta.log("info", f"wanted={me.wanted_level}")

def on_key_down(vk, down, shift, ctrl, alt):
    if down and vk == 0x74:  # F5
        ui.notify(f"peds: {len(world.get_all_peds())}")

def on_aborted():
    pass

Natives with out-params (BOOL*, int*, float*, Vector3*, Entity*...) return the values the game writes, after the normal result; trailing out-params can be omitted:

from gta import world
from gta.natives import shapetest

status, hit, pos, normal, entity = shapetest.GET_SHAPE_TEST_RESULT(handle)
target = world.raycast_from_camera()   # what the camera looks at

In a .pyv mod, use relative imports for your own modules (from . import mylib): each .pyv gets a private namespace, so two mods can ship modules with the same name.

Versions

The package version follows the PyloaderV release whose API it describes (pyloaderv 0.9.x = PyloaderV 0.9). Story mode only: PyloaderV and its mods are not for GTA Online.