JC4MP scripting reference
JC4MP servers run Lua resources: gamemodes, menus, UIs and tools. Each resource can have server scripts, client scripts and shared scripts, and players download the client and shared parts when they join. This reference covers everything a resource can use: the Lua API on both sides, every event, every enum, the JavaScript bridge for web UIs, and lists of the game names scripts pass in (vehicles, weapons, skins, NPCs, effects and more).
Scripts run on LuaJIT (Lua 5.1 syntax). The reference is grouped by where the API runs:
- Shared: available to both server and client scripts, plus the concepts that apply to both
- Server: only available to server scripts
- Client: only available to client scripts
Many types have a page on each side: the shared page explains the type and its common methods, and the server and client pages add what only that side can do.
New to JC4MP scripting? Start with Getting started, then read Resources and Net. Porting resources written for the old JC4MP API? See Porting.
Shared
| Page | What it covers |
|---|---|
| Resources | Folder layout, client/server/shared, lifecycle, require, downloads, the Resources table |
| Sandbox | Which Lua libraries and globals exist on each side, limits, error reporting |
| Events | Event.Add, Event.Remove, Event.Fire, Event.Cancel and how dispatch works |
| Net | How messages between client and server scripts work, Net.AddEvent, what values can be sent |
| Timer | Delayed and repeating callbacks |
| Hash | Hash, the game's 32-bit hash of a name |
| JSON | Parsing and writing JSON |
| Math types | vec2, vec3, vec4, quat, mat4, AABB |
| World | Handles, streaming, ownership, what is synced, finding objects |
| Weather | How weather sync works, sandstorms |
| ObjectHandle | Methods every networked object has, casting to typed handles |
| Player | PlayerHandle (the connection) and PlayerObjectHandle (the character) |
| Players | Finding players |
| VehicleHandle | Vehicle id, paint, dirt and parts |
| MountedGunHandle | Mounted guns |
| RigidObjectHandle | Physics props |
| NPCHandle | NPCs and how they are driven |
| TetherHandle | Grappling tethers |
| SandstormHandle | Sandstorms |
| Enums | Index of every enum table on both sides |
Shared enums: AclLevel, Key, NetObjectType, MoveType, MoveStyle, LookType, POIType, POIDisplayMode, Resource, ResourceAction, ResourceStatus, RigidObjectMotionType, VehiclePart, VehiclePartState, VehicleSeat, VehicleType, WeaponSlot, WeaponMode, AmmoType, WeatherAct, WeatherProperty, TornadoState.
Server
| Page | What it covers |
|---|---|
| Server events | Every event fired on the server |
| Resources | Starting, stopping and restarting resources, startup configuration |
| Net | Sending messages to players, Net.Sender |
| HTTP | Net.Fetch web requests |
| SQL | The server's SQLite database |
| Server | Server information |
| Chat | Chat messages |
| Server console | Console commands |
| World | Spawning and destroying objects, explosions |
| Weather | Syncing tornadoes, clouds and weather properties |
| ObjectHandle | Moving objects, setting health, velocity and data |
| Player | Kicking, banning, permissions, skins, weapons, animations, teleporting |
| VehicleHandle | Paint, locking, parts and drones |
| RigidObjectHandle | Motion type and collision |
| NPCHandle | NPC orders: move, follow, aim, fire, throw grenades, melee |
Client
| Page | What it covers |
|---|---|
| Client events | Every event fired on the client |
| Net | Sending messages to the server |
| Commands | Console commands (Cmd) |
| World | Time, gravity, waypoints, water and client-side objects |
| Weather | Lightning |
| ObjectHandle | Client-side data |
| Player | Character state, bones, effects and appearance |
| Players | The local player and name tags |
| VehicleHandle | Client-only vehicle methods |
| RigidObjectHandle | Bounding boxes |
| NPCHandle | Bounding boxes |
| Local | The local player |
| Client | Client version, uptime and network statistics |
| Game | Game state |
| Game objects | Client-side objects: POIs, water boxes, force pulses, effects and their base types |
| Input | Keyboard, mouse, game input and the clipboard |
| Camera | Camera position, direction and shakes |
| Render | Screen size and debug drawing |
| FX | Playing particle effects |
| Sound | Playing sounds and controlling channels |
| Physics | Raycasts |
| Terrain | Terrain information and vegetation shockwaves |
| NavMesh | Navigation mesh queries |
| RoadGraph | Roads, sea and air routes, paths and railways |
| Weapon | The weapon a player holds |
| GameUI | The game's own HUD |
| Asset | Checking whether game assets are loaded |
| UI and WebView | Web UIs from Lua: creating, showing and messaging webviews |
| WebView pages (JavaScript) | The JC4MP bridge inside a webview page |
Client enums: Ability, Action, InputAction, Bone, CameraShakeType, CharacterAttachedEffect, ForcePulseCategory, ForcePulseTuning, GameState, PfxLayer, RoadGraphType, WaterBoxStyle.
Game name lists
Names that scripts pass to spawn and play functions. See the lists index.
| Page | Used by |
|---|---|
| Vehicles | World.SpawnVehicle |
| Mounted guns | World.SpawnMountedGun |
| Weapons | GiveWeapon |
| Skins | SetSkin |
| NPCs | World.SpawnNPC |
| Animations | PlayAnimation |
| Effects | FX.Spawn |
| Explosions | World.SpawnExplosion |
| Rigid objects | World.SpawnRigidObject |
| Sounds | Sound |