Inventories is a great tool included with AliceOS to set up, manage, and use an inventory system in any AliceOS-powered visual novel. Developers can easily define items and manage the inventory with the Inventories API, and users get an easy experience with managing items using the Inventories app built with ScreenKit. Inventories is an opt-in system, so if you don't think you need Inventories, you don't have to work with it at all.
The Inventories app comes with some great features that work well with AliceOS:
- A fast and easy way to define items using the
ASInventoryItemclass that can state what an item is and how it can be used
- Methods to add and remove items from the inventory, as well as importing an inventory from a Python list
- GUI for players to use an item and see what they have in store
- Optional HUD to let players access the first five items in the inventory
A sample inventory system¶
Creating and maintaining the inventory can be accomplished easily in Ren'Py:
label the_story: python: used_office_key = False def use_office_key(): store.used_office_key = True office_key_item = ASInventoryItem( name="Office Key", description="Opens up the office door", canBeUsedOnce=True, specialUseCase=use_office_key ) "Quickly, I look around the room for any keys to open the door and finally get out of the office." "After searching under a few desks, I manage to find a key." $ inventory.addItem(office_key_item) while not used_office_key: "Great! Now to just get the door open." "The key unlocks the door, and I happily skip out." return
When a player uses the item via the Inventories app, all of the logic for handling one-time use and even removing the item from the inventory is taken care of for you.
Creating an item¶
The inventory works with the
ASInventoryItem class as a means of defining items and how they can be used in Inventories. Below are the required fields in the constructor (
Items in the inventory must use the
ASInventoryItem class to ensure compatibility with the app and with the inventory methods.
name: String containing the name of the item. Defaults to
description: String containing the description of the item. Defaults to an empty string.
canBeUsed: Boolean dictating whether the item can be used. Defaults to
specialUseCase: Function that dictates any game-changing behavior or any other actions to be completed when an item is used. Defaults to
canBeUsedOnce: Boolean dictating whether the item is a one-time-use. Defaults to
imageName: String containing the path to the image. Should be 128px by 128px. Defaults to the standard missing item image path.
Managing the inventory¶
The inventory can be invoked from
inventory and is an instance of the
ASInventories class, an app written with AppKit. The following methods are provided to make inventory management easier:
Open the Inventories app. Inherited from
Opens the Inventories HUD which lets players access the first five items in the inventory. Useful in the quick menu or in scenarios where opening the Inventories app is impractical.
Returns whether the inventory is empty or not as a boolean.
Returns the inventory as a list of items (
Checks whether the inventory contains a specific item.
item: The item to check for (
Returns: Boolean value stating whether the item is in the inventory
Looks for an item in the inventory and returns it, if possible.
name: String containing the name of the item
Returns: The appropriate
ASInventoryItem object if found or
None if the search fails.
Adds an item to the inventory if possible and displays a notification if the user permits.
item: The item to insert (
Raises: May raise a
TypeError if the item isn't an
Use an item if it exists in the inventory. Also removes any items that can no longer be used.
item: The item to use (
Raises: May raise a
KeyError if the item is not in the inventory
Imports the inventory from a Python list by appending each item to the inventory.
list: The list containing
ASInventoryItemitems to import
Raises: May raise a
TypeError if the list contains elements that are not
Saving the inventory¶
It might be helpful to make sure that the player's inventory is properly saved since the class re-initialized with an empty inventory from the beginning. We recommend storing the current inventory before closing out the game. For example, if you wanted to store the inventory to the persistent file:
label quit: $ persistent.saved_inventory = inventory.retrieve() return
Then, when you start the game again, you can reload these items:
label before_main_menu: $ inventory.importFromList(persistent.saved_inventory) return
Alternatively, you can save the state of these items in your game's file save or in Ren'Py's store variables:
default player_inventory =  $ player_inventory = inventory.retrieve() label after_load: $ inventory.importFromList(player_inventory) return
Using the HUD¶
The Inventories HUD is a great way to let players quickly access items without opening up the Inventories app. While you could make a cutton to open the app directly, it might be impractical at times. The HUD offers a solution as it shows players just the items and optionally lets them open the app for more items/details.
For instance, it might be useful to include this HUD in the quick menu of your visual novel:
screen quick_menu(): ## Ensure this appears on top of other screens. zorder 100 if quick_menu: hbox: style_prefix "quick" xalign 0.5 yalign 1.0 textbutton _("Back") action Rollback() textbutton _("History") action ShowMenu('history') textbutton _("Skip") action Skip() alternate Skip(fast=True, confirm=True) textbutton _("Auto") action Preference("auto-forward", "toggle") textbutton _("Save") action ShowMenu('save') textbutton _("Use Item") action Function(inventory.callRecentItems) textbutton _("Q.Save") action QuickSave() textbutton _("Q.Load") action QuickLoad() textbutton _("Prefs") action ShowMenu('preferences')
During gameplay, the "Use Item" button will appear next to the typical buttons in the quick menu and players can click on it to open the HUD.
More information on the
callRecentItems() method used can be found in the inventory's class documentation.