mc-assets 0.2.31 → 0.2.32

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.
@@ -27,64 +28,14 @@ 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>
 
 - ✅ item_frame
-- ✅ sign
-- ✅ wall_sign
-- ✅ acacia_sign
-- ✅ acacia_wall_sign
-- ✅ birch_sign
-- ✅ birch_wall_sign
-- ✅ dark_oak_sign
-- ✅ dark_oak_wall_sign
-- ✅ jungle_sign
-- ✅ jungle_wall_sign
-- ✅ oak_sign
-- ✅ oak_wall_sign
-- ✅ spruce_sign
-- ✅ spruce_wall_sign
-- ✅ crimson_sign
-- ✅ crimson_wall_sign
-- ✅ warped_sign
-- ✅ warped_wall_sign
-- ✅ glow_item_frame
-- ✅ mangrove_sign
-- ✅ mangrove_wall_sign
-- ✅ decorated_pot
-- ✅ acacia_hanging_sign
-- ✅ acacia_wall_hanging_sign
-- ✅ bamboo_hanging_sign
-- ✅ bamboo_sign
-- ✅ bamboo_wall_hanging_sign
-- ✅ bamboo_wall_sign
-- ✅ birch_hanging_sign
-- ✅ birch_wall_hanging_sign
-- ✅ cherry_hanging_sign
-- ✅ cherry_sign
-- ✅ cherry_wall_hanging_sign
-- ✅ cherry_wall_sign
-- ✅ crimson_hanging_sign
-- ✅ crimson_wall_hanging_sign
-- ✅ dark_oak_hanging_sign
-- ✅ dark_oak_wall_hanging_sign
-- ✅ jungle_hanging_sign
-- ✅ jungle_wall_hanging_sign
-- ✅ mangrove_hanging_sign
-- ✅ mangrove_wall_hanging_sign
-- ✅ oak_hanging_sign
-- ✅ oak_wall_hanging_sign
-- ✅ pale_oak_hanging_sign
-- ✅ pale_oak_wall_hanging_sign
-- ✅ spruce_hanging_sign
-- ✅ spruce_wall_hanging_sign
-- ✅ warped_hanging_sign
-- ✅ warped_wall_hanging_sign
 - ✅ black_banner
 - ✅ black_bed
 - ✅ black_shulker_box
@@ -136,10 +87,6 @@ This packages includes versions for: 1.7.10, 1.8, 1.8.1, 1.8.2, 1.8.3, 1.8.4, 1.
 - ✅ orange_bed
 - ✅ orange_shulker_box
 - ✅ orange_wall_banner
-- ✅ pale_oak_sign
-- ✅ pale_oak_wall_sign
-- ✅ piglin_head
-- ✅ piglin_wall_head
 - ✅ pink_banner
 - ✅ pink_bed
 - ✅ pink_shulker_box
@@ -155,9 +102,11 @@ This packages includes versions for: 1.7.10, 1.8, 1.8.1, 1.8.2, 1.8.3, 1.8.4, 1.
 - ✅ red_shulker_box
 - ✅ red_wall_banner
 - ✅ shulker_box
+- ✅ sign
 - ✅ skeleton_skull
 - ✅ skeleton_wall_skull
 - ✅ trapped_chest
+- ✅ wall_sign
 - ✅ white_banner
 - ✅ white_bed
 - ✅ white_shulker_box
@@ -170,6 +119,58 @@ This packages includes versions for: 1.7.10, 1.8, 1.8.1, 1.8.2, 1.8.3, 1.8.4, 1.
 - ✅ yellow_wall_banner
 - ✅ zombie_head
 - ✅ zombie_wall_head
+- ✅ acacia_sign
+- ✅ acacia_wall_sign
+- ✅ birch_sign
+- ✅ birch_wall_sign
+- ✅ dark_oak_sign
+- ✅ dark_oak_wall_sign
+- ✅ jungle_sign
+- ✅ jungle_wall_sign
+- ✅ oak_sign
+- ✅ oak_wall_sign
+- ✅ spruce_sign
+- ✅ spruce_wall_sign
+- ✅ crimson_sign
+- ✅ crimson_wall_sign
+- ✅ warped_sign
+- ✅ warped_wall_sign
+- ✅ glow_item_frame
+- ✅ mangrove_sign
+- ✅ mangrove_wall_sign
+- ✅ acacia_hanging_sign
+- ✅ acacia_wall_hanging_sign
+- ✅ bamboo_hanging_sign
+- ✅ bamboo_sign
+- ✅ bamboo_wall_hanging_sign
+- ✅ bamboo_wall_sign
+- ✅ birch_hanging_sign
+- ✅ birch_wall_hanging_sign
+- ✅ crimson_hanging_sign
+- ✅ crimson_wall_hanging_sign
+- ✅ dark_oak_hanging_sign
+- ✅ dark_oak_wall_hanging_sign
+- ✅ jungle_hanging_sign
+- ✅ jungle_wall_hanging_sign
+- ✅ mangrove_hanging_sign
+- ✅ mangrove_wall_hanging_sign
+- ✅ oak_hanging_sign
+- ✅ oak_wall_hanging_sign
+- ✅ piglin_head
+- ✅ piglin_wall_head
+- ✅ spruce_hanging_sign
+- ✅ spruce_wall_hanging_sign
+- ✅ warped_hanging_sign
+- ✅ warped_wall_hanging_sign
+- ✅ cherry_hanging_sign
+- ✅ cherry_sign
+- ✅ cherry_wall_hanging_sign
+- ✅ cherry_wall_sign
+- ✅ decorated_pot
+- ✅ pale_oak_hanging_sign
+- ✅ pale_oak_sign
+- ✅ pale_oak_wall_hanging_sign
+- ✅ pale_oak_wall_sign
 - ❌ end_gateway
 - ❌ end_portal
 - ❌ structure_void
@@ -315,6 +316,106 @@ 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