Note
Simple Inventory v3 is in beta right now. It should work, but there may be bugs and rough edges. Please report any issues you encounter!
The new version of my simple inventory system. No longer a part of my macro collection, it's now its own thing. If you need the old version, grab an older release (v2.10.0 or lower) of my custom macro collection.
- Downloads
- Installation
- Guides
- Macros
- APIs
- Issue Tracker
- Demo
- Source Code
Version 3 includes most of the features and functionality of v2, and adds:
- Consumables. Items can be associated with SugarCube code (sort of like a widget) or a callback function that can be executed when the item is "used."
- Item descriptions (as dialogs).
- Item names. You can provide items with both names and IDs, using the ID in code while the name will be used for displaying it in the game.
- Item and inventory tags. You can add tags to items and inventories as metadata.
- Item stacking. Duplicate items in an inventory can now stack meaning they'll take up one visual "slot" in the inventory, but will have a counter showing how many are present.
- More robust built-in UI options and components.
- A cleaned up, mostly simplified API and code structure.
Most new features are optional; you don't have to define items, for example. With the exception of stacking, it's possible to use this inventory in almost exactly the same way as v2.
This new simple inventory is totally incompatible with previous versions. Updating will require rewrites, so you may want to stick with v2 in ongoing projects.
Archives will be listed on the releases page, but you can also grab them from dist/
. Download the latest version, unzip, and add the files to your SugarCube 2 project. How you add the files will differ based on the compiler you use.
From the main story menu (the ▲ on the bottom left-hand side of the screen, near the story name) open the game's Story JavaScript area. Copy and paste the contents of simple-inventory.js
into this window. Likewise, copy and paste the contents of simple-inventory.css
into your Story Stylesheet area.
Tip
When opening the files to copy and paste them, use a text or code editor (your default text editor, like Notepad or TextEdit is fine). Avoid opening the files using any sort of rich-text editing program or a word processor.
Note
Some operating systems may warn you when you attempt to open a .js
file. This is normal behavior, and not necessarily an indication of the presence of malware. As long as you get the files from my GitHub repo, you should be okay.
In most CLI compilers (excluding Twee2) you can simply include the simple-inventory.js
and simple-inventory.css
files in your project's source folders, or list them as source files when you use Tweego.
You will need to create special JavaScript and CSS passages to include the code in your project, usually by using the passage tags script
and stylesheet
, respectively. Refer to the documentation of your compiler for more information.
If you use the excellent Twee 3 Language Tools extension for VSCode, which I recommend you do, then you'll probably want to provide macro definitions for the custom macros and widgets you use. Here's the macro definition file I use. It's not very detailed, but it should at least prevent the macros from showing up as errors.
Clone/fork/download the repo. Run npm install
to set everything up.
Once that's done, you can use NPM scripts to build the library or the demo/test project. See package.json
for details.
npm run build
: Build the JS and CSS. Outputs the resulting files todist/
. Seebuild.js
for more details. If you cant to add new files, you'll need to list them inbuild.js
or they won't get compiled.npm run demo
: Requires Tweego to be installed and on your path. Builds the demo file (seetest/
) and outputs it todocs/demo.html
.
I welcome contributions in the form of issues or PRs on GitHub.
If you've made a cool system with Simple Inventory 3, and have the time and inclination to create a minimal version that can be used as a recipe, please consider contributing it to benefit other users!
Please report bugs and errors, or typos in this documentation!
This code is dedicated to the public domain. You don't need to provide credit, attribution, or anything else if you don't want to. By contributing code or content to this project, you are releasing it into the public domain.
Note
If you do wish to credit me, which I always appreciate, you can credit me as Chapel, but please do not imply that I directly worked on your game.
Tip
If you have any questions or concerns about this, refer to the license or reach out to me.
If you're having an issue with this library and suspect that it's operator error rather than a bug, you can still open an issue, but a faster way to get help would be to post in one of these Twine communities:
- The Twine Category at IntFiction.org
- The Official Twine Discord Server
- The Unofficial Twine Subreddit
Tip
Regardless of where you seek help, you'll want to provide links this documentation or the repo for your potential answerers.
Note
Note: I suggest donating to Twine development or SugarCube development if you really want to help out, but I'd welcome a few dollars if you want!