Apex GP

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:

Third-party mods are read from mods inside the game's data folder. Everything the game ships is a separate, built-in set that adding a mod cannot break.
PlatformMods 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

  1. 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.json is wrong; mods/my-car/mod.json is right.
  2. 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.
  3. 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.json says "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.json is 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"
}
  • id must be unique across every installed mod. name, version, author, licence, kind and min_game_version are required.
  • kind is "car" or "track".
  • licence is free text: state the licence you are releasing your mod under. It is what the game records for your work.
  • schema_version is 1.
  • "override": true lets 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]
}
  • class is the internal id the game saves; label is the name a player sees (1 to 40 characters). profile is "modern", "classic", "supercar" or "hypercar" and picks the game's paint and decal shaders.
  • model and lods are glTF paths. A res:// 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 three lods.
  • decals_layout points at the game's decal layout for that profile; engine_bank is "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.

Car value limits. Missing, mistyped or out-of-range values are rejected.
FieldRange
mass300 – 3000 kg
power20 k – 1.5 M W (20–1500 kW)
max_torque50 – 2000 Nm
mu0.3 – 3
cla0 – 6
cda0.2 – 3
wheelbase1.5 – 4.5 m
track_f, track_r0.8 – 2.5 m
wheel_r_f, wheel_r_r0.2 – 0.6 m
tyre_half_f, tyre_half_r0.05 – 0.4 m
gears1 to 10 finite values, all above 0, strictly decreasing
lods0 to 3 paths
has_drs, has_halo, own_wheeltrue 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.

Buy Apex GP