Init

content/core-concepts/assets.en.md

@@ -0,0 +1,135 @@
+---
+title: Assets
+type: docs
+weight: 2
+---
+
+Assets in Hytale represent game content like items, blocks, and other resources. Understanding how to work with assets is essential for creating rich plugin experiences.
+
+**Packages:**
+- `com.hypixel.hytale.server.core.asset.type.item.config` (Item)
+- `com.hypixel.hytale.server.core.asset.type.blocktype.config` (BlockType)
+- `com.hypixel.hytale.server.core.inventory` (ItemStack)
+
+## Asset Types
+
+Hytale provides several asset types:
+
+| Asset Type | Description |
+|------------|-------------|
+| `Item` | Represents an item that can be held or stored |
+| `BlockType` | Defines a type of block in the world |
+| `EntityType` | Defines an entity type |
+
+## Working with Items
+
+### Getting an Item
+
+```java
+import com.hypixel.hytale.server.core.asset.type.item.config.Item;
+
+// Get an item by identifier
+Item sword = Item.getAssetMap().getAsset("hytale:iron_sword");
+
+// Check if item exists
+if (sword != null) {
+    // Use the item
+}
+```
+
+### Creating ItemStacks
+
+```java
+import com.hypixel.hytale.server.core.inventory.ItemStack;
+
+// Create an ItemStack with quantity
+ItemStack stack = new ItemStack("hytale:iron_sword", 5);
+
+// Or with just the item ID (quantity defaults to 1)
+ItemStack singleItem = new ItemStack("hytale:iron_sword");
+
+// Access properties
+String itemId = stack.getItemId();
+int quantity = stack.getQuantity();
+```
+
+## Working with Blocks
+
+### Getting a BlockType
+
+```java
+import com.hypixel.hytale.server.core.asset.type.blocktype.config.BlockType;
+
+BlockType stone = BlockType.getAssetMap().getAsset("hytale:stone");
+```
+
+### Block in World
+
+```java
+// Get block at position
+World world = player.getWorld();
+BlockType blockType = world.getBlockType(x, y, z);
+
+// Set block at position
+world.setBlock(x, y, z, "hytale:stone");
+```
+
+## Asset Registry
+
+Register custom assets through your plugin:
+
+```java
+@Override
+public void start() {
+    // Register custom assets
+    getAssetRegistry().register(myCustomAsset);
+}
+```
+
+## Asset Identifiers
+
+Assets are identified by namespaced identifiers:
+
+```
+namespace:path
+
+Examples:
+- hytale:stone
+- myplugin:custom_sword
+- myplugin:blocks/special_block
+```
+
+Your plugin's namespace is typically derived from your manifest's group and name.
+
+## Asset Packs
+
+Plugins can include embedded asset packs. Set `includesAssetPack: true` in your manifest:
+
+```json
+{
+  "name": "MyPlugin",
+  "version": "1.0.0",
+  "group": "com.example",
+  "main": "com.example.myplugin.MyPlugin",
+  "includesAssetPack": true
+}
+```
+
+Asset pack files should be structured in your JAR:
+
+```
+assets/
+└── myplugin/
+    ├── items/
+    │   └── custom_sword.json
+    └── blocks/
+        └── custom_block.json
+```
+
+## Best Practices
+
+{{< callout type="tip" >}}
+- Cache asset references when possible to avoid repeated lookups
+- Always null-check when retrieving assets by identifier
+- Use meaningful namespaced identifiers for your custom assets
+{{< /callout >}}