Generic JSON API

The typed modules know about specific content. The generic JSON API knows about nothing. It patches any asset by its raw JSON, given the asset's label. Use it when no typed module covers what you want to patch, or when you want to reach a field a typed module does not expose. Everything the typed modules do is built on top of this.

Patching by label

PM.JSON:Patch(label, name) registers a patch against a label. The first argument is the label, the second is your patch's name. From there the chain is identical to any other patch. This real patch raises a couple of minimum values in the exploration game mode:

PM.JSON:Patch("game_mode", "ExplorationModeScienceMinValues")
       :Named("GameMode_Exploration")
       :Do(function(json)
           json.DifficultyOptionDefinitions[2].MinValue = 0.1
           json.DifficultyOptionDefinitions[3].MinValue = 0.1
       end)

Inside the callback you get the asset's raw JSON. You navigate and edit it with plain field access, array indexing, and the JSON methods. There is no typed help here: you are working with the asset's structure directly, so you need to know its form. An existing asset of the same kind is the way to learn that form, and the patch cache is the easiest place to read one.

Creating with the generic API

PM.JSON:New(label, name, value) queues a brand new asset under a label. You pass the label, a globally unique name (its address), and the value:

PM.JSON:New("my_label", "MyThing", {
    someField = 1,
    anotherField = "hello",
})

New returns the queued asset. To create the asset only in some campaigns, add :Feature or :NoFeature to it. See Creating assets for the general pattern. See Features for gating.

The fully generic form

PM.JSON uses the built-in JSON converter, which leaves the asset as raw JSON. Underneath it, there is an even more general form on PM itself that lets you name the converter explicitly:

  • PM:Patch(converter, label, name) patches with a named converter.

  • PM:New(converter, label, name, value) creates with a named converter.

A converter is what turns an asset's JSON into the value your callback works with and back again. PM.JSON:Patch(label, name) is just PM:Patch("JSON", label, name) with the generic converter filled in, and PM.Parts:Patch(name) is the parts converter filled in. You almost never call the PM:Patch form directly. You use it only when a converter exists that no typed module wraps. See Converters explained.

When to use the generic API

  • A typed module exists for your content: use it. It is shorter and safer.

  • No typed module covers the label you need to patch: use PM.JSON:Patch.

  • A typed value does not expose the field you want: drop to raw JSON on that same value, since the typed wrappers and raw access share the underlying data.

If you believe a typed module would help for what you are patching, contact the Redux developers or the mod developer if what you are patching is from a mod.