rival-unreal 0.0.19
package for unreal tools to be used on thr3d Rival project
Requires Python: >=3.6

# Rival unreal package

First pass at python package to house io and task tools for unreal. There is also a [ue4_cmd](https://github.com/thr3dcgi/rival-unreal/blob/dev/src/rival_unreal/ue4_cmd.py) module
to run ue4edit commands in batch mode with a cli.

The rival_unreal package has a number of modules which simplify certain operations specific to the Rival Content Creator project. A specific example of this would be the ```load_thumbs_to_table``` function in [io.py](https://github.com/thr3dcgi/rival-unreal/blob/dev/src/rival_unreal/io.py#L32) which imports thumbnail images to unreal and adds them to a ProductTable data struct.

Also, [ue4_cmd](https://github.com/thr3dcgi/rival-unreal/blob/dev/src/rival_unreal/ue4_cmd.py) will allow us to execute a delivery api bundle action for packing unreal project data using either the cli or library imported as a module.

## Location

The package can either be cloned from [thr3d/rival-unreal](https://github.com/thr3dcgi/rival-unreal) or installed from [pypi/rival-unreal](https://pypi.org/project/rival-unreal) using [pip](https://pypi.org/project/pip/).

Sphinx is used for documentation. See [sphinx](#sphinx).

# Caveat
- NOTE: This is a python3 based project. Currently working on making it backward compatible w 2.7 but in the meantime, please install python3.6+ in order to test/use.

[python downloads](https://www.python.org/downloads/)

## Install
install to your python dist
```
pip install rival_unreal
```
or if you prefer to work in a virtual environent
```
pip install pipenv
pipenv install rival_unreal
```

### Confirm install is ok, enter the following commands
- You should see logging messages from rival_unreal module
```
python -c "import rival_unreal"
```

- You should see the help string noted below
```
ue4_cmd
```

# ue4_cmd module
This module enables running a ue4editor session as a batch script, with a python script to serve as an execution block.

```
usage: ue4_cmd [-h] -b BAT -u UPROJECT -s SCRIPT [-stdout] [-k KEYWORD]

Script to run ue4editor session on the command line.

optional arguments:
  -h, --help            show this help message and exit
  -b BAT, --bat BAT     bat file to run
  -u UPROJECT, --uproject UPROJECT
                        full path to uproject file
  -s SCRIPT, --script SCRIPT
                        python script to run in unreal session
  -stdout               If set, print all session stdout. Overrides 'keyword'.
  -k KEYWORD, --keyword KEYWORD
                        Filter session stdout for this string.
```
## Example
If you wanted to perform the simple task of loading a geo.fbx into unreal and then export it as a .uasset file, you could have a python script that looks like this:

```
import sys
import os
# First add the full absolute path source to PYTHONPATH (this should just be the current cwd path)
path = "C:/Users/aruil/OneDrive/Documents/GitHub/rival-unreal"
sys.path.insert(0, path + "/src")

import rival_unreal

# import mesh to unreal session
rival_unreal.io.import_mesh(
    filename=path + '/tests/data/RIVAL/rt/scene/geo.fbx',
    destination_path='/Game/RIVAL_ASSETS'
)

# export as uasset
_ = rival_unreal.io.export_rival_uassets(
    source_dir='/Game/RIVAL_ASSETS', destination_path=path + '/tests/data'
)
os.remove(path + '/tests/data/mesh.uasset')
print("rival_unreal: DONE!")
```
- NOTE: a script is included which autogenerates this and uses some test data for input. See [Auto generate script](https://github.com/thr3dcgi/rival-unreal/blob/dev/tests/test_generate_uasset.py)

Since the script is loaded into a session, any calls you want to make using the unreal python module are also valid.

## Windows bat file
A windows .bat script file is used to run the command in a windows shell [windows bat](https://github.com/thr3dcgi/rival-unreal/blob/dev/tests/data/ue4cmd.bat)


## unreal project
It is necessary for the ue4editor command to run in loaded project. So a path to a valid unreal project file on disk needs to be specified. This is an empty project which could be used.
```
/gfs/jobs/THR3D/Rival/rival_test/rival_test.uproject
```
- NOTE: The project needs to have both the [Editor Scripting Utilities](https://docs.unrealengine.com/4.26/en-US/ProductionPipelines/ScriptingAndAutomation/) and the [Python Editor Script](https://docs.unrealengine.com/4.26/en-US/ProductionPipelines/ScriptingAndAutomation/Python/) plugins enabled. To enable them for your project, you will have to open your project in the unreal editor, enable them in the plugin settings, and then save the project again.

## Sample command
You can use the sample script [test.py](https://github.com/thr3dcgi/rival-unreal/blob/dev/tests/data/test.py) but before doing so, make a copy of it and edit the ```path``` variable to point to the full path of your copy of the rival-unreal package. Then use the copied file as the argument to ```-s```.
```
ue4_cmd -b tests/data/ue4cmd.bat -u /gfs/jobs/THR3D/Rival/rival_test/rival_test.uproject -s ./tests/data/test.py
```

You should get output similar to this:
```
[root:INFO ] Running ue4 editor w project file ...
[root:INFO ] UE4CmdThread : Starting thread '0'
[root:INFO ] Running command:  C:\Program Files\...\Win64\UE4Editor-CMD.exe C:\...\rival_test.uproject -run=pythonscript -script="C:\...\test.py" -stdout -FullStdOutLogOutput
[root:INFO ] UE4CmdThread : Finished thread '0'
[root:INFO ] Output from session:

[2021.06.30-16.30.28:319][  0]LogPython: rival_unreal.tasks log file : C:\..\Rival_Unreal_rival_unreal.tasks_6d90bad2-19b1-4ca4-898b-de0fbeeb699a.log
[2021.06.30-16.30.28:326][  0]LogPython: rival_unreal._utils log file : C:\..\Rival_Unreal_rival_unreal._utils_b52dc92b-b737-45bd-8965-9ee9da34bd3d.log
[2021.06.30-16.30.28:327][  0]LogPython: rival_unreal.io log file : C:\..\Rival_Unreal_rival_unreal.io_71a03d2b-9dbb-4b42-9552-659e358cfbc0.log
[2021.06.30-16.30.28:419][  0]LogPython: rival_unreal: DONE!
```

# Dev Setup
```
pip install pipenv m2r pre-commit
pre-commit install
```

If the above steps are ok, feel free to make edits, the run the [Testing](#testing) and [DocPrep](#documentation-build-prep)
If you want to skip the pre-commit hooks, just add ```--no-verify``` to your commit command. i.e. ```git commit . -m 'quick fix' --no-verify```

## Testing
```
pipenv run pytest -sv
pipenv run python tests/test_generate_uasset.py
```

If this worked, you should see the messgage:
```
'__main__': Success! the uasset file 'C:/Users/aruil/OneDrive/Documents/GitHub/ue4_dev_projects/rival-unreal/tests/data/mesh.uasset' was created.
```

## Documentation Build Prep

do this before committing

- Convert the README.md to a sphinx rst (temporary, will eventually be part of pre-commit)
```
yes|m2r README.md
mv README.rst docs/source
cd docs && make clean && make html && cd ..
```

# Packaging

The pakage is installed to [pypi/rival-unreal](https://pypi.org/project/rival-unreal). In order to build and upload a new version, do the following
- Increase the MMR number in setup.py
```
setuptools.setup(
    name="rival-unreal",
    version="0.0.13",
    ...
```
- Then clean, build and upload (be sure you have a pypi account first)
```
rm -rf dist/* && py -m build
twine upload dist/*
```

# Extra documentation
## Packaging
https://packaging.python.org/tutorials/packaging-projects/

## pipenv
https://realpython.com/pipenv-guide/

## sphinx
https://sphinx-rtd-tutorial.readthedocs.io/en/latest/sphinx-quickstart.html

## m2r
https://pypi.org/project/m2r/

### tmp generated docs
file:///C:/Users/aruil/OneDrive/Documents/GitHub/rival-unreal/docs/build/html/index.html