Item spawn system

Collection or Distribution

In a Collection each entry is chosen independently from the other entries. Therefore the probability associated with each entry is absolute, in the range of 0…1. In the json files it is implemented as percentage with values from 0 to 100.

A probability of 0 (or negative) means the entry is never chosen, a probability of 100% means its always chosen. The default is 100, because it’s the most useful value. Default 0 would mean the entry can be removed anyway.

A Distribution is a weighted list like the current system. Exactly one entry is chosen from it. The probability of each entry is relative to the probability of the other entries. A probability of 0 (or negative) means it is never chosen.

An example: Suppose item A has a probability of 30 and item B has a probability of 20. Then the probabilities of the 4 combinations of A and B are:

Combination	Collection	Distribution
Neither A nor B	56%	0%
Only A	24%	60%
Only B	14%	40%
Both A and B	6%	0%

Format

The format is this:

{
    "type": "item_group",
    "subtype": "<subtype>",
    "id": "<some name>",
    "ammo": <some number>,
    "magazine": <some number>,
    "entries": [ ... ]
}

subtype is optional. It can be collection or distribution. If unspecified, it defaults to old, which denotes that this item group uses the old format (which is technically a distribution).

There are some caveats to watch out for when using ammo or magazine.

Entries array

The entries list contains entries, each of which can be one of the following:

Item
```
{ "item": "<item-id>", ... }
```
Group
```
{ "group": "<group-id>", ... }
```

Distribution

{
  "distribution": [
    "An array of entries, each of which can match any of these 4 formats"
  ]
}

Collection

{
  "collection": [
    "An array of entries, each of which can match any of these 4 formats"
  ]
}

The game decides based on the existence of either the item or the group value if the entry denotes a item or a reference to another item group.

Each entry can have more values (shown above as ...). They allow further properties of the item(s):

"damage": <number>|<array>,
"damage-min": <number>,
"damage-max": <number>,
"count": <number>|<array>,
"count-min": <number>,
"count-max": <number>,
"charges": <number>|<array>,
"charges-min": <number>,
"charges-max": <number>,
"active": "<bool>"
"contents-item": "<item-id>" (can be a string or an array of strings),
"contents-group": "<group-id>" (can be a string or an array of strings),
"ammo-item": "<ammo-item-id>",
"ammo-group": "<group-id>",
"container-item": "<container-item-id>",
"container-group": "<group-id>",

contents is added as contents of the created item. It is not checked if they can be put into the item. This allows water, that contains a book, that contains a steel frame, that contains a corpse.

count makes the item spawn repeat to create more items, each time creating a new item.

charges: Setting only min, not max will make the game calculate the max charges based on container or ammo/magazine capacity. Setting max too high will decrease it to maximum capacity. Not setting min will set it to 0 when max is set.

active: If true, activates the item on spawn. Note that this does not work for itemgroups, only individual items within itemgroups.

`active` Usage example

[
  {
    "id": "test_grenade",
    "type": "item_group",
    "subtype": "collection",
    "items": [{ "item": "grenade_act", "prob": 100, "active": true }]
  },
  {
    "type": "mapgen",
    "method": "json",
    "om_terrain": "shelter_roof",
    "weight": 100,
    "object": {
      // ...
      "place_items": [{ "item": "test_grenade", "x": 12, "y": 12, "chance": 100, "repeat": 1 }],
      "place_item": [{ "item": "grenade_act", "x": 15, "y": 15, "chance": 100, "active": true }]
    }
  }
]

"damage-min": 0,
"damage-max": 3,
"count": 4
"charges": [10, 100]

This will create 4 items, they can have different damage levels as the damage value is rolled separately for each of these items. Each item has charges (AKA ammo) in the range of 10 to 100 (inclusive); if the item needs a magazine before it can have charges, that will be taken care of for you. Using an array (which must have 2 entries) for charges/count/damage is equivalent to writing explicit min and max values. In other words "count": [a,b] is the same as "count-min": a, "count-max": b.

The container is checked and the item is put inside the container, and the charges of the item are capped/increased to match the size of the container.

Ammo and Magazines

Here are some ways to make items spawn with/without ammo/magazines (note that ammo-item can be specified for guns and magazines in the entries array to use a non-default ammo type):

Specify an ammo/magazine chance (introduced in Section 2) for the entire item group. ammo specifies the percent chance that the entries will spawn fully loaded (if it needs a magazine, it will be added for you). magazine specifies the percent chance that the entries will spawn with a magazine. Both of these default to 0 if unspecified.

Note that ammo and magazine only apply to tools, guns, and magazines. Furthermore, they don’t apply to tools whose entry explicitly specifies how much ammo (charges) to spawn with, or to tools whose JSON item definition specifies a random amount or a fixed, nonzero amount of initial charges.

If any item groups are referenced from your item group, then their ammo/magazine chances are ignored, and yours are used instead.
Use charges, charges-min, or charges-max in the entries array. A default magazine will be added for you if needed.

Shortcuts

This:

"items": [ "<id-1>", [ "<id-2>", 10 ] ]

means the same as:

"entries": [ { "item": "<id-1>" }, { "item": "<id-2>", "prob": 10 } ]

In other words: a single string denotes an item id, an array (which must contain a string and a number) denotes an item id and a probability.

This is true for groups as well:

"groups": [ "<id-1>", [ "<id-2>", 10 ] ]

This format does not support further properties of the created items - the probability is only optional for entries of collections!

The content of “entries”, “items” and “groups” are all added if those members exist. This will have the item <id-1> appear twice in the item group:

{
  "items": ["<id-1>"],
  "entries": [{ "item": "<id-1>" }]
}

Another example. The group “milk” spawns a container (taken from milk_containers) that contains milk (maximal amount that fits into the container, because there is no specific charges value defined).

{
    "type" : "item_group",
    "id": "milk_containers",
    "subtype": "distribution",
    "items": [
    "bottle_plastic", "bottle_glass", "flask_glass",
    "jar_glass", "jar_3l_glass", "flask_hip", "55gal_drum"
    ]
},
{
    "type" : "item_group",
    "id": "milk",
    "subtype": "distribution",
    "entries": [
        { "item": "milk", "container-group": "milk_containers" }
    ]
},

Inlined item groups

In some places one can define an item group directly instead of giving the id of a group. One can not refer to that group as it has no visible id (it has an unspecific/random id internally). This is most useful when the group is very specific to the place it is used and wont ever appear anywhere else.

As an example: monster death drops (death_drops entry in the MONSTER object, check here) can do this. If the monster is very specific (e.g. a special robot, a unique endgame monster), the item spawned upon its death won’t (in that form) appear in any other group.

Therefore, this snippet:

{
    "type": "item_group",
    "id": "specific_group_id",
    "subtype": "distribution",
    "items": [ "a", "b" ]
},
{
    "death_drops": "specific_group_id"
}

is equivalent to:

{
  "death_drops": {
    "subtype": "distribution",
    "items": ["a", "b"]
  }
}

The inline group is read like any other group and one can use all the properties mentioned above. Its type and its id members are always ignored.

Instead of a full JSON object, one can also write a JSON array. The default subtype is used and the array is read like the “entries” array (see above). Each entry of that array must be a JSON object. Example:

{
  "death_drops": [
    { "item": "rag", "damage": 2 },
    { "item": "bowling_ball" }
  ]
}

Notes

Testing

You can test your item groups in the game:

Load a game and call the debug menu

TIP (If a key isn’t bound to the debug menu or you forgot it, use ESC > 1)
Choose “Test Item Group”.
Select the item group you want to debug.

The game will then spawn items in that group 100 times and count the spawned items. They’ll then be displayed, sorted by their frequency.

TIP: You can filter anything in the debug menu using /

You should not add items to the item group EMPTY_GROUP. This group can be used when the game requires a group id, but you don’t want to spawn any items there. The group will never spawn items.

SUS

When adding items to item groups, attempt to locate or create SUS item groups. SUS item groups are collections that contain a reasonable realistic distribution of items that might spawn in a given piece of storage furniture. SUS stands for “specific use storage.” One of the aims of organizing item groups into specific use storage is to promote reusable tables that can be maintained and extended.

You can find SUS item groups at /data/json/itemgroups/SUS

JSON

tutorial

guides

map

reference

creatures

graphics

items

map

explanation

melee

Lua

tutorial

guides

reference

explanation

Item spawn system

Collection or Distribution

Format

Entries array

`active` Usage example

Ammo and Magazines

Shortcuts

Inlined item groups

Notes

Testing

SUS

tutorial

guides

map

reference

creatures

graphics

items

map

explanation

melee

tutorial

guides

reference

explanation

Item spawn system

Collection or Distribution

Format

Entries array

active Usage example

Ammo and Magazines

Shortcuts

Inlined item groups

Notes

Testing

SUS

`active` Usage example