How to use devices

This page outlines some tips and tricks on how to add devices to your project, and how to use them.

Note: This requires your project to be configured so that it is able to use devices. Integration for details on how to set that up.

How to use the Item Management UI

• When you first connect, you start with the “device quickbar” displayed.

  • You can enter the “Inventory view” screen by clicking the button on the left (or pressing TAB)

  • You can enter the “Place mode” screen with the button on the right (or pressing 9)
  • Clicking any quickbar slot will “select” that slot, opening its device-specific UI.
  • Pressing Q or the “cross” button will deselect the item, and exit the the device-specific UI.

  • Some devices may have additional controls, e.g. Device Modules.

  • Clicking on an empty slot (with the + icon) will also take you to the “Inventory view” screen, to manage adding items to the available slots.

  
• The “Inventory view” screen can be used to click and drag items to/from your quickbar.

  
• More details on the "place mode can be found in Place Mode.

• NOTE: Some parts of this UI can be hidden/disabled. See Live config for details on this.

NOTE: Device Inputs

Depending on the project, you may default to the mouse being visible and able to click on things on the screen (Approachability), or the mouse being captured for camera movement, and the cursor being hidden (game ready). For more details, see Control Schemes.

To support both of these flows, there are a few helper methods that can be used.

• BPC_M2_ApproachabilityCameraControl::AddClickToTurnOverrideStack/RemoveClickToTurnOverrideStack: Use these when initializing and tearing down an item respectively to force the item into "UI mode", so you can click on things on the screen.

• BP_Approachability_PlayerController::DisableAndLockUIMode/RestoreAndUnlockUIMode: Use these when initializing and tearing down an item respectively to force the item's execution into "game ready" mode.

If you want to make your item have inputs that listen to keys as shortcuts, the two recommended approaches would be to add the shortcuts to your button data (see Configure the “button data”), or listen to shortcuts in your item executor (see Adding input events to the executor).

NOTE: Some legacy devices expect LMB/RMB to be bound automatically, to trigger the Primary/Secondary Input events, e.g. the force push ability (PDA_Item_ImpulseGlove). If you need to achieve this behaviour, it is controlled by a capability in the roles data table: Capabilities.Inventory.ItemControlledQuickbarInputs. By default this is off, since having LMB/RMB always bound to the item handler can block other inputs, like "click to move". If you need this sort of behaviour, the preferred approach would be to explicilty listen to the inputs you want using ListenToInputs.

How to add items to your inventory/quickbar

Having items in your “starting inventory”

This is the currently desired use case - when you switch to a particular role, your Quickbar is automatically set up, with a defined list of items

• In the appropriate roles data table, add the item assets you want to the Starting Inventory Assets list.

  • E.g. if you want an item to be automatically given to presenters, but not given to regular participants, you can add it to specifically the Presenter role.

  • The entries in the list are the “Item Assets” (The PDA_Item_[X] asets).

  • 
  • Note: You can see which roles table you are using in your level’s WorldSettings

  • 

• Once these have been updated, you can switch to the role (e.g. in the Esc menu) and your Quickbar should be automatically set up.

• NOTE: The number of slots in your Quickbar is controlled by live config (Inventory.MaxEquipmentSlots).

• NOTE: By default, if you don’t have any items equipped, your Quickbar is hidden. If you don’t want this behavior, you can turn off the Inventory.Quickbar.HideIfEmpty feature flag.

Using the console (for testing purposes only)

We also have some console commands for testing out the inventory system, for e.g. granting and equipping different items:

• Juno.Inventory.AddItems [ItemName list, separated by spaces] - will add the item(s) to your inventory. e.g. Juno.Inventory.AddItems PDA_Item_Pointer PDA_Item_Ping_Approachability

  NOTE: Adding an item to your inventory will not automatically add it to your quickbar, since it doesn’t default to being “equipped”, unless the Inventory.AutoEquipItems live config is set to true.

• Juno.Inventory.RemoveItem [ItemName] - will remove the item from your inventory (and your quickbar if it was added there)

• Juno.Inventory.EquipItem [ItemName] - provided the item is in your inventory, equip it (which will add it to your quickbar)

• Juno.Inventory.SelectItem [ItemName] - selects the item, provided it is equipped (functionally the same as pressing the button in the quickbar, or using the num-keys)

Using the “Item granter” device

Using either of the above approaches, you can grant a player the PDA_Item_ItemGranter item.

With this device equipped, you can grant an item to everyone currently present in the level, either by typing it in manually, or selecting it from the list.

NOTE: This device is ALPHA, so may be subject to change.

Doing it manually

We have a number of blueprint accessible methods for granting items:

• JM_InventoryComponent::AddInventoryItem(s)

  • If you have access to the Morpheus Actor’s JM_InventoryComponent, and know the Name of your item/device, you can manually add it to that player.

  • You can either type the name(s) in manually, or use AssetNameFromSoftObjectPtr to search for the correct asset.

  • When you add the item, the Item Key is returned - this is the unique identifier used to refer to this added item.

  • NOTE: These need to be done from the server.

• GrantItemToAll

  • This is a helper function that grants the item to all players currently in the map.

  • NOTE: This hasn’t been tested at scale, so please get in touch if you’re wanting to use this for large scale events

  • NOTE: The item won’t automatically be added to late joiners.

  

For removing items, you use the RemoveItemByItemKey method.

• This takes the ItemKey - to find the item key of an item there are number of ways:

  • FirstKeyOfItem - this can be used to get the item key of an item with a given name in your inventory. If you don’t have any, it returns -1.

  • GetKeysWithItemName - if you can have multiple items with a given name (i.e. you are allowing duplicates of that item), you should instead use this, to get all the items.

  • If you keep track of the item key returned when you added the item, or get the key from the slot in your equipment component, you can refer to these to remove the item.

• If you have stacking items at that key, you can remove multiple at once using a NumToRemove value greater than one.

To equip items:

• If you have the Inventory.AutoEquipItems config flag set, items added to your inventory are automatically equipped.

• If you go to the inventory view, you can manually equip items by dragging them into your quickbar.

  
• Otherwise, you can manually equip the item using AddItemKeyToAssignmentSlots

  • If a SlotIndex >= 0 is provided, it will attempt to equip the item to that exact slot (replacing/swapping with the item already in that slot).

  • If a SlotIndex < 0 is provided, it will attempt to equip the item to the first empty slot. If there are no empty/available slots, the request will fail.