Metadata-Version: 2.5
Name: pyloaderv
Version: 0.9.1
Summary: Autocomplete and type stubs for PyloaderV (Python mods for GTA V), plus tools to create, pack and set up mods.
Project-URL: Homepage, https://www.gta5-mods.com/tools/pyloader-python-scripts-for-gta-v-enhanced
Author: meumeuh007
License-Expression: MIT
License-File: LICENSE
Keywords: autocomplete,gta-v,gta5,gtav,modding,pyloaderv,scripthookv,stubs
Classifier: Development Status :: 4 - Beta
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Operating System :: Microsoft :: Windows
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: Games/Entertainment
Classifier: Topic :: Software Development :: Code Generators
Classifier: Typing :: Stubs Only
Requires-Python: >=3.9
Description-Content-Type: text/markdown

# 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

| Command | What it does |
|---|---|
| `pyloaderv new <folder>` | Create a mod folder with a starter `main.py` (and a `pyrightconfig.json` that hides the "stub found but no source" warning: the real `gta` only exists in game) |
| `pyloaderv pack <folder> [-o Mod.pyv] [--bytecode]` | Pack a mod folder (with `main.py`) into one `.pyv` file. `--bytecode` ships `.pyc` only and needs Python 3.12 |
| `pyloaderv install <file.py/.pyv> --game <GTA V folder>` | Copy scripts into `<GTA V>/pyscript/` |
| `pyloaderv pip <packages> --game <GTA V folder>` | Install pip packages (numpy, requests...) for the game's embedded Python 3.12, into `shvpy_runtime/Lib/site-packages` |

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

```python
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:

```python
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.
