# BIS RPG Action Bar Buyer Setup Action Bar Kit is a runtime action-bar presentation and request-forwarding plugin. It does not own combat, abilities, inventory, targeting, or resource rules. Release changes are tracked in `Docs/Changelog.md`. ## Finding appearance settings - **General:** overall scale, Back glass and Border switches, Glass follows bar, movement, and safe-area controls. Border affects the outer action-bar frame; slot highlights remain available. Turn Glass follows bar off to reposition only the glass, then turn it on to reattach it. - **Bars:** choose all bars or an individual bar, then set capacity, arrangement, and spacing. - **Bar appearance:** slot size, glass dimensions (up to 600%), optional Background art and its separate opacity, and other opacity controls. Select one numbered bar on **Bars** to expose its individual bar-scale control; use **General** for the overall scale of all bars. Slider numbers and the rendered bar update while adjusting. Slot fill starts at **55%**; saved custom values are preserved. - **Labels**, **Cooldowns**, and **Input:** text, feedback, and interaction controls. - **Preview**, **Profiles**, then **Tools** finish the left navigation. Profiles is immediately above Tools. The BIS information icon in the header opens the separate Info page. Use **Reset Appearance** to restore standard appearance for the selected scope. Changing Back glass or Border in General does not erase opacity values. Background art is enabled at 75% opacity by default. Turn it off on Bar appearance for a plain glass bar, or set `bShowBackGlassArt = false` in a global layout or individual group setting in Blueprint/C++ for a project-wide backend default. Art opacity is independent of the black glass opacity, so disabling art leaves the underlying glass unchanged. To use your own artwork without C++, import an image as a Texture2D in your project, then set **Custom background texture** on the action-bar host's Layout Settings or a starting preset. An unset texture uses the bundled BIS art. For a runtime Blueprint change, copy the host's Layout Settings, set Custom background texture, then call **Set All Group Presentation Settings** so every bar picks it up. For one bar, copy **Get Effective Layout Settings for Group**, change that texture field, then call **Set Group Presentation Settings** with its zero-based group index. The Background art toggle and opacity slider still apply. **Reset Appearance** restores the default toggle and opacity without deleting a custom texture choice. Make sure a custom texture is included in the cooked project; a path saved only in player SaveGame data will not package the texture asset. For a default appearance in a fresh project, create a **Data Asset** in the Content Browser and choose the **ABKActionBarPreset** class. Expand its **Layout** to set the background texture and other appearance values; optionally fill **Slots** with starting actions. In **Project Settings > Plugins > BIS RPG Action Bar > Appearance and Layout**, choose that asset for **Default Preset**. The automatic host uses it without a Blueprint or C++ setup. A manually created host keeps its own configuration, and an existing player's saved settings take precedence until they use **Reset All** to restore the chosen preset. The plugin's cook hook includes the selected preset package and its normal referenced dependencies; verify any custom texture selected dynamically at runtime is separately referenced for cooking and appears in the packaged build. ## Zero-Blueprint Quick Start **Editing scope:** Appearance and Labels include an All Bars / numbered-bar selector. Joined bars use the shared appearance consistently for slots and glass; selecting an individual bar restores independent editing and its retained settings. Slot spacing runs along the slots in horizontal and vertical orientations. Background frames rotate to fit portrait glass instead of stretching the horizontal ends. Outward slot borders extend beyond the slot rectangle and do not resize the icon. The first twelve default keys are **1–9, 0, minus, equals**, left to right. Newly generated slots use an available standard key without taking a binding from another slot; existing player bindings remain intact. **Shift + left-drag** moves the ABK launcher even when action-bar movement is locked. Row and slot spacing preview continuously during slider movement. At standard glass width, the glass adds a compact inset around the slots instead of reserving large unused ends. For a Fab customer, the shortest supported setup is: 1. Choose **Add to Project** in Fab or the Epic Games Launcher. 2. Open the project and accept any enable/restart prompt. 3. Press **Play**. The plugin automatically finds the first local player and displays a working 12-slot bar. The initial slots are internally named `Action01` through `Action12`, use the `1` through `=` key row, and immediately forward key presses. They intentionally start without icon artwork. Open the gear panel's **Preview** page and click **Load Action Bar** to place all twelve samples in the first twelve slots while preserving keybinds, or drag any supplied sample onto a slot. Loading replaces those preview assignments and is disabled when a gameplay provider owns the bar. No Blueprint, widget, input mapping, preset, viewport call, or C++ setup is required to see and customize it. Mouse clicks work when the host game makes the cursor available. See `Docs/Install.md` for the customer-facing installation sheet. ## Optional One-Node Gameplay Hookup When the buyer wants the starter slots to run game-specific abilities or items: 1. In a PlayerController, pawn, HUD, or other local-player Blueprint, add `Event BeginPlay`. 2. Add `Start Action Bar Kit` and leave every pin at its default value. It safely returns the automatically created host instead of producing a second bar. 3. Bind the host's `On Action Slot Requested` event. Use the request's `ActionId` in a `Switch on Name` node to run game logic. Replace starter data later with `Set Slots`, or connect a preset/provider when the gameplay system is ready. `Start Action Bar Kit` automatically finds the first local PlayerController when its advanced `Player Controller` pin is empty. Calling it again is safe: it reuses the same host component instead of adding another viewport overlay, and automatic saved-settings loading only occurs during first creation so repeat calls do not reset live cooldown state. It can therefore be called from BeginPlay, a delayed initialization event, or a custom UI setup event. It returns `None` on a dedicated server or when no local PlayerController exists yet. See `Docs/BlueprintQuickStart.md` for the optional gameplay node recipe and troubleshooting checklist. ## Optional Preset or Provider Setup - Plug an `ABKActionBarPreset` into `Preset` when the bar should start with designer-authored layout and slot data. - Plug an object implementing `ABKActionProviderInterface` into `Action Provider` when gameplay owns live cooldowns, availability, movement, clearing, and key assignments. - Leave both empty for the 12 starter actions and handle `On Action Slot Requested` directly in Blueprint. - The game remains responsible for actual abilities, inventory items, targeting, resources, damage, and healing. Automatic startup can be disabled or tuned under `Project Settings > Plugins > BIS RPG Action Bar`. Manual startup always remains available, and an existing manually configured host takes precedence over the automatic path. When `bAutoDisplay` is enabled, the host component creates the native Slate action bar for the owning local player at BeginPlay. The renderer supports horizontal, vertical, and grid layouts, multiple independently sized 1-24-slot groups, independent slot size, per-group visibility, scale/spacing/style controls, optional buyer-supplied icons, bound-key activation and labels, full-slot radial cooldown wipes and seconds text, stack counts, integration tooltips, semantic unavailable states, click requests, and slot drag/drop. `bEnableBoundKeyInput` is enabled by default. The host polls each slot's exact chord on its owning local player and forwards a just-pressed chord through the same request path as a click; no Enhanced Input Action or Mapping Context is required for the bar itself. Plain and modified bindings are distinct, so `1`, `Shift+1`, `Control+1`, and `Alt+1` can drive four different slots. Use `SetSlotBoundKey` for an unmodified key, `SetSlotBoundChord` for a modified chord, and `ClearSlotBoundKey` from Blueprint or C++. For player-driven rebinding, click the gear, open **Input**, click **Key Binds**, hover any visible slot, hold any desired Shift/Control/Alt/Command modifiers, and press a keyboard or gamepad button. Right-click the slot, or press `Backspace` or `Delete` while it is hovered, to clear only that complete keybind. Right-click outside Key Binds mode leaves the assigned action untouched. Press `Escape` while hovering a slot to clear that binding; press it without a hovered slot to leave keybind mode. Ordinary binding changes are remembered automatically. Slot labels abbreviate modifiers as C, A, S, and M, such as `C+S+1`. Modifier keys by themselves, mouse buttons, and analog axes are deliberately ignored as bind candidates. For the no-provider beginner path, `Set Simple Action Bar Slot` changes one slot's ID and label without array work. Empty starter slots flash their border when clicked or triggered by key. Any supplied Preview action also starts an intentional five-second demonstration cooldown with the radial wipe, countdown, request lock, and cooldown events, so a buyer can test the complete presentation immediately. `Start Slot Cooldown` supplies the same optional self-contained presentation path for buyer-defined standalone actions and `Clear Slot Cooldown` ends it. Provider-backed bars reject these local helpers because live action and cooldown authority belongs to the provider. ## Built-In Settings Panel The gear button opens a plugin-owned black-glass panel centered in the viewport, independent of action-bar scale and drag position. The left rail displays General, Bars, Bar appearance, Labels, Cooldowns, Input, Preview, Profiles, and Tools. The BIS information icon in the header opens Info, which contains the quick start and studio attribution. Hold `Shift` and left- or right-drag anywhere on the panel to reposition it without conflicting with normal controls or scrolling. The Preview page displays twelve reusable 64-by-64 sample tiles in a four-column grid; drag one onto any standalone slot to copy its action ID, name, description, icon, and optional stack count while preserving the slot's keybind. Click it or press that slot's key to run its five-second demonstration cooldown. Health Potion additionally demonstrates three consumable charges: each successful use removes one, zero charges darkens and locks the slot, and removing/re-adding the potion restores three. Drag an assigned action onto another slot to swap, or drop it outside the bar to clear it; the drag cursor uses the real icon. Right-click is reserved for clearing the slot's keybind while **Key Binds** mode is active and never removes the assigned action. `Action slots: Locked` prevents palette assignment, swapping, and drag-off clearing while leaving activation available. The samples are not auto-assigned and the palette remains available after every drop. Provider-owned bars keep mutation authority through their interface. The Tools page supplies four directional arrow markers in the familiar movement-key arrangement. They are neutral positional references intended to help a player learn where movement keys sit relative to surrounding keybinds. Dragging one onto a standalone slot preserves that slot's existing keybind, and the marker remains reusable in Tools. These markers do not register movement input, move a character, or replace the project's normal input configuration. Appearance uses the reviewed stock black-glass palette and does not expose per-kit color wheels. Buyers retain transparency, opacity, scale, spacing, border-thickness, and visibility controls. The public layout and group color fields remain available as integration hooks for a host-owned or optional suite-wide appearance controller, so the standalone kit does not require a theme dependency. The settings cover overall scale, independent slot size, group count, each group's 1-24 slot capacity and visibility, layout mode, grid columns, spacing, glass width/height controls from compact to 600%, pane snapping, back/button/border/icon opacity, border thickness, independent label sizes, cooldown text size and decimals, slot key bindings, slot locking, and action/key/cooldown/radial/stack/tooltip visibility. Choose `All Bars` on the Bars page for a shared edit, or choose one numbered bar and keep that scope while visiting Appearance, Labels, and Cooldowns. With `Independent positions` enabled, each numbered bar can own its orientation, grid columns, scale, slot size/spacing, glass/opacity/border presentation, labels/tooltips, and cooldown presentation. Back glass always auto-fits the visible slot footprint: grouped bars grow across the longest horizontal group and upward as groups are added, while vertical/grid modes follow their real columns and rows. Split groups each receive an independently fitted pane. The glass sliders adjust extra room around that guaranteed coverage, so compact settings never leave buttons outside the pane. Every opacity control uses the same literal scale: 0% is fully transparent and 100% is fully opaque; Button Fill Opacity changes only the interior and Button Border Opacity changes only the continuous frame. The reviewed default appearance uses 25% back glass, 55% button and panel fill, 100% button border, 100% icon opacity, and a 2px border. Expanded standalone groups create real bindable slots. `Independent positions` allows each pane to move independently; Shift-left-drag still works over slots, while ordinary left-drag on empty back glass moves the pane without starting an assignment drag. With `Snap glass panes` enabled, nearby edges align flush and the attached panes move together as a loose cluster. Alt-drag a pane to detach it. With independent positions off, Shift-drag moves the complete bar. Moving Bar 1 does not carry the settings gear; that control retains its independent Shift-left-drag offset. With platform safe zone enabled, every complete movable element is constrained to its effective safe rectangle and is automatically recovered after resolution/DPI changes or an older off-screen save. With the safe zone disabled, free edge placement is allowed but a 24 px recovery handle remains visible. `Lock Movement` and `Reset Positions` remain available; ordinary settings changes are remembered automatically. Ordinary runtime edits are remembered automatically in the current setup; `Save Active` explicitly updates a named profile snapshot. Appearance, Labels, and Cooldowns each have a category-only reset that leaves positions, assignments, and keybinds untouched and is remembered in the current setup. `Reset Keybinds` has a dedicated confirmation and restores the bindings originally supplied by the starter setup, preset, or provider; a confirmed keybind reset saves immediately. The full `Reset` action retains its separate confirmation before restoring the assigned preset or plugin defaults. `Close` hides the panel and exits keybind mode. `Keep Mouse Cursor Visible` is available under `Project Settings > Plugins > BIS RPG Action Bar`. It is disabled by default so a newly installed bar does not change the host game's camera or input mode. Enable it for a mouse-driven demo: the first local player then uses Game-and-UI input, the cursor remains visible during capture, and click/hover events are enabled. A manually created host still takes precedence over auto-start and is never reconfigured by the auto-start subsystem. The Preview palette contains Health Potion, Rending Strike, Unbreakable, Auto Attack, Spinehook, Jawbreaker, Weathered Tonic, Ironrush, Ironhide, Bonewheel, Retaliation, and Severance. Approved BIS texture assets are under `Content/ActionBarKit/UI/StarterActions`; the kit does not require Abilities, Spellbook & Skills. Other samples demonstrate icons and cooldowns; the optional Auto Attack example supplies the documented unarmed demonstration, without implementing the other abilities. One original transparent directional-arrow master is included under `Resources/SourceArt/Tools`; runtime rotation produces the four consistent Tools markers without duplicating source artwork. Empty slots still render without artwork, and buyers may replace the `StarterActions` or `ToolActions` arrays or provide their own textures through slot view data. ## Neutral Demo Provider Open `/ActionBarKit/ActionBarKit/Demo/L_ActionBarKitDemo`, or drop `ABKDemoActionProvider` into any playable test map, for a zero-setup, artwork-free example. It creates 12 labeled slots, forwards clicks, previews a three-second cooldown, and supports drag reordering. The actor is Blueprintable, so it can also serve as a small reference implementation before a buyer connects their own provider. `/ActionBarKit/ActionBarKit/Demo/DA_ABK_NeutralPreset` provides the same neutral starting layout and slot data as a reusable preset. ## Runtime Updates - Call `SetSlots` when replacing the complete view model. - Call `RefreshFromActionProvider` when the provider's display or cooldown state changes. - Call `SetLayoutSettings` to rebuild the bar with new layout/style values. - Call `Apply Action Bar Drag Delta` when a custom UI wants to drive the same movement contract as the built-in renderer; `Set Movement Locked` and `Reset Layout Positions` expose the corresponding safety controls. - Call `ShowActionBar` or `HideActionBar` when the game owns visibility rules. - Call `SetSlotBoundKey`, `SetSlotBoundChord`, or `ClearSlotBoundKey` to rebind a standalone host. Provider-backed hosts forward plain/cleared keys to `SetActionSlotBoundKey` for backward compatibility and modified chords to `SetActionSlotBoundChord`. Providers should enforce uniqueness against the complete chord, not only the base key. - Bind `OnActionAssigned`, `OnActionRemoved`, `OnActionActivated`, `OnCooldownStarted`, `OnCooldownFinished`, and `OnKeybindChanged` when game-side Blueprint logic needs lifecycle notifications without polling the view model. Bind `OnActionSlotRequested` to execute gameplay only for a standalone host. A provider-backed host calls the provider's `TriggerActionSlot` and does not broadcast that standalone request; `OnActionActivated` observes provider acceptance in provider mode. In the standalone event route, it reports a processed bar request, not proof that your game accepted the ability; use your own ability result for that. Do not execute the same action again from `OnActionActivated`. `FABKActionSlotViewData` is presentation data. In the provider path, cooldown authority remains in the buyer's gameplay system; update `CooldownRemaining` and `CooldownDuration`, then refresh the host. The standalone `Start Slot Cooldown` helper is an optional beginner-facing display/request lock, not a replacement for a gameplay ability system. Tooltips read the same presentation contract and can show the action name/description, bound key, live cooldown, quantity/charges, and semantic availability. Supply `UnavailableReason` in slot view data—or call `Set Slot Availability With Reason` on a standalone host—for buyer-authored explanations such as `Requires 20 mana`. Action Bar Kit displays that text but never decides costs, range, targets, or failure rules. ## Persistence The current setup is remembered automatically as a working copy. The factory `Default` profile is protected: it cannot be renamed, overwritten or deleted, and choosing it restores the shipped layout. Enter a unique name (maximum 32 characters) and use `Save as New Profile` to retain your setup. Named profiles can be loaded, updated, renamed or deleted. Deleting a named profile requires confirmation; player-authored profiles and saves remain separate from plugin content. The host exposes `CreateUserProfile`, `LoadUserProfile`, `RenameUserProfile`, `DeleteUserProfile`, `SetDefaultUserProfile`, and active/default/profile-list queries to Blueprint. Existing `SaveUserSettings` calls now update the active profile, preserving backward compatibility. Profiles contain layout and standalone assignment presentation, never cooldowns or other gameplay-owned runtime state. The host exposes `SaveUserSettings`, `LoadUserSettings`, and `ResetToDefaultPreset` to Blueprint. By default it loads the `ActionBarKitUserSettings` save slot during BeginPlay and persists layout plus assignment presentation (`SlotIndex`, `ActionId`, text, icon, base key, and modifier flags). Older saves load as unmodified bindings. Cooldown, enabled, and usable runtime state are never saved. When a provider is attached, saved slot assignments are not applied because the provider remains authoritative; disable `bPersistSlotAssignments` when the buyer's ability or inventory system owns persistence. Named profiles and key layouts are player-authored SaveGame data under the host project's `Saved` directory. They are not plugin content and are excluded from Fab packages. The distributed plugin starts from its neutral default preset; local hardware-specific profiles such as a G13 layout do not ship. Provider-backed move, clear, and rebind requests return success from the provider. On success, the host refreshes from the provider instead of applying a second local mutation. This single-authority contract prevents double swaps and host/provider desynchronization. ## Product Boundary Action Bar Kit should own: - slot view data - slot requests - layout settings - key labels - cooldown display inputs - drag/drop requests - settings persistence APIs The buyer's game should own: - ability execution - item use - target lookup - resource costs - damage ownership, authoritative damage resolution, healing, buffs, and cooldown authority - game-specific icons and tooltips ## Version 1.1.0 Release Scope Version 1.1.0 is an independently buildable Blueprint plug-and-play BIS RPG Action Bar for Unreal Engine 5.8 on Win64. It includes player-authored profiles, a twelve-action preview palette, exact modifier chords, keybind-only right-click clearing, continuous slot borders, separately controlled fill and border opacity, independently positioned bars and utilities, optional glass-pane snapping, reusable directional training markers, provider-authoritative mutations, and the documented one-node idempotent bootstrap. The standalone product does not render an inventory launcher or require Inventory Kit, a theme add-on, or any third-party dependency. Version 1.1.0 also supplies the optional Auto Attack toggle, standing attack cycle, moving punch selection and editable equipment-category icons. For optional compatible-character demonstration setup, see [Equipment-Showcase-Setup.md](Equipment-Showcase-Setup.md). Only Auto Attack currently implements an attack; the other buttons retain preview cooldown behavior.