# Hytale Player Stats > Documents Hytale's player/entity stat system for reading and modifying stats like health, stamina, mana, oxygen, signature energy, and ammo using EntityStatMap and DefaultEntityStatTypes. Use when healing players, dealing damage, modifying stamina/mana, setting stat values, creating stat-related commands, or working with entity stats. Triggers - player stats, health, stamina, mana, oxygen, ammo, signature energy, EntityStatMap, DefaultEntityStatTypes, stat value, heal, damage, maximizeStatValue, subtractStatValue, addStatValue, setStatValue, resetStatValue, entity stats. - Skill: `jburlison/hytale-player-stats` (Agent Skill) - Install (CLI): `npx skillmds@latest add jburlison/hytale-player-stats` - Raw SKILL.md: https://api.skillmd.com/api/skills/jburlison/hytale-player-stats/raw - Safety review: pending - Works with: Claude Code, Claude.ai, OpenAI Codex - Category: Coding & Dev Tools - Author: JBurlison (https://skillmd.com/u/jburlison) - Updated: 2026-09-17 - Page: https://skillmd.com/skills/jburlison/hytale-player-stats --- # Hytale Player Stats Use this skill when reading or modifying player/entity stats (health, stamina, mana, etc.) in Hytale plugins. Stats are managed through the `EntityStatMap` component and accessed via `DefaultEntityStatTypes`. > **Source:** > > **Note:** Current server packages place `EntityStatMap` under `server.core.modules.entitystats` and ECS handles under `com.hypixel.hytale.component.*`. --- ## Quick Reference | Task | Code | |------|------| | Get stat map component | `store.getComponent(playerRef, EntityStatMap.getComponentType())` | | Set a stat value | `statMap.setStatValue(statIndex, value)` | | Add to a stat | `statMap.addStatValue(statIndex, amount)` | | Subtract from a stat | `statMap.subtractStatValue(statIndex, amount)` | | Maximize a stat (full restore) | `statMap.maximizeStatValue(statIndex)` | | Reset a stat | `statMap.resetStatValue(statIndex)` | --- ## Available Stats Hytale provides default stats via `DefaultEntityStatTypes`: | Stat | Accessor | |------|----------| | Health | `DefaultEntityStatTypes.getHealth()` | | Stamina | `DefaultEntityStatTypes.getStamina()` | | Mana | `DefaultEntityStatTypes.getMana()` | | Oxygen | `DefaultEntityStatTypes.getOxygen()` | | Signature Energy | `DefaultEntityStatTypes.getSignatureEnergy()` | | Ammo | `DefaultEntityStatTypes.getAmmo()` | --- ## Key Concepts ### EntityStatMap `EntityStatMap` is an ECS component that holds all stat values for an entity. Retrieve it from the store: ```java EntityStatMap statMap = (EntityStatMap) store.getComponent(playerRef, EntityStatMap.getComponentType()); ``` ### World Thread Safety All stat modifications **must** be performed on the world thread using `world.execute(() -> { ... })` to ensure thread safety. ### Stat Indices Each stat type (e.g., `DefaultEntityStatTypes.getHealth()`) returns a stat index used by `EntityStatMap` methods. Pass these indices to set/add/subtract/maximize/reset operations. --- ## Required Imports ```java import com.hypixel.hytale.component.Ref; import com.hypixel.hytale.component.Store; import com.hypixel.hytale.server.core.Message; import com.hypixel.hytale.server.core.modules.entitystats.EntityStatMap; import com.hypixel.hytale.server.core.modules.entitystats.asset.DefaultEntityStatTypes; import com.hypixel.hytale.server.core.universe.world.World; import com.hypixel.hytale.server.core.universe.world.storage.EntityStore; ``` --- ## EntityStatMap Methods | Method | Description | |--------|-------------| | `setStatValue(statIndex, value)` | Sets the stat to an exact value | | `addStatValue(statIndex, amount)` | Adds to the current stat value | | `subtractStatValue(statIndex, amount)` | Subtracts from the current stat value | | `maximizeStatValue(statIndex)` | Restores the stat to its maximum value | | `resetStatValue(statIndex)` | Resets the stat to its default value | --- ## Access Pattern The standard pattern for accessing and modifying stats: ```java // 1. Get the player reference Ref playerRef = /* obtain player ref */; // 2. Get the store and world Store store = playerRef.getStore(); World world = store.getExternalData().getWorld(); // 3. Modify on the world thread world.execute(() -> { EntityStatMap statMap = (EntityStatMap) store.getComponent(playerRef, EntityStatMap.getComponentType()); if (statMap != null) { // Perform stat operations here } }); ``` --- ## Example: Heal 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 playerRef = ctx.senderAsPlayerRef(); if (playerRef == null) return; // 2. Get the store and the world Store store = playerRef.getStore(); World world = store.getExternalData().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: Damage Self Command Removes a specified 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 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 store = playerRef.getStore(); World world = store.getExternalData().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.")); } }); } } ``` --- ## Common Patterns ### Restore All Stats ```java world.execute(() -> { EntityStatMap statMap = (EntityStatMap) store.getComponent(playerRef, EntityStatMap.getComponentType()); if (statMap != null) { statMap.maximizeStatValue(DefaultEntityStatTypes.getHealth()); statMap.maximizeStatValue(DefaultEntityStatTypes.getStamina()); statMap.maximizeStatValue(DefaultEntityStatTypes.getMana()); statMap.maximizeStatValue(DefaultEntityStatTypes.getOxygen()); } }); ``` ### Set Stat to Specific Value ```java world.execute(() -> { EntityStatMap statMap = (EntityStatMap) store.getComponent(playerRef, EntityStatMap.getComponentType()); if (statMap != null) { statMap.setStatValue(DefaultEntityStatTypes.getHealth(), 50.0f); } }); ``` ### Add to a Stat (Partial Heal) ```java world.execute(() -> { EntityStatMap statMap = (EntityStatMap) store.getComponent(playerRef, EntityStatMap.getComponentType()); if (statMap != null) { statMap.addStatValue(DefaultEntityStatTypes.getHealth(), 20.0f); } }); ``` --- ## Important Notes - Always null-check `playerRef` and `statMap` before use. - Always wrap stat modifications in `world.execute(() -> { ... })` for thread safety. - `maximizeStatValue` restores to the entity's configured maximum, not a hardcoded value. - These APIs work on any entity with an `EntityStatMap` component, not just players.