mc-assets 0.2.31 → 0.2.33

package/README.MD

@@ -10,6 +10,7 @@ npm i mc-assets
 
 ## Features
 
+- **NEW ITEMS FORMAT SUPPORT!!!** - Get different item models based on conditions (using item, display context, etc)
 - **Automatic Updates** - This library is automatically updated and published to npm.
 - **Fully Typed** - Today is nothing can be done without TypeScript. We ship best type definitions possible.
 - **Early Access** - It always includes the latest pre and rc (release candidate) version.
@@ -19,7 +20,7 @@ npm i mc-assets
 - **Easy to Use Items Textures** - Includes hand-crafted isometric textures for some blocks.
 - **Block Entities Models** - Includes community-crafted models for block entities.
 
-This module was originally designed as standalone package for [https://mcraft.fun](mcraft.fun) (repo) project so it is easier to maintain, but now it became a library that I think can cover any use case where you need to work with minecraft assets. This library means block states, models data and texture contents, it doesn't cover minecraft-data use cases. With the best block model parser you can build your own renderers, editors, etc.
+This module was originally designed as standalone package for [https://mcraft.fun](mcraft.fun) ([repo](https://github.com/zardoy/minecraft-web-client/)) project so it is easier to maintain, but now it became a library that I think can cover any use case where you need to work with minecraft assets. This library means block states, models data and texture contents, it doesn't cover minecraft-data use cases. With the best block model parser you can build your own renderers, editors, etc.
 
 For contributing & building instructions see [building](#building) section.
 
@@ -27,9 +28,9 @@ For contributing & building instructions see [building](#building) section.
 > Tested on Node.js 18 and above.
 
 
-All blockstates + models + all atlas textures for all versions bundled with rsbuild (uncompressed): 4.92 MB.
+All blockstates + models + all atlas textures for all versions bundled with rsbuild (uncompressed): 5.02 MB.
 
-This packages includes versions for: 1.7.10, 1.8, 1.8.1, 1.8.2, 1.8.3, 1.8.4, 1.8.5, 1.8.6, 1.8.7, 1.8.8, 1.8.9, 1.9, 1.9.1, 1.9.2, 1.9.3, 1.9.4, 1.10, 1.10.1, 1.10.2, 1.11, 1.11.1, 1.11.2, 1.12, 1.12.1, 1.12.2, 1.13, 1.13.1, 1.13.2, 1.14, 1.14.1, 1.14.2, 1.14.3, 1.14.4, 1.15, 1.15.1, 1.15.2, 1.16, 1.16.1, 1.16.2, 1.16.3, 1.16.4, 1.16.5, 1.17, 1.17.1, 1.18, 1.18.1, 1.18.2, 1.19, 1.19.1, 1.19.2, 1.19.3, 1.19.4, 1.20, 1.20.1, 1.20.2, 1.20.3, 1.20.4, 1.20.5, 1.20.6, 1.21, 1.21.1, 1.21.2-pre1, 1.21.2-pre3, 1.21.2-pre4, 1.21.2-rc1, 1.21.2-rc2, 1.21.2, 1.21.3, 1.21.4-pre1, 1.21.4-pre3, 1.21.4-rc3, 1.21.4.
+This packages includes versions for: 1.7.10, 1.8, 1.8.1, 1.8.2, 1.8.3, 1.8.4, 1.8.5, 1.8.6, 1.8.7, 1.8.8, 1.8.9, 1.9, 1.9.1, 1.9.2, 1.9.3, 1.9.4, 1.10, 1.10.1, 1.10.2, 1.11, 1.11.1, 1.11.2, 1.12, 1.12.1, 1.12.2, 1.13, 1.13.1, 1.13.2, 1.14, 1.14.1, 1.14.2, 1.14.3, 1.14.4, 1.15, 1.15.1, 1.15.2, 1.16, 1.16.1, 1.16.2, 1.16.3, 1.16.4, 1.16.5, 1.17, 1.17.1, 1.18, 1.18.1, 1.18.2, 1.19, 1.19.1, 1.19.2, 1.19.3, 1.19.4, 1.20, 1.20.1, 1.20.2, 1.20.3, 1.20.4, 1.20.5, 1.20.6, 1.21, 1.21.1, 1.21.2, 1.21.3, 1.21.4.
 
 <details>
 <summary>Included Block Entities (Additional Block Models) (136):</summary>
@@ -181,7 +182,7 @@ This packages includes versions for: 1.7.10, 1.8, 1.8.1, 1.8.2, 1.8.3, 1.8.4, 1.
 
 [Atlas explorer (web demo)](https://zardoy.github.io/mc-assets/).
 
-[External Models Playground](https://mcraft.fun/playground.html)
+[External Models Playground](https://mcraft.fun/playground/) ([Beta Version](https://s.mcraft.fun/playground/)).
 
 ## Usage
 
@@ -315,6 +316,108 @@ const ButtonHighlighted = styled(Button)`
 
 Please, don't use json / image files directly as their format is not stable and can change in the future, use the parsers instead.
 
+### Item Definitions
+
+The library provides a powerful system to handle dynamic item models that change based on various conditions:
+
+```ts
+import { getLoadedItemDefinitionsStore } from 'mc-assets'
+import { getItemDefinition } from 'mc-assets/dist/itemsDefinitions'
+import itemDefinitions from 'mc-assets/dist/itemDefinitions.json'
+
+const store = getLoadedItemDefinitionsStore(itemDefinitions)
+// we have zod schema as well as typescript types for item definitions
+
+// Example 1: Bow animation when pulling
+const bowModel = getItemDefinition(store, {
+    version: 'latest',
+    name: 'bow',
+    properties: { // full autocomplete of supported properties
+        'minecraft:using_item': true,
+        'minecraft:use_duration': 20 // Time in ticks, affects pull-back animation
+    }
+})
+// Returns: { model: 'minecraft:item/bow_pulling_2' } for full pull-back
+
+// Example 2: Bundle with items in inventory
+const bundleModel = getItemDefinition(store, {
+    version: 'latest',
+    name: 'brown_bundle',
+    properties: {
+        'minecraft:display_context': 'gui',
+        'minecraft:bundle/has_selected_item': true
+    }
+})
+// Returns composite model showing bundle with items when in inventory
+
+// Example 3: Clock showing time in different dimensions
+const clockModel = getItemDefinition(store, {
+    version: 'latest',
+    name: 'clock',
+    properties: {
+        'minecraft:time': 0.5,
+        'minecraft:context_dimension': 'minecraft:overworld'
+    }
+})
+// Returns appropriate clock face model based on time
+
+// Example 4: Compass pointing to targets
+const compassModel = getItemDefinition(store, {
+    version: 'latest',
+    name: 'compass',
+    properties: {
+        'minecraft:compass': 16,
+        'minecraft:context_dimension': 'minecraft:overworld',
+        'minecraft:has_component': false // true for lodestone compass
+    }
+})
+// Returns compass model pointing in the right direction
+
+// Example 5: Armor with trims
+const armorModel = getItemDefinition(store, {
+    version: 'latest',
+    name: 'chainmail_boots',
+    properties: {
+        'minecraft:trim_material': 'minecraft:diamond'
+    }
+})
+// Returns: { model: 'minecraft:item/chainmail_boots_diamond_trim' }
+```
+
+The item definition system supports various property types:
+
+- `minecraft:using_item`: Boolean for items being actively used
+- `minecraft:use_duration`: Number of ticks an item has been used
+- `minecraft:display_context`: Where the item is being displayed ('gui', 'ground', 'fixed', etc.)
+- `minecraft:time`: Time value for clock animations
+- `minecraft:context_dimension`: Current dimension affecting item behavior
+- `minecraft:compass`: Direction value for compass
+- `minecraft:has_component`: Special properties like lodestone tracking
+- `minecraft:trim_material`: Material used for armor trims
+- `minecraft:bundle/has_selected_item`: Bundle content state
+- And more...
+
+Each model can include:
+
+- Base model path
+- Tint information
+- Special rendering instructions
+- Watch properties for dynamic updates
+
+Handy method `getItemDefinitionModelResolved` is provided which includes the resolved texture information:
+
+```ts
+import { ItemsRenderer } from 'mc-assets'
+
+const renderer = new ItemsRenderer(/* ... */)
+const resolvedModel = getItemDefinitionModelResolved(store, {
+    version: 'latest',
+    name: 'bow',
+    properties: { /* ... */ }
+}, renderer)
+// Returns texture info ready to render
+```
+
 ## Building
 
 ```bash