Create / Mod files / Ships for mods

Ships for mods

A Ship is a whole DESIGN, authored once and spawned by id. It owns the section layout, whether the hull is clad, how far it must be dismantled before it collapses, and the voice it speaks to its pilot with. A Spaceship spawn names it and adds everything that differs per spawn: where it sits, who flies it, which side it is on, what it is permitted to do.

Ships are content like sections, scenarios and styles. Create a new id to add a design, or reuse a base id to rebuild every scenario's corvette at once.

This page is the field-by-field ship reference. For general RON spelling rules such as double parentheses, Some(...), and asset schemes, see RON spelling rules.

Why a ship is content

A full loadout runs to hundreds of lines. Inlining one in every scenario that spawns it means editing a corvette in eleven places and getting eleven slightly different corvettes. A ship id is the fix: one definition, one edit, and a mod can replace it for every scenario that names it.

The Ship item

[
    Ship((
        id: "my_corvette",
        name: "My Corvette",
        design: (
            sections: [
                (
                    id: "fuselage",
                    position: (0.0, 0.0, 0.0),
                    rotation: (0.0, 0.0, 0.0, 1.0),
                    source: Prototype(id: "basic_controller_section"),
                ),
                // ... hull, thruster, and weapon sections ...
            ],
        ),
    )),
]

The design

integrity fields:

presentation fields:

The voice is the DESIGN's, not its flight computer's: a hull that loses every controller section still knows how to warn about its own structure.

Section entries are the same records a design carried when it was inlined - see section prototypes for the ids the base game ships.

Spawning one

SpawnScenarioObject((
    base: (
        id: "raider_1",
        name: "Raider",
        position: (0.0, 0.0, -3000.0),
        rotation: (0.0, 0.0, 0.0, 1.0),
    ),
    kind: Spaceship((
        controller: AI((engage_delay: Some(8.0))),
        design: Prototype(id: "my_corvette"),
        inventory: {},
        lootable: false,
        credits: 2000,
    )),
)),

Changing one design for one spawn

A scenario that wants a harder flight computer or a fixed magazine does NOT need its own ship. section_patches on the spawn aims the same typed deltas a section reference carries at a section of the resolved design, and they are applied after the design's own, so the spawn wins:

kind: Spaceship((
    controller: AI(()),
    design: Prototype(
        id: "my_corvette",
        section_patches: {
            "fuselage": (config: (health: Some(500.0))),
            "turret_port": (config: (kind: Some(Turret((
                ammunition: Some(Limited(900)),
                reload: Some(Disabled),
            ))))),
        },
    ),
    inventory: {},
    lootable: false,
    credits: 2000,
)),

A section_patches key the design does not carry does nothing at runtime, so the content lint reports it as an error, and so does a patch that argues with the section's kind. The full patch surface is in the sections list.

Reach for a second ship id instead when the difference is what the design IS - the base game ships light_freighter and freighter_derelict as separate hulls because a missing drive, transom and wing are a different ship to fly, not a tweak. The Ledger does the same with its two hauler loads, cargob and cargob_lance: which torpedo TYPE the pods carry decides whether a defender's point defense can answer the salvo at all, and that is the ship, not a tweak to it.

One-off designs

A design nothing else will ever spawn can stay on the spawn:

kind: Spaceship((
    controller: None,
    design: Inline((
        sections: [
            (
                id: "bay",
                position: (0.0, 0.0, 0.0),
                rotation: (0.0, 0.0, 0.0, 1.0),
                source: Prototype(id: "torpedo_section"),
            ),
        ],
    )),
    inventory: {},
    lootable: false,
    credits: 2000,
)),

Inline((..)) takes the same fields as a ship's design. Use it for a scripted battery that is a single tube or a derelict that is five plates; anything a second scenario would spawn belongs in the catalog. It takes no section_patches: it is already this spawn's own.

Overlay and lint

• A mod ship with a base id REPLACES the base design, so every scenario naming it flies the mod's - the same last-wins overlay sections and styles follow.
• The same id twice in ONE bundle is a conflict: the first wins and the duplicate is skipped.
• A design is linted where it is AUTHORED, not where it is spawned: its section prototypes must resolve, its own patches must apply, its sections must not interpenetrate, and its link-point graph must be connected. A spawn's section_patches are linted where the spawn is.
• A spawn naming a ship no bundle provides is a lint error, and at runtime it spawns an empty root and logs rather than crashing.

Base ships

Every base design is BUILT: cells on a build grid, clad by the derived skin and painted by a style. Nothing in the base game is a modelled mesh.

Every crewed base hull carries a docking collar on the port flank, port_collar.

A mod may ship MODELLED craft instead, and The Ledger does: its racer, cargoa, cargoa_raider, cargob and cargob_lance are assembled from GLB parts the mod carries under its own gltf/parts/.