Mods / Player Status HUD

Tags:
Library HUD UI
Author:
Teotale
Side:
Both
Created:
May 6th at 9:20 AM
Last modified:
May 8th at 12:18 PM
Downloads:
2462
Follow Unfollow 70
Latest release (for Vintage Story 1.22.0 - 1.22.2, potentially outdated):
playerstatushud-v1.0.1-moddb.zip  1-click install

 

Player Status HUD

Developer-focused status HUD library for Vintage Story

Current public release: 1.2.0

Player Status HUD is a reusable HUD layer and API for mods that need player-facing status icons with tooltips and animation semantics. It is designed for integration first: provider-based data model, stable ids, deterministic merge behavior, and production-safe defaults.

Mods using this library

Integrators can treat these mods as live demos of the Player Status HUD API in production gameplay.

Production contract
  • UseMockStatuses=false by default.
  • Mock tooling exists for development, but no placeholder statuses appear unless explicitly enabled/run.
  • Integration mods can ship without exposing test-only states to players.

Why use this library

Stable runtime API Register providers once and stream statuses per frame via IStatusStripProvider.
Deterministic merge Sorted by SortOrder + StableId; duplicate id policy is predictable (last provider wins).
Semantic motion Built-in Neutral / Positive / Negative affect kinds for meaningful animation feedback.
Config-first layout HUD alignment and icon geometry are user-configurable without changing code.

Quick integration

Minimal client-side bootstrap:

var baseSys = api.ModLoader.GetModSystem<PlayerStatusStrip.PlayerStatusStripModSystem>();
IStatusStripHudApi? stripApi = baseSys?.StatusApi;
if (stripApi == null) return;
stripApi.RegisterProvider(myProvider);

Provider contract: append StatusDescriptor entries in Collect(), keep ids stable across frames, unregister on unload.

Configuration surfaces

  • Layout: ModConfig/playerstatusstrip-hudlayout.json — icon size/gap, anchor behavior, row baseline locking, profile settings, draw order.
  • Dev: ModConfig/playerstatusstrip-dev.json — `DevMode`, `UseMockStatuses`.
  • Runtime reload: press F8 for layout reload feedback in chat.

Dev testing scenarios

Scenario ids for regression and UX checks:

meal mining combat weather recovery buzz

Commands: /stripmock list, /stripmock run <id>, /stripmock stop.

What integrators get

  • A stable provider-based API for publishing status icons with tooltips and effect semantics.
  • A configurable HUD surface that players can tune without changing your integration code.
  • A built-in setup wizard for first-run layout selection (corner, inset, size, spacing).
  • Fast in-game verification flow via F8 (layout reload) and Ctrl+F8 (wizard).
  • Production-safe defaults: no mock visuals unless explicitly enabled in dev config.

Documentation index

  • API: PlayerStatusStrip/docs/PLAYER_STATUS_STRIP_API.md
  • Dev guide: PlayerStatusStrip/docs/PLAYER_STATUS_STRIP_DEV_GUIDE.md
  • Integration quick links: start with PLAYER_STATUS_STRIP_API.md, then use .striplayout show + Ctrl+F8 to validate your provider in-game.

Release metadata (version, modid, dependencies) is sourced from modinfo.json.

Built for Teotale

Created for the Teotale Vintage Story server ecosystem. Learn more at www.teotale.com.

If you are building server-side systems or gameplay mods, Player Status HUD gives you a shared status HUD contract for consistent UX.

Mod Version Mod IdentifierFor Game version Downloads Released Changelog Download 1-click mod install*
1.0.1 playerstatusstrip
1.22.0 - 1.22.2
1974 May 8th at 12:18 PM playerstatushud-v1.0.1-moddb.zip 1-click install

 

Player Status HUD - 1.0.1

Release date: 2026-05-08

Public patch release after ModDB baseline 1.0.0.

Highlights

  • Fix: stabilized edge-based HUD positioning across anchors.
  • Fix: corrected center-anchor behavior for scaled status icons.
  • i18n: added ru and uk translations for the layout wizard.
  • UX: negative status update pulse now uses horizontal shake animation.
  • UX: wizard preview now renders mock-only icons.
  • Provider API and status strip integration model remain stable.

Install / Update Notes

  • Replace contents of Mods/playerstatusstrip/ with this package (flat copy).
  • Confirm version 1.0.1 in the in-game mod list.
  • After lang/assets updates, perform a full client restart.

Full history: docs/CHANGELOG.md.

1.0.0 playerstatusstrip
1.22.0 - 1.22.2
160 May 7th at 11:03 AM playerstatushud-v1.0.0-moddb.zip 1-click install

 

Player Status HUD - 1.0.0

Release date: 2026-05-07

This release consolidates all changes delivered after the last published ModDB version 0.1.33.

Highlights (0.1.34 - 1.0.0)

  • Edge-based HUD positioning: migrated strip placement away from implicit dialog margins; inset behavior now matches screen edges across anchors.
  • Bottom-anchor stability: removed size-dependent hidden base; row baseline logic now handles top/center/bottom explicitly.
  • Wizard upgrades: presets for corner/inset/icon size/gap, better center behavior, and CenterBottom removed from active choices (with fallback for old configs).
  • Tooltip placement: bottom-anchored rows prefer rendering tooltip above icons with automatic fallback when needed.
  • Hotkeys finalized: F8 reloads layout, Ctrl+F8 opens/closes wizard; modifier registration fixed.
  • UX polish: wizard label shortened from Inset from corner to Inset.

Install / Update Notes

  • Replace mod contents with this package using flat copy into Mods/playerstatusstrip/.
  • Confirm version 1.0.0 in the in-game mod list.
  • If language files changed, do a full client restart before verification.

Full history: docs/CHANGELOG.md (Player Status HUD section).

0.1.33 playerstatusstrip
1.22.0 - 1.22.2
91 May 6th at 10:45 PM playerstatushud-v0.1.33-moddb.zip 1-click install

 

Player Status HUD - 0.1.33

Release date: 2026-05-08

Release focus: safe chat output for layout commands, tuned defaults for new players (icon size, top-right HUD, vertical offset). Baseline stability remains 0.1.28+ (F8 hotkey guard, LeftWorld / LevelFinalize HUD lifecycle). For .striplayout list and the full 0.1.28–0.1.29 story, use the mod’s 0.1.29 ModDB changelog or docs/changelog-0.1.29.html in the repository.

Changes since 0.1.29 (0.1.30 – 0.1.33)

  • 0.1.30: ShowChatNotification strings for .striplayout, .stripmock, and key list output avoid raw < / > so Vintage Story Vtml no longer breaks the chat UI.
  • 0.1.31: default StatusIconSize 46 px for new playerstatusstrip-hudlayout.json (0 still means auto if set explicitly).
  • 0.1.32: default DialogArea RightTop for new configs.
  • 0.1.33: default DialogOffsetY 8 (matches curated top-right layout with SlowTox Visualized 1.1.7 defaults).

Layout chat (reminder)

Client chat: .striplayout / /striplayout — help, list, show, get [key], set [key] [value], reload. Persists playerstatusstrip-hudlayout.json.

  • .striplayout list
  • .striplayout get StatusIconSize
  • /striplayout set StatusStripOffsetX 6

Compatibility

Game version: as declared in mod metadata.
Dependency: game: *

Install / Update Notes

  • Replace existing mod folder contents with this package (flat copy into Mods/playerstatusstrip/).
  • Confirm version 0.1.33 in the mod list; pair with SlowTox Visualized 1.1.7 if you use that provider.

Markdown: docs/CHANGELOG.md (Player Status HUD section).

0.1.29 playerstatusstrip
1.22.0 - 1.22.2
32 May 6th at 9:37 PM playerstatushud-v0.1.29-moddb.zip 1-click install

 

Player Status HUD - 0.1.29

Release date: 2026-05-08

Cumulative release: includes everything planned for 0.1.28 (stability after main-menu cycle, F8 hotkey guard, HUD lifecycle) plus 0.1.29 (.striplayout list). Safe to publish as a single ModDB package if you skipped 0.1.28.

Highlights

  • Hotkey F8 (from 0.1.28): RegisterHotKeyFirst runs only if playerstatusstrip_reloadlayout is not already in Input.HotKeys — prevents StartClientSide from crashing on the second world session.
  • HUD lifecycle (from 0.1.28): strip element is disposed on LeftWorld and recreated or reopened on LevelFinalize so the overlay matches a fresh game session.
  • Layout chat (0.1.25+): server boot creates playerstatusstrip-dev.json; client .striplayout / /striplayout can get/set/reload and persist playerstatusstrip-hudlayout.json.
  • .striplayout list (0.1.29): prints every scalar key supported by get/set with a short explanation (several chat lines). Nested NeutralAnim / PositiveAnim / NegativeAnim remain JSON-only; the command says so at the end.
  • help text and startup log mention list.

Fixes (0.1.28 baseline)

  • Fixed duplicate hotkey exception after return-to-menu → re-enter world (mod system no longer fails to start).
  • Fixed empty status strip until full client restart when HUD state was stale across sessions.

Example (layout chat)

In-game chat (client):

  • .striplayout list
  • .striplayout get StatusStripOffsetX
  • /striplayout set StatusIconGapPx 6

Compatibility

Game version: as declared in mod metadata.
Dependency: game: *

Install / Update Notes

  • Replace existing mod folder contents with this package (flat copy into Mods/playerstatusstrip/).
  • Confirm version 0.1.29 in the mod list; pair with SlowTox Visualized 1.1.4 if you use that provider.

If anything still fails after update, check client-main.log for Failed to start system PlayerStatusStrip or duplicate hotkey errors. Markdown: docs/CHANGELOG.md (Player Status HUD section).

0.1.25 playerstatusstrip
1.22.0 - 1.22.2
22 May 6th at 9:00 PM playerstatushud-v0.1.25-moddb.zip 1-click install

 

Player Status HUD - 0.1.25

Release date: 2026-05-06

Usability update for server operators and testers: default server config is now generated on startup, and HUD layout can be changed from in-game chat commands without manual JSON edits.

Highlights

  • Dedicated server now creates playerstatusstrip-dev.json during startup.
  • Added chat command group .striplayout//striplayout for live layout edits.
  • HUD layout updates are persisted to playerstatusstrip-hudlayout.json and reloaded immediately.

Added / Improved

  • New layout chat subcommands: help, show, get <key>, set <key> <value>, reload.
  • Runtime parser supports common config field types: string, bool, int, float, and double.
  • README updated with operator-facing layout command examples.

Example commands

Type in chat (client). Slash and dot prefixes both work:

  • .striplayout set StatusStripOffsetX 12 — shift strip horizontally; saves to playerstatusstrip-hudlayout.json and reloads HUD.
  • /striplayout get DialogArea — print current value of a layout field.
  • .striplayout show — short summary of the active layout (offsets, anchor, gap, etc.).

Fixes

  • Resolved missing config bootstrap on dedicated server installs.
  • Reduced config edit friction by removing mandatory out-of-game file edits for common layout tuning.
  • Improved feedback loop: chat command updates now trigger immediate HUD layout reload.

Compatibility

Game version: as declared in mod metadata.
Dependency: game: *

Install / Update Notes

  • Replace existing mod files with the latest release package contents.
  • Restart the client/server and verify version 0.1.25 in the in-game mod list.

This release focuses on operational convenience for multiplayer setups and faster in-game HUD iteration.

0.1.24 playerstatusstrip
1.22.0 - 1.22.2
175 May 6th at 9:28 AM playerstatushud-v0.1.24-moddb.zip 1-click install

 

Player Status HUD - 0.1.24

Release date: 2026-05-06

Finalization release: production-safe defaults for mock tooling, expanded modder docs, and release-facing documentation assets.

Highlights

  • Mock placeholders are disabled by default for production safety.
  • API and developer guides were expanded for third-party integration.
  • ModDB release materials were added and normalized to template-based docs.

Added / Improved

  • Added clear dev-config guidance in code and runtime logs for mock behavior.
  • Expanded PLAYER_STATUS_STRIP_API.md with integration patterns and scenario overview.
  • Added PLAYER_STATUS_STRIP_DEV_GUIDE.md with test/release checklist.

Fixes

  • Removed hardcoded version/package strings from landing and README docs.
  • Switched ModDB notes to reusable template format to avoid per-release doc drift.
  • Aligned release documentation with mod metadata as single source of truth.

Compatibility

Game version: as declared in mod metadata.
Dependency: game: *

Install / Update Notes

  • Replace existing mod files with the latest release package contents.
  • Restart the client and verify version 0.1.24 in the in-game mod list.

Thanks for testing and feedback - this release focuses on developer usability and release hygiene.

20 Comments (oldest first | newest first) (threaded | flat)

ChimMAG, May 29th at 11:43 AM

An updated and comprehensive Russian translation.

Stason4ikRU, May 14th at 1:46 PM

For some reason, the icons do not want to change their position, already 2 players have it.

Teotale , May 14th at 2:06 PM
@Stason4ikRU: For some reason, the icons do not want to change their position, already 2 players have it.

Do you mean that in the Ctrl+F8 settings menu, you're trying to change the corner where the icons are displayed, but the icons always stay in the same place? (For example, the top-right corner)

Outwise, May 13th at 3:35 PM

I know this is intended for other mods to use as a library, but does it have any current functionality by itself? e.g. showing a status icon when hungry, cold, wet, etc?

Willownezz, May 13th at 1:36 AM

This is awesome, I hope it also gets integration with https://mods.vintagestory.at/alchemy 

to get the potions' status 

TheInsanityGod, May 7th at 3:01 PM

Honestly we could really use a library like this but for hud bars (health, hunger, thirst, etc) to deal with allignment and overlapping issues.

TheInsanityGod, May 7th at 4:45 PM
@Elocrypt: Like this? https://mods.vintagestory.at/hudshelf

I was thinking more along the lines of it automatically spacing the bars but thats awesome too, guess now I have even more compatibility stuff to work on :P

Elocrypt, May 7th at 4:59 PM
@TheInsanityGod: I was thinking more along the lines of it automatically spacing the bars but thats awesome too, guess now I have even more compatibility stuff to work on :P

Ah gotcha! HudShelf is more for free dragging individual HUDs. For automatic bar spacing, something like a shared strip container that mods register bars to (and it handles layout/gaps/ordering) would be ideal. I could look at adding a bar-strip mode to HudShelf if there's interest? 

Teotale , May 7th at 8:55 PM (modified May 7th at 9:08 PM)
@TheInsanityGod: Honestly we could really use a library like this but for hud bars (health, hunger, thirst, etc) to deal with allignment and overlapping issues.

You could try visualizing the player's thirst as status indicators in the HUD bar.

On the one hand, managing thirst will become more difficult, since the player won't see the exact thirst value (for example, 1000/1500).

On the other hand, in real life, you don’t have a clear understanding of how much you want to drink anyway; thirst strikes suddenly.

Example implementation (3 statuses: Mild Thirst, Severe Thirst, Dying of Dehydration)

 

Heebeejeebees, May 7th at 7:12 AM (modified May 7th at 7:13 AM)

I certainly hope people take this mod seriously. There's a lot of potential for third-party authors to produce radically-different UIs with this approach, which could result in more neat-looking interfaces that better-convey player status than the usual bars.

If you're looking to make a bigger splash through general-use mods, OmegaHaxors doesn't seem interested in developing Mortal Damage anymore from what I've seen, and his mod has a lot of outdated pre-revive stuff in it. A reprisal that still provides the bare essential code for delayed health state which is designed from the bottom-up for 1.21+ would be very nice.

Because… y'know it isn't very fair to be attacked by a bear, and have death be near-instant when in-reality, that isn't a thing which happens instantly — the dying process takes a little while, at-least, and being able to use poultice for saving oneself from imminent death feels hella-nice.

Consider it. Not only would that be a fun mod to include for Teotale, it'd be a boon for everybody who thinks health should be a gradual thing in either direction.

Teotale , May 7th at 1:46 PM
@Heebeejeebees: I certainly hope people take this mod seriously. There's a lot of potential for third-party authors to produce radically-different UIs with this approach, which could result in more neat-looking interfaces that better-convey player status than the usual b

I agree - it’s fair when heavy damage isn’t dealt instantly, but instead is dealt gradually and quickly depletes your health, while giving you a brief window of a couple of seconds to react and use health regeneration methods to avoid fatal damage

Heebeejeebees, May 7th at 3:51 PM (modified May 8th at 2:55 AM)
@Teotale: I agree - it’s fair when heavy damage isn’t dealt instantly, but instead is dealt gradually and quickly depletes your health, while giving you a brief window of a couple of seconds to react and use health regeneration methods to avoid fatal damage

I did forget to mention; this could be another, smaller example mod of how vanilla mechanics could incorporate into Player Status HUD. So it would not only act as a reprisal for argiably one of Vintage Story's most significant QoL mods, it would also be a concrete example of how new integrations could be added into this mod. Though, because it'd also be a vanilla integration, you'd reckon with having to include basic statuses for health, satiety, oxygen and temperature for this mod before you incorporate statuses for things like bleeding and healing as part of a separate delayed health mod I'm suggesting, which arguably should be a separate mod for people who want the vanilla bars, but the icon status to represent ongoing health effect state.

Perhaps, delayed satiety could be incorporated into this too, so eating doesn't immediately give you the satiation boost, but you instead eat to counter depleting satiety with a temporary boon which could be further incorporated into existing obesity mods, if they exist to represent eating too much. But that needs to be a separate integration, otherwise you'd be dealing with scope creep just to make everything in the game more gradual.

Teotale , May 6th at 1:44 PM

I'll be adding a video or GIF to the mod page soon, showing some test scenarios. Things like: meal, mining, combat, weather, recovery, buzz

El_Neuman, May 6th at 11:13 AM

Amazing icons, love it!)

Teotale , May 6th at 2:04 PM
@El_Neuman: Amazing icons, love it!)

They're just placeholder icons for test scenarios 😅
For the first release of the mod, I decided not to include any pre-made status presets, in the hope that modders would “tailor” the status visuals to fit the atmosphere of their own mods

Teotale , May 6th at 9:29 AM

I'll be porting my mod https://mods.vintagestory.at/slowtoxvisualizer to this library soon