Merge branch 'main' into dev

Author: okunamayanad

.gitignore

@@ -11,6 +11,9 @@
 /build
 *.tsbuildinfo
 
+# JetBrains IDEs
+.idea/
+
 # misc
 .DS_Store
 *.pem

content/docs/en/guides/ecs/entity-component-system.mdx

@@ -66,4 +66,4 @@ Systems contains the logic for your game (or in this case, a mod).
 
 For example:
 - A "WinConditionSystem" may process every Entity that contains the components "Position" and "Velocity"
-- If an entity reaches the position `(0, 0, 0)`, the system will trigger a "You Won!" message.
+- If an entity reaches the position `(0, 0, 0)`, the system will trigger a "You Won!" message.

content/docs/en/guides/plugin/block-components.mdx

@@ -48,11 +48,57 @@ public class ExampleBlock implements Component<ChunkStore> {
 }
 ```
 
-ExampleBlock stores the behavior for the block. Here, it simply places an Ice Block at `x + 1` relative to its current position when it ticks.
+ExampleBlock is a custom component that stores the behavior and data for your ticking block. Here, it simply places an Ice Block at x + 1 relative to its current position when it ticks.
 
 ---
 
-### 2. ExampleSystem - handles ticking
+### 2. ExampleInitializer - marks blocks as ticking when placed
+
+```java
+public class ExampleInitializer extends RefSystem {
+
+    @Override
+    public void onEntityAdded(@Nonnull Ref ref, @Nonnull AddReason reason, @Nonnull Store store, @Nonnull CommandBuffer commandBuffer) {
+        BlockModule.BlockStateInfo info = (BlockModule.BlockStateInfo) commandBuffer.getComponent(ref, BlockModule.BlockStateInfo.getComponentType());
+        if (info == null) return;
+
+        ExampleBlock generator = (ExampleBlock) commandBuffer.getComponent(ref, ExamplePlugin.get().getExampleBlockComponentType());
+        if (generator != null) {
+            int x = ChunkUtil.xFromBlockInColumn(info.getIndex());
+            int y = ChunkUtil.yFromBlockInColumn(info.getIndex());
+            int z = ChunkUtil.zFromBlockInColumn(info.getIndex());
+
+            WorldChunk worldChunk = (WorldChunk) commandBuffer.getComponent(info.getChunkRef(), WorldChunk.getComponentType());
+            if (worldChunk != null) {
+				worldChunk.setTicking(x, y, z, true);
+            }
+        }
+    }
+
+    @Override
+    public void onEntityRemove(@Nonnull Ref ref, @Nonnull RemoveReason reason, @Nonnull Store store, @Nonnull CommandBuffer commandBuffer) {
+    }
+
+    @Override
+    public Query getQuery() {
+        return Query.and(BlockModule.BlockStateInfo.getComponentType(), ExamplePlugin.get().getExampleBlockComponentType());
+    }
+}
+```
+
+ExampleSystemInitializer is a RefSystem that reacts when block entities with the ExampleBlock component are added or removed. This is crucial for marking blocks as ticking when they're first placed.
+
+**Key Points:**
+
+* Tells the game that this block should tick, allowing `ExampleSystem` to process it.
+
+```java
+worldChunk.setTicking(x, y, z, true);
+```
+
+---
+
+### 3. ExampleSystem - handles ticking
 
 ```java
 public class ExampleSystem extends EntityTickingSystem {
@@ -104,6 +150,9 @@ public class ExampleSystem extends EntityTickingSystem {
 }
 ```
 
+ExampleSystem is an EntityTickingSystem that runs every tick to execute the logic for all ticking blocks with the ExampleBlock component.
+
+**Key Points:**
 
 * **Get the block component**
 
@@ -132,7 +181,7 @@ return BlockTickStrategy.CONTINUE;
 
 ---
 
-### 3. ExamplePlugin - registers components and systems
+### 4. ExamplePlugin - registers components and systems
 
 ```java
 public class ExamplePlugin extends JavaPlugin {
@@ -164,7 +213,9 @@ public class ExamplePlugin extends JavaPlugin {
 }
 ```
 
-### 4. Configure In-Game
+---
+
+### 5. Configure In-Game
 
 ![block-component-1](/assets/guides/block-component-1.png)
 

content/docs/en/guides/plugin/item-interaction.mdx

@@ -1,5 +1,5 @@
 ---
-title: "Custom Item and Interaction"
+title: "Create Custom Item and Interaction"
 description: "Learn how you can create a custom item interactions for your custom items"
 authors:
     - name: "Marcel-TO"
@@ -212,5 +212,110 @@ public class SendMessageInteraction extends SimpleInstantInteraction {
 }
 ```
 
+## Advanced Interaction Features
+Interactions are highly flexible. Since they are nested, you can combine multiple interactions to create complex behaviors. For example, you could have an interaction that first checks certain conditions (like player health or environment) before executing another interaction. Afterwards, you can chain interactions to create a sequence of actions triggered by a single item use. Or you could create interactions that need to be charged over time before they activate.
+
+To get your creative juices flowing, here are some examples of interaction types:
+
+1. **Condition**: Check specific conditions before allowing the interaction to proceed (e.g., only if player crouches):
+```json
+{
+    "Type": "Condition",
+    "Crouching": true, // only allow if player is crouching example
+    "Failed": "Block_Secondary",
+    "Next": {
+        ... // next interaction to run if condition is met
+    }
+}
+```
+
+2. **Charge**: Require the player to hold the interaction for a certain duration before it activates (This behavior for example is called if the player eats food):
+```json
+{
+    "Type": "Charging",
+    "FailsOnDamage": true, // cancel if player takes damage
+    "HorizontalSpeedMultiplier": 0.4, // reduce speed while charging
+    "Next": {
+        "2.5" : {  // interaction after 2.5 seconds of charging
+            ... // interaction to run after charge time
+        },
+    },
+    "Failed": {
+        ... // interaction to run if charging fails
+    }
+}
+```
+
+3. **Serial**: Execute a series of interactions in order, one after the other:
+```json
+{
+    "Type": "Serial",
+    "Interactions": [
+        {
+            ... // first interaction
+        },
+        {
+            ... // second interaction
+        }
+    ]
+}
+```
+
+4. **Replace**: Replace the default behavior of the item (e.g., inherited from parent) with a custom interaction:
+```json
+{
+    "Type": "Replace",
+    "Var": "Item_Default_Interaction",
+    "DefaultValue": {
+        "Interactions": [
+            {
+                ... // default interaction that replaces the original
+            }
+        ]
+    }
+}
+```
+
+5. **Simple**: Simple Interaction that performs a single action, such as sending a message or applying an effect:
+```json
+{
+    "Type": "Simple"
+}
+```
+
+### Advanced Interaction Example
+Here is an example of a more complex interaction that requires the player to crouch and charge for 2.5 seconds before executing the custom action:
+
+```json
+{
+    ... // existing item properties from above
+    "Interactions": {
+        "Secondary": {
+            "Interactions": [
+                {
+                    "Type": "Condition",
+                    "Crouching": true,
+                    "Failed": "Block_Secondary",
+                    "Next": {
+                        "Type": "Charging",
+                        "FailsOnDamage": true,
+                        "HorizontalSpeedMultiplier": 0.5,
+                        "Next": {
+                            "2.5": {
+                                "Type": "my_custom_interaction_id",
+                            }
+                        },
+                        "Failed": {
+                            "Type": "Simple"
+                        }
+                    }
+                }
+            ]
+        }
+    }
+}
+```
+
+
 ## Conclusion
-You have now created a custom item with a unique interaction in your Hytale plugin. You can expand upon this foundation to create more complex items and interactions as needed for your mod.
+You have now created a custom item with a unique interaction in your Hytale plugin. You can expand upon this foundation to create more complex items and interactions as needed for your mod. Keep experimenting, chain interactions, and explore the possibilities to enhance gameplay!

content/docs/en/guides/plugin/meta.json

@@ -1,12 +1,18 @@
 {
   "title": "Server Plugins",
   "pages": [
+    "---Getting Started---",
     "setting-up-env.mdx",
     "build-and-test.mdx",
     "browsing-serverjar.mdx",
+    "logging.mdx",
+    "---Core Concepts---",
     "creating-commands.mdx",
     "creating-events.mdx",
+    "playing-sounds.mdx",
+    "sending-notifications.mdx",
     "chat-formatting.mdx",
+    "---More Topics---",
     "..."
   ],
   "icon": "Terminal"

content/docs/en/guides/plugin/player-stats.mdx

@@ -0,0 +1,114 @@
+---
+title: "Player Stats"
+description: "A simple guide on how to edit player stats."
+authors:
+    - name: "Bird"
+      link: "https://discord.com/users/495709580068651009"
+---
+
+# Overview
+
+This guide shows you how to read and modify player stats like health and stamina using the `EntityStatMap` component.
+
+## Available Stats
+
+Hytale provides several default stats via `DefaultEntityStatTypes`:
+
+- **Health**: `DefaultEntityStatTypes.getHealth()`
+- **Stamina**: `DefaultEntityStatTypes.getStamina()`
+- **Mana**: `DefaultEntityStatTypes.getMana()`
+- **Oxygen**: `DefaultEntityStatTypes.getOxygen()`
+- **Signature Energy**: `DefaultEntityStatTypes.getSignatureEnergy()`
+- **Ammo**: `DefaultEntityStatTypes.getAmmo()`
+
+---
+
+## Example 1: Heal Command
+
+This command restores the player's health to its maximum value.
+
+
+```java
+public class HealCommand extends CommandBase {
+    public HealCommand() {
+        super("heal", "Restores your health to maximum.");
+        this.setPermissionGroup(GameMode.Adventure);
+    }
+
+    @Override
+    protected void executeSync(@Nonnull CommandContext ctx) {
+        // 1. Get the player reference
+        Ref<EntityStore> playerRef = ctx.senderAsPlayerRef();
+        if (playerRef == null) return;
+
+        // 2. Get the store and the world
+        Store<EntityStore> store = playerRef.getStore();
+        EntityStore entityStore = store.getExternalData();
+        World world = entityStore.getWorld();
+
+        // 3. Perform modification on the world thread
+        world.execute(() -> {
+            EntityStatMap statMap = (EntityStatMap) store.getComponent(playerRef, EntityStatMap.getComponentType());
+            if (statMap != null) {
+                statMap.maximizeStatValue(DefaultEntityStatTypes.getHealth());
+                ctx.sendMessage(Message.raw("Your health has been restored!"));
+            }
+        });
+    }
+}
+```
+
+---
+
+## Example 2: Damage Self Command
+
+This command removes a specific amount of health from the player.
+
+```java
+public class DamageSelfCommand extends CommandBase {
+    private final Argument amountArg;
+
+    public DamageSelfCommand() {
+        super("damageself", "Damages yourself by a specific amount.");
+        this.setPermissionGroup(GameMode.Adventure);
+        this.amountArg = this.withRequiredArg("amount", "Amount of damage", ArgTypes.FLOAT);
+    }
+
+    @Override
+    protected void executeSync(@Nonnull CommandContext ctx) {
+		// 1. Get the player reference
+        Ref<EntityStore> playerRef = ctx.senderAsPlayerRef();
+        if (playerRef == null) return;
+
+        // 2. Get command arg
+        Float amount = (Float) this.amountArg.get(ctx);
+        if (amount == null) return;
+
+        // 3. Get the store and the world
+        Store<EntityStore> store = playerRef.getStore();
+        EntityStore entityStore = store.getExternalData();
+        World world = entityStore.getWorld();
+        
+        // 4. Perform modification on the world thread
+        world.execute(() -> {
+            EntityStatMap statMap = (EntityStatMap) store.getComponent(playerRef, EntityStatMap.getComponentType());
+            if (statMap != null) {
+                statMap.subtractStatValue(DefaultEntityStatTypes.getHealth(), amount);
+                ctx.sendMessage(Message.raw("Ouch! You took " + amount + " damage."));
+            }
+        });
+    }
+}
+```
+
+---
+
+## Useful Methods
+
+Common methods available on `EntityStatMap`:
+
+- **Set**: `statMap.setStatValue(statIndex, value)`
+- **Add**: `statMap.addStatValue(statIndex, amount)`
+- **Subtract**: `statMap.subtractStatValue(statIndex, amount)`
+- **Maximize**: `statMap.maximizeStatValue(statIndex)`
+- **Reset**: `statMap.resetStatValue(statIndex)`