feat: explain storage logistics optimizations in dictionary of spirits

Author: klikli-dev

src/generated/resources/assets/occultism/lang/en_us.json

@@ -732,6 +732,22 @@
   "book.occultism.dictionary_of_spirits.storage.storage_stabilizer.spotlight.text": "Storage Stabilizers increase the storage space in the storage dimension of the storage actuator. The higher the tier of the stabilizer, the more additional storage it provides. The following entries will show you how to craft each tier.\n\\\n\\\n",
   "book.occultism.dictionary_of_spirits.storage.storage_stabilizer.upgrade.text": "It is **safe to destroy a storage stabilizer** to upgrade it. The items in the [Storage Actuator](entry://storage/storage_controller) will not be lost or dropped - you simply cannot add new items until you add enough storage stabilizers to have free slots again.\n",
   "book.occultism.dictionary_of_spirits.storage.storage_stabilizer.upgrade.title": "Upgrading",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation.description": "Inserting and extracting items from the Storage Actuator",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation.extraction.text": "Extracting items can lead to performance issues, especially when pipes with Item Filters are used, because then the entire huge storage is searched for these items one by one.\n\\\n\\\nTo *massively* improve performance, use Transporter Spirits to extract from the Storage Actuator or Stable Wormhole. Even if the Spirit deposits into a chest right next to the storage system, and a pipe extracts from that chest, the performance is **much** better than if a pipe extracts directly.\n",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation.extraction.title": "Extracting Items",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation.insertion.text": "When inserting items, you do not need to do anything, the Storage Actuator will maximize performance automatically for you. It is safe to insert high amounts of items at high frequencies without negative impact on game performance.\n",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation.insertion.title": "Inserting Items",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation.intro.text": "The Storage Actuator behaves much like a big chest or shulker box. That means, hoppers and pipes can insert and extract items.\n",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation.intro.title": "Storage Logistics",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation.name": "Storage Logistics",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation.performance.text": "Due to the potentially huge amount of items in the storage system, it is good to consider some performance aspects, otherwise your system might slow down your game or even a server you are playing on.\n",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation.performance.title": "Performance",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation_theurgy.description": "Inserting and extracting items from the Storage Actuator using Theurgy Logistics",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation_theurgy.extraction.text": "Once again, item extraction is the critical issue for performance.\n\\\n\\\nTo make use of the performance optimization, use a [](item://theurgy:logistics_item_extractor) and apply a [](item://theurgy:list_filter) to extract the desired items.\n\\\n\\\nThe Theurgy Guidebook \"The Hermetica\" has a chapter on Theurgy mercurial logistics and how to use them to insert and extract items.\n",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation_theurgy.extraction.title": "Extracting Items",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation_theurgy.intro.text": "Much like transporter Spirits, Theurgy Mercurial Logistics systems are optimized to work with the Storage Actuator and Stable Wormholes.\n",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation_theurgy.intro.title": "Theurgy Storage Integration",
+  "book.occultism.dictionary_of_spirits.storage.storage_system_automation_theurgy.name": "Theurgy Storage Integration",
   "book.occultism.dictionary_of_spirits.summoning_rituals.afrit_essence.intro.text": "[](item://occultism:afrit_essence) is required to safely call on the more powerful spirits, commonly used in the form of red chalk. To obtain the essence, an [#](ad03fc)Afrit[#]() needs to be summoned unbound into this plane, and killed. Be warned that this is no simple endeavour, and unbound spirit presents great danger to all nearby.\n",
   "book.occultism.dictionary_of_spirits.summoning_rituals.afrit_essence.intro.title": "Afrit Essence",
   "book.occultism.dictionary_of_spirits.summoning_rituals.afrit_essence.name": "Afrit Essence",

src/generated/resources/data/occultism/modonomicon/books/dictionary_of_spirits/entries/storage/storage_system_automation.json

@@ -0,0 +1,69 @@
+{
+  "background_u_index": 0,
+  "background_v_index": 0,
+  "category": "occultism:storage",
+  "description": "",
+  "hide_while_locked": false,
+  "icon": {
+    "item": "minecraft:hopper"
+  },
+  "name": "book.occultism.dictionary_of_spirits.storage.storage_system_automation.name",
+  "pages": [
+    {
+      "type": "modonomicon:text",
+      "anchor": "",
+      "condition": {
+        "type": "modonomicon:none"
+      },
+      "show_title_separator": true,
+      "text": "book.occultism.dictionary_of_spirits.storage.storage_system_automation.intro.text",
+      "title": "book.occultism.dictionary_of_spirits.storage.storage_system_automation.intro.title",
+      "use_markdown_in_title": false
+    },
+    {
+      "type": "modonomicon:text",
+      "anchor": "",
+      "condition": {
+        "type": "modonomicon:none"
+      },
+      "show_title_separator": true,
+      "text": "book.occultism.dictionary_of_spirits.storage.storage_system_automation.performance.text",
+      "title": "book.occultism.dictionary_of_spirits.storage.storage_system_automation.performance.title",
+      "use_markdown_in_title": false
+    },
+    {
+      "type": "modonomicon:text",
+      "anchor": "",
+      "condition": {
+        "type": "modonomicon:none"
+      },
+      "show_title_separator": true,
+      "text": "book.occultism.dictionary_of_spirits.storage.storage_system_automation.extraction.text",
+      "title": "book.occultism.dictionary_of_spirits.storage.storage_system_automation.extraction.title",
+      "use_markdown_in_title": false
+    },
+    {
+      "type": "modonomicon:text",
+      "anchor": "",
+      "condition": {
+        "type": "modonomicon:none"
+      },
+      "show_title_separator": true,
+      "text": "book.occultism.dictionary_of_spirits.storage.storage_system_automation.insertion.text",
+      "title": "book.occultism.dictionary_of_spirits.storage.storage_system_automation.insertion.title",
+      "use_markdown_in_title": false
+    }
+  ],
+  "parents": [
+    {
+      "draw_arrow": true,
+      "entry": "occultism:storage/storage_controller",
+      "line_enabled": true,
+      "line_reversed": false
+    }
+  ],
+  "show_when_any_parent_unlocked": false,
+  "sort_number": -1,
+  "x": -6,
+  "y": -2
+}

src/generated/resources/data/occultism/modonomicon/books/dictionary_of_spirits/entries/storage/storage_system_automation_theurgy.json

@@ -0,0 +1,51 @@
+{
+  "background_u_index": 0,
+  "background_v_index": 0,
+  "category": "occultism:storage",
+  "condition": {
+    "type": "modonomicon:mod_loaded",
+    "mod_id": "theurgy"
+  },
+  "description": "",
+  "hide_while_locked": false,
+  "icon": {
+    "item": "theurgy:list_filter"
+  },
+  "name": "book.occultism.dictionary_of_spirits.storage.storage_system_automation_theurgy.name",
+  "pages": [
+    {
+      "type": "modonomicon:text",
+      "anchor": "",
+      "condition": {
+        "type": "modonomicon:none"
+      },
+      "show_title_separator": true,
+      "text": "book.occultism.dictionary_of_spirits.storage.storage_system_automation_theurgy.intro.text",
+      "title": "book.occultism.dictionary_of_spirits.storage.storage_system_automation_theurgy.intro.title",
+      "use_markdown_in_title": false
+    },
+    {
+      "type": "modonomicon:text",
+      "anchor": "",
+      "condition": {
+        "type": "modonomicon:none"
+      },
+      "show_title_separator": true,
+      "text": "book.occultism.dictionary_of_spirits.storage.storage_system_automation_theurgy.extraction.text",
+      "title": "book.occultism.dictionary_of_spirits.storage.storage_system_automation_theurgy.extraction.title",
+      "use_markdown_in_title": false
+    }
+  ],
+  "parents": [
+    {
+      "draw_arrow": true,
+      "entry": "occultism:storage/storage_system_automation",
+      "line_enabled": true,
+      "line_reversed": false
+    }
+  ],
+  "show_when_any_parent_unlocked": false,
+  "sort_number": -1,
+  "x": -6,
+  "y": -4
+}

src/main/java/com/klikli_dev/occultism/datagen/OccultismBookProvider.java

@@ -3993,6 +3993,7 @@ private BookEntryModel makeCraftStorageSystemEntry(CategoryEntryMap entryMap, ch
                 );
     }
 
+
     private BookEntryModel makeCraftDimensionalMatrixEntry(CategoryEntryMap entryMap, char icon) {
         this.context().entry("craft_dimensional_matrix");
 
@@ -4432,6 +4433,7 @@ private BookEntryModel makeCraftOtherworldGogglesEntry(CategoryEntryMap entryMap
                         gogglesRecipe
                 );
     }
+
     private BookEntryModel makeCraftWildTrimEntry(CategoryEntryMap entryMap, char icon) {
         this.context().entry("craft_wild_trim");
 
@@ -4959,6 +4961,7 @@ private BookEntryModel makeHordeHuskEntry(CategoryEntryMap entryMap, char icon)
                         description
                 );
     }
+
     private BookEntryModel makeHordeDrownedEntry(CategoryEntryMap entryMap, char icon) {
         this.context().entry("horde_drowned");
         this.lang().add(this.context().entryName(), "Wild Horde Drowned");
@@ -4994,6 +4997,7 @@ private BookEntryModel makeHordeDrownedEntry(CategoryEntryMap entryMap, char ico
                         description
                 );
     }
+
     private BookEntryModel makeHordeCreeperEntry(CategoryEntryMap entryMap, char icon) {
         this.context().entry("horde_creeper");
         this.lang().add(this.context().entryName(), "Wild Horde Creeper");
@@ -5029,6 +5033,7 @@ private BookEntryModel makeHordeCreeperEntry(CategoryEntryMap entryMap, char ico
                         description
                 );
     }
+
     private BookEntryModel makeHordeSilverfishEntry(CategoryEntryMap entryMap, char icon) {
         this.context().entry("horde_silverfish");
         this.lang().add(this.context().entryName(), "Wild Horde Silverfish");
@@ -5064,6 +5069,7 @@ private BookEntryModel makeHordeSilverfishEntry(CategoryEntryMap entryMap, char
                         description
                 );
     }
+
     private BookEntryModel makeHordeIllagerEntry(CategoryEntryMap entryMap, char icon) {
         this.context().entry("horde_illager");
         this.lang().add(this.context().entryName(), "Mini Illager Invasion");
@@ -5099,6 +5105,7 @@ private BookEntryModel makeHordeIllagerEntry(CategoryEntryMap entryMap, char ico
                         description
                 );
     }
+
     private BookEntryModel makePossessWeakBreezeEntry(CategoryEntryMap entryMap, char icon) {
         this.context().entry("possess_weak_breeze");
         this.lang().add(this.context().entryName(), "The first key");
@@ -5134,6 +5141,7 @@ private BookEntryModel makePossessWeakBreezeEntry(CategoryEntryMap entryMap, cha
                         description
                 );
     }
+
     private BookEntryModel makePossessBreezeEntry(CategoryEntryMap entryMap, char icon) {
         this.context().entry("possess_breeze");
         this.lang().add(this.context().entryName(), "In the chamber");
@@ -5169,6 +5177,7 @@ private BookEntryModel makePossessBreezeEntry(CategoryEntryMap entryMap, char ic
                         description
                 );
     }
+
     private BookEntryModel makePossessStrongBreezeEntry(CategoryEntryMap entryMap, char icon) {
         this.context().entry("possess_strong_breeze");
         this.lang().add(this.context().entryName(), "Glorious Vault");
@@ -5211,8 +5220,9 @@ private BookCategoryModel makeStorageCategory() {
 
         var entryMap = ModonomiconAPI.get().getEntryMap();
         entryMap.setMap(
+                "_______ṡ___________________",
                 "___________________________",
-                "_________w_r_______________",
+                "_______ș_w_r_______________",
                 "___________________________",
                 "_____0_c___s_1_2_3_4________",
                 "___________________________",
@@ -5226,6 +5236,14 @@ private BookCategoryModel makeStorageCategory() {
         var storageController = this.makeStorageControllerEntry(entryMap, 'c');
         storageController.withParent(BookEntryParentModel.create(overview.getId()));
 
+        var storageSystemAutomation = this.makeStorageSystemAutomationEntry(entryMap, 'ș');
+        storageSystemAutomation.withParent(BookEntryParentModel.create(storageController.getId()));
+
+        var storageSystemAutomationTheurgy = this.makeStorageSystemAutomationTheurgyEntry(entryMap, 'ṡ');
+        storageSystemAutomationTheurgy.withParent(BookEntryParentModel.create(storageSystemAutomation.getId()));
+        storageSystemAutomationTheurgy.withCondition(BookModLoadedConditionModel.create().withModId("theurgy"));
+
+
         var storageStabilizer = this.makeStorageStabilizerEntry(entryMap, 's');
         storageStabilizer.withParent(BookEntryParentModel.create(storageController.getId()));
 
@@ -5275,6 +5293,8 @@ private BookCategoryModel makeStorageCategory() {
                 .withEntries(
                         overview,
                         storageController,
+                        storageSystemAutomation,
+                        storageSystemAutomationTheurgy,
                         storageStabilizer,
                         craftStabilizerTier1,
                         craftStabilizerTier2,
@@ -5377,6 +5397,112 @@ private BookEntryModel makeStorageControllerEntry(CategoryEntryMap entryMap, cha
                 );
     }
 
+    private BookEntryModel makeStorageSystemAutomationEntry(CategoryEntryMap entryMap, char icon) {
+        this.context().entry("storage_system_automation");
+        this.lang().add(this.context().entryName(), "Storage Logistics");
+        this.lang().add(this.context().entryDescription(), "Inserting and extracting items from the Storage Actuator");
+
+        this.context().page("intro");
+        var intro = BookTextPageModel.create()
+                .withTitle(this.context().pageTitle())
+                .withText(this.context().pageText());
+
+        this.lang().add(this.context().pageTitle(), "Storage Logistics");
+        this.lang().add(this.context().pageText(),
+                """
+                        The Storage Actuator behaves much like a big chest or shulker box. That means, hoppers and pipes can insert and extract items.
+                        """);
+
+        this.context().page("performance");
+        var performance = BookTextPageModel.create()
+                .withTitle(this.context().pageTitle())
+                .withText(this.context().pageText());
+
+        this.lang().add(this.context().pageTitle(), "Performance");
+        this.lang().add(this.context().pageText(),
+                """
+                        Due to the potentially huge amount of items in the storage system, it is good to consider some performance aspects, otherwise your system might slow down your game or even a server you are playing on.
+                        """);
+
+        this.context().page("extraction");
+        var extraction = BookTextPageModel.create()
+                .withTitle(this.context().pageTitle())
+                .withText(this.context().pageText());
+
+        this.lang().add(this.context().pageTitle(), "Extracting Items");
+        this.lang().add(this.context().pageText(),
+                """
+                        Extracting items can lead to performance issues, especially when pipes with Item Filters are used, because then the entire huge storage is searched for these items one by one.
+                        \\
+                        \\
+                        To *massively* improve performance, use Transporter Spirits to extract from the Storage Actuator or Stable Wormhole. Even if the Spirit deposits into a chest right next to the storage system, and a pipe extracts from that chest, the performance is **much** better than if a pipe extracts directly.
+                        """);
+
+        this.context().page("insertion");
+        var insertion = BookTextPageModel.create()
+                .withTitle(this.context().pageTitle())
+                .withText(this.context().pageText());
+
+        this.lang().add(this.context().pageTitle(), "Inserting Items");
+        this.lang().add(this.context().pageText(),
+                """
+                        When inserting items, you do not need to do anything, the Storage Actuator will maximize performance automatically for you. It is safe to insert high amounts of items at high frequencies without negative impact on game performance.
+                        """);
+
+
+        return BookEntryModel.create(this.modLoc(this.context().categoryId() + "/" + this.context().entryId()), this.context().entryName())
+                .withIcon(Items.HOPPER)
+                .withLocation(entryMap.get(icon))
+                .withPages(
+                        intro,
+                        performance,
+                        extraction,
+                        insertion
+                );
+    }
+
+    private BookEntryModel makeStorageSystemAutomationTheurgyEntry(CategoryEntryMap entryMap, char icon) {
+        this.context().entry("storage_system_automation_theurgy");
+        this.lang().add(this.context().entryName(), "Theurgy Storage Integration");
+        this.lang().add(this.context().entryDescription(), "Inserting and extracting items from the Storage Actuator using Theurgy Logistics");
+
+        this.context().page("intro");
+        var intro = BookTextPageModel.create()
+                .withTitle(this.context().pageTitle())
+                .withText(this.context().pageText());
+
+        this.lang().add(this.context().pageTitle(), "Theurgy Storage Integration");
+        this.lang().add(this.context().pageText(),
+                """
+                        Much like transporter Spirits, Theurgy Mercurial Logistics systems are optimized to work with the Storage Actuator and Stable Wormholes.
+                        """);
+
+        this.context().page("extraction");
+        var extraction = BookTextPageModel.create()
+                .withTitle(this.context().pageTitle())
+                .withText(this.context().pageText());
+
+        this.lang().add(this.context().pageTitle(), "Extracting Items");
+        this.lang().add(this.context().pageText(),
+                """
+                        Once again, item extraction is the critical issue for performance.
+                        \\
+                        \\
+                        To make use of the performance optimization, use a [](item://theurgy:logistics_item_extractor) and apply a [](item://theurgy:list_filter) to extract the desired items.
+                        \\
+                        \\
+                        The Theurgy Guidebook "The Hermetica" has a chapter on Theurgy mercurial logistics and how to use them to insert and extract items.
+                        """);
+
+        return BookEntryModel.create(this.modLoc(this.context().categoryId() + "/" + this.context().entryId()), this.context().entryName())
+                .withIcon(ItemRegistry.LIST_FILTER.get())
+                .withLocation(entryMap.get(icon))
+                .withPages(
+                        intro,
+                        extraction
+                );
+    }
+
     private BookEntryModel makeStorageStabilizerEntry(CategoryEntryMap entryMap, char icon) {
         this.context().entry("storage_stabilizer");