xiaokun/netease-modsdk-wiki
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

搬运一批Bedrock wiki内容，完善翻译

Browse Source
This commit is contained in:
boybook
2025-03-20 00:13:44 +08:00
parent ead7392a76
commit 4896c1a4f2
163 changed files with 33930 additions and 1464 deletions
Download Patch File Download Diff File Expand all files Collapse all files

10
docs/wiki/loot/index.md Normal file
View File

@@ -0,0 +1,10 @@
---
title: Loot, Recipes, and Trading
categories:
- title: General
color: blue
- title: Documentation
color: red
- title: Tutorials
color: green
---

746
docs/wiki/loot/item-functions.md Normal file
View File

@@ -0,0 +1,746 @@
---
title: Item Functions
category: Documentation
nav_order: 4
tags:
- Stable
- Last updated for Version 1.18.10
mentions:
- Ciosciaa
- MedicalJewel105
- ThomasOrs
toc_max_level: 1
---
Item functions modify the nature of an item in [loot tables](/loot/loot-tables) and [trade tables](/loot/trade-tables).
TODO
can enchantments be prefixed with minecraft:/whatever?
Functions
Note that every single thing tested here was in trade tables only
Usable in loot tables and trade tables only
Are objects with `function` and other props…
None accept Molang
No Java additional functions or properties were successful
All may be prefixed with any sequence of text followed by a colon, like `minecraft:exploration_map` or `d1245436576u:fio2ejfoijfiowejf::::::exploration_map`
## General
A handful of functions are available for basic item properties. These functions are usable on any item.
| Function | Container Loot | Block Drops | Fishing | Entity Drops | Entity Equipment | Trade Tables |
| -------------------- | -------------- | ----------- | ------- | ------------ | ---------------- | ------------ |
| `set_count` | ✅ | ✅ | ✅ | ✅ | ✅ | ❌ |
| `set_name` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `set_lore` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `set_data` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `random_block_state` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `random_aux_value` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `set_damage` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
### Count
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ❌ |
::: tip NOTE
Trade tables use the [`"quantity"` property](/loot/trade-tables#quantity) to set their count.
:::
The `set_count` function sets the count for that item entry.
<CodeHeader>Count Function</CodeHeader>
```json
{
"function": "set_count",
"count": {
"min": 2,
"max": 4
}
}
```
The `"count"` property determines how many of that item should be yielded; it can either be provided as an integer or a [range object](#). Provided counts values may be larger than the stack size for that item. When this happens, the item will leak into other slots if in a container or separate into multiple different item stacks if dropped into the world. The count property actually defaults to `0`, so it should always be included.
### Name
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
The name of an item can be set using the `set_name` function. Names are visible in the user interface when hovering over an item. Names can be changed by players using anvils.
<CodeHeader>Name Function</CodeHeader>
```json
{
"function": "set_name",
"name": "Cursed Bow"
}
```
The name to give the item is given with the string `"name"` property. By default, name text appears italicized. However, item names support format codes, and `§r` can be inserted at the start of the text to reset it to non-italics. Raw text is unsupported in item names. `\n` can be used for newlines.
### Lore
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
The `set_lore` function sets the lore for an item.
<CodeHeader>Lore Function</CodeHeader>
```json
{
"function": "set_lore",
"lore": [
"",
""
]
}
```
The `"lore"` property configures the lore. It can be represented as either a string or an array of strings. All lore strings support format codes but do not support localization. In the array form, each string represents a new line of lore. Each such string's formatting context is independent, meaning formatting will reset with each string. By default, purple and italicized text is used for lore; this can be reset by prepending the reset format code (`§r`) to each string as necessary. `\n` can be used within any lore string to form a newline while preserving the current formatting context.
### Data
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`set_data` establishes the data for the given item, similar to the argument in the `/give` command. If used on a block, it will set the block's data value. If used on an item, it will set it's aux value. Unlike the command, however, `set_data` cannot set the durability of an item. For that, use [`durability`](#durability).
<CodeHeader>Data Function</CodeHeader>
```json
{
"function": "set_data",
"data": 2
}
```
The `"data"` property sets the item's data. If not provided, it will default to `0`. `"data"` can either be provided as an integer or a range object.
As an integer:
```json
"data": 1
```
As a range object:
```json
"data": {
"min": 0,
"max": 5
}
```
The object form will randomly select a data value inclusively between the provided minimum and maximum each instance this function's item entry is selected.
### Block State
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`random_block_state` sets an individual block state for a block.
<CodeHeader>Block State Function</CodeHeader>
```json
{
"function": "random_block_state",
"block_state": "wiki:color",
"values": 3
}
```
Sets a block state for a block
block_state
Required string name of block state
values
Can be number or min/max object
Defaults to 0… kinda required otherwise pointless? IDK…
### Aux Value
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`random_aux_value`
<CodeHeader>Aux Value Function</CodeHeader>
```json
{
"function": "random_aux_value",
"values": {
"min": 2,
"max": 4
}
}
```
Sets aux value of an item
values
Can be integer or min/max object
Min/max object chosen uniformly randomly
Only used for aux value; won't, for example, set damage of a tool but will set color of wool
Overrides any provided aux value as identifier `:suffix`, like `minecraft:wool:10`
Works on block data, too
### Durability
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
Item durability can be set using the `set_damage` function.
<CodeHeader>Durability Function</CodeHeader>
```json
{
"function": "set_damage",
"damage": {
"min": 0.5,
"max": 1
}
}
```
The `"damage"` property sets the item's durability. It can be represented either as a number or a [range object](#). Values are intended to range from `0` to `1`, where `0` is the minimum possible durability for an item and `1` is undamaged.
## Item-Specific Data
Some functions are only usable by a certain set of items. See each function for which items are relevant.
| Function | Container Loot | Block Drops | Fishing | Entity Drops | Entity Equipment | Trade Tables |
| -------------------- | -------------- | ----------- | ------- | ------------ | ---------------- | ------------ |
| `furnace_smelt` | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| `set_book_contents` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `exploration_map` | ✅ | ✅ | ✅ | ✅ | ✅ | ⚠️ |
| `set_banner_details` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `random_dye` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `set_actor_id` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `fill_container` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
### Heat Item
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ❌ |
| Block drops | ❌ |
| Fishing | ❌ |
| Entity drops | ✅ |
| Entity equipment | ❌ |
| Trade table | ❌ |
`furnace_smelt`
<CodeHeader>Heat Item Function</CodeHeader>
```json
{
"function": "furnace_smelt"
}
```
auto-implies that the entity must’ve been on fire when they died
Vanilla files use a function condition for this, but even removing that condition still implies that the entity must’ve died on fire for the furnace_smelt function to trigger
### Book Contents
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`set_book_contents`
<CodeHeader>Book Contents Function</CodeHeader>
```json
{
"function": "set_book_contents",
"title": "",
"author": "",
"pages": [
"",
""
]
}
```
Sets data for a book
Can only be used on `writable_book` or `written_book`
author
String name of the author
title
String name of the book
pages
Array of strings — each string is the contents of that page
Supports up to 50 strings and 798 characters per string
12,800‌ character limit across all pages
Use `\n` in the string (not `\\n`) to add newlines
Can’t use tabs
Can use color codes; Each different page string resets the color codes each time
### Exploration Map
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`exploration_map`
<CodeHeader>Exploration Map Function</CodeHeader>
```json
{
"function": "exploration_map",
"destination": "village"
}
```
trade table info:
destination
Currently only `monument` `mansion`.
Nothing else, not even buried treasure (this one looks like it’ll work — names the map right instead of Unknown Map like the others, but it doesn’t point anywhere). :(
Loot table info:
Destination
Works for any /locate location (see old recipe notes for caveats there; this is for container loot tables)
Only works if in the appropriate dimension
If a mansion or monument, gets named, colored, and icon’d correctly, corresponding to the right marker decoration
If invalid or no destination is given, shows no marker but still has the river and ocean lines on the map
Works in containers and both entity equipment and drops
Keep in mind how only 2 locations worked from traders
### Banner Type
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`set_banner_details`
<CodeHeader>Banner Type Function</CodeHeader>
```json
{
"function": "set_banner_details"
}
```
Sets type of a `banner` (only usable on this)
type
Can only be 0 or 1
0 is just a white banner
1 is illager banner
### Random Dyeing
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`random_dye`
<CodeHeader>Random Dyeing Function</CodeHeader>
```json
{
"function": "random_dye"
}
```
Randomly dyes leather armor or horse armor
Doesn’t work on wool or whatever
### Spawn Eggs
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`set_actor_id`
<CodeHeader>Spawn Eggs Function</CodeHeader>
```json
{
"function": "set_actor_id"
}
```
Usable with spawn eggs
id
Should be the identifier for the mob
in trade tables, defaults to trader's entity type
### Container Contents
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`fill_container`
<CodeHeader>Container Contents Function</CodeHeader>
```json
{
"function": "fill_container"
}
```
Sets the contents of a container block
loot_table
Path to loot table file from behavior pack root
loot_table needed or will just be the normal item
Cannot point to that current loot table
Works in containers and both entity stuff and blocks
## Enchanting
| Function | Container Loot | Block Drops | Fishing | Entity Drops | Entity Equipment | Trade Tables |
| -------------------------- | -------------- | ----------- | ------- | ------------ | ---------------- | ------------ |
| `enchant_book_for_trading` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `enchant_with_levels` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `enchant_randomly` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `enchant_random_gear` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
| `specific_enchants` | ✅ | ✅ | ✅ | ✅ | ✅ | ✅ |
### Enchant for Trading
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`enchant_book_for_trading`
<CodeHeader>Enchant for Trading Function</CodeHeader>
```json
{
"function": "enchant_book_for_trading"
}
```
documented in trade tables
### Level-Based Enchantments
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`enchant_with_levels` enchants items using enchantment table logic, optionally allowing for treasure enchantments.
<CodeHeader>Level-Based Enchantments Function</CodeHeader>
```json
{
"function": "enchant_with_levels",
"levels": {
"min": 15,
"max": 21
},
"treasure": true
}
```
Enchants books as though off an enchantment table with the given levels
Unlike enchanting table, doesn’t cap at 30, otherwise seems symmetrical
level 99999 gives ludicrously powerful books… with pretty much every possible enchantment on them
treasure
Enables treasure enchantments as possibilities for that item
boolean, defaults to false
If false, curses can't appear as possibilities; if true, they can
levels
Can be number or min/max object
Defaults to 0
Can be negative, but will just be remapped as though 0.
### Random Enchantments
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`enchant_randomly`
<CodeHeader>Random Enchantments Function</CodeHeader>
```json
{
"function": "enchant_randomly"
}
```
Randomly picks a count of enchantments and their strengths for the given item
treasure
Enables treasure enchantments as possibilities for that item
boolean, defaults to false
### Enchant Gear
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`enchant_random_gear`
<CodeHeader>Enchant Gear Function</CodeHeader>
```json
{
"function": "enchant_random_gear"
}
```
Randomly picks a count of enchantments and their strengths for the given item
Pretty much like enchant_randomly, but seemingly no treasure enchantments
Not working on shears, but does even work on carrot-on-a-stick
chance
Number from 0 to 1
Chance that the item is enchanted at all
Defaults to 0
Going over 1 doesn't make it "more" enchanted
### Specific Enchantments
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ✅ |
| Block drops | ✅ |
| Fishing | ✅ |
| Entity drops | ✅ |
| Entity equipment | ✅ |
| Trade table | ✅ |
`specific_enchants`
<CodeHeader>Specific Enchantments Function</CodeHeader>
```json
{
"function": "specific_enchants"
}
```
Applies a specific set of enchantments
enchants
Can be string array or object
For array, any mix of strings or objects (see below)
For string, an enchantment id
For object:
id
The identifier for the enchantment
See below for names
level
Optional, defaults to 1
Can be an exact number or a 2-valued array, representing min and max, inclusive
## External Factors
| Function | Container Loot | Block Drops | Fishing | Entity Drops | Entity Equipment | Trade Tables |
| --------------------------- | -------------- | ----------- | ------- | ------------ | ---------------- | ------------ |
| `looting_enchant` | ❌ | ❌ | ❌ | ✅ | ❌ | ❌ |
| `explosion_decay` | ❌ | ✅ | ❌ | ❌ | ❌ | ❌ |
| `set_data_from_color_index` | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
| `trader_material_type` | ❌ | ❌ | ❌ | ❌ | ❌ | ✅ |
### Held Tool Looting Enchantment
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ❌ |
| Block drops | ❌ |
| Fishing | ❌ |
| Entity drops | ✅ |
| Entity equipment | ❌ |
| Trade table | ❌ |
`looting_enchant`
<CodeHeader>Held Tool Looting Function</CodeHeader>
```json
{
"function": "looting_enchant",
"count": {
"min": 0,
"max": 1
}
}
```
Count can be an integer or min/max
### Explosion Decay
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ❌ |
| Block drops | ✅ |
| Fishing | ❌ |
| Entity drops | ❌ |
| Entity equipment | ❌ |
| Trade table | ❌ |
`explosion_decay`
<CodeHeader>Explosion Decay Function</CodeHeader>
```json
{
"function": "explosion_decay"
}
```
By default, always survives. If in an explosion, has a chance of not dropping based on explosion power at that block’s location
### Entity Color
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ❌ |
| Block drops | ❌ |
| Fishing | ❌ |
| Entity drops | ❌ |
| Entity equipment | ❌ |
| Trade table | ✅ |
`set_data_from_color_index`
<CodeHeader>Entity Color Function</CodeHeader>
```json
{
"function": "set_data_from_color_index"
}
```
Sets the data value of the block to the value of the `minecraft:color` component on the entity
### Trader Material Type
| Usage | Usable |
| ---------------- | ------ |
| Container loot | ❌ |
| Block drops | ❌ |
| Fishing | ❌ |
| Entity drops | ❌ |
| Entity equipment | ❌ |
| Trade table | ✅ |
`trader_material_type`
<CodeHeader>Trader Material Type Function</CodeHeader>
```json
{
"function": "trader_material_type"
}
```
Only in trades? Maybe it can work somewhere in loot

292
docs/wiki/loot/loot-tables.md Normal file
View File

@@ -0,0 +1,292 @@
---
title: Loot Tables
category: Documentation
nav_order: 1
tags:
- Stable
- Last updated for Version 1.18.10
mentions:
- Ciosciaa
- Etanarvazac
- SmokeyStack
---
::: warning
This document is a work in progress.
:::
Loot tables are used to select a set of items from a declared collection. Loot tables can be used from:
- The `/loot` command
- Container contents
- Block drops
- Fishing
- Mob drops
- Equipment on spawned mobs
- Other various mob actions
A different collection of items may be chosen each instance the same loot table would be used, based on [external conditions](#), and [innate randomness](#). Such variation is crucial for playability and adventuring, especially in more RPG-driven systems.
## Integration
Loot tables are not registered add-on entries and are instead referenced by path from the above sources. Loot tables may be placed anywhere within a behavior pack, but it's recommended to place them under the top-level `loot_tables` directory, following vanilla convention.
<FolderView
:paths="[
'BP/loot_tables/blocks/cypress_door.json',
'BP/loot_tables/blocks/cypress_door.json',
'BP/loot_tables/blocks/cypress_door.json'
]"
/>
## Structure
Loot tables are represented as JSON objects with a single required `"pools"` array property.
<CodeHeader>#</CodeHeader>
```json
{
"pools": [
…
]
}
```
The loot returned from a loot table invocation will be the *collective sum* of the yields of all pools provided here.
### Pools
Pools act as isolated constructs for selecting items; the results of pools cannot be influenced by other pools.
<CodeHeader>#</CodeHeader>
```json
{
"rolls": 1,
"entries": [
{
"type": "item",
"name": "wiki:silver"
}
]
}
```
Two types of pools are available: general-purpose [weighted random pools](#weighted-random-pools) and [tiered pools](#tiered-pools), the latter of which is traditionally used for selecting mob equipment.
#### Weighted Random Pools
A traditional weighted random pool selects items based on relative weight, choosing a number of yields based on a configured roll count.
<CodeHeader>artifacts.json/pools/0</CodeHeader>
```json
{
"rolls": {
"min": 2,
"max": 4
},
"entries": [
{
"type": "item",
"name": "minecraft:golden_apple",
"weight": 20
},
{
"type": "item",
"name": "minecraft:appleEnchanted",
"weight": 1
},
{
"type": "item",
"name": "minecraft:name_tag",
"weight": 30
}
]
}
```
##### Rolls
###### Bonus Rolls
The roll count for a weighted random pool may be altered based on the player's luck using the optional `"bonus_rolls"` property.
```json
```
##### Entry Weighting
The weight is the chance of this entry being chosen. The higher the weight in comparison to other entries in this "entries" array, the higher the chance of the entry being chosen.
```json
"weight": 3
```
###### Quality
The weight of an entry can be changed based on the player's luck using the quality property.
```json
"quality": 2
```
Currently, luck is only expressed when fishing with a fishing rod enchanted with Luck of the Sea.
#### Tiered Pools
Tiered pools are used to select exactly one entry from a collection.
```json
{
"tiers": {
"initial_range": 2,
"bonus_rolls": 3,
"bonus_chance": 0.095
},
"entries": [
{
"type": "loot_table",
"name": "loot_tables/entities/armor_set_leather.json"
},
{
"type": "loot_table",
"name": "loot_tables/entities/armor_set_gold.json"
},
{
"type": "loot_table",
"name": "loot_tables/entities/armor_set_chain.json"
},
{
"type": "loot_table",
"name": "loot_tables/entities/armor_set_iron.json"
},
{
"type": "loot_table",
"name": "loot_tables/entities/armor_set_diamond.json"
}
]
}
```
A pool becomes tiered with the inclusion of the `"tiers"` object property:
```json
"tiers": {
"initial_range": 2,
"bonus_rolls": 3,
"bonus_chance": 0.095
}
```
Entries in a tiered pool are *ordered*. The selected entry for a tiered pool is based on its index. To determine this index, a starting index is randomly rolled and then a batch of success rolls attempt to increment this starting index.
The starting index is decided by rolling a random integer between 1 and the integer property `"initial_range"`. If no initial range is provided, it defaults to `1`, forcing a starting index of 1.
Next, attempts are made to advanced the index using additional rolls. The count of these roll attempts is given as an integer to `"bonus_rolls"`. The chance that any such roll succeeds is given via `"bonus_chance"`. Chances for `"bonus_chance"` are out of 1, meaning `0.5` would be a 50% chance for any bonus roll to succeed. Each successful roll increases the index by 1. Both of these properties default to `0`, meaning both must be provided to use this additional rolls mechanic.
The final determined index is used to select the corresponding entry as that pool's yield. Indices in tiered pools are one-indexed, meaning the first entry has an index of 1, the second has an index of 2, and so forth. If the determined index is larger than the entry count for that pool, no yield will be provided.
::: warning
All [conditions](#) on entries in a tiered pool are ignored. Conditions on the pool itself are still allowed.
:::
### Entries
Entries are the selectable units of a pool. Three different types of entries are available.
```json
```
#### Item Entries
Item entries are the fundamental entry type for selecting loot. Item entries refer to
```json
```
#### Loot Table Entries
Loot hierarchies can be formed using loot table entries.
```json
```
#### Empty Entries
When selected, empty entries won't yield any loot for that roll.
```json
"type": "empty",
"weight": 4
```
Empty entries can generally be mimicked using [a roll count](#) whose range includes 0, [random chance conditions](#), or [count functions](#) that could randomly select 0. Their primary advantage is readability when using [weighted random pools](#): denoting by weight when a roll won't yield an entry may be easier to understand.
### Functions
Functions are what makes loot tables so powerful. They can do a wide range of tasks for each entry in your loot table. For example, they can change the amount of an item is dropped, what enchantments are present (even on items that normally cannot be enchanted), the item name, it's lore, and it can even write books! View [item functions](/loot/item-functions) for a full list of functions and how they're used.
<CodeHeader>artifacts.json/pools/entries</CodeHeader>
```json
{
"type": "item",
"name": "minecraft:dirt",
"weight": 10,
"functions": [
{
"function": "set_count",
"count": {
"min": 16,
"max": 64
}
},
{
"function": "set_name",
"name": "Pile of dirt"
}
]
}
```
### Conditions
Conditions check to see if a certain criteria is met. Examples: "Was Zombie killed by Player", "Did the sword have the Looting enchantment on it? If so, what level?"
<CodeHeader>artifacts.json/pools/entries</CodeHeader>
```json
{
"conditions": [
{
"condition": "killed_by_player"
},
{
"condition": "random_chance_with_looting",
"chance": 0.025,
"looting_multiplier": 0.01
}
],
"rolls": 1,
"entries": [
{
"type": "item",
"name": "minecraft:iron_ingot",
"weight": 1
},
{
"type": "item",
"name": "minecraft:carrot",
"weight": 1
},
{
"type": "item",
"name": "minecraft:potato",
"weight": 1
}
]
}
```
## Overrides

125
docs/wiki/loot/randomized-structure-loot.md Normal file
View File

@@ -0,0 +1,125 @@
---
title: Randomized Structure Loot
category: Tutorials
mentions:
- MedicalJewel105
- SirLich
- SmokeyStack
- Ciosciaa
- rebrainertv
tags:
- easy
---
Adding loot tables to containers in structure is easy, you need to have a PC and your choice of either [NBT Studio](https://github.com/tryashtar/nbt-studio/releases/download/v1.14.1/NbtStudio.exe) (executable) or [Loot Tabler](https://mcbe-essentials.github.io/structure-editor/loot-tabler) (browser application).
## Setup
### Creating the Loot Table
To start, create the directory `BP/loot_tables/chests` and create your loot table file here.
You can learn how to make loot tables in [Beginners Guide](/guide/loot-table)
<CodeHeader>BP/loot_tables/chests/my_structure_loot.json</CodeHeader>
```json
{
"pools": [
{
"rolls": {
"min": 8,
"max": 10
},
"entries": [
{
"type": "item",
"name": "minecraft:glass_bottle",
"functions": [
{
"function": "set_count",
"count": {
"min": 4,
"max": 6
}
}
],
"weight": 1
},
{
"type": "item",
"name": "minecraft:potion",
"functions": [
{
"function": "set_count",
"count": {
"min": 4,
"max": 6
}
}
],
"weight": 1
}
]
}
]
}
```
### Exporting Structure
Once you have created your loot table, export your structure into `BP/structures`. Then follow the steps for either NBT Studio or Loot Tabler
![](/assets/images/tutorials/randomised-structure-loot/export_structure.png)
## NBT Studio (Executable)
### Software Preparation
Download and launch [NBT Studio](https://github.com/tryashtar/nbt-studio/releases/download/v1.14.1/NbtStudio.exe)
### Adding the Loot Table
Launch NBT Studio and open file `(Ctrl + O)`
![](/assets/images/tutorials/randomised-structure-loot/open_file.png)
Find your container (Ctrl + F)
![](/assets/images/tutorials/randomised-structure-loot/find_container.png)
Navigate to your container, `block_position_data` > `block_entity_data`. Add a string tag
![](/assets/images/tutorials/randomised-structure-loot/add_string_tag1.png)
Add `LootTable` and the file path to your loot table
![](/assets/images/tutorials/randomised-structure-loot/add_string_tag2.png)
Save changes (Ctrl + S)
## Loot Tabler (Browser Application)
:::tip
To export a structure on mobile devices, [Download this pack.](https://mcpedl.com/export-structure-button-android-addon/)
:::
### Adding the Loot Table
Open the website and click "Upload". Choose your structure file.
![](/assets/images/tutorials/randomised-structure-loot/LootTable-step1.png)
Find your container in the containers list, making use of the information displayed under "Container Options"
![](/assets/images/tutorials/randomised-structure-loot/LootTable-step2.png)
Under "Loot Table", enter the path to your loot table. Set "Loot Table Seed" to blank or `0` if you want the loot to generate randomly. If you want the loot table to generate consistently, enter a specific value.
![](/assets/images/tutorials/randomised-structure-loot/LootTable-step3.png)
Download your structure file and place it in `BP/structures`.
## Testing
Load your structure and open the container
![](/assets/images/tutorials/randomised-structure-loot/test.png)

778
docs/wiki/loot/recipes.md Normal file
View File

@@ -0,0 +1,778 @@
---
title: Recipes
category: Documentation
nav_order: 3
tags:
- Stable
- Last updated for Version 1.20.30
mentions:
- Ciosciaa
- SirLich
- MedicalJewel105
- TheHyperWhale
- Luthorius
- QuazChick
---
Recipes are the means of handling several item transactions, namely those occurring in crafting tables, furnaces, campfires, and brewing stands.
![](/assets/images/loot/recipes/recipe.png)
::: tip
Anvil interactions are handled within an [item definition](/items/item-components), not via recipe files. Loom transactions are currently unavailable.
:::
No experimental toggles are required to use recipes or any of their features.
### Registration
All recipes are stored in the `recipes` folder in the behavior pack root. The files can be named and organized under any folder hierarchy as desired.
This arbitrary structure is used for the paths in this document:
<FolderView
:paths="[
'BP/recipes/crafting/weapons/cold_steel_sword.json',
'BP/recipes/decorations/knobs/brass.json',
'BP/recipes/covered_arch.json',
'BP/recipes/magic/magic_ash.json',
'BP/recipes/brewing/negative/paralysis.json',
'BP/recipes/illumination_potion.json'
]"
/>
As an example, a "cold steel sword" might be crafted using the following [shaped recipe](#shaped-recipes):
<CodeHeader>BP/recipes/crafting/weapons/cold_steel_sword.json</CodeHeader>
```json
{
"format_version": "1.17.41",
"minecraft:recipe_shaped": {
"description": {
"identifier": "wiki:cold_steel_sword"
},
"tags": ["crafting_table", "altar"],
"pattern": [
"X",
"X",
"I"
],
"key": {
"X": "wiki:cold_steel",
"I": "minecraft:stick"
},
"unlock": [
{
"item": "wiki:cold_steel"
},
{
"item": "minecraft:wool",
"data": 3
},
{
"context": "PlayerInWater"
}
],
"result": "wiki:cold_steel_sword"
}
}
```
## Shared Properties and Structures
### Format Version
The [format version](/guide/format-version) is intended to version the schema used for the body of a recipe. It is provided with the top-level `"format_version"` property.
<CodeHeader>#/</CodeHeader>
```json
"format_version": "1.17.41"
```
In practice, the format version can be set to any value or even omitted.
::: warning
It's strongly recommended to include a format version anyway, choosing a value that represents an actual Minecraft version to help future-proof the code. Consider using the current release version or last major release version.
:::
### Description
The `"description"` object, required within any recipe type, holds the identifier of a recipe.
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"description": {
"identifier": "wiki:cold_steel_sword"
}
```
Its only child is the required `"identifier"` property, which is designed to uniquely identify a recipe across all packs applied to a world. There are no namespacing requirements for recipe identifiers except that no two full recipe identifiers in a single pack may match.
::: warning
It's strongly recommended to use a namespace. Namespaces are a standard in other add-on domains and assist in logically scoping the recipe to a pack, lessening possibilities of collisions for players wanting to use multiple behavior packs in their world.
:::
### Tags
Recipes are linked to crafting interfaces using the required `"tags"` array property, which must be placed within any recipe type. These tags will make the recipe be shared across different blocks that uses the `minecraft:crafting_table` component. When the recipe does not inlcude the `crafting_table` tag, or any vanilla tag, but a tag from your custom block, the recipe will only be shared to that custom block and not the crafting table/stonecutter/etc. At least one tag must be provided.
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"tags": ["crafting_table", "altar"]
```
Vanilla interfaces are exposed to tags for each set of recipe types.
Crafting:
- `crafting_table`
- `stonecutter`
- `smithing_table`
:::
warning Note that if you want to make a smithing recipe, you will need to use `<namespace>:netherite_ingot` for the second slot, though using a different identifier will not work. **This no longer works after 1.18.30**.
:::
Cooking and Smelting:
- `furnace`
- `blast_furnace`
- `smoker`
- `campfire`
- `soul_campfire`
Brewing:
- `brewing_stand`
Education:
- `material_reducer`
::: tip
Additionally, [custom crafting tables](/blocks/block-components#crafting-table) can declare a custom tag for crafting recipes to use. Custom cooking and smelting blocks and custom brewing stands are not currently available.
:::
::: tip
To effectively disable a recipe (useful for [overriding](#overrides) a prior recipe), set the tag array to `[""]`.
:::
### Recipe Unlocking
Minecraft 1.20.30 added recipe unlocking to the game. In order to have your recipes use this function, you `manifest.json` must have a `min_engine_version` of 1.20.11 (1.20.30 is recommender). You also need to add the `unlock` array with its objects to your recipe.
```json
"unlock": [
{
"item": "wiki:cold_steel" //item to unlock recipe
},
{
"item": "minecraft:wool", //item to unlock recipe
"data": 3
},
{
"context": "PlayerInWater" //event to unlock recipe
}
]
```
Each object in this array contains `"item"` and this tells the recipe what item the player needs in their inventory in order for this recipe to be unlocked. It also accepts data values. `"context"` is used to determine what event unlocks this recipe. `"PlayerInWater"` will unlock this recipe when the player enters water. This is also the only known context for recipes.
### Item Descriptors
Working with recipes entails referencing items across a number of properties. Items may be provided in one of two formats: a string reference or an item object. Both formats have means of handling data values, but only the item object may be used to specify a count for that item (usable in recipe outputs). For recipe inputs, if no data value is provided, items with any data value under that identifier will be usable for that input. The data value for an output defaults to `0` if one is not explicitly provided. Selecting recipe inputs by item tags is not supported.
#### String Reference
Generally, a string reference is just the namespace and identifier combination for that item:
<CodeHeader>#/minecraft:recipe_shapeless/ingredients/0</CodeHeader>
```json
"minecraft:planks"
```
String references additionally support specification of a data value as a suffix:
<CodeHeader>#/minecraft:recipe_shapeless/ingredients/0</CodeHeader>
```json
"minecraft:planks:2"
```
#### Item Object
The item object is a more explicit construct for referencing items.
<CodeHeader>#/minecraft:recipe_shapeless/ingredients/0</CodeHeader>
```json
{
"item": "minecraft:planks",
"data": 2,
"count": 3
}
```
The required `"item"` property functions the same as the string reference format. Although an explicit data field is available, the data suffix string format is still supported in the `"item"` property. However, unlike the suffix form, `"data"` can accept Molang. The Molang here is evaluated once on world load, not per-crafting attempt. Variables cannot be used to pass data between properties in a recipe. Furthermore, the nature of input items cannot be queried. Currently, the only known usable query in the `"data"` property is `q.get_actor_info_id`, used to look up the ID of an entity's spawn egg by its identifier:
<CodeHeader>#/minecraft:recipe_shapeless/result</CodeHeader>
```json
{
"item": "minecraft:spawn_egg",
"data": "q.get_actor_info_id('minecraft:chicken')"
}
```
The optional integer `"count"` property may be used to stack items. It defaults to `1`. Currently, setting the count only functions in [crafting](#crafting) and [furnace](#heating) recipe outputs and [shapeless recipe ingredients](#ingredients). A provided count is ignored in other locations.
::: tip NOTE
If a count greater than `1` is provided for an item that does not stack, an error will be thrown. There is no way to force single-return recipe outputs, like those in shapeless recipes or brewing mixes, to return multiple items in one transaction.
:::
::: warning
Despite having similarities to trade [table item descriptors](/loot/trade-tables#items), recipe item descriptors cannot use functions.
:::
#### Identifier Additions
Additional identifiers not typically usable are available to recipes to describe basic potions.
<CodeHeader>#/minecraft:recipe_brewing_mix/input</CodeHeader>
```json
"minecraft:potion_type:strength"
```
These identifiers are not usable in the object notation, only the string notation. Variants are unavailable for splash and lingering potions. All such identifiers follow the format: <code>minecraft:potion_type:<em>potion_effect</em></code>, where <code><em>potion_effect</em></code> can be one of the following:
- `water`
- `awkward`
- `mundane`
- `thick`
- `healing`
- `regeneration`
- `swiftness`
- `strength`
- `harming`
- `poison`
- `slowness`
- `weakness`
- `water_breathing`
- `fire_resistance`
- `nightvision`
- `invisibility`
- `leaping`
- `slow_falling`
- `turtle_master`
- `wither`
Where supported, `long_` and `strong_` prefixes may be used to designate modified potions, such as `minecraft:potion_type:strong_poison`.
## Crafting
Crafting operations instantly transform inputs to outputs using crafting grids. Two crafting recipe types are available: [shapeless recipes](#shapeless-recipes), whose inputs may be arranged in any way, and [shaped recipes](#shaped-recipes), used to define strict arrangements of inputs.
Crafting recipes support both crafting tables and stonecutters:
<CodeHeader>#/minecraft:recipe_shapeless/</CodeHeader>
```json
"tags": ["crafting_table", "stonecutter"]
```
`"crafting_table"` applies to both vanilla crafting tables and the player 2 × 2 crafting grid in their inventory. There is currently no way to opt into one but not the other. Crafting recipes additionally support custom tags, linking recipes to a [crafting grid provided by a custom block](/blocks/block-components#crafting-table).
### Shapeless Recipes
Shapeless recipes simply bind a collection of inputs to a single output on a crafting grid.
![](/assets/images/loot/recipes/shapeless_recipe.png)
<CodeHeader>BP/recipes/decorations/knobs/brass.json</CodeHeader>
```json
{
"format_version": "1.17.41",
"minecraft:recipe_shapeless": {
"description": {
"identifier": "wiki:brass_door_knob"
},
"group": "handles",
"tags": ["construction_bench"],
"ingredients": [
"wiki:brass",
{
"item": "wiki:screw",
"data": 2
}
],
"unlock": [
{
"item": "wiki:cold_steel"
},
{
"item": "minecraft:wool",
"data": 3
},
{
"context": "PlayerInWater"
}
],
"result": {
"item": "wiki:door_knob",
"data": 3
}
}
}
```
#### Ingredients
The required `"ingredients"` array property lists the items required as inputs for the crafting recipe.
<CodeHeader>#/minecraft:recipe_shapeless/</CodeHeader>
```json
"ingredients": [
"wiki:brass",
{
"item": "wiki:screw",
"data": 2
}
]
```
Each entry is an [item descriptor](#item-descriptors). If an ingredient provides a count, that count must be expressed across multiple crafting grid slots. Using stacked items in a single grid slot to yield a product is unsupported. If the items required for crafting are available but the count of ingredients is greater than the crafting interface being used supports, the recipe will automatically be made unavailable in the recipe book.
#### Shapeless Results
Shapeless recipe outputs are expressed using the required `"result"` property and may be expressed as either an [item descriptor](#item-descriptors) or an array of a single item descriptor.
<CodeHeader>#/minecraft:recipe_shapeless/</CodeHeader>
```json
"result": {
"item": "wiki:door_knob",
"data": 3
}
```
### Shaped Recipes
Shaped recipes enforce that the ingredients used during crafting conform to a strict shape.
![](/assets/images/loot/recipes/shaped_recipe.png)
<CodeHeader>BP/recipes/covered_arch.json</CodeHeader>
```json
{
"format_version": "1.17.41",
"minecraft:recipe_shaped": {
"description": {
"identifier": "wiki:covered_arch"
},
"tags": ["crafting_table"],
"pattern": [
"SSS",
"I I",
"I I"
],
"key": {
"S": "wiki:cloth",
"I": "wiki:support"
},
"unlock": [
{
"item": "wiki:cold_steel"
},
{
"item": "minecraft:wool",
"data": 3
},
{
"context": "PlayerInWater"
}
],
"result": [
{
"item": "wiki:covered_arch",
"count": 3
},
"wiki:crafting_scrap"
]
}
}
```
#### Patterns
The required `"pattern"` array property establishes the shape used for the recipe.
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"pattern": [
"SSS",
"I I",
"I I"
]
```
Each entry in the array is a string representing a row in the crafting grid. Each character in each string represents a slot within that row. Spaces by default represent slots that should be empty.
Characters act as a shorthand to visually describe an item. Each distinct character is matched with a [key](#keys) that dictates what item should be present in that slot.
::: tip
If the pattern is only comprised of spaces, empty crafting interfaces able to fit that pattern's size will constantly match the recipe. A player may retrieve an infinite amount of the crafting output, including immediately filling their inventory to the limit upon shift-retrieving the result.
:::
##### Row Normalization
The pattern grid must be at most 3 × 3 but may be smaller. If string lengths are mismatched, Minecraft will automatically extend shorter strings, implying spaces in filled slots. The following two are equivalent:
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"pattern": [
"MA",
"IFI",
"M"
]
```
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"pattern": [
"MA ",
"IFI",
"M "
]
```
::: tip NOTE
Currently, no crafting grids, including those configurable from custom blocks, may be larger than 3 × 3. If the expressed pattern is unusable within the current crafting interface, the recipe will automatically be unavailable in the recipe book.
:::
##### Grid Freedom
Spaces are not automatically implied to fill in any remaining slots in the 3 × 3 space. If a provided pattern is smaller than the crafting grid being used, the pattern can be used anywhere so long as the structure and contents are maintained. As an example, consider the following pattern on a crafting table:
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"pattern": [
"O"
"OO"
]
```
The "L" shape isn't restricted to the upper-left corner of the crafting grid. Using a 3 × 3 grid as an example, the pattern would be usable with any of these configurations:
<Spoiler title="Possible Configurations">
*Underscores represent empty slots.*
```txt
O__
OO_
___
```
```txt
_O_
_OO
___
```
```txt
___
O__
OO_
```
```txt
___
_O_
_OO
```
</Spoiler>
To restrict placements to a particular location, use explicit spaces, which enforce empty slots in certain locations. The following is only usable in the upper-left corner of a grid:
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"pattern": [
"O "
"OO "
" "
]
```
##### Symmetry
All shaped recipes are innately horizontally symmetric:
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"pattern": [
"Z "
" Z "
" Z"
]
```
The preceding recipe may also be used by a player as though it were set to:
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"pattern": [
" Z"
" Z "
"Z "
]
```
#### Keys
Keys provide meaning to characters in a [pattern](#patterns), done via the required `"key"` object property, which maps key names to [item descriptors](#item-descriptors).
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"key": {
"S": "wiki:cloth",
"I": "wiki:support"
}
```
Every key present in the pattern should be accounted for here. Keys names are case-sensitive. If an item supports multiple data values and no data value is provided, any item of that identifier will be usable for that key. Any `"count"` property present in an item descriptor is ignored and regarded as `1`; stacked items in a crafting grid slot are only consumable one at a time.
::: tip NOTE
Any unicode character from `U+0020` to `U+07FF` may be used as a key name. If a key name has more than one character, only the first character is considered. Since spaces are by default used to signify empty slots on a grid and there's no way to re-designate a key for a blank slot, it's not recommended to use them as a key.
:::
::: warning
If a character in the pattern is not present in the key map, it will be treated as though it were a space, a designated empty tile.
:::
### Recipe Unlocking
Minecraft 1.20.30 added recipe unlocking to the game. In order to have your recipes use this function, you `manifest.json` must have a `min_engine_version` of 1.20.11 (1.20.30 is recommender). You also need to add the `unlock` array with its objects to your recipe.
```json
"unlock": [
{
"item": "wiki:cold_steel" //item to unlock recipe
},
{
"item": "minecraft:wool", //item to unlock recipe
"data": 3
},
{
"context": "PlayerInWater" //event to unlock recipe
}
]
```
Each object in this array contains `"item"` and this tells the recipe what item the player needs in their inventory in order for this recipe to be unlocked. `"context"` is used to determine what event unlocks this recipe. `"PlayerInWater"` will unlock this recipe when the player enters water. This is also the only known context for recipes.
#### Shaped Results
Shaped crafting recipe outputs behave very similarly to their [shapeless counterparts](#shapeless-results). Unlike array results for shapeless recipes, however, shaped recipe result arrays may contain more than one [item descriptor](#item-descriptors).
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"result": [
{
"item": "wiki:covered_arch",
"count": 3
},
"wiki:crafting_scrap"
]
```
The first entry in the array will be used as the visible output of the crafting block. All other values are automatically placed in the player's inventory upon removing the visible result from the output slot. There does not seem to be a limit on the number of items that may be returned from a crafting action.
::: tip NOTE
Any items not able to fit in the player's inventory are instead placed in the input slots of the crafting table left-to-right and then top-to-bottom. Anything not able to fit there is then thrown from the player as though they had used the "Drop Item" action.
:::
### Recipe Book
The recipe book automatically indexes and displays available recipes to the player, intelligently accounting for [ingredient counts](#ingredients) in shapeless recipes or [pattern constraints](#patterns) in shaped recipes. When multiple recipes point to the same output, the recipe book uses its own unique prioritization system.
When both recipes being compared are shapeless recipes, the following rules determine prioritization in order:
- Lower ingredient count of the _first_ listed ingredient
- More negative [priority](#priority)
- Lower-valued identifier string
For shaped recipes, recipes with "lesser" identifiers, when compared as strings, are always prioritized.
When comparing a shaped recipe to a shapeless recipe, the rules for comparing shapeless recipes are used; however, the interpreted count of ingredients for the shaped recipe is different from its actual ingredient count. Exactly how the ingredient count for a shaped recipe is determined is unknown.
### Grouping
This section is included informatively. Groups are present in crafting recipes in vanilla definitions, given with the optional `"group"` string property.
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"group": "slingshots"
```
It is currently unknown what, if anything, this property achieves. Presumably, it would be used with the [recipe book](#recipe-book). Neither using new custom groups nor reusing groups from vanilla definitions appear to achieve anything.
### Priority
Crafting recipes support an additional property for handling input collisions, `"priority"`, which primarily acts as a [tiebreaker](#prioritization) when multiple recipes could possibly apply to the given situation. Priorities are provided directly within the crafting recipe type object.
<CodeHeader>#/minecraft:recipe_shaped/</CodeHeader>
```json
"priority": 2
```
Crafting recipes with lower priority values take precedence. So, if all else is equal, a recipe with a priority of `0` would be used over a recipe with priority `1`. Priorities may be negative if necessary. If `"priority"` is not provided, a priority of `0` is implied.
## Heating
Furnace recipes are used to transform an item using a heat source over a period of time. A slight misnomer, furnace recipes are used with any interface that involves a heat source, including campfires.
![](/assets/images/loot/recipes/furnace_recipe.png)
<CodeHeader>BP/recipes/magic/magic_ash.json</CodeHeader>
```json
{
"format_version": "1.17.41",
"minecraft:recipe_furnace": {
"description": {
"identifier": "wiki:magic_ash"
},
"tags": ["soul_campfire"],
"input": "wiki:bone_fragments",
"output": {
"item": "wiki:magic_ash",
"count": 4
}
}
}
```
All vanilla heating blocks are supported via tags.
<CodeHeader>#/minecraft:recipe_furnace/</CodeHeader>
```json
"tags": ["furnace", "blast_furnace", "smoker", "campfire", "soul_campfire"]
```
### Heating Transactions
Furnace recipes bind exactly one input [item descriptor](#item-descriptors) to exactly one output item descriptor.
<CodeHeader>#/minecraft:recipe_furnace/</CodeHeader>
```json
"input": "wiki:bone_fragments"
"output": {
"item": "wiki:magic_ash",
"count": 4
}
```
Any count given in the input is ignored. XP returns and fuel sources for a cooking and smelting recipe cannot be altered. The time required to heat an item is set by the used block and is unchangeable.
## Brewing
Brewing recipes are used to transform an item using another item as a catalyst. Two brewing recipe types are available: [brewing mixes](#brewing-mixes), which do not transition data from input to output, and [brewing containers](#brewing-containers), which do.
Only one interface supports brewing recipes:
<CodeHeader>#/minecraft:recipe_brewing_container/</CodeHeader>
```json
"tags": ["brewing_stand"]
```
### Brewing Transactions
Brewing transactions are similar to [heating transactions](#heating-transactions), requiring an input and output, each pointing to a single [item descriptor](#item-descriptors). Brewing recipes, however, also require the `"reagent"` property as a catalyst, which also can only point to a single item descriptor.
<CodeHeader>#/minecraft:recipe_brewing_mix/</CodeHeader>
```json
"input": "wiki:flask",
"reagent": "wiki:jade",
"output": "wiki:insanity_resistance"
```
Provided count values are ignored in these brewing properties. Items are meant to transform one at a time in a brew.
::: warning
If the input item for a brewing recipe has the ability to stack, the _entire_ stack will be consumed in the transformation. There are currently no workarounds to avoid this.
:::
After the brewing time has passed, the catalyst is consumed, and output items directly replace input items.
::: warning
Currently, the stackability of the produced output is bugged, regardless of whether a data value was specified. In particular, the output is incompatible and will not stack with items of the same identifier and data value.
:::
### Brewing Mixes
Brewing mixes are simple brewing recipes theoretically designed to isolate the data value of the input from the data value of the output.
![](/assets/images/loot/recipes/brewing_mix_recipe.png)
<CodeHeader>BP/recipes/brewing/negative/paralysis.json</CodeHeader>
```json
{
"format_version": "1.17.41",
"minecraft:recipe_brewing_mix": {
"description": {
"identifier": "wiki:paralysis_brew"
},
"tags": ["brewing_stand"],
"input": "wiki:amberglass_flask",
"reagent": "wiki:viporfly_poison",
"output": "wiki:paralysis_brew"
}
}
```
::: warning
Unfortunately, assigned data values are broken for brewing mix recipes.
In general, a brewing recipe will never work if a data value is supplied to the input. The only exceptions are if the input is one of the following:
- `minecraft:potion`
- `minecraft:splash_potion`
- `minecraft:lingering_potion`
- [Potion identifier additions](#identifier-additions)
If a data value is specified for a reagent using the `"data"` property format, a brew occurs when any item with the given identifier is placed as a reagent for that recipe, regardless of data value. However, the brew only succeeds if the correct data value is matched. If it’s not, the brew will appear to succeed, but the input will not be transformed into the output; despite the brew failing, the reagent and a percentage of the blaze powder fuel are consumed anyway.
:::
### Brewing Containers
Brewing containers are designed to pass the data value of an input to the transformed output.
![](/assets/images/loot/recipes/brewing_container_recipe.png)
<CodeHeader>BP/recipes/illumination_potion.json</CodeHeader>
```json
{
"format_version": "1.17.41",
"minecraft:recipe_brewing_container": {
"description": {
"identifier": "wiki:illumination_potion"
},
"tags": ["brewing_stand"],
"input": "minecraft:potion",
"reagent": "wiki:radiant_berries",
"output": "wiki:illumination_potion"
}
}
```
Brewing containers are stricter than [brewing mixes](#brewing-mixes) about their inputs. Only the following item types are allowed in a brewing container recipe:
- `minecraft:potion`
- `minecraft:splash_potion`
- `minecraft:lingering_potion`
- [Potion identifier additions](#identifier-additions)
Because the data value is carried downstream from input to output in a brewing container recipe, assigned data values in `"input"` and `"output"` are ignored.
## Overrides
As with all domains in add-ons, the pack order in the behavior pack list affects how Minecraft chooses files to use during gameplay. Higher-listed behavior pack entries take priority over lower-listed ones, including the base vanilla pack.
To override a recipe in a lower-listed pack, the recipe type and identifiers must both match. The override file can be named and located in any way — only the contents matter. Partial overrides are not accepted in recipes; the entire recipe must be redefined.
::: warning
Overrides only work if the recipe type is an _exact_ match. In most cases, a mismatch results in a new recipe created alongside the existing one.
If attempting to construct an override that converts between the two crafting recipe types, an error will be thrown. To circumvent this, first copy the vanilla definition into the pack. Next, set the `"tags"` for that file to `[""]`; this effectively disables the recipe. Finally, set up a new file as the other crafting recipe type, choosing a different identifier to avoid the error.
:::
## Prioritization
After considering [overrides](#overrides), if multiple recipes would apply based on the inputs, the outputs are selected using the following tiebreakers, considered in order:
- Recipes declared in higher-ordered packs in the world behavior packs list
- If for crafting recipes, _lower_-valued [priority properties](#priority)
- If for crafting recipes, [shaped recipes](#shaped-recipes) over [shapeless ones](#shapeless-recipes)
- "Lesser" identifiers, as interpreted by string comparison

703
docs/wiki/loot/trade-tables.md Normal file
View File

@@ -0,0 +1,703 @@
---
title: Trade Tables
category: Documentation
nav_order: 2
tags:
- Stable
- Last updated for Version 1.18.10
mentions:
- Ciosciaa
- SirLich
- TheItsNameless
---
Trade tables represent the fundamental data behind trading item transactions for an entity. Trade tables are not standalone; they must be referenced from an [entity component](https://bedrock.dev/docs/stable/Entities#minecraft%3Aeconomy_trade_table). Using the randomizing properties available to trade tables, trade offers, item counts, and cost calculations may vary across entity instances, even if all would point to the same trade table.
![](/assets/images/loot/trade_tables/trading.png)
Trade tables are not identified or versioned. Like loot tables, trade tables do not support Molang and instead rely on JSON constructs, like range objects and [functions](#functions). Despite being different, trade tables still support comments.
## Integration
Trade tables don't represent a primary add-on system, like blocks or biomes. They aren't registered by being placed in a specific folder; instead, they're referenced (from entities). Trade tables may be placed anywhere within a behavior pack.
::: tip
It's recommended to follow vanilla convention and place all trade tables within the top-level `trading` directory in a behavior pack. From there, any hierarchy can be employed.
:::
<FolderView
:paths="[
'BP/trading/minister.json',
'BP/trading/economy_trades/cleric_trades.json'
]"
/>
The following example is referenced and analyzed throughout the document:
<Spoiler title="Trade Table File Example">
<CodeHeader>BP/trading/minister.json</CodeHeader>
```json
{
"tiers": [
{
"groups": [
{
"num_to_select": 1,
"trades": [
{
"wants": [
{
"item": "wiki:blessing_glyph",
"quantity": {
"min": 2,
"max": 4
},
"price_multiplier": 0.5
},
{
"item": "minecraft:book"
}
],
"gives": [
{
"item": "minecraft:enchanted_book",
"functions": [
{
"function": "enchant_book_for_trading",
"base_cost": 4,
"base_random_cost": 12,
"per_level_cost": 4,
"per_level_random_cost": 8
}
]
}
],
"max_uses": 7,
"trader_exp": 3
},
{
"wants": [
{
"item": "wiki:crystalline_spiritite",
"quantity": 32,
"price_multiplier": 0.125
}
],
"gives": [
{
"item": "wiki:exalted_blade",
"functions": [
{
"function": "enchant_with_levels",
"treasure": true,
"levels": {
"min": 15,
"max": 25
}
}
]
}
],
"max_uses": 2,
"reward_exp": false,
"trader_exp": 8
}
]
}
]
},
{
"total_exp_required": 28,
"trades": [
{
"wants": [
{
"choice": [
{
"item": "wiki:sacred_stones",
"quantity": {
"min": 4,
"max": 6
},
"price_multiplier": 0.5
},
{
"item": "wiki:blessed_beads",
"quantity": {
"min": 16,
"max": 24
},
"price_multiplier": 0.5
}
]
}
],
"gives": [
{
"item": "wiki:aeleon_jewels",
"quantity": {
"min": 4,
"max": 6
}
}
],
"max_uses": 2
}
]
}
]
}
```
</Spoiler>
## Structure
Trade tables are represented as un-versioned, un-namespaced objects.
<CodeHeader>#</CodeHeader>
```json
{
"tiers": [
{
"groups": […]
},
{
"total_exp_required": 28,
"trades": […]
}
]
}
```
Trade tables use [tiers](#tiers) to structure trade organization. Tiers are defined with the required top-level `"tiers"` array property. Tiers appear in order in the trading interface.
### Tiers
Tiers act as an unlockable set of trades and represent the highest level of grouping in a trade table.
<CodeHeader>#/tiers/0</CodeHeader>
```json
{
"groups": […]
}
```
<CodeHeader>#/tiers/1</CodeHeader>
```json
{
"total_exp_required": 28,
"trades": […]
}
```
Each tier must either represent a set of [trades](#trades) (as `"trades"`) or [trade groups](#groups) (as `"groups"`); one of these properties is required. If trades are specified, all such trades will appear for that tier. If instead groups are given, trades from all listed groups will be used for that tier; how each group selects its trades depends on its configuration.
::: tip NOTE
If both `"trades"` and `"groups"` are given in a tier, the trades declaration is ignored in favor of groups.
:::
Within a tier, trades appear in order in the trading interface. If trades are grouped, those groups will appear in their defined order as well, organized by group and then by trade. Trades in one group are not visually differentiable from trades in other groups; only tiers are visually separated and identifiable.
#### Experience Requirement
Tiers are unlocked when the _trader_ meets experience thresholds. Each trader has its own internal lifetime experience that accumulates when trading with players. The amount of experience obtained per trade depends on that trade's [experience reward](#trader-experience). The optional `"total_exp_required"` property specifies how much experience the trader needs in order for that tier to unlock.
<CodeHeader>#/tiers/1/</CodeHeader>
```json
"total_exp_required": 28
```
By default, the amount of experience needed is set to the index of the trade tier. Therefore, the second tier would require the trader to have 1 XP; the third tier would require 2 XP; and so forth. The first tier is always unlocked automatically, [regardless of its set experience threshold](#initial-tier-experience).
#### Tier Unlocking
Tiers are unlocked in order. When a new tier is unlocked, the subsequent tier is additionally checked to see if its threshold is met by the current XP. If it is, it unlocks and checks its subsequent tier, and so forth. Tier unlocking is checked when the rewarded trader experience would suffice for multiple tiers or if a [provided initial experience](#initial-tier-experience) would unlock subsequent tiers when correctly updated by the game.
::: tip NOTE
Since tiers are checked one-at-a-time, if tier unlocking would stop due to the XP requirements of a tier not being met, no subsequent tiers will be checked, even if those later tiers' XP requirements have been met.
:::
##### Initial Tier Experience
Special handling occurs for a non-zero experience threshold in the first tier. If negative, _all_ tiers will be unlocked. If greater than 0, the initial experience of the trader is set to the provided value.
::: warning
When the initial tier's experience threshold is non-zero, a manual update is required for a trader's trades to reflect the actual nature of their trade table. In these cases, performing a trade or closing and re-opening the trading interface will update the interface correctly. Initially, only the first tier will be available even if other tiers should be unlocked.
:::
##### Tier Freezing
Excluding the [initial tier](#initial-tier-experience), it's possible to freeze trades at a tier:
<CodeHeader>Example Tier Freeze</CodeHeader>
```json
"total_exp_required": -1
```
When its prior tier is unlocked, a tier with a negative XP requirement will immediately unlock, [as expected](#tier-unlocking). However, it will be impossible for the player to progress to any subsequent tiers.
### Trade Groups
Trade groups are a way to randomly select which trades an individual trader should use for a tier.
<CodeHeader>#/tiers/0/groups/0</CodeHeader>
```json
{
"num_to_select": 1,
"trades": […]
}
```
The trades from which to select are given with the required `"trades"` array; each entry is a [trade](#trades). A select number of these trades, indicated by the optional `"num_to_select"` property, will be picked for that tier for each trader. If `"num_to_select"` is `0`, all trades will be selected; this is the default.
::: tip NOTE
Trade groups cannot be nested for advanced chance selection.
:::
::: tip
Currently, no random selection count is possible. Nor is weighting by trade, but trades can be duplicated within the array to effectively increase their likelihood of being selected.
:::
### Trades
Trades represent a transaction between a trader and the player.
<CodeHeader>#/tiers/0/trades/1</CodeHeader>
```json
{
"wants": […],
"gives": […],
"max_uses": 2,
"reward_exp": false,
"trader_exp": 8
}
```
Once a trade is picked for a trade slot, it will not fundamentally change. Only the [quantity](#quantity) can be modified in certain situations.
::: tip
Individual trade definitions can affect more than just trades themselves. Notably, an entity can [hold a particular item](https://bedrock.dev/docs/stable/Entities#minecraft%3Abehavior.trade_interest) in response to the player holding an item.
:::
#### Wanted and Given Items
The fundamental transactional units are declared using `"wants"` and `"gives"`; players trade with `"wants"` to receive `"gives"`. Both properties must be arrays and are required.
<CodeHeader>#/tiers/0/trades/1/</CodeHeader>
```json
"wants": […],
"gives": […]
```
A trade can have between 1 and 2 wanted entries and must have exactly 1 given entry. Each entry of either array may be either an [item](#items) or a [choice](#choices).
The trading interface will adapt depending on the number of items wanted. In some circumstances, some trading modifiers, such as [quantity-modifying enchantment functions](#quantity-modifying-enchantment-functions), only affect the first wanted item.
::: tip NOTE
If an object is provided as an entry that contains both item and choice properties, only the choice part is considered; the item parts will be ignored.
:::
#### Trade Limit
A trader can typically only perform an individual trade a set number of times before having to resupply. The numeric `"max_uses"` property configures this number.
<CodeHeader>#/tiers/0/trades/1/</CodeHeader>
```json
"max_uses": 2
```
Trade limits are specific to each trade. Diminishing supply in one trade won't affect another trade, even if both trades have the same wanted and given items. By default, a trader will be able to carry out an individual trade 7 times before needing to resupply.
::: tip NOTE
The act of resupplying is handled by an entity component (`"minecraft:trade_resupply": {}`).
:::
If a value of `0` is given, that trade will be shown in the trading interface but will be impossible to use. If a negative value is given, that trade will never need resupplying; it will be infinitely usable.
#### Player Experience
Experience orbs intended for the _player_ can be disabled for a trade using the optional Boolean `"reward_exp"` property.
<CodeHeader>#/tiers/0/trades/1/</CodeHeader>
```json
"reward_exp": false
```
By default, `"reward_exp"` is true, and the player will be rewarded with some experience for trading. The amount of experience received is not modifiable within a trade table.
#### Trader Experience
Traders may receive experience when the player finalizes a trade. This property is the key to establishing a trade progression system with a trader using [tiers](#tiers).
<CodeHeader>#/tiers/0/trades/1/</CodeHeader>
```json
"trader_exp": 8
```
The amount of experience to reward the _trader_ is given the the optional numeric property `"trader_exp"`. By default, the trader will receive 1 XP.
::: tip
For non-linearly spaced tiers, it's typical for the trader experience to increase in higher tiers. This way, lower-tier trades will have less leveling impact than higher-tier trades.
:::
### Choices
Choices are simple objects for randomly selecting an item to use for a trade. One item is selected with uniform randomness for that trade for each instance of a trader.
<CodeHeader>#/tiers/1/trades/0/wants/0</CodeHeader>
```json
{
"choice": [
{
"item": "wiki:sacred_stones",
…
},
{
"item": "wiki:blessed_beads",
…
}
]
}
```
Choices only contain the required `"choice"` array property. Each entry in the array is an [item](#items). At least one item must be provided.
::: tip NOTE
Choices cannot be nested.
:::
::: tip
There are currently no means of specifying a weight for a given item, but an item may be duplicated within the array to effectively increase its likelihood for being selected.
:::
### Items
Items are the subjects of a trade. Their definitions are shared between wanted and given items, but there are some various implications depending on location used.
<CodeHeader>#/tiers/1/trades/0/wants/0/choice/0</CodeHeader>
```json
{
"item": "wiki:sacred_stones",
"quantity": {
"min": 4,
"max": 6
},
"price_multiplier": 0.5
}
```
<CodeHeader>#/tiers/0/groups/0/trades/1/gives/0</CodeHeader>
```json
{
"item": "wiki:exalted_blade",
"functions": [
{
"function": "enchant_with_levels",
"treasure": true,
"levels": {
"min": 15,
"max": 25
}
}
]
}
```
#### Item Reference
Items are referenced within trades using the required `"item"` string property.
<CodeHeader>#/tiers/1/trades/0/wants/0/choice/0/</CodeHeader>
```json
"item": "wiki:exalted_blade"
```
The item reference must point to the identifier of an item. A data value can be provided in-place to the reference as a suffix:
<CodeHeader>Example Data Assignment</CodeHeader>
```json
"item": "minecraft:log:2"
```
::: tip
Data values can also be set (and much more conveniently randomized) using the `set_data` function.
:::
If no data value is specified for a _wanted_ item, any item with that identifier may be traded. If no data value is specified for a _given_ item, a data value of `0` is implied.
#### Quantity
The optional `"quantity"` property specifies the count of items wanted or given in a trade.
<CodeHeader>#/tiers/1/trades/0/wants/0/choice/0/</CodeHeader>
```json
"quantity": {
"min": 4,
"max": 6
}
```
Quantity can be expressed as either an integer literal or a range object, such as seen above. If expressed as a range, a random value is selected uniformly inclusively within the specified limits. If no quantity is provided, the item count will default to 1.
::: tip NOTE
Quantity is always bounded by the stack size and can only affect a single slot in a trade. It's impossible to, for example, enforce a requirement of 100 planks from a single slot (although this can be done using 2 `"wants"`) or giving 2 un-stackable swords to the player in a single trade.
:::
#### Price Multiplier
The price multiplier dictates how an item's [base quantity](#quantity) is altered due to certain events.
<CodeHeader>#/tiers/1/trades/0/wants/0/choice/0/</CodeHeader>
```json
"price_multiplier": 0.5
```
`"price_multiplier"` is optional and defaults to `0`. Two systems exist that use the price multiplier: a modern and a legacy system. In the modern system, the given price multiplier can only affect the _first wanted item_ in a trade. In the legacy system, any _wanted items_ can be affected.
##### Fluctuation Factors
Trade prices fluctuate as a result of serval factors:
- An increased demand, occurring when trading for the same item across multiple [resupplies](#trade-limit)
- Being recently cured, such as villagers being cured from being zombie villagers
- Being _near_ a trader who was recently cured
- Trading with a player who is affected with "Hero of the Village"
The price multiplier affects all these situations with the exception of a player having "Hero of the Village" when using the new pricing formula, which uses fixed values.
##### Cost Calculations
The price multiplier directly and solely affects cost increases in response to an increased demand for a trade. By default, demand is 0 and cannot decrease past that value. Demand for a trade stacks, increasing when resupplying after that trade [has been exhausted](#trade-limit) and decreasing if no trades occurred between resupplies.
Cost increase due solely to demand is linear, where each increase in demand adds a proportion of the base cost, given by the price multiplier. Assuming the following variables…
| Variable | Meaning |
| -------- | ------------------------------------------------------------------------------------ |
| _c_ | Total cost |
| _p_ | Base cost, including [quantity overrides](#quantity-modifying-enchantment-functions) |
| _m_ | Price multiplier |
| _d_ | Current demand |
<br>
…The following formula can be used to calculate the total cost when no other factors are present:
_c_ = _p_ × (1 + _m_ \* _d_)
::: tip NOTE
Other situations additionally use entity properties for cost calculations and are not provided here.
:::
If the price multiplier is `0`, the quantity will remain constant in most situations (except the "Hero of the Village" modifier using the new pricing formula).
::: tip NOTE
A negative price multiplier is possible but can't affect increasing costs due to [demand](#trade-limit); the multiplier will effectively be capped to `0`. However, negative values do affect prices in response to the trader recently being cured, the trader being nearby another trader who was recently cured, or trading with a player affected with "Hero of the Village" _using the legacy pricing formulas_.
:::
#### Functions
Functions are used to modify the nature of the item. The optional `"functions"` array contains a collection of functions to be applied to the item.
<CodeHeader>#/tiers/0/groups/0/trades/1/gives/0/</CodeHeader>
```json
"functions": [
{
"function": "enchant_with_levels",
"treasure": true,
"levels": {
"min": 15,
"max": 25
}
}
]
```
The functions used by trade tables are shared with loot tables. When used ([where usable](#unusable-wanted-item-functions)) in a wanted item declaration, they act to restrict the nature of the wanted item. Such function restrictions can only affect the first wanted item.
##### Generally Unusable Functions
In general, functions behave well for trading; however, the following do not work anywhere in trade tables:
- `set_count`
- `furnace_smelt`
- `looting_enchant`
- `trader_material_type`
::: tip NOTE
`set_count`'s functionality is replaced by the [quantity property](#quantity).
`trader_material_type`, seen only in a single vanilla trade table, would theoretically set the data value of the item based on the mark variant of the entity, but this doesn't seem to be usable in any custom way.
:::
##### Unusable Wanted Item Functions
In general, using functions to specify item attributes for a wanted item will require the offered item to conform to those attributes. However, the following functions do not enforce a strict match and are therefore useless on wanted items:
- `set_name`
- `set_lore`
- `set_damage`
- `set_book_contents`
- `random_dye`
- `fill_container`
##### Quantity-Modifying Enchantment Functions
2 functions actually set the quantity for the first _wanted item_ if being used as _given items_, potentially overriding any provided [quantity](#quantity) for that first wanted item:
- `enchant_with_levels`
- `enchant_book_for_trading`
::: tip NOTE
Despite overriding the quantity, all [modified trade prices](#fluctuation-factors) adapt correctly. These functions cannot affect the quantity of a second wanted item, even when using the legacy cost formulas. If these functions are used on a _wanted item_, the quantity is not overridden.
:::
###### Enchant with Levels Function
`enchant_with_levels` randomly enchants an item as through enchanted from an enchantment table.
<CodeHeader>#/tiers/0/groups/0/trades/1/gives/0/functions/0</CodeHeader>
```json
{
"function": "enchant_with_levels",
"treasure": true,
"levels": {
"min": 5,
"max": 25
}
}
```
The cost for the first wanted item is determined by adding this function's chosen level value (capped to `0` if it would be negative) to the original [quantity](#quantity). The level value is computed from the optional `"levels"` property. If a numeric literal is used, that value is the chosen level value. If a range object is used, as above, a random number is rolled inclusively between the provided minimum and maximum. That random number then acts as the chosen level value. In the above example, the first wanted item's cost would be increased by 5 to 25.
###### Enchant Book for Trading Function
`enchant_book_for_trading` is intended solely for trading. Its properties combine to determine the first wanted item's cost.
<CodeHeader>#/tiers/0/groups/0/trades/0/gives/0/functions/0</CodeHeader>
```json
{
"function": "enchant_book_for_trading",
"base_cost": 4,
"base_random_cost": 12,
"per_level_cost": 4,
"per_level_random_cost": 8
}
```
This function was only designed to be used on books, rolling for a single enchantment across all possible non-curse enchantments, including treasure enchantments. The function doesn't adapt to the current item. If used on a book, an enchantment will always successfully be applied; if used on something else enchantable, it's possible the item won't be successfully enchanted.
::: tip NOTE
Presumably, when failing, the function rolls for an enchantment not applicable to the item and then fails to apply this irrelevant enchantment, resulting in an unenchanted item. The successfulness of enchanting a non-book is therefore proportional to the number of enchantments applicable to that item.
:::
The total cost is set from a base cost, which is independent of the rolled enchantment, and a per-level cost, which is dependent on the random roll. All cost configuration properties are optional.
The base cost is computed by summing a starting value and a random roll. The starting value is given with `"base_cost"`, which defaults to `2`. The random roll is provided via `"base_random_cost"`, which defaults to `4`. A number will be uniformly randomly selected inclusively between 0 and the `"base_random_cost"` when a trade is generated for a trader.
For each level on the chosen enchantment, the same process occurs as in the base cost calculations: a fixed value is added to a uniformly randomly selected value. In this case, the base per-level cost is given with `"per_level_cost"`, which defaults to `3`, and the random per-level cost is given with `"per_level_random_cost"`, which defaults to `10`. The random per-level roll may be different for each level.
Once the base cost and costs for each level are calculated, they are summed together to form the total cost. Finally, if the chosen enchantment is a treasure enchantment, the cost is then doubled. As usual, this cost cannot be less than 1 or greater than the stack size of that item. This formula holds true regardless of the pricing system being used by the trader.
::: warning
If either random cost property is negative, there seems to be a 50-50 chance that the cost will be either the given [quantity](#quantity) or the maximum stack size for that first wanted item.
:::
::: tip
If the total combined cost would be negative (assuming no negative random cost properties were used), the provided [quantity](#quantity) of the affected wanted item is used instead. The simplest means of guaranteeing this would be:
<CodeHeader>Example Quantity-Based Enchanted Book Cost</CodeHeader>
```json
{
"function": "enchant_book_for_trading",
"base_cost": -1,
"base_random_cost": 0,
"per_level_cost": 0,
"per_level_random_cost": 0
}
```
:::
##### Spawn Egg Trader Binding
The `"set_actor_id"` function is used to set the data value of a spawn egg based on a provided entity identifier, given with `"id"`.
<CodeHeader>Example Spawn Egg Trader Binding</CodeHeader>
```json
{
"function": "set_actor_id"
}
```
In trade tables, if no ID is provided, the trader's entity type will be assigned to the egg.
## Overrides
Because trade tables do not use in-data identifiers, they are overridden simply by replacing a prior trade table with a new one. You can learn more about [asset overrides here](/concepts/overwriting-assets)
Below are the currently used vanilla trade tables for each trader:
|Trader|Path|
|-|-|
|Stone Mason|`BP/trading/economy_trades/stone_mason_trades.json`|
|Farmer|`BP/trading/economy_trades/farmer_trades.json`|
|Fisherman|`BP/trading/economy_trades/fisherman_trades.json`|
|Butcher|`BP/trading/economy_trades/butcher_trades.json`|
|Shepherd|`BP/trading/economy_trades/shepherd_trades.json`|
|Leather Worker|`BP/trading/economy_trades/leather_worker_trades.json`|
|Librarian|`BP/trading/economy_trades/librarian_trades.json`|
|Cartographer|`BP/trading/economy_trades/cartographer_trades.json`|
|Cleric|`BP/trading/economy_trades/cleric_trades.json`|
|Tool Smith|`BP/trading/economy_trades/tool_smith_trades.json`|
|Weapon Smith|`BP/trading/economy_trades/weapon_smith_trades.json`|
|Fletcher|`BP/trading/economy_trades/fletcher_trades.json`|
|Armorer|`BP/trading/economy_trades/armorer_trades.json`|
|Wandering Trader|`BP/trading/economy_trades/wandering_trader_trades.json`|
::: tip NOTE
Additional trade tables exist directly within the `trading` folder, but these are deprecated. Only the tables in the `economy_trades` sub-folder are currently used.
:::
Alternatively, a trader entity definition can be updated to point to a new trade table location.

32
docs/wiki/loot/trading-behavior.md Normal file
View File

@@ -0,0 +1,32 @@
---
title: Trading Behavior
category: General
nav_order: 2
mentions:
- Ciosciaa
- MedicalJewel105
---
Making an entity a trader is accomplished via `minecraft:trade_table` or `minecraft:economy_trade_table` components. Both of them will open a trading UI from the given path, but the economy trades component has some more options referring to some Village and Pillage trading mechanics. Other AI goals you'll need are `minecraft:behavior.trade_with_player`, optionally `minecraft.behavior:trade_interest` (allows the mob to hold/offer an item) and, potentially, `"minecraft:trade_resupply": {}`.
For a simple trading UI, `trade_table` + `trade_with_player` components should do the trick.
1. Add `"minecraft:behavior.trade_with_player": {}` to your entity's components.
2. Copy the following code into a component group of your entity. I'll call mine `"wiki:trader"`;
<CodeHeader>BP/entities/trader.json</CodeHeader>
```json
"minecraft:trade_table": {
"display_name": "Trading Entity", // Text to be displayed.
"table": "trading/trading_entity_trades.json", // Path to the trade table file
"new_screen": true //If set to false, the UI will display as the pre-Village&Pillage one.
}
```
3. Now make sure the component group is added to the entity via an event. It's a good idea to add it in `minecraft:entity_spawned` event, since it triggers on spawn.
If you don't feel confident with events and component groups, make sure you're familiar with entity definition rules/concepts. See the [Intro to Entities](/entities/entity-intro-bp).
:::warning
If you add the component in components, it will cause all kinds of problems, including blank trading UIs for all entities in the world. Because of an issue with the trading AI goals, they must be added in component groups.
:::