User overlays and overrides¶

You can change a profile you did not write, a profile you downloaded or one that ships with Amri, without editing its files. Your changes live in a separate place that an update to the original profile does not touch. This page covers the two ways to do it: a local override file inside the profile, and a separate user overlay profile that layers on top.

Why not edit the profile directly¶

If you edit a downloaded profile's profile.toml or its command files, the next update to that profile can overwrite your edits. The two mechanisms here keep your changes in space the update does not replace, so an update to the base profile leaves your customization intact.

`user/overrides.toml`¶

Every profile folder may contain a user/ directory. It is your local space, and an update to the profile preserves it. The file user/overrides.toml adds or changes commands in that one profile:

elite_dangerous/
  profile.toml            # the author's file, replaced on update
  categories/
  scripts/
  user/                   # yours, preserved across updates
    overrides.toml        # your added or changed commands
    scripts/              # your added or changed Lua files

user/overrides.toml is loaded last, after the author's profile.toml and all of its includes, and merged on top. It holds [[command]] and [category.*] entries, the same shape as an included file. It never contains a [profile] section. A command you define here with the same name as one the author defined replaces the author's version:

# elite_dangerous/user/overrides.toml
# Rebind the author's "open_map" to a different key, and add one command.

[[command]]
name = "open_map"                 # same name as the author's command: yours wins
description = "Open the map with my key."
lua = "amri.input.tap('f2')"
[command.trigger]
pattern = "[open;show] the map"

[[command]]
name = "quick_save"
description = "My own addition."
lua = "amri.input.tap('f5')"
[command.trigger]
pattern = "quick save"

Shadowing a script¶

user/scripts/ is searched before scripts/ when a command loads its Lua file. A file at user/scripts/<path> shadows the file at the same <path> in scripts/, so you can replace one script without touching the author's copy. Put your version at the same relative path:

user/scripts/combat/target_ship.lua   # shadows scripts/combat/target_ship.lua

Both user/overrides.toml and user/scripts/ are optional. When they are absent, nothing changes.

User overlays: `[overlay] base = "..."`¶

An override edits one profile in place. A user overlay is a separate, small profile that layers on top of a named base profile. It is the "shared base plus per-title tweak" pattern: one base profile carries the commands common to a game family, and a thin overlay per title changes only what differs.

You declare an overlay with an [overlay] section naming the base:

# elite_horizons/profile.toml
[profile]
name = "elite_horizons"
description = "Horizons tweaks on top of the shared Elite base."

[overlay]
base = "elite_base"        # this profile layers on top of elite_base

[[command]]
name = "deploy_srv"        # a command specific to this title
description = "Deploy the surface vehicle."
lua = "amri.input.tap('backspace')"
[command.trigger]
pattern = "deploy [srv;buggy]"

When you load elite_horizons, Amri merges elite_base first, then this overlay on top, and runs the single merged result. A command the overlay defines with the same name as one in the base replaces the base command.

base names another profile, not a file

base is the name from another profile's [profile] section, not a path. That base profile stands on its own; the overlay adds to it. A user overlay uses base. The other form, applies_to, marks an engine-shipped system overlay and is not something a user profile uses; see System overrides.

Which to use¶

You want to	Use
Change or add commands in one specific downloaded profile	`user/overrides.toml` in that profile
Replace one of a profile's script files	a file in that profile's `user/scripts/`
Keep a shared base for several titles and tweak per title	a user overlay with `[overlay] base = "..."`

Reach for user/overrides.toml when the change belongs to one profile. Reach for an overlay when several profiles share a base and each needs its own small difference on top.

What you cannot override¶

The engine's built-in "Amri, ..." commands are protected. A profile, an override, or an overlay that redefines one of those names fails to load unless you have allowed it in your own engine.toml. See System overrides for how that permission is granted.

For the full merge order, how ties between includes, base, overlay, and user/overrides.toml are resolved (more specific wins), see Composition.