Say goodbye to the Tutorial Chest! This framework is designed to supersede Tutorial Chest usage by enabling mod authors to easily add new items to the camp chests and player inventories.
Other user's assetsAll the assets in this file belong to the author, or are from free-to-use modder's resources
Upload permissionYou are not allowed to upload this file to other sites under any circumstances
Modification permissionYou are allowed to modify my files and release bug fixes or improve on the features so long as you credit me as the original creator
Conversion permissionYou can convert this file to work with other games as long as you credit me as the creator of the file
Asset use permissionYou are allowed to use the assets in this file without permission as long as you credit me
Asset use permission in mods/files that are being soldYou are not allowed to use assets from this file in any mods/files that are being sold, for money, on Steam Workshop or other platforms
Asset use permission in mods/files that earn donation pointsYou must get permission to earn Donation Points for your mods if they use my assets
Author notes
Mod authors may enable donation points for any mods using this framework as a dependency, and may freely use the Framework Template file to help build integration with this mod. This mod's code itself is AGPLv3-licensed. For details, refer to the GitHub link in the description.
File credits
ISF has code adapted code from Compatibility Framework and uses code (as dependency) from Volition Cabinet, both licensed under the MIT License. A copy of CF's license is added to relevant portions of this mod. Volitio extends his gratitude to the CL team for making their code available under such an open and permissive license, enabling seamless collaboration across the modding community!
The Item Shipment Framework (ISF for short) allows mod authors to directly ship vanilla or modded items into the camp chest or host's inventory. It aims to provide a superior alternative to the Tutorial Chest and Trader Inventory item shipment approaches.
When users first load into the game with this mod installed, all available camp chests will receive the Item Shipment Framework Mailbox. This is the main location where mod authors will send items to their users, however, authors may additionally choose to place items directly into the host's inventory.
Inside the mailbox, users will find the Item Shipment Framework Utilities scroll case, which houses various utility scrolls that trigger commands for the framework. As well as the Tutorial Chest, located in Player 1's mailbox. This "Tutorial Chest" serves as legacy mod compatibility, for those mods which have not been updated to support the Item Shipment Framework. The items inside of it can be manually refreshed, using the "Reset the Tutorial chest" command scroll.
In the Baldur's Gate 3 Mod Manager, enable the Script Extender by clicking on the 'Tools' tab at the top left of the program and selecting 'Download and Extract the Script Extender'. Alternatively, press CTRL+SHIFT+ALT+T while BG3MM's window is focused;
Volition Cabinet is a requirement for this mod, so make sure it is installed and up-to-date (1.5.0 or greater). Its load order should not matter;
Import this mod's .zip file into the Mod Manager, and drag the mod from the right panel of the Mod Manager to the left panel;
Drag this mod to the bottom of your load order, as it needs to be placed below any mods that rely on this framework;
Save and export your load order. The ISF will now automatically pick up any mods that use the framework.
To uninstall, use the scroll inside the utility case located inside any mailbox. The Trashcan mod can also help you tie up any loose ends when uninstalling mods that have delivered items through ISF.
When you load a save with the mod for the first time, the ISF will automatically create an av_item_shipment_framework_config.json file with sane default options into your Script Extender folder. If you, however, want to change any of its settings, here are instructions:
Spoiler:
Show
You can easily navigate to the JSON user configuration file on Windows by pressing WIN+R and entering:
explorer %LocalAppData%\Larian Studios\Baldur's Gate 3\Script Extender\AVItemShipmentFramework
Open the JSON file with any text editor, even regular Notepad will work. Here's what each option inside does (order doesn't matter):
"GENERAL": "enabled": Toggle this to true to activate the mod, or set it to false if you wish to deactivate it without removing it. Enabled by default.
"FEATURES": "notifications": A section for notification settings. "enabled": Set to true to enable in-game notifications when you receive items. Enabled by default. "ping_chest": If set to true, camp chests will be pinged when receiving items. Enabled by default. "vfx": If set to true, a VFX will be emitted from your character when camp chests receive items. Enabled by default. "spawning": "allow_during_tutorial": Set to false to disable spawning new items or entities during tutorial sections. Enabled by default.
"DEBUG": "level": Adjust the verbosity of debug logs. A setting of 0 disables debug logs, 1 provides minimal logging, and 2 enables detailed, verbose logs. 0 by default. After saving your changes while the game is running, load a save to reflect your changes.
ISF SE console commands: - !isf_ship_all: This command triggers the shipment of all items managed by ISF. It is executed by default during gameplay start, such as when loading a save or changing regions. Using !isf_ship_all true bypasses the usual checks and forces all items to be shipped.
- !isf_ship_mod <MOD_UUID>: This command specifically triggers the shipment of items for a mod identified by its unique mod UUID. Adding true at the end of the command skips the framework's usual checks and forces the shipment.
- !isf_uninstall: This command uninstalls the ISF. During the uninstallation, any items managed by the framework, except for ISF items, may be moved to the camp chest based on user confirmation. Following confirmation, the ISF container is deleted.
- !isf_refill: This command refills taken items in the mailboxes.
- !isf_tut_update: This command updates the Tutorial Chests copies to ensure that the items they contain are current.
GENERAL INFORMATION
The Item Shipment Framework is a simple and modular tool that allows mod authors to ship items to their users. In this section, you'll learn about the ISF, what it can do, and how easy it is to integrate your mods into the framework. Whether you're developing a new mod or updating one with an existing user base, integrating it into the ISF follows the same process. For mods that already have an existing user base, integrating with ISF is user-friendly, as it ensures that players will not receive duplicates for items they already possess. This is achievable due to the series of checks that the ISF can perform.
The framework provides a JSON configuration example file for mod integration, with comments detailing each setting. Due to (harmless) linting errors with said comments in standard JSON, both JSON and JSONC formats are supported by the ISF and are parsed in the same way, with or without comments.
ISF doesn't force mods into a mandatory dependency with the Script Extender. The configuration file will be picked up in case users have ISF installed, but will simply remain inert otherwise. Therefore, if your mod is designed to function without the Script Extender or even without ISF, integrating it with ISF will not change this.
QUICK-START | HOW TO INTEGRATE YOUR MODS
Using this quick-start guide, authors can learn how seamlessly to send their items to the camp chest using the ISF!
To get your mod up and running with ISF, you can drag and drop its main folder inside our bespoke web tool that will parse the contents of the mod folder and generate an ISF configuration JSON file based on your mod's contents:
Click "Save ISF JSON" to download the generated file.
Place the JSON file alongside your mod's meta.lsx file.
That's it! With this tool, you can easily generate the necessary ISF configuration for your Baldur's Gate 3 mod. Now, please, review the generated JSON file and make sure all the items you wish to ship have been accounted for, and that the settings chosen fit your mod's needs.
Default settings: the default settings, also used by this generated JSON, will:
Send a single copy of each item to all four possible mailboxes, and none directly to the host's inventory.
Verify if an item exists in the player's party inventories, mailboxes, and perform an internal ISF check using ModVars.
To learn more about the ISF and how it functions, head over to our Wiki hosted on GitHub! It goes over every setting available to you in the config file, and showcases some example mods, which feature multiple different use cases.
DISCLAIMER: Mod authors should NOT add the ISF as a dependency in their meta.lsx file. It needs to be loaded last, and doing so could prevent that. Authors should only add it as a requirement on their mod's Nexus page.
EXAMPLE MODS WHICH USE THE FRAMEWORK
Each of these mods showcases different use cases for the framework. You can learn more about how they were made here on our Wiki.
Volitio: Script Extender implementation, ISF config JSON generator website, Brazilian Portuguese and French localizations.
"If I can see further, it is by standing on the shoulders of giants". Creating this framework would've been a herculean task without the foundational work of Focus and Nells/Community Library team from which I learned from and continue to build upon. I will be forever grateful for their open-source contributions to the Baldur's Gate 3 modding scene. Of course, none of this would be possible without the work put into Script Extender by Norbyte. Also thank you to all the authors that tested ISF and provided feedback during the beta! Belinn, jerinski, wesslen, Armarui, lokelani, Kilay, Maze and so many others that shared support! - Volitio
If you'd like to support either of us directly, you may do so by following these links:
Give Feedback
