Init

content/world/entities/mounts.en.md

@@ -0,0 +1,291 @@
+---
+title: Mounts
+type: docs
+weight: 11
+---
+
+The mount system allows entities to ride other entities or sit on blocks.
+
+**Package:** `com.hypixel.hytale.builtin.mounts`
+
+## Overview
+
+The mount system supports:
+- Riding NPC entities
+- Sitting on block-based seats
+- Minecart vehicle mechanics
+- Mount-specific movement controls
+
+## Architecture
+
+```
+Mount System
+├── Components
+│   ├── NPCMountComponent - Mount NPC configuration
+│   ├── MountedComponent - "I am riding something"
+│   ├── MountedByComponent - "Something rides me"
+│   ├── BlockMountComponent - Block seat
+│   └── MinecartComponent - Minecart vehicle
+├── Systems
+│   ├── MountSystems - Core mount logic
+│   └── NPCMountSystems - NPC-specific logic
+├── Interactions
+│   ├── MountInteraction - Mount NPC
+│   ├── SeatingInteraction - Sit on block
+│   └── SpawnMinecartInteraction - Create minecart
+└── Commands
+    ├── MountCommand - Force mount
+    ├── MountCheckCommand - Check status
+    └── DismountCommand - Force dismount
+```
+
+## Components
+
+### NPCMountComponent
+
+Attached to NPCs that can be mounted:
+
+```java
+public class NPCMountComponent implements Component<EntityStore> {
+    // Player currently riding (if any)
+    private PlayerRef ownerPlayerRef;
+
+    // Original NPC role before mounting
+    private int originalRoleIndex;
+
+    // Mount configuration
+    // Movement speeds, abilities, etc.
+}
+```
+
+### MountedComponent
+
+Attached to entities that are riding something:
+
+```java
+public class MountedComponent implements Component<EntityStore> {
+    // Reference to what we're riding
+    private Ref<EntityStore> mountRef;
+}
+```
+
+### MountedByComponent
+
+Attached to entities being ridden:
+
+```java
+public class MountedByComponent implements Component<EntityStore> {
+    // Reference to the rider
+    private Ref<EntityStore> riderRef;
+}
+```
+
+### BlockMountComponent
+
+Chunk component for block-based seating:
+
+```java
+public class BlockMountComponent implements Component<ChunkStore> {
+    // Block position and configuration
+    // Player currently seated
+}
+```
+
+### MinecartComponent
+
+Vehicle component for minecarts:
+
+```java
+public class MinecartComponent implements Component<EntityStore> {
+    // Rail movement configuration
+    // Speed, acceleration, etc.
+}
+```
+
+## Mounting NPCs
+
+### Mount Interaction
+
+Players mount NPCs via interaction:
+
+```java
+// Registered as "Mount" interaction type
+Interaction.CODEC.register("Mount",
+    MountInteraction.class,
+    MountInteraction.CODEC);
+```
+
+### Mounting Process
+
+1. Player interacts with mountable NPC
+2. `NPCMountComponent` is added/configured
+3. `MountedComponent` added to player
+4. `MountedByComponent` added to NPC
+5. NPC role changes to "mounted" behavior
+6. Player movement settings updated
+
+### Dismounting
+
+Dismounting can happen:
+- Player manually dismounts
+- Player disconnects
+- Mount or player dies
+- Command forces dismount
+
+```java
+// Dismount NPC
+MountPlugin.dismountNpc(store, mountEntityId);
+
+// Reset player movement settings
+MountPlugin.resetOriginalPlayerMovementSettings(playerRef, store);
+```
+
+## Block Seating
+
+### Seating Interaction
+
+Players sit on blocks via interaction:
+
+```java
+// Registered as "Seating" interaction type
+Interaction.CODEC.register("Seating",
+    SeatingInteraction.class,
+    SeatingInteraction.CODEC);
+```
+
+### Block Mount API
+
+```java
+BlockMountAPI api = BlockMountAPI.get();
+
+// Check if block is a seat
+boolean isSeat = api.isSeat(world, blockPos);
+
+// Get seated player
+PlayerRef seated = api.getSeatedPlayer(world, blockPos);
+```
+
+## Minecarts
+
+### Spawn Minecart Interaction
+
+Create minecarts via interaction:
+
+```java
+// Registered as "SpawnMinecart" interaction type
+Interaction.CODEC.register("SpawnMinecart",
+    SpawnMinecartInteraction.class,
+    SpawnMinecartInteraction.CODEC);
+```
+
+### Minecart Behavior
+
+- Follows rail tracks
+- Configurable speed and acceleration
+- Can carry players and items
+- Collision with other minecarts
+
+## NPC Core Component
+
+NPCs can use mount actions:
+
+```java
+// Registered core component type
+NPCPlugin.get().registerCoreComponentType("Mount", BuilderActionMount::new);
+```
+
+```json
+{
+  "Type": "Mount",
+  "MountTarget": "player",
+  "Duration": 10.0
+}
+```
+
+## Commands
+
+### /mount
+
+Force mount a player on an NPC:
+
+```
+/mount <player> <npc_selector>
+```
+
+### /mountcheck
+
+Check mount status:
+
+```
+/mountcheck <player>
+```
+
+### /dismount
+
+Force dismount a player:
+
+```
+/dismount <player>
+```
+
+## Plugin Access
+
+```java
+MountPlugin mounts = MountPlugin.getInstance();
+
+// Component types
+ComponentType<EntityStore, NPCMountComponent> npcMountType =
+    mounts.getMountComponentType();
+ComponentType<EntityStore, MountedComponent> mountedType =
+    mounts.getMountedComponentType();
+ComponentType<EntityStore, MountedByComponent> mountedByType =
+    mounts.getMountedByComponentType();
+ComponentType<EntityStore, MinecartComponent> minecartType =
+    mounts.getMinecartComponentType();
+ComponentType<ChunkStore, BlockMountComponent> blockMountType =
+    mounts.getBlockMountComponentType();
+```
+
+## Systems
+
+### Mount Tracking
+
+```java
+// Update mount position tracking
+MountSystems.TrackerUpdate
+
+// Remove mount tracking on entity removal
+MountSystems.TrackerRemove
+```
+
+### Death Handling
+
+```java
+// Dismount player when they die
+NPCMountSystems.DismountOnPlayerDeath
+
+// Dismount when mount dies
+NPCMountSystems.DismountOnMountDeath
+```
+
+### Movement
+
+```java
+// Handle player mount input
+MountSystems.HandleMountInput
+
+// Teleport mounted entity with mount
+MountSystems.TeleportMountedEntity
+```
+
+## Events
+
+### Player Disconnect
+
+When player disconnects while mounted:
+
+```java
+// Automatically dismount on disconnect
+getEventRegistry().register(PlayerDisconnectEvent.class,
+    MountPlugin::onPlayerDisconnect);
+```