Introduction

Record Edits writes down what you change in a level as a recipe, and replays a recipe onto another copy of the level - a newer copy of your own, a collaborator's, a fresh one - or onto another level. Record a fix once, then apply it wherever it is needed, with a dry run first that says what will happen.

Open it from File → Record Edits.... The window can be closed while you record: recording carries on, and the menu item says "(recording)".

Recording

Press Record, edit the level as usual, then press Stop & Save Recipe... and pick where to save it (by default in your game folder's DATA\MODTOOLS\RECIPES). While you record, the window lists each undo step you make. Discard stops without keeping anything.

Every way of editing is recorded: the editor's windows and inspector, the flowgraph, the viewport, popups, and changes an AI assistant makes. What you undo while recording is left out, and so is anything you change and then change back - a recipe holds the net change between pressing Record and Stop. Saving while you record is fine. If you open another level while recording, the recording stops and is kept for you to save.

What a Recipe Holds

  • composites made, renamed and deleted, with their pin types;
  • entities made (whole: type, name, every parameter, resources, animation or sequence) and deleted;
  • each parameter set or removed, with the value it had before as well as after;
  • links made and removed, and the order an entity's links fire in;
  • CAGEAnimation tracks, TriggerSequence entries, alias and proxy paths, brush shapes;
  • material values: texture slots, constants, priority.

Keeping each before value is what lets a replay tell when the target level differs from the one you recorded on.

What It Doesn't Carry

A recipe is edits, not files: models, textures and material mappings you import or make while recording, and the collision and physics that come with an import, aren't in it - the recipe lists them under not carried, and a replay that needs them says the model or material is missing. Bring them into the target level first, with Port Composites or the importers, then replay. Edits of the game's shared files (configs, text, UI) aren't recorded either: those travel in a mod.

Replaying

Open the target level, press Open Recipe... and pick the recipe. Nothing changes yet: the window shows the dry run. Press Apply to make the ready steps. The whole replay is one undo step, called Replay: name: Undo takes all of it back. Save afterwards - or Save and Build, when the recipe placed or moved models, lights or collision.

The Dry Run

Each step of the recipe gets a status:

  • ready - the target is as the recipe found it: the step will be made.
  • ready (merge) - an entity's links: the target has other links too, so the recorded ones are added and removed and the rest kept.
  • already done - the target already has the result (replaying a recipe twice changes nothing the second time).
  • conflict - something else is there now: someone changed that value too. Conflicts are skipped, unless you press Apply, Overwriting Conflicts.
  • missing - what the step works on isn't in the target: a composite, an entity, a model or material it draws.

Ids: Kept or New

On a copy of the level the recipe was recorded in, what it adds keeps its recorded ids, so later recipes recorded on the same level still find it. On another level - or when one of those ids is already used in the target by something else - everything the recipe adds gets new ids, and every link and path to it follows. The dry run says which it will do and why. The Ids box can force either.

Checking a Replay

To see that a replay did what you recorded, save both levels and compare the one you recorded on with the one you replayed onto: replayed onto a copy of the same level, the two compare as the same.

The Recipe File

A recipe (.ocrecipe) is plain text, one JSON object per line: a header (its name, the level it was recorded on, when, the undo steps made, what it doesn't carry), then one step per line, for example:

{"op":"set_param","composite":"0D-82-73-37","composite_name":"AYZ\\Levels\\Torrens\\Torrens","entity":"5C-6D-93-B8","entity_name":"LightReference_6","param":"intensity_multiplier","before":{"float":0.03},"after":{"float":0.17}}

Lines starting with # are skipped, so you can annotate a recipe, or delete steps you don't want before replaying it.

For AI Assistants

An AI assistant connected to OpenCAGE records with record_edits (start, status, stop with a name and path, discard) and replays with replay_recipe (a path or the recipe's text, dry_run, ids auto / keep / remap, conflicts skip / overwrite). Edits the assistant makes while you record are recorded with yours.