diff --git a/docs/source/guides/rpakmodding.rst b/docs/source/guides/rpakmodding.rst index 512d2110..4e52cdf8 100644 --- a/docs/source/guides/rpakmodding.rst +++ b/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. diff --git a/docs/source/repak/assets/texture.rst b/docs/source/repak/assets/texture.rst index bc12bd82..475eefdf 100644 --- a/docs/source/repak/assets/texture.rst +++ b/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 ``/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 ``/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`` -------------------- diff --git a/docs/source/repak/map.rst b/docs/source/repak/map.rst index 2d435d85..5ff60590 100644 --- a/docs/source/repak/map.rst +++ b/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.