To hopefully prevent many questions about how things work with "Magic Bags", I started this new discussion topic.

Magic Bags are a convenience function. Their main purpose is to keep a character's main inventory clean.

By default, the "magic bag functionality" is turned on.
When turned on, all items that are configured to go to one of the up to 11 bags, will automatically be put into their corresponding bag instead of the main inventory when they enter the character's main inventory. (Items *always* go to the main inventory first but are then moved to the bags from there.)

The game engine has a built-in functionality that hides items marked as "quest item" in trader windows. This is what the mod uses, all magic bags are marked as quest items. The engine also has the functionality to return quest items to main characters when a companion leaves the party. (This is no mod functionality but a game engine functionality.).
So, when a companion is dismissed or leaves the party for any other reason, the bags and their contents held by the companion are returned to one of the main players ... because the engine thinks they are real quest items. (which they are not really ;-)

When starting a game with the mod, all characters receive 11 bags for different categories, and they get a single "controller" (the controller's item looks a little bit like a remote control.)
Characters also receive a couple of new "spells": they receive a bedroll spell which summons a bedroll for healing outside of combat (and the special coffin version which is only usable for characters that have the "Zombie" talent.
Characters also receive the "Magic Bag Control" skill which is used to turn automatic bag functionality off and on. There are a couple of ways to turn off the functionality but the spell is the *only* way to turn it on again once it's turned off.
All these skill can be found in a character's spellbook which can be opened either by pressing "K" or by clicking one of the icons below the character's portrait.

There is a section in the spell book which contains all non-ability spells, i.e. all spells that do not belong to any ability (Hydrosophist, Expert Marksman, etc.).
The bedroll spells and the "Magic Bag Control" spell can be found in this section.
(The spell "Staff of Magus" is also in this section for example.)

When magic bag functionality is turned off, the character receives the status "Clean" which is indicated by small icon to the right of the character portrait.
(The character is not really clean then, or dirty otherwise, there are internal technical reasons why it has to be that way ....)

When the functionality is turned off, items that enter the main inventory no longer go to their configured bag if one is configured.
There is an exception to this though, stackable items (like potions, special arrows, grenades, etc.) *always* go to the container which already holds a stack of them. (Even if the "stack" holds only a single item.)
This is an engine built-in functionality and cannot be turned off.
And again, there is an exception even to this exception: items never go into a locked container inside the character's inventory (e.g. a locked chest), even if they could stack with an item inside the locked container.

While there is only one way to turn on magic bag functionality - the Magic Bag Control spell -, there are several direct and indirect ways to turn it off:
- the Magic Bag Control spell is a toggle spell which turns functionality on/off and does nothing else (except activating/deactivating the "Clean" status which has no other functionality other than being an indicator.
- dragging the controller into one bag turns off magic bag functionality *and* empties the bag to the main inventory at the same time. The controller gets moved out of the bag again too.
- double-clicking the controller or choosing "Use" from the controller's right-click menu turns off functionality and empties *all* magic bags to the main inventiory.

Items added to the main inventory (or thrown or manually moved out of a bag) while the functionality is off, are in a "pending state", i.e. they wait to be automatically sucked into the bag again once the functionality is turned on again.
Once turned on again, the pending items are sucked into the bags again.

Items can never be manually added to a bag they are not configured for, no matter if the functionality is turned on or off, a bag will always throw out items not configured for it.
The exception to this is the equipment bag (and maybe the tools bag, which I don't remember anymore.)
The equipment bag is a mere convenience bag meant to hold alternate equipment sets for a character. Nothing is configured to go there automatically and nothing will be thrown out of it.
(But an item configured for another bag might get "claimed" from it by the "rightful bag".)


The mod dose not only contain the bags but (among some other changes) also the Cyseal Crafting Station (the new "homestead") which has 22 containers placed for even more different categories. The containers in the crafting station have no automatic functionality (beside the default functionality the engine has for containers.)
The purpose of the different containers in the station is to be receivers for automatic distribution of items that are sent to the homestead when choosing "Send to Homestead" from an item's right-click menu. When "Send to Homestead" is selected from the menu, items are sent to the homestead container they are configured for.
Items can also be manually added to any container, the containers will accept everything put into them and never throw out anything automatically.

Magic Bags cannot be sent to the homestead containers this way, instead, when choosing "Send to Homestead" is clicked from their right-click menu, the items inside the bag will be sent to homestead.


Some kind of FAQ:

How can I sell items from inside a bag ?
You cannot. You have to move items outside of the bags so that they show up in a trader window. Magic bag functionality must be turned off to do this. (As described above)

How can I disable magic bag functionality ?
- use the "Magic Bag Control" spell which is an on/off toggle skill
- drag the controller onto one of the magic bags which turns functionality off and empties the bag
- double click the controller or choose "Use" from it's right-click menu to turn off functionality and unload *all* magic bags

How can I re-enable magic bags functionality when it's turned off ?
Use the "Magic Bag Control" spell.

What happens with bags that are not carried but stored in the homestead (for example inside the tools cage) ?
Nothing happens, they stay there, possibly with all the content that was inside them at the point when the bag was moved to the container

What happens if I move a bag between characters ?
If the receiving character holds his own bag of the same type, the content of the received bag will be put inside this bag and the received bag will be empty and marked as "spare bag" for the receiver. It can be sent back to the original sender and will be the main bag for this character again.
If the receiver does *not* hold a bag of the same type, the received bag will be registered as his main bag of that type

What happens if a bag-receiving character has magic bag functionality turned off ?
The items that were insied the bag when the sender sent it, will be unloaded to the receiver's main inventory. As above, the received bag will either become the receiver's main or spare bag.

What happens if I choose "Send to Homestead" from a magic bag's right-click menu ?
The contents of the bag are sent to the homestead (and distributed according to their configuration). The bag itself stays inside the character inventory.

How can I send a magic bag itself to the homestead ?
You cannot. The bag can be manually moved to one of the containers however. (My advice is to put it inside the tools cage.) A bag can be moved into any container by the way, not only to the ones in the homestead.

Can I accidently sell magic bags ?
Unfortunately yes.
Be careful not to put a magic bag into a regular backpack inside your inventory because this is the only way to even accidently sell magic bags. The engine does nothing but hide quest items from trade windows, it does *not* prevent accidental selling of quest items. (As said above, the bags are marked as "quest items" internally in order to hide them in trade windows..)
Together with the trader cleanup functionality, bags can get lost !
So never put a magic bag (or any real quest item) into a regular backpack, it's dangerous.

I have magic bag functionality turned off but the arrow (grenade, potion, etc.) I receive still wanders into a magic bag. Can this be prevented ?
No. If the engine finds an instance of a stackable item inside the inventory (including the bags), it will try to fill the stack before opening a new stack. This functionality is engine built-in and cannot be disabled.

How do I know if functionality is turned on or off.# ?
By the status icon "Clean" to the right of a character's portrait. If functionality is off, the status is active, if functionality is on, there is no "Clean" status.

Can I craft from inside Magic Bags ?
Yes. In the Experiment tab of the crafting window, double click a bag and it's content will be shown instead of the main inventory. While inside a bag, there should be a button at the top of the crafting window to close and leave the bag again. (This is the same for
Crafting from the Recipe tab takes into account all items inside the main inventory including any bags inside it. Opening bags is irrelevant there.

Is there a better way to use special arrows (grenades, potions) than to open the main inventory, then open the bag and then use the item ?
Yes, simply drag the magic bag (e.g. the arrow quiver) onto your skill bar, Clicking the icon will then directly open the bag without consulting the main inventory.
Unfortunately, when moving a bag to another character, the engine will remove the bag from the skill bar. This is again a built-in functionality and cannot be prevented.


Why do some things seem a bit complicated ?
Because a modder can only work inside the restrictions of the given engine functionality and inside the given scripting API ... If the API were more complete, some more things could have been implemented and some more convenience would have been possible.



Please let me know if I there are still open questions, I'll try to answer them to my best knowledge ;-)