Modding Guide

What a mod is

A mod is one folder, and the folder name is the mod id.

mymod/
  mod.json                      the manifest (required)
  definitions/                  JSON definitions, any sub-folders you like
    placeables/mymod-bench.json
  assets/                       models, textures and sounds
    mymod/bench.glb

Symlinks inside a mod are refused. Limits: 64 mods loaded at once, 4096 definition files of 1 MiB each per mod, and a mod.json of up to 64 KiB.

Quick start

1. Make a folder, for example user://mods/mymod/.
2. Add a mod.json. This is the Halloween one:

{
  "id": "halloween",
  "version": "1.0.0",
  "name": "Halloween Night",
  "author": "Terminal Turbulence",
  "description": "Example mod: a glowing jack-o-lantern, Hollowmoon Charters on a ghostly tri-motor, and a bat-wing light twin.",
  "api": { "min": 1, "max": 1 }
}

3. Put at least one JSON file in definitions/.
4. Open Main menu › Mods and switch the mod on. New user mods start on; shipped mods start off. Changes apply when you start or load a game.
5. Select the mod's row to read its problems, if any.

Add, override, load order

Every definition file is a JSON object with a type (the content kind), an id and a version. The kind comes from type, not from the folder, but keep the base game's folder names so people can find things.

Adding

A new id must start with your mod id and a dash. In the halloween mod that is halloween-jack-o-lantern. Anything else is rejected.

Overriding

Use the same type and id as an existing definition. The new one replaces the old one as a whole: there is no field patching and no delete. If your override fails the cross-reference checks, the original is restored and the error names your file.

Single-definition kinds

Sixteen kinds have exactly one definition, with id default: passenger-flow, baggage-flow, landside, emergency-services, economy, commerce, general-aviation, atc, weather-rules, air-traffic, music-playlist, passenger-names, engine-sound-mix, day-night, airfield-lighting and staffing. You can only override default, which means restating the whole file.

Load order

The base game loads first, then each enabled mod in the player's list order, adjusted so dependencies and present loadAfter mods come first. A later mod's definition replaces an earlier one with the same id. Mods cannot add new content kinds.

A bad file does not stop the game. It is dropped with an error naming the file and JSON position, and the rest of the mod still loads. If the base game fails to load with mods on, the game reloads without mods and the Mods screen shows why.

Moddable content kinds

Each kind is checked against content/schemas/<type>.schema.json, which is the exact list of fields and limits. Copy the nearest base definition from content/definitions/<folder>/ as a starting point.

Most kinds carry sim rules, so a mod can change how the airport plays, not just how it looks. Balance is the mod author's job.

Assets and material looks

Definitions name assets by a path with no extension and no res://, e.g. "mesh": "halloween/hw_jack_o_lantern". The game looks for <mod>/assets/<path>.<ext>, then falls back to the base game. Keep your files under a folder named after your mod.

Art conventions: 1 unit = 1 metre, +Y up, front faces −Z, origin at the footprint centre on the ground, no node rotation or scale, a 4 m grid. Suggested triangle budgets: ground vehicles up to 1,500, aircraft 6,000–12,000, furniture up to 500.

Material looks (curated presets, no shaders)

A placeable can also cast a point light (light: position, colour, energy 0.1–16, range 1–40 m, night only). Lights are shadowless and capped at 32 in the whole game.

Halloween walkthrough

The Halloween Night mod is two themed airframes, a ghostly airline, two music tracks and a glowing pumpkin. It's made of 9 JSON files, 3 GLB models, 1 PNG texture and 2 OGG tracks.

A placeable with a glowing face and a light

{
  "type": "placeable",
  "id": "halloween-jack-o-lantern",
  "version": 1,
  "category": "decor",
  "subcategory": "landscaping",
  "displayName": "Jack-o'-lantern",
  "mesh": "halloween/hw_jack_o_lantern",
  "footprint": { "widthCells": 1, "depthCells": 1 },
  "construction": { "costMinor": 25000, "buildMinutes": 15 },
  "materials": [
    { "material": "hw_pumpkin_face",
      "emission": { "nightOnly": true, "flicker": { "amplitude": 0.25, "hz": 2.5 } } }
  ],
  "light": {
    "positionCentimetres": { "x": 0, "y": 110, "z": -190 },
    "color": "#ff9a3c", "energy": 1.2, "rangeMetres": 7, "nightOnly": true
  }
}

Shortened. hw_pumpkin_face is the material's name inside the GLB.

An airline with its own livery and aircraft

{ "type": "airline", "id": "halloween-hollowmoon-charters", "version": 1,
  "displayName": "Hollowmoon Charters",
  "archetype": "archetype-regional",
  "livery": "halloween-livery-hollowmoon",
  "color": "#2A1F4A",
  "fleet": [ { "aircraft": "halloween-ghost-trimotor" } ] }

{ "type": "livery", "id": "halloween-livery-hollowmoon", "version": 1,
  "displayName": "Hollowmoon Charters", "weight": 1,
  "textures": { "halloween-ghost-trimotor": "halloween/liveries/hollowmoon_ghost_trimotor" } }

The livery maps an aircraft type id to a PNG. The airline names the livery and lists the aircraft it flies, and reuses the base regional archetype.

A ghostly aircraft

The tri-motor is an aircraft-type (size S, 14 seats) with keep-out polygons and a translucent, rim-lit look:

"materials": [
  { "material": "ac_livery", "transparency": "depth-prepass",
    "rim": { "color": "#a8ffd8", "energy": 0.8, "power": 3 } },
  { "material": "hw_ghost_glow",
    "emission": { "flicker": { "amplitude": 0.15, "hz": 0.8 } } }
]

Its turnaround lists tasks (deboard, cleaning, fuel, cargo, boarding, pushback) with minutes, order and conflicts, plus vehicle docks that must clear the keep-outs.

Music

The mod overrides the playlist definition: it restates base tracks 1–18 and adds two that point at mod files.

{ "id": "halloween_autumn_twilight", "number": 19, "title": "Autumn Twilight",
  "path": "halloween/music/autumn_twilight", "mood": "calm" }

Testing a mod

Each row in Main menu › Mods says whether the mod is loaded, off, missing, loaded with problems, or not loaded and why. Errors name the file and JSON pointer, e.g. /footprint/widthCells.

The JSON Schemas in content/schemas/ work in any schema-aware editor. Check models, textures and sound in the game itself.

Saves and mods

• Mod switched off or removed: liveries fall back to the house livery and the mod's airlines end their contracts, but placed pieces from the mod block the load with a message naming the mod. Turning it back on fixes it.
• Mod changed: the save loads with a "mods changed" warning when the version or the definition files differ.
• New mod switched on later: old saves are unaffected.

Limits and not yet supported

• No code: no C#, GDScript or .pck mods. Material looks are fixed presets.
• No new content kinds, and no field-level patching or deleting of base definitions.
• Single-definition kinds are whole-file overrides and conflict between mods.
• No reordering in the Mods screen; use dependencies and loadAfter.
• Terrain-look textures, UI icons and fonts still load from the game only. Build-menu previews are looked up in your mod's previews folder first.
• Mod models have no LODs yet, and a first load of a big file can hitch.
• No seasonal or date-based content yet.
• Content must be original: no real airlines, liveries or trademarked aircraft names.