Data Driven Loot Integration API

Data-Driven Loot Integration API

Biblio can add thematically matched books to another mod's loot tables without Java compatibility code and without replacing the target loot table.

Availability

This API is present in builds containing the tagged loot integration feature. At this wiki's source snapshot, its verified implementation was on the repository branch agent/work-tags-loot-integrations, not the public default branch. Structure and modpack authors should require a Biblio release that explicitly includes this API.

File location

Place one or more JSON files under this path in a mod or datapack:

data/<your_namespace>/biblio/loot_integrations/<name>.json

Biblio scans this directory across all loaded namespaces during server resource reload.

Minimal rule

{
  "target": "othermod:chests/sunken_library",
  "tags": ["ocean", "maritime"]
}

target is the loot table ID, not the structure ID. One structure can use several different loot tables.

The equivalent split form is:

{
  "mod": "othermod",
  "loot_table": "chests/sunken_library",
  "tags": ["ocean", "maritime"]
}

Complete example

{
  "targets": [
    "othermod:chests/library",
    "othermod:chests/library_treasure"
  ],
  "any_tags": ["science", "philosophy", "mythology"],
  "all_tags": ["nonfiction"],
  "exclude_tags": ["ocean"],
  "works": ["on_the_origin_of_species", "common_sense"],
  "exclude_works": ["example_exception"],
  "rolls": {"min": 1, "max": 3},
  "chance": 0.65
}

This illustrative combination is intentionally restrictive: a candidate must satisfy the work allow-list, all tag tests, and all exclusions.

Field reference

Field	Type	Default	Meaning
target	loot table ID	—	One target loot table
targets	array of loot table IDs	—	One or more target loot tables
mod + loot_table	strings	—	Alternative way to build one target ID
tags	string or array	empty	Shorthand for any_tags
any_tags	string or array	empty	Work must have at least one listed tag
all_tags	string or array	empty	Work must have every listed tag
exclude_tags	string or array	empty	Work is rejected if it has any listed tag
works	string or array	empty	Optional allow-list of exact Biblio work IDs
exclude_works	string or array	empty	Exact work IDs to reject
rolls	integer or range object	1	Books attempted when the rule runs
chance	number from 0.0 to 1.0	1.0	Probability that the rule runs for a target loot roll

At least one target form is required. target and targets may be used together; duplicates within the same rule are collapsed. The split mod + loot_table form is used only when neither direct target field supplied a target.

Use either tags or any_tags, not both. In the verified parser, tags takes precedence when both are present.

Tag matching

All non-empty filters are combined:

1. If works is present, the work ID must be in it.
2. The work ID must not be in exclude_works.
3. Every all_tags value must match.
4. At least one any_tags/tags value must match when that list is non-empty.
5. No exclude_tags value may match.

Short tags use the Biblio namespace, so "ocean" means "biblio:ocean". See Work-Level Tags.

With no tag or work filters, a rule can select any enabled Biblio work.

Rolls and chance

A fixed count:

{
  "rolls": 2
}

An inclusive random range:

{
  "rolls": {"min": 1, "max": 3}
}

Zero rolls are valid. Minimum rolls cannot be negative, and maximum rolls cannot be less than minimum. The implementation also accepts top-level min_rolls and max_rolls, but the rolls field is preferred for integration files.

chance is checked once each time the rule sees its target loot table. If it passes, the rule performs its configured rolls.

Selection behavior

For each roll, Biblio:

1. filters works using the rule,
2. removes works with no enabled physical volume,
3. chooses one eligible work uniformly,
4. chooses one enabled physical volume from that work uniformly, and
5. rolls that volume's normal Biblio quality and signed-copy table.

This preserves fair work selection and automatically respects the server's Biblio chest settings.

Rules are additive. If several files or rules target the same loot table, every matching rule is evaluated and may add books. Keep integrations coordinated to avoid accidental duplicates or excessive loot.

Multiple rules in one file

A file can be one rule, a top-level array, or an object with a rules array:

{
  "rules": [
    {
      "target": "othermod:chests/observatory",
      "tags": ["science"],
      "rolls": 1
    },
    {
      "target": "othermod:chests/crypt_library",
      "any_tags": ["gothic", "afterlife"],
      "exclude_tags": ["comedy"],
      "chance": 0.4
    }
  ]
}

Optional compatibility

A structure mod can ship this sidecar JSON in its own resources without putting Biblio-specific entries in its normal loot table. When Biblio is absent, no Biblio reload listener reads the sidecar and it does not modify the mod's loot table. The structure mod should keep Biblio optional rather than declaring it as a required dependency.

Reload and test

1. Install a Biblio build that includes tagged integrations.
2. Add the mod or datapack containing the sidecar JSON.
3. Run /reload or restart the server.
4. Watch the server log for Biblio integration errors or “matches no works” warnings.
5. Test an unopened container that uses the exact target loot table.

See Troubleshooting if no book appears.