Document starpak path things for RePak

docs/source/guides/rpakmodding.rst

@@ -1,6 +1,21 @@
 RPak Modding
 ============
 
+What Are RPaks/Starpaks?
+^^^^^^^^^^^^^^^^^^^^^^^^
+
+.rpak files are a file format created by Respawn as the main way to store and load in-game assets,
+such as textures, materials, datatables, animation recordings, etc. The assets in the .rpak file are kept stored in memory
+as long as the .rpak file is loaded.
+
+.starpak files are another file format created by Respawn to complement the .rpak file format.
+They contain streamed asset data, saving hardware resources by only loading the data when needed.
+The most common example of streamed asset data is high resolution textures. The low resolution versions are kept permanently loaded
+in a .rpak file, whilst the higher resolution versions are loaded as needed.
+
+What can RPak mods do?
+----------------------
+
 RPak mods can be used for the following:
 
 * Custom UI
@@ -119,6 +134,7 @@ Below is an example of a map file that creates an RPak called ``example.rpak`` w
         "name":"example",
         "assetsDir":"../assets",
         "outputDir":"../rpaks",
+        "starpakPath": "example.starpak"
         "version": 7,
         "files":[
             {
@@ -131,6 +147,7 @@ Below is an example of a map file that creates an RPak called ``example.rpak`` w
 - ``name``: the name of the file that gets created by RePak.
 - ``assetsDir``: the folder that RePak bases the file path on when looking for textures.
 - ``outputDir``: the folder that RePak will put the files that it creates in.
+- ``starpakPath``: the path of the starpak file for streaming textures.
 - ``version``: the RPak version RePak will use when creating the RPaks. **Version 7 is Titanfall 2, version 8 is Apex Legends.**
 - ``files``: an array of all of the assets that RePak will create in the RPak.
 - ``$type``: the type of asset that this asset is, use ``txtr`` for textures.
@@ -228,6 +245,7 @@ The file structure of your ``paks`` folder should be similar to this:
 
     paks
     ├── example.rpak
+    ├── example.starpak
     └── rpak.json
 
 - ``example.rpak``: this is the RPak file that you made.

docs/source/repak/assets/texture.rst

@@ -23,8 +23,8 @@ The image used by a texture must be in the .dds format and must be in one of the
 Examples:
 =========
 
-1. Basic Texture Asset
-----------------------
+1. Basic Texture Asset - No streaming
+-------------------------------------
 
 .. code-block:: json
 
@@ -38,7 +38,25 @@ Examples:
     The image file in this texture asset will be called ``test_texture.dds`` and will be at ``<ASSETSDIR>/textures/models/humans/test_texture.dds``
 
 .. note::
-    This texture will not be stored in a .starpak file, and all mip levels will be stored in the .rpak file
+    Because ``disableStreaming`` is ``true``, this texture will not be stored in a .starpak file, and all mip levels will be stored in the .rpak file
+
+2. Streamed Texture Asset
+-------------------------------------
+
+.. code-block:: json
+
+    {
+        "$type": "txtr",
+        "path": "textures/models/humans/test_texture_2",
+        "starpakPath": "test_texture_2.starpak"
+    }
+
+.. note::
+    The image file in this texture asset will be called ``test_texture_2.dds`` and will be at ``<ASSETSDIR>/textures/models/humans/test_texture_2.dds``
+
+.. note::
+    Because ``disableStreaming`` is not present, this texture will have it's higher resolution mip levels stored in ``test_texture_2.starpak``, as defined by the ``starpakPath``.
+    It will not use the default ``starpakPath`` if one is defined outside of the ``files`` array
 
 Asset Structure:
 ================
@@ -75,6 +93,28 @@ The ``path`` field must start with ``textures/`` and must not end with a file ex
     ``Attempted to add txtr asset '%s' that was not using a supported DDS type. Exiting...``
     where ``%s`` is the ``path`` field of the texture.
 
+``starpakPath``
+---------------
+
+The ``starpakPath`` field of a texture asset determines the path of the starpak in which the higher resolution mip levels should be stored.
+
+If no ``starpakPath`` value is specified, RePak will default to using the default ``starpakPath``, defined at file scope in the map file.
+
+The ``starpakPath`` field should be a string, and importantly, should end in ``.starpak``. 
+
+.. note::
+    If the starpak name ends in ``_hotswap.starpak`` (e.g. ``my_thing_hotswap.starpak``) then Titanfall 2 will view it as optional.
+    This allows the starpak to be moved, removed, or replaced while the game is running and streaming the texture.
+    This can be useful for debugging.
+
+.. error::
+    If the ``starpakPath`` is not present, and no ``starpakPath`` is defined at file scope, RePak will output the following error to the console.
+
+    ``attempted to add asset '%s' as a streaming asset, but no starpak files were available.
+    to fix: add 'starpakPath' as an rpak-wide variable
+    or: add 'starpakPath' as an asset specific variable``
+    where %s is the ``path`` of the texture asset
+
 ``disableStreaming``
 --------------------
 

docs/source/repak/map.rst

@@ -28,8 +28,8 @@ Examples:
 
     It also will have the name ``new.rpak`` and will be created in the ``./build`` folder.
 
-2. Single Texture
--------------------
+2. Single Texture + Single Starpak
+----------------------------------
 
 ``example2.json``
 
@@ -40,6 +40,7 @@ Examples:
         "assetsDir": "../depot",
         "outputDir": "../output",
         "version": 7,
+        "starpakPath": "example2.starpak",
         "files":
         [
             {
@@ -60,18 +61,20 @@ Examples:
     |       └─ models
     |           └─ my_texture.dds
     └── output
+        ├─ example2.starpak
         └─ example2.rpak
 
 .. note ::
     This example map file creates an RPak named ``example2.rpak`` which contains 1 texture asset.
+    This texture will have it's higher resolution mip levels stored in example2.starpak
 
 .. note ::
     The texture will replace any vanilla textures that have the same path. ( ``textures/models/my_texture`` )
 
     This is useful for creating basic skins and camos.
 
-3. Multiple Textures
--------------------
+3. Multiple Textures + Multiple Starpaks
+----------------------------------------
 
 ``example3.json``
 
@@ -82,6 +85,7 @@ Examples:
         "assetsDir": "../depot",
         "outputDir": "../output",
         "version": 7,
+        "starpakPath": "example3.starpak",
         "files":
         [
             {
@@ -94,6 +98,7 @@ Examples:
             },
             {
                 "$type": "txtr",
+                "starpakPath": "example3-spc.starpak",
                 "path": "textures/models/my_texture_spc"
             }
         ]
@@ -112,46 +117,54 @@ Examples:
     |           ├─ my_texture_nml.dds
     |           └─ my_texture_spc.dds
     └── output
+        ├─ example3.starpak
+        ├─ example3-spc.starpak
         └─ example3.rpak
 
-.. note ::
+.. note::
     This example map file creates an RPak named ``example3.rpak`` which contains 3 texture assets.
+    These textures each have their higher resolution mip levels stored in starpaks.
 
-.. note ::
+    ``my_texture_col`` and ``mp_texture_nml`` use ``example3.starpak``, as they do not specify their own ``starpakPath``.
+    This makes them use the default ``starpakPath`` that is defined at the file scope, instead of in the individual textures.
+
+    ``my_texture_spc`` uses ``example3-spc.starpak``, as it specifies it's own ``starpakPath``.
+
+.. note::
     This RPak is a good example of a skin that would normally require the skin tool to install.
     The advantage of this method is that the skin can be uninstalled or temporarily disabled when packed as a mod.
 
 Structure:
 ==========
 
-name
-----
+``name``
+--------
 
 The ``name`` field of a map file determines the name of the resulting RPak.
 
 The ``name`` is appended with ``.rpak`` and defaults to ``new`` if no ``name`` is provided. 
 This results in a default RPak called ``new.rpak``.
 
-.. warning ::
+.. warning::
     In the event that no ``name`` is provided in the map file, RePak will output the following warning to the console:
 
     ``Map file should have a 'name' field containing the string name for the new rpak, but none was provided. Defaulting to 'new.rpak' and continuing...\n``
 
-assetsDir
----------
+``assetsDir``
+-------------
 
 The ``assetsDir`` field of a map file determines the root path which the program combines with the ``path`` for assets in order to find the correct file.
 This path may be a relative path, or an absolute path.
 
 The ``assetsDir`` provided in the map file is appended with a slash ( ``\`` ) if necessary
 
-.. warning ::
+.. warning::
     If no ``assetsDir`` is provided, it defaults to the working directory ( ``.\`` ) as well as outputting the following warning to the console:
 
     ``No assetsDir field provided. Assuming that everything is relative to the working directory.\n``
 
-outputDir
----------
+``outputDir``
+-------------
 
 The ``outputDir`` field of a map file determines the folder that the program will write the RPak and StaRPak files to once they have been created.
 This path may be a relative path, or an absolute path.
@@ -160,17 +173,17 @@ The ``outputDir`` provided in the map file is appended with a slash ( ``\`` ) if
 
 If no ``outputDir`` is provided in the map file, RePak defaults to ``.\build\``
 
-version
--------
+``version``
+-----------
 
 The ``version`` field of a map file determines the RPak version that RePak will create.
 
-.. error ::
+.. error::
     If no ``version`` field is provided, RePak will output the following error and the program will stop:
 
     ``Map file doesn't specify an RPak version\nUse 'version: 7' for Titanfall 2 or 'version: 8' for Apex\n``
 
-.. error ::
+.. error::
     If an invalid ``version`` field is provided, RePak will output the following error and the program will stop:
 
     ``Invalid RPak version specified\nUse 'version: 7' for Titanfall 2 or 'version: 8' for Apex\n``
@@ -182,8 +195,21 @@ List of known ``version`` values:
 * ``7``: Titanfall 2
 * ``8``: Apex Legends
 
-files
------
+``starpakPath``
+---------------
+
+The ``starpakPath`` field of a map file determines the default starpak path for textures (and other streamed assets) to use.
+
+.. note::
+    If the starpak name ends in ``_hotswap.starpak`` (e.g. ``my_thing_hotswap.starpak``) then Titanfall 2 will view it as optional.
+    This allows the starpak to be moved, removed, or replaced while the game is running and streaming the texture.
+    This can be useful for debugging.
+
+.. note::
+    RePak will not throw any errors if no ``starpakPath`` field is specified, however the individual textures may throw errors if they do not have a ``starpakPath`` specified
+
+``files``
+---------
 
 The ``files`` field of a map file is an array of JSON objects, each one representing an RPak asset.