# fivem-natives-db

Offline-Nachschlagewerk für **FiveM Natives** und **docs.fivem.net** — als SQLite-Datenbank
mit Volltextsuche (FTS5), CLI und fertigem Claude-Code-Skill.

| | |
|---|---|
| Natives | **7.359** (6.416 GTA5 + 943 Cfx) |
| Doc-Seiten | **342** aus `citizenfx/fivem-docs` |
| Größe | ~11 MB SQLite + ~4 MB JSONL |
| Dependencies | keine — nur Python 3.8+ Stdlib |

## Installation als Claude-Code-Skill

Ins Skill-Verzeichnis klonen, dann findet Claude Code die `SKILL.md` automatisch:

```bash
git clone https://git.d4rkst3r.de/D4rkst3r/fivem-natives-db.git ~/.claude/skills/fivem-natives
```

Unter Windows (PowerShell):

```powershell
git clone https://git.d4rkst3r.de/D4rkst3r/fivem-natives-db.git "$env:USERPROFILE\.claude\skills\fivem-natives"
```

Danach greift Claude bei Fragen zu Natives, Hashes, Signaturen oder FiveM-Docs
automatisch auf die lokale DB zu, statt die Doku zu raten oder online zu fetchen.

Alternativ irgendwohin klonen und `fivem.py` direkt benutzen.

## CLI

```bash
python fivem.py ragdoll                      # kombinierte Suche (Natives + Docs)
python fivem.py show SetPedToRagdoll         # volles Detail
python fivem.py show 0xAE99FB955581844A      # ... auch per Hash oder jhash
python fivem.py search vehicle engine --apiset client --limit 20
python fivem.py ns                           # alle 45 Namespaces
python fivem.py ns VEHICLE                   # Natives eines Namespace
python fivem.py docs fxmanifest              # Docs-Volltextsuche
python fivem.py doc scripting-reference/resource-manifest
python fivem.py stats
```

`show` liefert Signatur, Parameter mit Typ und Beschreibung, Rückgabewert,
Beschreibungstext und die offiziellen Codebeispiele:

```
## SetPedToRagdoll
`0xAE99FB955581844A`  **PED** | **client** | **gta5**
Native-Name: `SET_PED_TO_RAGDOLL`

void SetPedToRagdoll(Ped ped, int minTime, int maxTime, int ragdollType,
                     BOOL bAbortIfInjured, BOOL bAbortIfDead, BOOL bForceScriptControl)
```

Mit `--json` gibt es maschinenlesbare Ausgabe.

## Schema

`data/natives.db`:

| Tabelle | Inhalt |
|---|---|
| `natives` | ein Eintrag pro Native — s.u. |
| `natives_fts` | FTS5 über `name`, `lua_name`, `ns`, `description`, `param_names`, `aliases`, `hash` |
| `docs` | `path`, `slug`, `section`, `title`, `weight`, `url`, `body` (Shortcodes aufgelöst), `raw` |
| `docs_fts` | FTS5 über `title`, `section`, `slug`, `body` |
| `meta` | `built_at`, `native_count`, `doc_count`, `sources`, `schema_version` |

Spalten in `natives`:

`hash`, `jhash`, `name` (Original, z.B. `SET_ENTITY_COORDS`), `lua_name`
(Aufrufname, z.B. `SetEntityCoords`), `ns`, `source` (`gta5`|`cfx`), `game`,
`apiset` (`client`|`server`|`shared`), `results`, `results_description`,
`description`, `signature`, `params_json`, `param_names`, `examples_json`,
`aliases`, `url`.

Direkt per SQL nutzbar:

```sql
SELECT n.lua_name, n.ns, n.signature
FROM natives_fts f JOIN natives n ON n.id = f.rowid
WHERE natives_fts MATCH 'vehicle AND engine'
  AND n.apiset = 'client'
ORDER BY rank LIMIT 20;
```

`data/natives.jsonl` enthält dieselben Natives als eine JSON-Zeile pro Native —
praktisch für `grep`, wenn kein Python zur Hand ist.

## Rebuild

```bash
python build.py --refresh
```

Quellen:

- `https://runtime.fivem.net/doc/natives.json` — GTA5-Natives
- `https://runtime.fivem.net/doc/natives_cfx.json` — Cfx/FiveM-Natives
- `https://github.com/citizenfx/fivem-docs` — Markdown von docs.fivem.net
- `https://runtime.fivem.net/doc/events/{client,server}.html.json` — Event-Referenz

Ohne `--refresh` wird aus `.cache/` gebaut (nicht eingecheckt).

Beim Build werden die Hugo-Shortcodes der Docs aufgelöst, damit der Inhalt
durchsuchbar ist: `code` (bindet Beispieldateien ein), `native_link` (wird zum
Link auf docs.fivem.net), `alert` (wird zum Blockquote), `rmv`/`rmv2`, `events`
(zieht die Client-/Server-Event-Referenz), `youtube`/`video`/`forum_topic`.

## Namenskonvertierung

`lua_name` folgt exakt der Regel aus FiveM `ext/natives/codegen_out_lua.lua`:

```
name:lower():gsub('_(%a)', upper):gsub('^%l', upper)
```

Ein Unterstrich vor einer **Ziffer** bleibt deshalb erhalten:

| Native | Lua |
|---|---|
| `SET_ENTITY_COORDS` | `SetEntityCoords` |
| `_FORCE_VEHICLE_ENGINE_SYNTH` | `ForceVehicleEngineSynth` |
| `DRAW_SCALEFORM_MOVIE_3D_SOLID` | `DrawScaleformMovie_3dSolid` |
| `UI3DSCENE_IS_AVAILABLE` | `Ui3dsceneIsAvailable` |
| (unbenannt) | `N_0x<hash>` |

## Hinweis zur Repo-Größe

`data/` ist eingecheckt, damit ein Clone sofort einsatzbereit ist. Jeder Rebuild
legt ~15 MB in die Git-History. Bei häufigen Updates den Data-Commit amenden oder
die History gelegentlich squashen.

## Lizenz

Der Code hier ist frei verwendbar. Die Daten stammen von Cfx.re:
Natives-Metadaten und `citizenfx/fivem-docs` stehen unter den jeweiligen
Lizenzen der Upstream-Projekte.