Initial commit — Southwest Roleplay FiveM

PORTING.md

@@ -0,0 +1,90 @@
+# FiveM Port — Feature Porting Guide
+
+## Status
+
+| Layer | Status | Notes |
+|---|---|---|
+| TypeORM entities (207) | ✅ Copied verbatim | Zero changes needed |
+| Express REST API | ✅ Copied verbatim | Zero changes needed |
+| Shared constants | ✅ Copied verbatim | |
+| Core log/DB/Redis/Mongo | ✅ Copied verbatim | |
+| `mp` server shim | ✅ Done | Covers events, players, vehicles, config |
+| `mp` client shim | ✅ Done | Covers events, game, gui, browsers→NUI |
+| RPC system | ✅ Done | Replaces `mp.events.addProc` |
+| Player wrapper | ✅ Done | Wraps FiveM net ID into PlayerMp-compatible object |
+| Vehicle wrapper | ✅ Done | Wraps FiveM entity handle |
+| CommandSystem | ✅ Done | Uses `RegisterCommand()` per command |
+| Server features (101) | 🔲 Not started | See porting order below |
+| Client features (~80) | 🔲 Not started | See porting order below |
+
+---
+
+## How to port a server feature
+
+1. **Copy** the feature folder from `game-server/src/features/<name>/` to `fivem-server/src/server/features/<name>/`
+2. **Fix imports** — update relative paths (e.g. `../../entities/` → `../../entities/`, `../../core/` stays the same)
+3. **Search for `mp.colshapes`** — FiveM has no server colshapes. Replace with the polygon position-tracking system.
+4. **Search for `mp.objects.new` / `mp.peds.new`** — use FiveM `CreateObject` / `CreatePed` natives.
+5. **Search for `player.call(`** — this works unchanged via `PlayerWrapper.call()`.
+6. **Uncomment the import** in `src/server/index.ts` and add to `featuresParallel` or `featuresSeries`.
+
+## How to port a client feature
+
+1. **Copy** the feature folder from `game-client/src/<name>/` to `fivem-server/src/client/features/<name>/`
+2. **Fix imports**
+3. **Replace `mp.events.addProc`** with `rpc.registerClientProc` from `../core/rpc`
+4. **Replace `mp.browsers.new(url).execute(js)`** with `nui.send(type, data)` (PostMessage to Vue)
+5. **Replace `mp.game.invoke(hash, ...args)`** with direct native calls where the name is known, or keep `mp.game.invoke` (the shim passes through to `Citizen.invokeNative`)
+6. **Uncomment the require** in `src/client/index.ts`
+
+---
+
+## Suggested porting order (server features)
+
+Start with features that have minimal RageMP API surface and no colshape dependency:
+
+1. `shared` — pure data sync
+2. `time` — simple, no colshapes
+3. `weather` — simple
+4. `chat` — core comms, needed by everything
+5. `login` — needed before players can do anything
+6. `session` — depends on login
+7. `player` — needed by commands
+8. `permissions` — needed by guards
+9. `money` — needed by jobs/most features
+10. `inventory` — high-value, many features depend on it
+11. `vehicle` — large but critical
+12. `job/*` — already on feature/jobsystem branch, good to port early
+
+Defer until late (complex colshape or streaming dependencies):
+- `properties` (heavy colshape use → needs polygon system)
+- `furniture` (server objects)
+- `drugs` (colshapes + objects)
+- `graffiti` (colshapes)
+
+---
+
+## RageMP → FiveM cheatsheet
+
+| RageMP (server) | FiveM (server) |
+|---|---|
+| `mp.events.add('playerJoin', (p) => ...)` | Auto-mapped by shim → `playerConnecting` |
+| `mp.events.add('playerQuit', (p) => ...)` | Auto-mapped by shim → `playerDropped` |
+| `mp.events.add('myEvent', (p, data) => ...)` | Shim registers net event; player injected from `source` |
+| `player.call('event', [a, b])` | `TriggerClientEvent('event', netId, a, b)` |
+| `player.notify(msg)` | `TriggerClientEvent('_mp:notify', netId, msg)` |
+| `player.setVariable(k, v)` | FiveM StateBag: `Player(id).state.set(k, v, true)` |
+| `mp.vehicles.new(model, pos, opts)` | `vehicleRegistry.create(model, pos, opts)` |
+| `mp.events.addProc('name', fn)` | `rpc.register('name', fn)` |
+| `mp.colshapes.newSphere(...)` | Use polygon position tracking system |
+| `mp.players.broadcast(msg)` | `TriggerClientEvent('_mp:chatMessage', -1, msg)` |
+
+| RageMP (client) | FiveM (client) |
+|---|---|
+| `mp.events.add('render', fn)` | Shim adds to tick loop |
+| `mp.events.callRemote('event', ...args)` | `TriggerServerEvent('event', ...args)` |
+| `mp.events.addProc('name', fn)` | `rpc.registerClientProc('name', fn)` |
+| `mp.players.local.setComponentVariation(...)` | `SetPedComponentVariation(PlayerPedId(), ...)` |
+| `mp.game.invoke('0xHASH', ...args)` | `Citizen.invokeNative('0xHASH', ...args)` |
+| `mp.browsers.new(url)` | FiveM NUI (declared in `fxmanifest.lua`, one page) |
+| `mp.gui.chat.push(msg)` | `TriggerEvent('chat:addMessage', { args: [msg] })` |