.. _packaging-environments:

======================
Packaging Environments
======================

An Unreal project needs to be packaged before it can be distributed. This process produces the engine 
executables and bundles up all of the assets that are needed for the client to start up the engine by 
itself without starting it from the editor or Visual Studio.

This process will compile the C++ code for HoloOcean and "cook" the ``.uasset`` files (including 
blueprints!) into one large ``.pak`` file, and create the directory structure needed.

Adding HoloOcean Worlds
=======================

The finished package will only contain the worlds (called "levels" in the editor) that are added into 
the project. The ``holoocean`` repo only contains the example level. You can create new worlds by 
simply making a new level in the Unreal Engine editor. Please reference :ref:`create-env` for more 
details on creating levels.

.. note::
    
    Because the other packaged worlds distributed with HoloOcean contain purchased assets, they are 
    only available to official BYU FROST Lab members. Other users will have to develop their own
    worlds in the HoloOcean repo.

Cooking Content
===============
You may need to cook the content to "refresh" the assets, levels, and blueprints that 
``holoocean/engine`` reads. 

**From Unreal Editor:**

Platforms ➡ Windows/Linux ➡ Cook Content

Packaging HoloOcean
===================

Operating System
----------------
It is best to package HoloOcean using the same operating system it will be run on. If you want to run 
your project for Windows, you should be using Unreal Engine in Windows to compile the project, and 
vice versa for Linux. 

If you are using Windows, it is possible to package an executable for Linux. 
**If you wish to cross compile from Windows to Linux, you must implement the following changes. 
Otherwise, you can continue to** :ref:`package-holoocean`.

1. Go to your Unreal Engine version within the Epic Games Launcher. Right click on the arrow next to 
   the "Launch" button and select Options.

    .. image:: images/linux_steps_p1.png

2. Under "Target Platforms", select Linux and install.

    .. image:: images/linux_steps_p2.png

3. Download the Cross-Compile Toolchain v22 (refer to `Unreal Engine's Cross-Compile documentation <https://dev.epicgames.com/documentation/en-us/unreal-engine/linux-development-requirements-for-unreal-engine?application_version=5.3>`_).

    .. image:: images/linux_steps_p3.png

4. Modify your Visual Studio 2022 install to include the "Linux and embedded development with C++"

    .. image:: images/linux_steps_p4.png

With these changes, you should be able to compile for Linux from Windows.

.. _`package-holoocean`:
Packaging
---------

1. From within the Unreal Editor, select Platforms ➡ Windows/Linux ➡ Package Project

    .. image:: images/package-project.png

.. _`package-install-directory`:

2. Select the Package Location

    In order to be able to call ``holoocean.make()``, you will need to place the packaged engine in 
    :ref:`package-locations`. Make sure the version in the path matches the output of the 
    ``holoocean.util.get_holoocean_version`` command.

    After selecting the package location, the exported package should have this structure: 

    .. code::

        + worlds
        |--+ PackageName
            |-- config.json
            |-- materials.csv
            |-- WorldName-ScenarioName.json (optional)
            |--+ Linux (or Windows)
                | UE5 build output


    For reference, this is what it looks like for the Ocean package on Windows:

    .. image:: images/custom_packaging_location.png

3. Edit Configuration Files

    The ``config.json`` file and ``materials.csv`` are not generated by the packaging process. 
    Copy the ``config.json`` and ``materials.csv`` from ``engine\Content\Config``.

    For the ``config.json``, edit the file to include the names of your custom levels. The ``env_min`` and ``env_max`` parameters are 
    used for octree generation. Make sure that they are big enough to contain your entire level or the octrees will not be generated.
    
    Ensure the following two fields match the operating system you are using:

    .. code::

        "platform": "linux"
        "path": "Linux/Holodeck/Binaries/Linux/Holodeck"

    OR

    .. code::

        "platform": "windows"
        "path": "Windows/Holodeck/Binaries/Win64/Holodeck.exe"

    For the ``materials.csv``, the material names should match the materials that you use for your landscape and assets. 

    Optional configuration files for each scenario must be made by the user. They are placed in the 
    ``worlds/PackageName`` directory. See :ref:`custom-scenarios` for details on how to create
    configuration files for your scenarios.

The packaged project should now be ready to run. You can access your packaged environments and 
associated scenarios using the ``holoocean.make()`` command.