Mods
Mods
Apex GP car classes and circuits are mods. You can install third-party ones, and everything the game ships is a mod too, so a car or a circuit you make follows the same rules as the built-in ones.
Mod support is in Apex GP 0.9.3 and later, so the released desktop and Android builds include it. On Android the mods folder is only reachable over a USB cable (see below).
What you can change
A mod is a folder of data: a small mod.json that describes the mod, plus a content file and any models, textures and sounds it uses. That is the whole format. There are two kinds:
- Cars — a new car class: its shape (a glTF model plus optional lower-detail versions), its paint, and every number the game uses to drive it, from mass and power to gear ratios and tyre size.
- Circuits — a new track: either your own geometry, or a copy of a built-in circuit with different settings such as its name, lap count or rain chance.
What a mod can include: .json, glTF models (.glb, .gltf, .bin), images (.png, .jpg, .jpeg, .webp) and audio (.ogg, .mp3).
Mods cannot run code. There are no scripts and no shaders in a mod: a car's paint is chosen from the game's own shaders, not shipped with the mod. That is deliberate — it is what keeps a mod to being only a car or a circuit.
Not in this version
- Livery-only or paint-only mods (a mod changes a whole car class, not just its colours).
- Sound-only mods, HUD mods and menu mods.
- There is no in-game mod browser or manager, and no Workshop. You install a mod by putting a folder in the mods folder by hand, below.
Where the mods folder is
Third-party mods live in a mods folder inside Apex GP's data folder. The game creates the folder the first time it starts, if it is not there. These are the exact locations the game looks in:
| Platform | Mods folder |
|---|---|
| Windows | %APPDATA%\apexgp\mods |
| macOS | ~/Library/Application Support/apexgp/mods |
| Linux | ~/.local/share/apexgp/mods (or $XDG_DATA_HOME/apexgp/mods if you set it) |
| Android | /storage/emulated/0/Android/data/dev.phil.apexgp/files/mods |
On Windows and macOS the same folder holds your settings, career and logs; see where Apex GP keeps its files on the support page.
Android: mods go in the app's own storage, at the path above. Since Android 11, the system blocks file-manager apps from browsing Android/data on their own. The reliable way to put a mod there is a USB cable and adb:
adb push my-car /storage/emulated/0/Android/data/dev.phil.apexgp/files/mods/
Some file managers can be granted access to that folder; if yours can, it works just as well.
Install, update and remove a mod
- Unzip it. You want the mod's own folder — the one that contains
mod.json— sitting directly inside the mods folder. The usual mistake is an extra folder level:mods/my-car/my-car/mod.jsonis wrong;mods/my-car/mod.jsonis right. - Restart the game. Apex GP reads the mods folder once, when it starts. A mod added while the game is running is not seen until you relaunch.
- Pick it like anything else. A car mod appears in the ordinary car picker under the name in its
mod.json; a circuit mod appears in the ordinary circuit list.
- Update: replace the mod's folder with the new version and restart.
- Remove: delete the mod's folder and restart. Nothing else changes; the game's own cars and circuits are separate.
- A mod and a built-in with the same id: a user mod that claims a built-in id is refused unless its
mod.jsonsays"override": true. Without that line the user mod is dropped and the built-in keeps loading; with it, your mod replaces the built-in. Two user mods that share an id are both dropped.
When a mod does not show up
When the game starts it writes one line to its log, in logs/godot.log in the data folder above. It looks like this — the numbers depend on your mods:
[mods] { "mods": 15, "user": 1, "cars": 4, "tracks": 11, "errors": 0 }
If "errors" is 0, every mod was read. If it is more than 0, at least one mod was broken and was skipped. The game still starts, and every other mod still works — one bad mod never stops the game. The log line counts the failures but does not name them, so the way to find the culprit is to remove the mods one at a time (or add them one at a time) and restart each time.
The usual reasons a mod is rejected:
- The folder level is wrong, or
mod.jsonis missing or not spelled exactly that way. - Two mods share an
id, or a user mod reuses a built-in id without"override": true. - A file type that is not allowed, or a file that points outside the mod's own folder.
- A file over the size cap (64 MB each, 256 MB per mod).
- A number outside its allowed range — the limits are in the creator section below.
Make a car or a circuit
Everything the game ships is built from these same files, so a mod that loads is a mod that fits the game exactly. There is no editor and no exporter: you write JSON and point it at your own model, or at one of the game's.
mod.json
Every mod has one. Name the folder after the id.
{
"schema_version": 1,
"id": "com.example.mycar",
"name": "Example Car",
"version": "1.0.0",
"author": "Your name",
"licence": "CC-BY-4.0",
"kind": "car",
"min_game_version": "0.9.3"
}
idmust be unique across every installed mod.name,version,author,licence,kindandmin_game_versionare required.kindis"car"or"track".licenceis free text: state the licence you are releasing your mod under. It is what the game records for your work.schema_versionis1."override": truelets a user mod replace a built-in id;order(a number) sets its sorting position. Both are optional.
car.json — a new car
car.json is one flat row of values, the same row the game's own classes use. This example is complete and valid: it reuses one of the game's car models, so you can drop it in and try it before pointing model at your own .glb in the mod folder.
{
"schema_version": 1,
"class": "examplecar",
"label": "Example Car",
"profile": "classic",
"decals_layout": "res://assets/car/livery_classic.json",
"engine_bank": "v10",
"model": "res://assets/car/classic/car.glb",
"lods": [
"res://assets/car/classic/car_lod1.glb",
"res://assets/car/classic/car_lod2.glb",
"res://assets/car/classic/car_lod3.glb"
],
"wheelbase": 2.9,
"track_f": 1.744,
"track_r": 1.674,
"wheel_r_f": 0.319,
"wheel_r_r": 0.336,
"tyre_half_f": 0.16,
"tyre_half_r": 0.21,
"mass": 580.0,
"mu": 1.58,
"cla": 2.3,
"cda": 1.05,
"power": 510000.0,
"max_torque": 402.0,
"rpm_idle": 4000.0,
"rpm_max": 13000.0,
"rpm_peak": 12000.0,
"rpm_up": 12400.0,
"rpm_down": 10500.0,
"gears": [18.4, 14.2, 11.0, 8.6, 6.7, 5.1],
"has_drs": false,
"has_halo": false,
"own_wheel": true,
"cockpit_eye": [0.0, 0.76, -0.27],
"cockpit_pitch": -5.5,
"box": [1.65, 0.48, 4.35],
"box_pos": [0.0, 0.36, -0.21],
"rain_pos": [0.0, 0.4, 1.9],
"nose_cam": [0.0, 0.3, -2.62],
"inertia": [500.0, 560.0, 190.0],
"com": [0.0, 0.26, 0.1]
}
classis the internal id the game saves;labelis the name a player sees (1 to 40 characters).profileis"modern","classic","supercar"or"hypercar"and picks the game's paint and decal shaders.modelandlodsare glTF paths. Ares://path uses one of the game's own assets; a plain name like"car.glb"loads a file from inside your mod folder. Up to threelods.decals_layoutpoints at the game's decal layout for that profile;engine_bankis"v6"or"v10".- The shape fields (
cockpit_eye,box,box_pos,rain_pos,nose_cam,inertia,com) are[x, y, z]numbers.
track.json — a new circuit
A track has a short form and a full form. The full form is the game's own track schema — the whole geometry — with schema_version and an id added. The short form points at a built-in circuit and overrides its settings, which is how a mod can change a circuit's name, laps, or how likely it is to rain:
{
"schema_version": 1,
"id": "exampletrack",
"source": "res://assets/tracks/apex.json",
"name": "Example Circuit",
"place": "Somewhere",
"length": 4000.0,
"laps": 5,
"style": "park",
"rain": 0.2
}
source must be a built-in res://assets/tracks/ path. Leave it out and put the full geometry in track.json instead. The settings here are what the menus show.
What the validator accepts
Every mod is checked before it loads. A value outside these ranges is rejected by name, rather than being allowed to break the driving physics.
| Field | Range |
|---|---|
mass | 300 – 3000 kg |
power | 20 k – 1.5 M W (20–1500 kW) |
max_torque | 50 – 2000 Nm |
mu | 0.3 – 3 |
cla | 0 – 6 |
cda | 0.2 – 3 |
wheelbase | 1.5 – 4.5 m |
track_f, track_r | 0.8 – 2.5 m |
wheel_r_f, wheel_r_r | 0.2 – 0.6 m |
tyre_half_f, tyre_half_r | 0.05 – 0.4 m |
gears | 1 to 10 finite values, all above 0, strictly decreasing |
lods | 0 to 3 paths |
has_drs, has_halo, own_wheel | true or false |
The rpm fields nest: rpm_idle below rpm_down below rpm_up, with rpm_up and rpm_peak no higher than rpm_max. Audio has to be .ogg or .mp3.
Using other people's mods
Mods are made by other players, and Apex GP does not make or check them. Install them at your own risk, and keep a copy of anything you would miss if it broke.
Do not redistribute other people's copyrighted or branded content in a mod. Apex GP itself ships fictional teams and drivers and parodied circuit names for that reason. The game does include one third-party model as a built-in mod — the Supercar — used with its author's permission; its credit is in the game's own credits screen.
Something you would like to be able to change that mods do not cover yet? Email hello@apexgp.racing.