minecraft-data 3.9.0 → 3.10.2

package/doc/api.md

@@ -1,364 +1,657 @@
 # API
 
+Import the module:
+
+```js
+const minecraftData = require('minecraft-data')
+
+const mcData = minecraftData('1.19')
+```
+
+or using es6 import syntax:
+
+```js
+import minecraftData from 'minecraft-data'
+
+const mcData = minecraftData('1.19')
+```
+
+All examples reference `minecraftData` as the module, and `mcData` as the version data.
+
 ## Blocks
 
-### minecraft-data.blocks
+### mcData.blocks
+
+Blocks indexed by id
 
-blocks indexed by id
+Example:
 
-### minecraft-data.blocksByName
+```js
+console.log(mcData.blocks[1]) // Object containing information for "Stone"
+```
+
+### mcData.blocksByName
+
+Blocks indexed by name
+
+Example:
+
+```js
+console.log(mcData.blocksByName['stone']) // Object containing information for "Stone"
+```
+
+### mcData.blocksArray
 
-blocks indexed by name
+Array of blocks
 
-### minecraft-data.blocksArray
+### mcData.blocksByStateId
 
-unindexed blocks
+Blocks indexed by state id
 
-### minecraft-data.blocksByStateId
+Example:
+
+```js
+console.log(mcData.blocksByStateId[100]) // Object containing information for "Lava" (as Lava has a state range from 91 to 106)
+```
 
-blocks indexed by state id
+### mcData.blockStates
 
-### minecraft-data.blockCollisionShapes
+**_Bedrock edition only_**
 
-block collision shapes
+Array of block states
+
+Example:
+
+```js
+console.log(mcData.blockStates[50]) // Object containing block state information for "Warped Door"
+```
+
+### mcData.blockCollisionShapes
+
+Block collision shapes. Contains `blocks`, with each block (indexed by name) containing an array of collision shape ids. Also contains `shapes`, providing all collision shapes information (indexed by id).
+
+Example:
+
+```js
+console.log(mcData.blockCollisionShapes.blocks['oak_stairs']) // Array of collision shape ids for "Oak Stairs"
+// Returns: [ 42, 32, 43, 33, 37, 27, 38, 28 ]
+
+console.log(mcData.blockCollisionShapes.shapes[42]) // Collision information for collision shape id 42
+// Returns: [ [ 0, 0, 0, 1, 0.5, 1 ], [ 0.5, 0.5, 0.5, 1, 1, 1 ] ]
+```
 
 ## Items
 
-### minecraft-data.items
+### mcData.items
 
-items indexed by id
+Items indexed by id
 
-### minecraft-data.itemsByName
+Example:
 
-items indexed by name
+```js
+console.log(mcData.items[772]) // Object containing information for "Wheat"
+```
+
+### mcData.itemsByName
+
+Items indexed by name
 
-### minecraft-data.itemsArray
+Example:
+
+```js
+console.log(mcData.itemsByName['wheat']) // Object containing information for "Wheat"
+```
 
-unindexed items
+### mcData.itemsArray
+
+Array of items
 
 ## Foods
 
-### minecraft-data.foods
+### mcData.foods
 
-foods indexed by id
+Foods indexed by id
 
-### minecraft-data.foodsByName
+Example:
 
-foods indexed by name
+```js
+console.log(mcData.foods[1003]) // Object containing information for "Pumpkin Pie"
+```
 
-### minecraft-data.foodsByFoodPoints
+### mcData.foodsByName
 
-foods indexed by food points
+Foods indexed by name
 
-### minecraft-data.foodsBySaturation
+Example:
 
-foods indexed by saturation
+```js
+console.log(mcData.foodsByName['pumpkin_pie']) // Object containing information for "Pumpkin Pie"
+```
 
-### minecraft-data.foodsArray
+### mcData.foodsArray
 
-unindexed foods
+Array of foods
 
 ## Biomes
 
-### minecraft-data.biomes
+### mcData.biomes
 
-biomes indexed by id
+Biomes indexed by id
 
-### minecraft-data.biomesArray
+Example:
 
-unindexed biomes
+```js
+console.log(mcData.biomes[20]) // Object containing information for "Windswept Gravelly Hills"
+```
+
+### mcData.biomesByName
+
+Biomes indexed by name
+
+Example:
+
+```js
+console.log(mcData.biomesByName['windswept_gravelly_hills']) // Object containing information for "Windswept Gravelly Hills"
+```
 
-### minecraft-data.biomesByName
+### mcData.biomesArray
 
-biomes object indexed by name
+Array of biomes
 
 ## Recipes
 
-### minecraft-data.recipes
+### mcData.recipes
+
+Recipes indexed by the resulting item id
+
+Example:
+
+```js
+console.log(mcData.recipes[31]) // Recipe information for crafting "Dripstone Block"
+
+// Returns:
+// {
+//   inShape: [ [ 1100, 1100 ], [ 1100, 1100 ] ],
+//   result: { count: 1, id: 13 }
+// }
 
-recipes indexed by id
+// Note: 1100 is the block ID of "Pointed Dripstone"
+```
 
 ## Instruments
 
-### minecraft-data.instruments
+### mcData.instruments
+
+Instruments indexed by id
 
-instruments indexed by id
+Example:
+
+```js
+console.log(mcData.instruments[5])
+// Returns: { id: 5, name: 'flute' }
+```
 
-### minecraft-data.instrumentsArray
+### mcData.instrumentsArray
 
-unindexed instruments
+Array of instruments
 
 ## Materials
 
-### minecraft-data.materials
+### mcData.materials
 
-materials indexed by name
+Material types indexed by name
+
+Example:
+
+```js
+console.log(mcData.materials['mineable/axe'])
+// Returns: { '702': 2, '707': 4, '712': 12, '717': 6, '722': 8, '727': 9 }
+```
 
 ## Entities
 
-### minecraft-data.mobs
+### mcData.mobs
 
-mobs indexed by id
+Mobs (passive, neutral, and hostile) indexed by id
 
-### minecraft-data.objects
+Example:
 
-objects indexed by id
+```js
+console.log(mcData.mobs[30]) // Object containing information for "Ghast"
+```
 
-### minecraft-data.entitiesByName
+### mcData.objects
 
-entities indexed by name
+Objects (non-mob entities such as vehicles and projectiles) indexed by id
 
-### minecraft-data.entitiesArray
+Example:
 
-unindexed entities
+```js
+const mcData = MinecraftData('1.8.9')
+
+console.log(mcData.objects[10]) // Object containing information for "Minecart"
+```
+
+### mcData.entities
+
+Entities indexed by id
+
+Example:
+
+```js
+console.log(mcData.entities[25]) // Object containing information for "Evoker"
+```
+
+### mcData.entitiesByName
+
+Entities indexed by name
+
+Example:
+
+```js
+console.log(mcData.entitiesByName['evoker']) // Object containing information for "Evoker"
+```
+
+### mcData.entitiesArray
+
+Array of entities
 
 ## Enchantments
 
-### minecraft-data.enchantments
+### mcData.enchantments
 
-enchantments indexed by id
+Enchantments indexed by id
 
-### minecraft-data.enchantmentsByName
+Example:
 
-enchantments indexed by name
+```js
+console.log(mcData.enchantments[37]) // Object containing information for "Mending"
+```
+
+### mcData.enchantmentsByName
+
+Enchantments indexed by name
 
-### minecraft-data.enchantmentsArray
+Example:
 
-unindexed enchantments
+```js
+console.log(mcData.enchantmentsByName['mending']) // Object containing information for "Mending"
+```
 
-### minecraft-data.defaultSkin
+### mcData.enchantmentsArray
 
-(bedrock edition) Skin geometry and texture data for default player skin
+Array of enchantments
+
+### mcData.defaultSkin
+
+**_Bedrock edition only_**
+
+Skin geometry and texture data for default player skin
 
 ## Protocol
 
-### minecraft-data.protocol
+### mcData.protocol
+
+The Minecraft protocol
+
+### mcData.protocolComments
+
+The Minecraft protocol comments
 
-the minecraft protocol
+### mcData.protocolYaml
 
+**_Bedrock edition only_**
 
-### minecraft-data.protocolComments
+The url to the files of the protocol yaml
 
-the minecraft protocol comments
+## Windows (GUIs)
 
-## Windows
+### mcData.windows
 
-### minecraft-data.windows
+Windows indexed by id
 
-windows indexed by id
+Example:
 
-### minecraft-data.windowsByName
+```js
+console.log(mcData.windows['minecraft:villager']) // Object containing window information for the villager GUI
+```
+
+### mcData.windowsByName
 
-windows indexed by name
+Windows indexed by name
 
-### minecraft-data.windowsArray
+Example:
+
+```js
+console.log(mcData.windowsByName['NPC Trade']) // Object containing window information for the villager GUI
+```
 
-unindexed windows
+### mcData.windowsArray
 
+Array of windows
 
 ## Version
 
-### minecraft-data.version.version
+For version comparison, the other version must be of the same type, and the prefix is always implied
 
-the version number (example : 47)
+### mcData.version.version
 
-### minecraft-data.version.minecraftVersion
+The version number
 
-the minecraft number (example : 1.8.3)
+Example:
 
-### minecraft-data.version.type
+```js
+console.log(mcData.version.version) // 759
+```
+
+### mcData.version.minecraftVersion
 
-the version type, currently 'pc' or 'bedrock'
+The full Minecraft version
 
-### minecraft-data.version.majorVersion
+Example:
 
-the major version (example : 1.8), also the name of the minecraft-data version
+```js
+console.log(mcData.version.minecraftVersion) // 1.19
+```
 
-### minecraft-data.version.dataVersion
+### mcData.version.type
 
-"Data version" for this Minecraft version, used for example when writing chunks to disk
+The version type, either `pc` or `bedrock`
 
-### minecraft-data.version.< (other)
-Returns true if the current version is less than than the `other` version's dataVersion
+Example:
 
-### minecraft-data.version.> (other)
-Returns true if the current version is greater than the `other` version's dataVersion
+```js
+console.log(mcData.version.type) // pc
+```
 
-### minecraft-data.version.== (other)
-Returns true if the current version is equal to the `other` version's dataVersion
+### mcData.version.majorVersion
 
-### minecraft-data.version.>=, minecraft-data.version.<=
+The major Minecraft version
 
-Same as above but also allows equal dataVersion. The other version must be of the same type, the prefix is always implied.
+Example:
 
-Example Usage: 
 ```js
-const mcd = require('minecraft-data')('1.16.4')
-console.log('1.16.4 >= 1.17 ?', mcd.version['>=']('1.17')) // False
+const mcData = MinecraftData('1.16.5')
 
-const mcd = require('minecraft-data')('bedrock_1.17.0')
-console.log('1.17.0 > 1.16.220 ?', mcd.version['>']('1.16.220')) // True
+console.log(mcData.version.majorVersion) // 1.16
+```
+
+### mcData.version.dataVersion
+
+The "data version" for this Minecraft version, used for example when writing chunks to disk
+
+Example:
+
+```js
+console.log(mcData.version.dataVersion) // 3105
+```
+
+### mcData.version.[<](<version>), mcData.isOlderThan(<version>)
+
+Returns `true` if the current version is less than than the other version's `dataVersion`, or else `false`
+
+### mcData.version.[<=](<version>)
+
+Same as above but also checks for an equivalent `dataVersion`
+
+### mcData.version.[==](<version>)
+
+Returns `true` if the current version is equal to the other version's `dataVersion`, or else `false`
+
+### mcData.version.[>](<version>)
+
+Returns `true` if the current version is greater than the other version's `dataVersion`, or else `false`
+
+### mcData.version.[>=](<version>), mcData.isNewerOrEqualTo(<version>)
+
+Same as above but also checks for an equivalent `dataVersion`
+
+Example Usage:
+
+```js
+const mcData = MinecraftData('1.16.4')
+console.log(mcData.version['>=']('1.17')) // Returns false, as 1.16.4 is older than 1.17
+
+const mcData = MinecraftData('bedrock_1.17.0')
+console.log(mcData.version['>']('1.16.220')) // Returns true, as 1.17.0 is newer than 1.16.220
 ```
 
 ## Effects
 
-### minecraft-data.effects
+### mcData.effects
 
-effects indexed by id
+Effects indexed by id
 
-### minecraft-data.effectsByName
+Example:
 
-effects indexed by name
+```js
+console.log(mcData.effects[5]) // Object containing information for "Strength"
+```
 
-### minecraft-data.effectsArray
+### mcData.effectsByName
+
+Effects indexed by name
+
+Example:
+
+```js
+console.log(mcData.effectsByName['strength']) // Object containing information for "Strength"
+```
 
-unindexed effects
+### mcData.effectsArray
+
+Array of effects
 
 ## Attributes
 
-### minecraft-data.attributes
+### mcData.attributes
+
+Attributes indexed by resource name
+
+Example:
+
+```js
+console.log(mcData.attributes['minecraft:generic.movement_speed']) // Object containing information for "minecraft:generic.movement_speed"
+```
+
+### mcData.attributesByName
 
-attributes indexed by resource name (generic.movementSpeed || minecraft:generic.movement_speed)
+Attributes indexed by name
 
-### minecraft-data.attributesByName
+Example:
 
-attributes indexed by minecraft-data name (movementSpeed)
+```js
+console.log(mcData.attributesByName['movementSpeed']) // Object containing information for "minecraft:generic.movement_speed"
+```
 
-### minecraft-data.attributesArray
+### mcData.attributesArray
 
-unindexed attributes
+Array of attributes
 
 ## Particles
 
-### minecraft-data.particles
+### mcData.particles
 
-particles indexed by id
+Particles indexed by id
 
-### minecraft-data.particlesByName
+Example:
+
+```js
+console.log(mcData.particles[12]) // Object containing information for "dripping_water"
+```
 
-particles indexed by name
+### mcData.particlesByName
 
-### minecraft-data.particlesArray
+Particles indexed by name
 
-unindexed particles
+Example:
+
+```js
+console.log(mcData.particlesByName['dripping_water']) // Object containing information for "dripping_water"
+```
+
+### mcData.particlesArray
+
+Array of particles
 
 ## Commands
 
-### minecraft-data.commands 
+### mcData.commands
+
+Commands and parsers
 
-Command tree
+Example:
+
+```js
+const mcData = MinecraftData('1.13')
+
+console.log(mcData.commands)
+// Returns:
+// {
+//   root: {
+//     type: 'root',
+//     name: 'root',
+//     executable: false,
+//     redirects: [],
+//     children: [ ... ]
+//   },
+//   parsers: [ ... ]
+// }
+```
 
 ## Loot
 
-### minecraft-data.entityLoot
+### mcData.entityLoot
+
+Entity loot indexed by entity name
+
+Example:
 
-entity loot indexed by name
+```js
+console.log(mcData.entityLoot['zombie']) // Object containing loot information for "Zombie"
+```
 
-### minecraft-data.entityLootArray
+### mcData.entityLootArray
 
-unindexed entity loot
+Array of entity loot
 
-### minecraft-data.blockLoot
+### mcData.blockLoot
 
-block loot indexed by name
+Block loot indexed by block name
 
-### minecraft-data.blockLootArray
+Example:
 
-unindexed block loot
+```js
+console.log(mcData.blockLoot['diamond_ore']) // Object containing loot information for "Diamond Ore"
+```
 
-## Map icons
+### mcData.blockLootArray
 
-### minecraft-data.mapIcons
+Array of block loot
 
-mapIcons indexed by id
+## Map icons
 
-### minecraft-data.mapIconsByName
+### mcData.mapIcons
 
-mapIcons indexed by name
+Map icons indexed by id
 
-### minecraft-data.mapIconsArray
+Example:
 
-unindexed mapIcons
+```js
+console.log(mcData.mapIcons[20]) // Object containing map icon information for "banner_purple"
+```
 
-## type
+### mcData.mapIconsByName
 
-pe or pc
+Map icons indexed by name
 
-## minecraft-data.language
+Example:
 
-object from language key to string
+```js
+console.log(mcData.mapIconsByName['banner_purple']) // Object containing map icon information for "banner_purple"
+```
 
-## minecraft-data.loginPacket
+### mcData.mapIconsArray
 
-example of login packet
+Array of map icons
 
-## Protocol versions
+### mcData.type
 
-Those are common data and directly available in the `require('minecraft-data')` object.
-No need to specify a version before accessing them. They are indexed by pc and pe.
+The type of the current version, either `pc` or `bedrock`
 
-### minecraft-data.versions
+### minecraftData.language
 
-unindexed minecraft versions
+Object containing `en_US` language conversions
 
-### minecraft-data.versionsByMinecraftVersion
+Example:
 
-minecraft versions indexed by minecraft version (example : 1.8.8)
+```js
+console.log(mcData.language['argument.player.unknown'])
+// Returns: 'That player does not exist'
+```
 
-### minecraft-data.preNettyVersionsByProtocolVersion
+### minecraftData.loginPacket
 
-pre netty minecraft versions indexed by protocol version (example : 47)
+Login packet example
 
-### minecraft-data.postNettyVersionsByProtocolVersion
+### mcData.supportFeature(<feature>)
 
-post netty minecraft versions indexed by protocol version (example : 47)
+This can be used to check if a specific feature is available in the current Minecraft version. This is usually only used for handling version-specific functionality.
 
-### minecraft-data.supportedVersions.pc
+Example:
 
-Array of pc supported versions
+```js
+const mcData = minecraftData('1.18.2')
 
-### minecraft-data.supportedVersions.pe
+console.log(mcData.supportFeature('blockStateId')) // Returns: true
+```
 
-Array of pe supported versions
+## Tints
 
-### minecraft-data.legacy.pc.blocks
+### mcData.tints
 
-Mapping from 1.12 block:metadata to 1.13 block names
+Tints indexed by the tint type (`grass`, `foliage`, `water`, `redstone`, `constant`)
 
-examples 0:0 -> minecraft:air
+## Protocol versions
 
-### minecraft-data.supportFeature(featureName) : Boolean
+These are common data and directly available in the `minecraftData` object.
+No need to specify a version before accessing them.
 
-This can be used to check is a specific feature is available in the current Minecraft version. This is usually only required for handling version-specific functionality.
+### minecraftData.versions
 
-## Schemas
+Array of all Minecraft versions (separated into `pc` (java) and `bedrock`)
 
-### minecraft-data.schemas.biomes
+### minecraftData.versionsByMinecraftVersion
 
-### minecraft-data.schemas.blocks
+All versions indexed by Minecraft version (separated into `pc` (java) and `bedrock`)
 
-### minecraft-data.schemas.blockLoot
+### minecraftData.preNettyVersionsByProtocolVersion
 
-### minecraft-data.schemas.effects
+Pre-netty Minecraft versions indexed by protocol version (separated into `pc` (java) and `bedrock`)
 
-### minecraft-data.schemas.entities
+### minecraftData.postNettyVersionsByProtocolVersion
 
-### minecraft-data.schemas.entityLoot
+Post netty minecraft versions indexed by protocol version (separated into `pc` (java) and `bedrock`)
 
-### minecraft-data.schemas.instruments
+### minecraftData.supportedVersions
 
-### minecraft-data.schemas.items
+Array of supported versions (separated into `pc` (java) and `bedrock`)
 
-### minecraft-data.schemas.materials
+### minecraftData.legacy.pc.blocks
 
-### minecraft-data.schemas.particles
+Mapping from 1.12 block:metadata to 1.13 block names
 
-### minecraft-data.schemas.protocol
+Example:
 
-### minecraft-data.schemas.protocolVersions
+```js
+console.log(mcData.legacy.pc.blocks['171:15']) // Returns: 'minecraft:black_carpet'
+```
+
+## Schemas
 
-### minecraft-data.schemas.recipes
+These are common data and directly available in the `minecraftData` object.
+No need to specify a version before accessing them.
 
-### minecraft-data.schemas.version
+Available schemas:
 
-### minecraft-data.schemas.windows
+`biomes`, `blocks`, `blockLoot`, `effects`, `entities`, `entityLoot`, `instruments`, `items`, `materials`, `particles`, `protocol`, `protocolVersions`, `recipes`, `version`, `windows`