Skip to main content

​
Skill and item hotbar

RPGJS provides a persistent, server-authoritative ten-slot hotbar for learned skills, usable regular items, and plugin-provided entry types. Slot contents are synchronized to clients and included in player snapshots. The server remains responsible for validating ownership, consuming SP or items, and applying gameplay effects in standalone and MMORPG modes.

​
Display and hide the built-in hotbar

Open the prebuilt CanvasEngine GUI from a server player hook:
showHotbar() initializes from the current loadout by default. Pass autoInitialize: false when the game needs to seed it later. Hiding the GUI does not clear persistent assignments:
The default keyboard controls are 1 through 0. Holding the left gamepad bumper opens the radial selector; choose with the left stick and release the bumper to use the slot. Games can replace these client bindings through their normal RPGJS control configuration. Bind the actions hotbar1, hotbar2, …, hotbar0; slot state never stores a physical keyboard or gamepad key.

​
Start with items, skills, or both

Pass an ordered list to initialize a specific loadout:
A skill must be learned. An item must be present in the inventory, usable, and consumable. Invalid initial entries are ignored. Calling initializeHotbar() again preserves player choices, so use assignment methods for later changes:
Slots use zero-based indexes. Assigning the same entry elsewhere moves it instead of duplicating it. When no explicit list is supplied, initialization places skills with numeric database keys first, then fills free slots with the remaining learned skills and usable consumable items. If the loadout is still empty, the state remains uninitialized so a later skill or inventory refresh can seed it.

​
Assign from the main menu

The built-in main menu supplies Items and Skills lists. Selecting an eligible entry exposes Assign to hotbar, followed by the slot picker:
The Items screen keeps separate Item, Weapon, and Armor tabs for browsing. Weapons and armors are managed from the Equip screen and never expose Use or Assign to hotbar. Regular items that are non-consumable, absent, or otherwise unusable cannot be assigned through the native item entry type. Register a custom entry type when a game needs tools, emotes, quests, or another authoritative action. The assignment action is also omitted from Items or Skills when that entry type is excluded by allowedEntryTypes.

​
Configure capacity

The persistent state always retains ten slots, while capacity controls how many are currently accessible:
Reducing capacity preserves assignments in locked slots. Call player.refreshHotbar() after game-specific state changes that can affect a custom capacity resolver. Restrict a hotbar to items, skills, or another registered entry type with allowedEntryTypes:
The option also accepts a per-player resolver. Entries excluded by the current configuration stay in the persistent ten-slot state, but are rendered as empty and cannot be assigned or used. Allowing their type again restores them without changing the player’s saved layout. When the last copy of a consumable item is used from the native hotbar, its assignment is cleared automatically. Remaining stacks keep their assignment and update the quantity badge. Action Battle forwards the same configuration and can resolve visibility per player:
With autoOpen, the module re-evaluates enabled on map changes and closes an open hotbar when the resolver returns false.

​
Theme the native component

The built-in component uses CSS custom properties with defaults. Set them from a client stylesheet; replacing the component is not required:

​
Theme variables

The semantic @rpgjs/ui-css hotbar primitives remain available through the --rpg-ui-hotbar-* variables. Component-specific --rpg-hotbar-* values take precedence when both are provided.

​
Replace the visual component

For a different layout or markup, register another GUI using the same prebuilt id. The server APIs and persistent state remain unchanged:
The last component registered for PrebuiltGui.Hotbar wins. See Prebuilt GUI Contracts for the complete data and interaction contract.

​
Use and observe slots

Standard entries can be used directly on the authoritative server:
Battle or targeting modules can inspect player.getHotbar() and route the selected entry through their own authoritative action. @rpgjs/action-battle does this automatically, including cooldowns, projectiles, and targeting. Modules can observe every state transition:
change.action is initialize, assign, clear, select, or refresh. change.state is a detached snapshot safe to inspect or send to another service.

​
Add an entry type

Plugins can register an authoritative type without changing the generic GUI:
The returned function restores the previous definition for that type. Register shared types during module/server setup and call the cleanup function when the owning integration is disposed.