Documentation/content/world/entities/mounts.en.md

title, type, weight

title	type	weight
Mounts	docs	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:

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:

public class MountedComponent implements Component<EntityStore> {
    // Reference to what we're riding
    private Ref<EntityStore> mountRef;
}

MountedByComponent

Attached to entities being ridden:

public class MountedByComponent implements Component<EntityStore> {
    // Reference to the rider
    private Ref<EntityStore> riderRef;
}

BlockMountComponent

Chunk component for block-based seating:

public class BlockMountComponent implements Component<ChunkStore> {
    // Block position and configuration
    // Player currently seated
}

MinecartComponent

Vehicle component for minecarts:

public class MinecartComponent implements Component<EntityStore> {
    // Rail movement configuration
    // Speed, acceleration, etc.
}

Mounting NPCs

Mount Interaction

Players mount NPCs via interaction:

// 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

// Dismount NPC
MountPlugin.dismountNpc(store, mountEntityId);

// Reset player movement settings
MountPlugin.resetOriginalPlayerMovementSettings(playerRef, store);

Block Seating

Seating Interaction

Players sit on blocks via interaction:

// Registered as "Seating" interaction type
Interaction.CODEC.register("Seating",
    SeatingInteraction.class,
    SeatingInteraction.CODEC);

Block Mount API

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:

// 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:

// Registered core component type
NPCPlugin.get().registerCoreComponentType("Mount", BuilderActionMount::new);

{
  "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

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

// Update mount position tracking
MountSystems.TrackerUpdate

// Remove mount tracking on entity removal
MountSystems.TrackerRemove

Death Handling

// Dismount player when they die
NPCMountSystems.DismountOnPlayerDeath

// Dismount when mount dies
NPCMountSystems.DismountOnMountDeath

Movement

// Handle player mount input
MountSystems.HandleMountInput

// Teleport mounted entity with mount
MountSystems.TeleportMountedEntity

Events

Player Disconnect

When player disconnects while mounted:

// Automatically dismount on disconnect
getEventRegistry().register(PlayerDisconnectEvent.class,
    MountPlugin::onPlayerDisconnect);