Mounts

Mounts

Mounts are rideable NPC entities that players can summon and ride.

Version: 1.3.0

How It Works

1. Summon: Right-click a Mount Horn item
2. Spawn: Mount NPC spawns instantly near the player (no cast time)
3. Mount: Player is automatically placed on the mount
4. Ride: WASD controls movement, mount position syncs for all players
5. Dismount: Press F to dismount — mount NPC despawns after 500ms

Summoning is instant — there is no cast animation or cast time.

Drop Guard

If a player drops their Mount Horn while riding, the mount is automatically dismissed. This prevents orphaned mount NPCs if the summoning item is lost.

Multiplayer Sync

The mount system uses Hytale’s native setMountEntityId() to link the player to the mount NPC. This ensures:

• Position Sync: Mount position is automatically synced for all players by the engine
• Animation Sync: An ECS ticking system copies movement states to the mount NPC, playing Walk/Run/Idle animations visible to all players
• Dismount Sync: Native NPCMountSystems handles dismount broadcasting

Mount Types

Type	NPC Role	Description
walk	KS_Mount_Walk_Role	Ground mount — walk and run
fly	KS_Mount_Fly_Role	Walk + Fly MotionController (flying is WIP)
swim	KS_Mount_Swim_Role	Swim MotionController (WIP)

Mount Configuration

In the pet type JSON under mountConfig:

{
  "mountConfig": {
    "mountType": "walk",
    "mountYOffset": 1.8,
    "speed": 1.4,
    "baseHealth": 80
  }
}

Field	Description
mountType	"walk" or "fly" — determines which NPC role is used
mountYOffset	How high above the mount the rider sits (in blocks)
speed	Speed multiplier for the mount
baseHealth	Mount NPC health

All Mounts

Uncommon

Mount	Speed	Y-Offset	Health	Entity
Horse	1.4	1.8	80	Horse
Camel	1.3	2.7	100	Camel
Wolf	1.4	1.2	50	Wolf_Black

Rare

Mount	Speed	Y-Offset	Health	Entity
Moose	1.3	2.5	120	Moose_Bull
Bison	1.1	2.2	150	Bison
Polar Bear	1.0	2.0	100	Bear_Polar

Epic

Mount	Speed	Y-Offset	Health	Entity
Cave Rex	1.5	3.5	150	Rex_Cave
Sabertooth	1.6	1.8	100	Tiger_Sabertooth

Legendary

Mount	Speed	Y-Offset	Health	Entity
Dragon	1.8	5.2	200	Dragon_Frost

Mount Horns

Mount Horns are tradeable summoning items:

• Item ID: Configured per mount type (e.g., Mount_Horn_Horse)
• Metadata: BsonDocument with mount instance data
• Right-click: Summon mount instantly or dismount if already riding
• Data Sync: Mount stats are synced back to the horn on dismount

Mount Lifecycle

Event	What Happens
Summon	NPC spawned instantly with Interactable + NPCMountComponent
Mount	MountNPC packet sent, setMountEntityId set, MovementStates.mounting = true
Ride	ECS system syncs animations, engine syncs position
Dismount (F key)	Native system handles player state, entity removed after 500ms
Drop Horn	Auto-dismount triggered, mount NPC cleaned up
Death	MountSystem (DeathSystems.OnDeathSystem) auto-dismounts
Disconnect	onPlayerDisconnect dismounts and cleans up
Server Start	forceRemoveAllKSRoleNpcs() removes leftover mounts
Server Stop	Same cleanup via CountDownLatch on all worlds

Mount Controls

Key	Action
WASD	Move the mount
F	Dismount
Shift	Sprint (if mount supports it)

Mount UI

Access via /kspet mount or /kspet mounts:

• Current Mount section with dismount button
• Available Mounts grid with mount button per slot
• Pagination when more than 3 mounts available

Mount entities are cleaned up on server start/stop. If the server crashes while mounts are active, the NPCs may persist as “world NPCs” until the next clean start.