Hotbar #

• Prerequisites
• Core Principles of the Hotbar
  • Hotbar Structure
    • Container Reference System
    • Binding to Allowed Containers
    • Auto-Unlinking from Nested Items
  • Hotbar Actions
    • Link Item
    • Delink Item
    • Swap Item
  • Alternative Implementations
    • Minecraft-Style Container Hotbar
    • Comparison of Approaches
• How To Guides
  • How to Configure Hotbar Slots
  • How to Add Custom Hotbar Actions
  • How to Implement Container-Based Hotbar
• PREREQUISITES

Core principles of the hotbar #

Hotbar Structure #

The hotbar system provides quick access to frequently used items through keyboard shortcuts. Instead of opening the inventory and finding an item, players can press a number key to instantly use an item assigned to that hotbar slot.

The hotbar is not a container like the inventory system. Instead, it's an array that maintains references to items in containers. Each hotbar slot knows which container an item is in and which slot within that container, allowing it to quickly access and use that item.

Key Concepts:

• Hotbar slots are references to items in containers, not copies
• Items can be linked to a hotbar slot while remaining in their container
• When an item is used from the hotbar, it's actually used from the container
• Hotbar binds to specific containers and updates when those containers change
• Items in restricted containers (nested backpacks, etc.) cannot be hotbar-linked

This reference-based system ensures that item data stays consistent. When you use an item from the hotbar, the actual item in your inventory is consumed, preventing duplication or synchronization issues.

Hotbar vs Container

Understanding the difference is important:

• Container: Physical storage that holds item data
• Hotbar: Quick-access reference system that points to items in containers

Items live in containers. The hotbar just points to them for quick access.

Container Reference System #

The hotbar maintains references to items rather than storing the items themselves.

Reference Structure:

Each hotbar slot contains:

• Container Reference: Which container holds the item
• Slot Index: Which slot in that container

The hotbar does not store item data directly. To get item information (icon, name, quantity, etc.), you use the container reference and slot index to query the actual item from its container.

When a player presses a hotbar key:

• The system checks which item is linked to that hotbar slot
• Gets the container reference
• Gets the slot index within that container
• Accesses the item from the container using GetItemAtSlot or similar function
• Retrieves the item data for display or actions
• Executes the item's default action
• Updates both the container and hotbar display

Update System

The hotbar binds to container update events:

• When any linked container updates (item added, removed, used, moved)
• The container triggers OnInventorySlotUpdated event
• The hotbar receives the event
• Checks if the update affects any hotbar-linked items
• Updates hotbar slot displays accordingly

This ensures the hotbar always shows current item state:

• Correct quantity after using a consumable
• Correct durability after using a tool
• Empty slot if item is removed
• Updated position if item is moved within allowed containers

Why References Instead of Copies?

Using references instead of copying item data:

• Prevents item duplication bugs
• Ensures consistency between inventory and hotbar
• Automatically updates when item state changes
• Saves memory (one item data, multiple references possible)
• Makes multiplayer synchronization simpler

Binding to Allowed Containers #

The hotbar only binds to containers that are designated as “hotbar-allowed.” This prevents issues with items in inaccessible locations being used from the hotbar.

Allowed Container Types

By default, the hotbar binds to:

• Default type containers (main inventory)
• Equipment type containers (equipped items)

The hotbar does NOT bind to:

• Container type containers (backpacks, nested containers)
• Crafting containers
• Other specialized containers

Why Restrict Containers?

Restricting which containers can have hotbar-linked items prevents confusing gameplay:

• Players shouldn't be able to use items from a backpack that's inside another backpack
• Items in crafting queues shouldn't be accessible via hotbar
• Only readily accessible items should have hotbar shortcuts

• Player has a backpack in their main inventory
• Backpack contains a health potion
• Player cannot link that potion to the hotbar
• If they move the potion to main inventory, they can link it

This creates clear expectations: only items in your main accessible inventory can be hotbar-linked.

Configuration

You can customize which container types are allowed:

• In the inventory component or hotbar manager
• Specify the allowed container types
• The hotbar will automatically bind to containers of those types
• Ignore all other containers

Auto-Unlinking from Nested Items #

When an item is moved from an allowed container to a restricted container, it automatically unlinks from the hotbar.

Auto-Unlink Logic:

• Item is linked to hotbar slot 3
• Player moves item from main inventory into a backpack
• System detects item is now in a Container type (not allowed for hotbar)
• Automatically removes the hotbar link
• Hotbar slot 3 becomes empty
• Item's hotbar reference is cleared

Why Auto-Unlink?

This prevents issues like:

• Trying to use an item that's not easily accessible
• Confusion about where items are located
• Accessing items from closed containers
• Gameplay exploits with nested inventory access

User Feedback

When an item auto-unlinks:

• The hotbar slot visually clears
• The item remains in the backpack (just not hotbar-accessible)
• Player can re-link it if they move it back to main inventory

Moving Items and Hotbar References

The system tracks items across containers:

• Item linked to hotbar moves to new slot in same container: Hotbar reference updates to new slot
• Item moves to different allowed container: Hotbar reference updates to new container and slot
• Item moves to restricted container: Hotbar link is removed
• Item is removed/consumed: Hotbar slot becomes empty

This intelligent tracking ensures the hotbar always reflects item availability.

Hotbar Actions #

Link Item #

Linking an item to the hotbar creates a reference that allows quick access via keyboard shortcut.

Linking Method – Drag and Drop:

• Click and drag an item from inventory
• Drop it onto a hotbar slot
• System creates the link
• Hotbar slot displays the item

Link Validation:

Before creating a link, the system checks:

• Is the item in an allowed container type?
• Does the item have a default action that can be executed from hotbar?
• Is the hotbar slot available or should it replace existing link?

If validation fails, the link is not created and the player is informed why.

Hotbar Data Update:

When an item is linked:

• The item struct stores which hotbar slot it's linked to
• The hotbar slot stores which container and index the item is at
• Both references are maintained and synchronized
• UI updates to show the link

Delink Item #

Delinking removes an item from the hotbar without affecting the item in the inventory.

Delinking Methods:

Right-Click Hotbar Slot

• Right-click the hotbar slot
• Select “Remove from Hotbar”
• Link is cleared
• Item remains in inventory

Drag Away

• Click and drag the hotbar slot
• Drag outside the hotbar area
• Release mouse button
• Link is cleared

Replace with Another Item

• Drag a different item onto an occupied hotbar slot
• The old link is removed
• New link is created
• Old item remains in inventory

Delink Process:

• Clear the hotbar slot's container reference and index
• Clear the item's hotbar reference
• Update UI to show empty hotbar slot
• Item remains in its container, just not hotbar-linked

Automatic Delinking

Items are automatically delinked when:

• Moved to a restricted container
• Removed from inventory (dropped, sold, destroyed)
• Container is destroyed or unloaded

Swap Item #

Swapping items between hotbar slots allows players to reorganize their hotbar layout.

Swap Scenarios:

Swapping Two Items

• Drag hotbar slot 1 (has an apple)
• Drop onto hotbar slot 3 (has a sword)
• Apple moves to slot 3
• Sword moves to slot 1

Moving One Item

• Drag hotbar slot 2 (has a potion)
• Drop onto hotbar slot 5 (empty)
• Potion moves to slot 5
• Slot 2 becomes empty

Swap Function Implementation:

• Store both items' data temporarily
• Update item 1's hotbar reference to new slot
• Update item 2's hotbar reference to new slot (if exists)
• Update hotbar slots with new references
• Update UI to reflect the swap

Keyboard Shortcuts for Swapping

Some implementations allow:

• Hold Shift + Number to swap current selected item with that hotbar slot
• Drag from inventory onto hotbar to replace (with confirmation)
• Click hotbar slot to equip/use, hold and drag to reorder

Visual Feedback

During a swap:

• Show drag preview
• Highlight valid drop targets
• Animate the swap
• Play sound feedback

Alternative Implementations #

Minecraft-Style Container Hotbar #

An alternative to the reference-based hotbar is implementing the hotbar as an actual container.

How It Works:

• The hotbar is a container (like inventory or equipment)
• It has actual slots that hold item data
• Items are moved TO the hotbar, not linked
• Using a hotbar item consumes it from the hotbar container
• The hotbar container shows in the main inventory UI

Implementation:

• Create a new container with Container Type “Hotbar”
• Set it to spawn on player initialization
• Set number of slots to match desired hotbar size (typically 9-10)
• Create UI that displays this container's slots
• Bind keyboard shortcuts to slot indices

• Simpler logic (items actually exist in hotbar)
• No reference tracking needed
• Easier to understand for players (items visibly move)
• No sync issues between inventory and hotbar
• Works identically to any other container

Drawbacks:

• Items take up inventory space
• Need to manually move items to hotbar
• Can't quickly switch between multiple item sets
• Less flexible than reference system
• Items must be moved rather than linked

Use Cases:

• Games where hotbar is a separate limited-access bar
• Survival games where hotbar management is part of the challenge
• Games wanting Minecraft-like inventory feel
• Simpler implementations without reference complexity

Comparison of Approaches #

Reference-Based Hotbar (Current System):

• Items stay in inventory while linked to hotbar
• More complex implementation with reference tracking
• Must handle auto-unlinking logic
• Flexible – doesn't consume inventory space

Container-Based Hotbar (Minecraft Style):

• Hotbar is an actual container with slots
• Simple implementation using existing container system
• Items physically move to hotbar slots
• Takes up inventory space but easier to understand visually
• Gives flexibility of references with clarity of containers
• More complex but maximizes player options

Design Considerations:

• What's your target audience's familiarity?
• Is hotbar limitation part of the challenge?
• How often will players reorganize hotbar?
• How important is quick item access?
• What's your development time/complexity budget?

---

How to guides #

How to Configure Hotbar Slots #

This guide explains how to set up the hotbar for your character.

Step 1: Configure Number of Slots #

Decide how many hotbar slots you want:

• 5 slots: Minimal, focus on few key items
• 9-10 slots: Standard (Minecraft, many RPGs)
• 12+ slots: MMO-style, many items

In your character blueprint or hotbar component:

• Find the Hotbar Slots array
• Set the size to your desired number

Step 2: Bind Input Actions #

Set up keyboard inputs for each hotbar slot:

• Open Project Settings → Input
• Create Action Mappings for each slot (Hotbar1, Hotbar2, etc.)
• Bind to keyboard keys (1, 2, 3, etc.)

Step 3: Implement Hotbar Actions #

In your character or hotbar manager blueprint:

• For each input action, create an event
• When pressed, execute the item's default action from that hotbar slot
• Handle empty slots (do nothing or show message)

Step 4: Create Hotbar UI #

Create a widget for the hotbar display:

• Add horizontal box for slot layout
• For each slot, create a slot widget
• Bind each slot to the corresponding hotbar index
• Show item icon, quantity, keybind number

Step 5: Bind to Container Updates #

Ensure the hotbar updates when items change:

• Bind to AC_Inventory_Advanced's OnInventorySlotUpdated event
• When event fires, check if it affects hotbar-linked items
• Update affected hotbar slot displays

Step 6: Configure Allowed Containers #

Set which container types can have hotbar-linked items:

• In the hotbar component or inventory settings
• Add “Default” and “Equipment” to allowed types
• Exclude “Container”, “Crafting”, and other restricted types

Step 7: Test Functionality #

Test all hotbar features:

• Link items from inventory
• Press hotbar keys to use items
• Move items and verify hotbar updates
• Move items to backpacks and verify auto-unlink
• Swap hotbar slots
• Delink items

How to Add Custom Hotbar Actions #

This guide explains how to add special hotbar functionality beyond the default action.

Step 1: Identify Custom Action Needs #

Determine what custom actions you need:

• Hold to charge/aim
• Double-tap for special ability
• Modifier keys (Shift + Hotbar for alternate action)
• Long press vs short press
• Combo actions (press 1 then 2 quickly)

Step 2: Modify Input Handling #

Instead of simple key press, implement advanced input detection:

For Hold Actions:

• Detect key down (start hold)
• Track hold duration
• Execute action based on hold time
• Detect key up (release)

For Modifier Actions:

• Check if Shift/Ctrl/Alt is held
• Execute different action based on modifier
• Example: Press 1 = Use, Shift+1 = Drop

Step 3: Implement Action Switching #

Allow items to have multiple hotbar actions:

• In item data table, add array of hotbar actions
• Primary action (normal press)
• Secondary action (modifier or hold)
• Tertiary action (double-press)

Step 4: Create Action Execution Logic #

In the hotbar manager:

• Determine which action was triggered
• Get the appropriate action from the item
• Execute that action
• Provide feedback to player

Hotbar 1 Pressed:

1. Get item from slot 1
2. If Shift held:

 - Execute secondary action

1. Else if hold timer > 1 second:

 - Execute charge action

1. Else:

 - Execute primary action

Step 5: Visual Feedback #

Show players what actions are available:

• Tooltip on hover shows all actions
• Icon changes when modifier held
• Progress bar for hold actions
• Flash animation for combo window

Step 6: Test Complex Inputs #

Test all input combinations:

• Normal press
• Hold
• Modifier + press
• Double-tap
• Ensure no conflicts or bugs

How to Implement Container-Based Hotbar #

This guide explains how to convert from reference-based to container-based hotbar.

Step 1: Create Hotbar Container #

In the inventory component's Containers to Spawn:

• Add a new container entry
• Set Container Type to “Hotbar” (or create this type)
• Set Number of Slots to desired count (9-10 typical)
• Set Custom Container Class if needed

Step 2: Modify Hotbar UI #

Change the hotbar UI to bind to the container:

• Get reference to the hotbar container
• Create slot widgets for each container slot
• Bind to the container's OnInventorySlotUpdated event
• Display items directly from container slots

Step 3: Implement Item Movement to Hotbar #

Allow players to move items to hotbar:

• Drag items from inventory to hotbar
• Use transfer functions to move items between containers
• Items physically move from inventory to hotbar container

This is identical to moving items to any other container.

Step 4: Update Hotbar Key Handling #

Modify hotbar key press logic:

• Get item from hotbar container at slot index
• Execute item's default action
• Item is consumed/used from hotbar container
• No reference lookup needed

Step 5: Add Hotbar to Main Inventory UI #

Show the hotbar container in the inventory panel:

• The hotbar container appears as a grid
• Position it at the bottom of inventory
• Players can move items to/from hotbar like any container
• Clear visual separation from main inventory

Step 6: Remove Reference Logic #

Remove or disable:

• Hotbar linking functions
• Reference tracking
• Auto-unlink logic
• Container type restrictions for hotbar

The hotbar now works like any other container.

Step 7: Test Container Hotbar #

Test the new system:

• Move items to hotbar
• Use items from hotbar
• Verify items are consumed from hotbar
• Move items back to inventory
• Verify persistence (save/load)

• Simpler code
• No reference management
• Clear item location
• Familiar to players who know Minecraft

Trade-offs Accepted:

• Must manually organize hotbar
• Hotbar takes inventory space
• Less flexible quick access
• Items must be moved, not linked