✨ Added asset pack support 📦

Quick 2hr draft - BUILDS, NOT TESTED.

A new file type "*.assetpack" was added to modcache with all the usual treatment:
- the file is recorded to the cache file (/cache/cache.json),
- it's searchable and selectable via UI (`LT_AssetPack`)
- can have a thumbnail (filename format '{}-mini.*'' where {} is the assetpack file name without extension)
- The file itself can be empty, recognized entries are `assetpack_name` (display name), `assetpack_description` (for display in selector UI) and `assetpack_author` (same syntax as in rig-def (aka .truck) file).

Assetpacks are referenced by the file name (standard approach) and can be used for both terrains and actors:
- Terrains: in .terrn2 file, add section `[AssetPacks]` followed by list of filenames (with extension, each on separate line) ending with `=` token, same as in `[Objects/Scripts]` sections - this is a quirk of the game.
- Actors: in the .truck file, use section `assetpacks` followed by list of filenames (with extension, each on separate line)

Note that, unlike any other mod, assetpacks aren't loaded to their own resource group but rather to the resoruce group of the mod which requested them. Therefore try to name all resources in an unique way to avoid clashes.

Author: ohlidalp

source/main/Application.h

@@ -261,7 +261,7 @@ enum VisibilityMasks
     HIDE_MIRROR       = BITMASK(3),
 };
 
-enum LoaderType //!< Operation mode for GUI::MainSelector
+enum LoaderType //!< Search mode for `ModCache::Query()` & Operation mode for `GUI::MainSelector`
 {
     LT_None,
     LT_Terrain,   // Invocable from GUI; No script alias, used in main menu
@@ -278,6 +278,7 @@ enum LoaderType //!< Operation mode for GUI::MainSelector
     LT_AllBeam,   // Invocable from GUI; Script "all",  ext: truck car boat airplane train load
     LT_AddonPart, // No script alias, invoked manually, ext: addonpart
     LT_Tuneup,    // No script alias, invoked manually, ext: tuneup
+    LT_AssetPack, // No script alias, invoked manually, ext: assetpack
 };
 
 // ------------------------------------------------------------------------------------------------

source/main/GameContext.cpp

@@ -126,7 +126,7 @@ bool GameContext::LoadTerrain(std::string const& filename_part)
     // Init resources
     App::GetCacheSystem()->LoadResource(terrn_entry);
 
-    // Load the terrain
+    // Load the terrain def file
     Terrn2Def terrn2;
     std::string const& filename = terrn_entry->fname;
     try
@@ -145,6 +145,35 @@ bool GameContext::LoadTerrain(std::string const& filename_part)
         return false;
     }
 
+    // Load asset packs into the terrain-bundle's resource group (quick & dirty approach).
+    // See also `ContentManager::resourceCollision()` - we always keep the original file and dump the colliding one.
+    for (std::string const& assetpack_filename: terrn2.assetpack_files)
+    {
+        CacheEntryPtr assetpack_entry = App::GetCacheSystem()->FindEntryByFilename(LT_AssetPack, /*partial=*/false, assetpack_filename);
+        if (assetpack_entry)
+        {
+            try
+            {
+                Ogre::ResourceGroupManager::getSingleton().addResourceLocation(
+                    assetpack_entry->resource_bundle_path, // name (source)
+                    assetpack_entry->resource_bundle_type, // type (source)
+                    terrn_entry->resource_group, // resGroup (target)
+                    false, // recursive
+                    true); // readOnly
+            }
+            catch (std::exception const& e)
+            {
+                App::GetConsole()->putMessage(Console::CONSOLE_MSGTYPE_TERRN, Console::CONSOLE_SYSTEM_ERROR,
+                    fmt::format(_L("Failed to load asset pack '{}': {}"), assetpack_entry->fname, e.what()));
+            }
+        }
+        else
+        {
+            App::GetConsole()->putMessage(Console::CONSOLE_MSGTYPE_TERRN, Console::CONSOLE_SYSTEM_WARNING, 
+                fmt::format(_L("Asset pack '{}' requested by terrain '{}' not found"), assetpack_filename, terrn2.name));
+        }
+    }
+
     // CAUTION - the global instance must be set during init! Needed by:
     // * GameScript::spawnObject()
     // * ProceduralManager

source/main/physics/ActorManager.cpp

@@ -90,6 +90,7 @@ ActorPtr ActorManager::CreateNewActor(ActorSpawnRequest rq, RigDef::DocumentPtr
     ActorSpawner spawner;
     spawner.ConfigureSections(actor->m_section_config, def);
     spawner.ConfigureAddonParts(actor->m_working_tuneup_def);
+    spawner.ConfigureAssetPacks(actor, def);
     spawner.ProcessNewActor(actor, rq, def);
 
     if (App::diag_actor_dump->getBool())

source/main/physics/ActorSpawner.cpp

@@ -142,6 +142,43 @@ void ActorSpawner::ConfigureAddonParts(TuneupDefPtr& tuneup_def)
     }
 }
 
+void ActorSpawner::ConfigureAssetPacks(ActorPtr actor, RigDef::DocumentPtr def)
+{
+    for (auto& module: m_selected_modules)
+    {
+        for (RigDef::Assetpack const& assetpack: module->assetpacks)
+        {
+            CacheEntryPtr assetpack_entry = App::GetCacheSystem()->FindEntryByFilename(LT_AssetPack, /*partial=*/false, assetpack.filename);
+            if (assetpack_entry)
+            {
+                // Load asset packs into the actor-bundle's resource group (quick & dirty approach).
+                // See also `ContentManager::resourceCollision()` - we always keep the original file and dump the colliding one.
+                try
+                {
+                    Ogre::ResourceGroupManager::getSingleton().addResourceLocation(
+                        assetpack_entry->resource_bundle_path, // name (source)
+                        assetpack_entry->resource_bundle_type, // type (source)
+                        actor->getUsedActorEntry()->resource_group, // resGroup (target)
+                        false, // recursive
+                        true); // readOnly
+
+                    Ogre::ResourceGroupManager::getSingleton().initialiseResourceGroup(
+                        actor->getUsedActorEntry()->resource_group);
+                }
+                catch (std::exception const& e)
+                {
+                    this->AddMessage(Message::TYPE_ERROR, fmt::format(_L("Failed to load asset pack '{}': {}"), assetpack.filename, e.what()));
+                }
+            }
+            else
+            {
+                this->AddMessage(Message::TYPE_WARNING, fmt::format(_L("Asset pack '{}' requested by actor '{}' not found"),
+                    assetpack.filename, actor->getUsedActorEntry()->fname));
+            }
+        }
+    }
+}
+
 void ActorSpawner::CalcMemoryRequirements(ActorMemoryRequirements& req, RigDef::Document::Module* module_def)
 {
     // 'nodes'

source/main/physics/ActorSpawner.h

@@ -96,6 +96,7 @@ class ActorSpawner
     /// @{
     void                           ConfigureSections(Ogre::String const & sectionconfig, RigDef::DocumentPtr def);
     void                           ConfigureAddonParts(TuneupDefPtr& tuneup_def);
+    void                           ConfigureAssetPacks(ActorPtr actor, RigDef::DocumentPtr def);
     void                           ProcessNewActor(ActorPtr actor, ActorSpawnRequest rq, RigDef::DocumentPtr def);
     static void                    SetupDefaultSoundSources(ActorPtr const& actor);
     /// @}

source/main/resources/CacheSystem.cpp

@@ -138,6 +138,7 @@ CacheSystem::CacheSystem()
     m_known_extensions.push_back("skin");
     m_known_extensions.push_back("addonpart");
     m_known_extensions.push_back("tuneup");
+    m_known_extensions.push_back("assetpack");
 }
 
 void CacheSystem::LoadModCache(CacheValidity validity)
@@ -719,6 +720,12 @@ void CacheSystem::AddFile(String group, Ogre::FileInfo f, String ext)
                 new_entries.push_back(entry);
             }
         }
+        else if (ext == "assetpack")
+        {
+            CacheEntryPtr entry = new CacheEntry();
+            FillAssetPackDetailInfo(entry, ds);
+            new_entries.push_back(entry);
+        }
         else
         {
             CacheEntryPtr entry = new CacheEntry();
@@ -1163,6 +1170,38 @@ void CacheSystem::FillAddonPartDetailInfo(CacheEntryPtr &entry, Ogre::DataStream
     }
 }
 
+void CacheSystem::FillAssetPackDetailInfo(CacheEntryPtr &entry, Ogre::DataStreamPtr ds)
+{
+    GenericDocumentPtr doc = new GenericDocument();
+    BitMask_t options = GenericDocument::OPTION_ALLOW_SLASH_COMMENTS | GenericDocument::OPTION_ALLOW_NAKED_STRINGS;
+    doc->loadFromDataStream(ds, options);
+
+    GenericDocContextPtr ctx = new GenericDocContext(doc);
+    while (!ctx->endOfFile())
+    {
+        if (ctx->isTokKeyword() && ctx->getTokKeyword() == "assetpack_name")
+        {
+            entry->dname = ctx->getTokString(1);
+        }
+        else if (ctx->isTokKeyword() && ctx->getTokKeyword() == "assetpack_description")
+        {
+            entry->description = ctx->getTokString(1);
+        }
+        else if (ctx->isTokKeyword() && ctx->getTokKeyword() == "assetpack_author")
+        {
+            int n = ctx->countLineArgs();
+            AuthorInfo author;
+            if (n > 1) { author.type             = ctx->getTokString(1); }
+            if (n > 2) { author.id               = (int)ctx->getTokFloat(2); }
+            if (n > 3) { author.name             = ctx->getTokString(3); }
+            if (n > 4) { author.email            = ctx->getTokString(4); }
+            entry->authors.push_back(author);
+        }
+
+        ctx->seekNextLine();
+    }
+}
+
 void CacheSystem::FillTuneupDetailInfo(CacheEntryPtr &entry, TuneupDefPtr& tuneup_def)
 {
     if (!tuneup_def->author_name.empty())
@@ -1863,6 +1902,8 @@ size_t CacheSystem::Query(CacheQuery& query)
             add = (query.cqy_filter_type == LT_AddonPart);
         else if (entry->fext == "tuneup")
             add = (query.cqy_filter_type == LT_Tuneup);
+        else if (entry->fext == "assetpack")
+            add = (query.cqy_filter_type == LT_AssetPack);
         else if (entry->fext == "truck")
             add = (query.cqy_filter_type == LT_AllBeam || query.cqy_filter_type == LT_Vehicle || query.cqy_filter_type == LT_Truck);
         else if (entry->fext == "car")

source/main/resources/CacheSystem.h

@@ -46,7 +46,7 @@ namespace RoR {
 
 struct AuthorInfo
 {
-    int id;
+    int id = -1;
     Ogre::String type;
     Ogre::String name;
     Ogre::String email;
@@ -350,6 +350,7 @@ class CacheSystem
     void FillSkinDetailInfo(CacheEntryPtr &entry, std::shared_ptr<SkinDef>& skin_def);
     void FillAddonPartDetailInfo(CacheEntryPtr &entry, Ogre::DataStreamPtr ds);
     void FillTuneupDetailInfo(CacheEntryPtr &entry, TuneupDefPtr& tuneup_def);
+    void FillAssetPackDetailInfo(CacheEntryPtr &entry, Ogre::DataStreamPtr ds);
     /// @}
 
     void GenerateHashFromFilenames();         //!< For quick detection of added/removed content

source/main/resources/ContentManager.cpp

@@ -330,7 +330,9 @@ bool ContentManager::resourceCollision(Ogre::Resource* resource, Ogre::ResourceM
 {
     // RoR loads each resource bundle (see CacheSystem.h for info)
     // into dedicated resource group outside the global pool [see CacheSystem::LoadResource()]
-    // This means resource collision is entirely content creator's fault.
+    // This means resource collision is pretty much content creator's fault, with 2 exceptions:
+    // * asset packs (introduced 2024) are mixed into the requesting mod's resource group.
+    // * bundled resources (e.g. beamobjects.zip) are also mixed into the mod's resource group.
     RoR::LogFormat("[RoR|ContentManager] Skipping resource with duplicate name: '%s' (origin: '%s')",
         resource->getName().c_str(), resource->getOrigin().c_str());
     return false; // Instruct OGRE to drop the new resource and keep the original.

source/main/resources/rig_def_fileformat/RigDef_File.h

@@ -70,6 +70,7 @@ enum class Keyword
     AIRBRAKES,
     ANIMATORS,
     ANTILOCKBRAKES,
+    ASSETPACKS,
     AUTHOR,
     AXLES,
     BACKMESH,
@@ -399,6 +400,11 @@ struct AeroAnimator // used by Animator
     unsigned int engine_idx = 0u;
 };
 
+struct Assetpack
+{
+    std::string filename;
+};
+
 struct BaseWheel
 {
     float width = 0.f;
@@ -1473,6 +1479,7 @@ struct Document
         std::vector<Airbrake>              airbrakes;
         std::vector<Animator>              animators;
         std::vector<AntiLockBrakes>        antilockbrakes;
+        std::vector<Assetpack>             assetpacks;
         std::vector<Author>                author;
         std::vector<Axle>                  axles;
         std::vector<Beam>                  beams;

source/main/resources/rig_def_fileformat/RigDef_Parser.cpp

@@ -235,6 +235,7 @@ void Parser::ProcessCurrentLine()
     {
         case Keyword::AIRBRAKES:            this->ParseAirbrakes();               return;
         case Keyword::ANIMATORS:            this->ParseAnimator();                return;
+        case Keyword::ASSETPACKS:           this->ParseAssetpacks();              return;
         case Keyword::AXLES:                this->ParseAxles();                   return;
         case Keyword::BEAMS:                this->ParseBeams();                   return;
         case Keyword::BRAKES:               this->ParseBrakes();                  return;
@@ -1633,6 +1634,17 @@ void Parser::ParseAirbrakes()
     m_current_module->airbrakes.push_back(airbrake);
 }
 
+void Parser::ParseAssetpacks()
+{
+    if (! this->CheckNumArguments(1)) { return; }
+
+    Assetpack assetpack;
+
+    assetpack.filename = this->GetArgStr(0);
+
+    m_current_module->assetpacks.push_back(assetpack);
+}
+
 void Parser::ParseVideoCamera()
 {
     if (! this->CheckNumArguments(19)) { return; }

source/main/resources/rig_def_fileformat/RigDef_Parser.h

@@ -116,6 +116,7 @@ class Parser
     void ParseAirbrakes();
     void ParseAnimator();
     void ParseAntiLockBrakes();
+    void ParseAssetpacks();
     void ParseAuthor();
     void ParseAxles();
     void ParseBeams();

source/main/resources/rig_def_fileformat/RigDef_Regexes.h

@@ -122,6 +122,7 @@ namespace Regexes
     E_KEYWORD_BLOCK("airbrakes")       /* Position 2 */           \
     E_KEYWORD_BLOCK("animators")       /* Position 3 etc... */    \
     E_KEYWORD_INLINE("AntiLockBrakes")                            \
+    E_KEYWORD_BLOCK("assetpacks")                                 \
     E_KEYWORD_INLINE("author")                                    \
     E_KEYWORD_BLOCK("axles")                                      \
     E_KEYWORD_BLOCK("backmesh")                                   \

source/main/resources/terrn2_fileformat/Terrn2FileFormat.cpp

@@ -112,6 +112,15 @@ bool Terrn2Parser::LoadTerrn2(Terrn2Def& def, Ogre::DataStreamPtr &ds)
         }
     }
 
+    if (file.HasSection("AssetPacks"))
+    {
+        for (auto& assetpack: file.getSettings("AssetPacks"))
+        {
+            Ogre::String assetpack_filename = SanitizeUtf8String(assetpack.first);
+            def.as_files.push_back(TrimStr(assetpack_filename));
+        }
+    }
+
     this->ProcessTeleport(def, &file);
 
     return true;

source/main/resources/terrn2_fileformat/Terrn2FileFormat.h

@@ -62,6 +62,7 @@ struct Terrn2Def
     std::list<Terrn2Author>  authors;
     std::list<std::string>   tobj_files;
     std::list<std::string>   as_files;
+    std::list<std::string>   assetpack_files;
     std::list<Terrn2Telepoint> telepoints;
     std::string              caelum_config;
     int                      caelum_fog_start;