Anatomy of a mod

The .oamod zip and the profile oamod.yaml: identity, layout, limits, data keys, script extensions and the standard hacks it turns on.

The package

A .oamod is a zip of the mod's folder. The profile lies at the top, or in the one folder the top holds (the Finder's Compress makes such a file). Stored or deflated entries; no links, device names, absolute paths or ..; at most 4 GiB unpacked.

escalation.oamodthe file a player downloads or opens├─ oamod.yamlrequired the profile: identity, layout, limits, hacks├─ badge.png256 × 256, shown in the Library and on this site├─ totala1.hpi · esc.ufoarchives, listed under layout in load order├─ units/ · weapons/ · features/loose data folders, layered over the archives├─ scripts/ · objects3d/ · textures/COB scripts, 3DO models, GAF textures├─ sounds/ · bitmaps/ · guis/audio, pictures and menus the mod replaces└─ README · LICENCEanything else is carried along and ignored

The profile

Strict YAML: one document, one top-level mapping, no anchors, no block scalars. Everything the file leaves out plays as 3.1c.

oamod: 1
id: escalation                 # kebab-case, 1 to 32 bytes; the install folder's name
name: Escalation
version: "10.2.0"             # free text, never ordered
author: {name: Wotan and the ESC team}
packaging: {revision: 1, date: 2026-10-15, packager: Core Prime}
homepage: https://example.net/escalation
tags: [units, balance, ai]
requires: {base: ta-3.1c, engine: ">= 0.8.0"}   # quote the engine range

layout:
  archives: [esc.ufo, escgui.ccx]
limits:
  units-per-player: {default: 1500, max: 5000}
hacks:
  ai.income-multipliers: {easy: 1.0, medium: 1.5, hard: 2.0}
  weapons.high-arc-ballistic: true
  veterancy.model: escalation

What it may declare

Key	What it does	Standard
`identity`	Names, badge, homepage, tags, the base game and expansions it needs.	§6.1
`layout`	Which archives and folders make the mod, in load order.	§6.2
`limits`	Engine limits the mod raises, each with a default and a maximum the host may choose.	§6.3
`script-extensions`	Extra values the mod's unit scripts read, such as unit.kills-x100.	§7
`data-keys`	Extra keys in FBI and TDF files the engine must honour.	§8
`hacks`	The standard hacks the mod turns on; sim hacks must agree between players.	§9
`strings`, `media`	Translated names and the mod's own pictures and sounds for the menus.	§10

Where it installs

Into Documents/Open Annihilation/Mods/, by the profile's id, never by the file's name. A newer revision of the same version replaces, keeping one version back in .backup; another version may install alongside as Mods/-. Everything is checked before anything is written, and a stop at any point leaves the folder in the state before or after the change.

Checks before publishing

The profile passes validation as a load would: resolved twice, the second time with the package's INI and the player's registry settings.
No two names differ only in ASCII case; no file and folder share a name.
version and packaging.revision have never been published with different bytes. The publish script refuses it.
Every hack named is one this Open Annihilation implements, or the Library lists the mod and cannot install it.

Next: Make a mutator The standard on GitHub