JSON API changes

[mugling]

As per @illi-kun's suggestion changes to the core engine that might break third-party mods will be announced here. If you are developing a mod you may wish to subscribe to notifications on this issue.

Developers merging significant changes should make a short entry here linking back to the relevant PR. The intended format is for announcements and to maintain a changelog, not Q&A. Further discussion can and should continue in the original PR or otherwise you may consider opening a further issue.

Known third-party mods:

• PKmod by @pisskop
• Cataclysm++ by @Noctifer-de-Mortem
• Mining by @DangerNoodle

[mugling]

Changes

• seat_nocargo is redundant and was deprecated in #19254

Migration

Vehicles using this part should instead use seat or an equivalent vehicle part.

[mugling]

Changes

• ammolink and casing abstracts were changed from AMMO to GENERIC in #18836

Migration

If using either abstract via copy-from you need to update the type to GENERIC and drop the redundant count field. If adding either to an item_group you should instead set count there.

Additional notes

Any item type can now be made to stack by setting stackable: true

[Coolthulhu]

Changes

• Engine jsons rewritten. Need docs to link here. EDIT: Reverted
• Syntax for tree and shrub harvest rewritten. See https://github.com/CleverRaven/Cataclysm-DDA/wiki/Harvest-data

[codemime]

Changes

• sym in overmap_terrain now accepts only one symbol instead of an array of symbols. The symbol still rotates accordingly if "rotate": true is specified. Changed in #19518.

Migration

Replace all arrays of symbols in overmap_terrain with the first symbol in each array (e.g. "sym": [ 94, 62, 118, 60 ] with "sym": 94).

Additional notes

The set of supported symbols is limited. Currently rotatable symbols are:

     60; 62; 94; 118; 4194410-4194413; 4194417; 4194421-4194424;

More symbols may be added on request.

[codemime]

Changes

edit-mode isn't supported anymore and was replaced with inheritance. Changed in #19020.

Migration

Use copy-from to inherit from other objects or abstracts.

[Coolthulhu]

New feature

New generic attack syntax that allows defining custom monster attacks in json #19702.

Description here:
https://github.com/CleverRaven/Cataclysm-DDA/wiki/Monster-special-attacks

[codemime]

Changes

In overmap_special:

• Various "linear" terrains can be present in overmaps. Define "overmap": "road_..." to make an adjoined road (sewer, ant tunnel e.t.c.) of your liking. Mention its point in connections if you want to make a connection.
• terrain can now be omitted in connections when point points to an overmap of the desired type.

Changed in #20003.

Example

"overmaps": [
    { "point": [0,-1,0], "overmap": "road_end_north" }
],
"connections": [
    { "point": [0,-1,0] }
]

[Coolthulhu]

Changes

• #20299 (not merged yet) Monster attack messages no longer use string format type syntax and <npcname>, instead using <attacker_name>, <target_name> and <target_part_accusative>

[codemime]

Changes

Flags for overmap terrains have been replaced with respective boolean fields. See the updated doc for details.

Also, rotatable overmap specials can't have non-rotatable terrains in them. Linear terrains (roads, sewers, e.t.c.) are considered to be rotatable.

Migration

These fields need to be replaced with flags (in our usual manner "flags": [ "FLAG_1", "FLAG_2", ...]) :

Field : value	Flag	Note
"allow_road": true	"ALLOW_OVERRIDE"
"known_down": true	"KNOWN_DOWN"
"known_up": true	"KNOWN_UP"
"line_drawing": true	"LINEAR"
"rotate": false	"NO_ROTATE"	Terrains are now rotatable by default
.	"RIVER"	There was no field for this
"sidewalk": true	"SIDEWALK"

Changed in #20295.

[Coolthulhu]

Changes

• epower parts that aren't engines, reactors or alternators need a new flag "ENABLED_DRAINS_EPOWER": #20376

[Coolthulhu]

New feature

• Nested crafting lists in #20469. First declare a using that contains only one type of components (tools or consumed items) and only one set of alternatives, then inline it as if it was a single component, then add "LIST" after count. See the linked PR for examples.

[Coolthulhu]

New feature

• Computer bindings in json mapgen added in #20770.

Usage described on wiki:
https://github.com/CleverRaven/Cataclysm-DDA/wiki/Mapgen:-computers

[codemime]

Changes

In overmap_terrain:

• The flag ALLOW_OVERRIDE is obsoleted and isn't supported anymore.

Migration

The flag needs to be removed. AFAIK there are no mods that use this flag, but Justin Case (I was wrong: PKs_Rebalancing uses it, maybe someone else's as well). You can do either of the following:

1. Extend an existing location (see overmap_locations.json) used by the connection you want to allow overriding (see overmap_connections.json):

{
    "type": "overmap_location",
    "id": "desired_id",
    "copy-from": "desired_id",
    "extend": { "terrains": [ "id_of_your_terrain" ] }
}

2. Extend the connection itself with your new location:

   2.1. Add a new location and mention your overmap_terrain there (see above).
   2.2. Extend the desired connection/connections with your new location:

   {
    "type": "overmap_connection",
    "id": "desired_id",
    "copy-from": "desired_id",
    "extend" : { "subtypes": [
      {
        "terrain": "id_of_a_road_or_whatever",
        "locations": [ "id_of_your_new_location" ]
      }
    ] }
  }

Changed in #21620.

[Shinino]

#22198 -- this actually will affect a number of mods (anything touching regional_map_settings.json) - pasting the affected part here:

This section needs to be added to regional_settings_mod.json of any mod that has this issue (I put it right after shop_options, which is where it is in the main game's file

"houses": {
"house_two_story_basement": 1,
"house": 1000,
"house_base": 333
},

Mods affected: Bright Nights and Small Town Building Pack thus far -- verified that making this change in Bright Nights resolves the issue -- just don't know how to go about pushing a fix :)

[ZhilkinSerg]

Changes

In bionic:

• bionic fields (faulty, power_source, toggled, gun_bionic, weapon_bionic and armor_interface) were moved to corresponding bionics flags (BIONIC_FAULTY, BIONIC_POWER_SOURCE, BIONIC_TOGGLED, BIONIC_GUN, BIONIC_WEAPON, BIONIC_ARMOR_INTERFACE) in #22701.

Backward compatibility is preserved, so you can use fields instead of flags, but warning message will appear when starting game with mod using fields instead of flags for bionics.

[ZhilkinSerg]

Changes

version field was added for modinfo.json in #23032.

[Night-Pryanik]

monster_species and monster_kill_goal fields could be specified for newly added MGOAL_KILL_MONSTER_SPEC mission goal in #23745 and in #23769, respectively. monster_kill_goal field could also be specified for MGOAL_KILL_MONSTER_TYPE mission goal.

[ZhilkinSerg]

Changes:

• Additional syntax with fields (id, quantity, charges and flags) for used_up_item node in heal iuse-action.

New syntax:

"used_up_item" : { "id": "rag", "quantity": 1, "charges": 2, "flags": [ "FILTHY" ] }

Old syntax (will default to quantity of 1, charges of 1 and no additional flags.):

"used_up_item" : "rag"

Changed in #23858.

[ZhilkinSerg]

Basements can now have different ids which allow spawing in certain basement variant (see "High tech, low life" start scenario ).

Changes:

• added house_basement_chance to regional map settings json (this allows control to number of houses that have basements);
• added list of basements to regional map settings json (this allows to change weights of different types of basements and also have basements with different id);

Configuration example:

"city": {
...
          "house_basement_chance": 5,       "//": "one_in(n) chance a house has a basement",
...
          "basements": {
              "basement": 1000,
              "basement_bionic": 50
          },

Changed in #24036.

[mlangsdorf]

New feature:

furniture, terrain, monsters, vehicle parts, and items can have a "looks_like" field. This is pretty straightforward in how it is added to json:

{
    "type": "GENERIC",
    "id": "mjolnir",
    "name": "Mjölnir",
    "look_like": "hammer_sledge",
    ...
}

looks_like is set to the id of another object of the same time (furniture for furniture, monster for monster, etc). If a tileset tries to find a tile for an object with a looks_like field and fails, it repeats the search against the looks_like object and uses that tile if it finds it. If will continue searching until it finds a tile or reaches a looks_like object that doesn't have a looks_like field, at which point it falls back to the original item's ascii symbol.

looks_like is automatically set to copy-from for objects with a copy-from, but an explicit looks_like overrides the looks_like from copy-from. ie:

{
    "type": "GENERIC",
    "id": "lokis_knockoff",
    "copy-from": "mjolnir",
    ...
}

will use the tile for lokis_knockoff it the tileset has it, the tile for mjolnir if lokis_knockoff doesn't have a tile, and the tile for a hammer_sledge if mjolnir doesn't have a tile.
while

{
    "type": "GENERIC",
    "id": "lokis_knockoff_sharp",
    "copy-from": "lokis_knockoff",
    "looks_like": "warhammer",
    ...
}

will look like a warhammer if there isn't a tile for it.

[BrianLefler]

Changes

In mapgen json, the "add" directive has now been renamed "place_item" to match the already existing "place_items" directive. "Chance" is now interpreted as a percentile chance, not a one-in-X chance, bringing it in line with "place_items" and most other mapgen functions.

Migration

Change "add" to "place_item". If your chance was defined as one-in-X, change to a percentile chance (i.e., newChance = 100 / oldChance). If your chance was already being defined as percentiles, it will begin to work properly after this change.

[KorGgenT]

Changes

Harvest entries have changed in how they work; they are now required for all monsters.
See the doc for details

[kevingranade]

Updates to this issue have been sporadic, I'm absolutely certain they're incomplete, and there is no indication that anyone is reading them. Worse, it's unreadABLE, there's no reasonable way to use this stream of notifications to determine what you need to do in your mod. If we're going to support modding, we need up-to-date documentation in the repository people can reference.