Skip to content
Update Developer Guide authored by Travis Law's avatar Travis Law
# Developer Guide
StarFab is developed in Python using [Qt for Python](https://wiki.qt.io/Qt_for_Python). The Python version must be the same as the currently supported version of Blender so that the StarFab [Blender add-on](/blender) will function smoothly. StarFab is developed in Python using [Qt for Python](https://wiki.qt.io/Qt_for_Python). The Python version must be the same as the currently supported version of Blender so that the StarFab [Blender add-on](/blender) will function smoothly.
* [Core Guidelines](#core-guidelines) * [Core Guidelines](#core-guidelines)
...@@ -18,7 +20,7 @@ StarFab is developed in Python using [Qt for Python](https://wiki.qt.io/Qt_for_P ...@@ -18,7 +20,7 @@ StarFab is developed in Python using [Qt for Python](https://wiki.qt.io/Qt_for_P
* [PyCharm Debugging](#pycharm-debugging) * [PyCharm Debugging](#pycharm-debugging)
* [Debug Environment Variables](#debug-environment-variables) * [Debug Environment Variables](#debug-environment-variables)
# Core Guidelines ## Core Guidelines
* Python [3.9.2](https://www.python.org/downloads/release/python-392/) * Python [3.9.2](https://www.python.org/downloads/release/python-392/)
* [Black](https://black.readthedocs.io/en/stable/) for code style/formatting * [Black](https://black.readthedocs.io/en/stable/) for code style/formatting
...@@ -28,37 +30,35 @@ StarFab is developed in Python using [Qt for Python](https://wiki.qt.io/Qt_for_P ...@@ -28,37 +30,35 @@ StarFab is developed in Python using [Qt for Python](https://wiki.qt.io/Qt_for_P
> In this early phase of development, Linux and OSX support is not being kept up to date. Even so, always take multi-platform support into account when working on StarFab > In this early phase of development, Linux and OSX support is not being kept up to date. Even so, always take multi-platform support into account when working on StarFab
## Dependencies ### Dependencies
As stated above, StarFab uses [Poetry](https://python-poetry.org/) to manage dependencies and requirements. See the `pyproject.toml` file in the repo for what python dependencies are being used in StarFab. During development, however, many changes may actually be done in [scdatatools](https://gitlab.com/scmodding/frameworks/scdatatools). It's recommended to clone both projects, then use `pip install -e` the local version of scdatatools. As stated above, StarFab uses [Poetry](https://python-poetry.org/) to manage dependencies and requirements. See the `pyproject.toml` file in the repo for what python dependencies are being used in StarFab. During development, however, many changes may actually be done in [scdatatools](https://gitlab.com/scmodding/frameworks/scdatatools). It's recommended to clone both projects, then use `pip install -e` the local version of scdatatools.
### Optional Dependencies #### Optional Dependencies
Often these optional dependencies are included in the platform specific release packages. Often these optional dependencies are included in the platform specific release packages.
#### View and Convert textures (dds) ##### View and Convert textures (dds)
To view or convert textures (.dds*) files, StarFab relies on [texconv](https://github.com/microsoft/DirectXTex/releases) or [compressonator](https://gpuopen.com/compressonator/). Ensure that `texconv` or `compressonatorcli` is installed and in your system `PATH`. To view or convert textures (.dds*) files, StarFab relies on [texconv](https://github.com/microsoft/DirectXTex/releases) or [compressonator](https://gpuopen.com/compressonator/). Ensure that `texconv` or `compressonatorcli` is installed and in your system `PATH`.
#### Convert Audio Files (wem) ##### Convert Audio Files (wem)
To convert wem files, you must have [ww2ogg](https://github.com/hcs64/ww2ogg) and [revorb](https://cloudflare-ipfs.com/ipfs/QmVgjfU7qgPEtANatrfh7VQJby9t1ojrTbN7X8Ei4djF4e/revorb.exe) in your path. **Both are included in the MSI installer for Windows.** To convert wem files, you must have [ww2ogg](https://github.com/hcs64/ww2ogg) and [revorb](https://cloudflare-ipfs.com/ipfs/QmVgjfU7qgPEtANatrfh7VQJby9t1ojrTbN7X8Ei4djF4e/revorb.exe) in your path. **Both are included in the MSI installer for Windows.**
> **Note for Windows: you must have the Vorbis codecs installed to listen to audio in StarFab. You can download them on [Xiph.org](https://xiph.org/dshow/downloads/)** > **Note for Windows: you must have the Vorbis codecs installed to listen to audio in StarFab. You can download them on [Xiph.org](https://xiph.org/dshow/downloads/)**
##### Convert CryEngine Models (cga/cgf/chr/skin)
#### Convert CryEngine Models (cga/cgf/chr/skin)
scdatatools uses [cgf-converter](https://github.com/Markemp/Cryengine-Converter) to convert CryEngine models to a standard format (Collada/dae) scdatatools uses [cgf-converter](https://github.com/Markemp/Cryengine-Converter) to convert CryEngine models to a standard format (Collada/dae)
## Developer Quick Start
# Developer Quick Start
While there are many ways to configure your development environment, the following methods are known to work/repeatable. While there are many ways to configure your development environment, the following methods are known to work/repeatable.
## System Dependencies ### System Dependencies
### Windows #### Windows
> All command snippets are assumed to be in Git Bash unless specifically stated otherwise > All command snippets are assumed to be in Git Bash unless specifically stated otherwise
...@@ -84,7 +84,7 @@ pyenv install 3.9.2 ...@@ -84,7 +84,7 @@ pyenv install 3.9.2
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python - curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
``` ```
### Linux/OSX #### Linux/OSX
##### pyenv ##### pyenv
...@@ -106,7 +106,7 @@ pyenv install 3.9.2 ...@@ -106,7 +106,7 @@ pyenv install 3.9.2
curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python - curl -sSL https://raw.githubusercontent.com/python-poetry/poetry/master/get-poetry.py | python -
``` ```
## Cloning ### Cloning
The recommend folder structure is created as follows. The recommend folder structure is created as follows.
...@@ -120,7 +120,7 @@ git clone git@gitlab.com:scmodding/tools/starfab.git tools/starfab ...@@ -120,7 +120,7 @@ git clone git@gitlab.com:scmodding/tools/starfab.git tools/starfab
git clone git@gitlab.com:scmodding/frameworks/scdatatools.git frameworks/scdatatools git clone git@gitlab.com:scmodding/frameworks/scdatatools.git frameworks/scdatatools
``` ```
### Initial Setup #### Initial Setup
In the `scmodding` folder created above: In the `scmodding` folder created above:
...@@ -133,7 +133,7 @@ poetry install ...@@ -133,7 +133,7 @@ poetry install
poetry run python -m pip install -e ../../frameworks/scdatatools poetry run python -m pip install -e ../../frameworks/scdatatools
``` ```
# Running ## Running
From within the `scmodding/tools/starfab/` folder: From within the `scmodding/tools/starfab/` folder:
...@@ -141,9 +141,9 @@ From within the `scmodding/tools/starfab/` folder: ...@@ -141,9 +141,9 @@ From within the `scmodding/tools/starfab/` folder:
poetry run python -m starfab poetry run python -m starfab
``` ```
# Tips and Tricks ## Tips and Tricks
## PyCharm Debugging ### PyCharm Debugging
Setting up PyCharm to run StarFab is as simple as configuring the project's Python Interpreter to use the poetry virtual environment (this is in `starfab/.venv/`) and creating a Python run configuration to run the `starfab` module. Setting up PyCharm to run StarFab is as simple as configuring the project's Python Interpreter to use the poetry virtual environment (this is in `starfab/.venv/`) and creating a Python run configuration to run the `starfab` module.
...@@ -158,7 +158,7 @@ In addition, PyCharm can be used to debug the blender add-ons while they're runn ...@@ -158,7 +158,7 @@ In addition, PyCharm can be used to debug the blender add-ons while they're runn
This will trigger the StarFab Blender add-on to connect to the PyCharm debug server when it is loaded. This will trigger a breakpoint, and you can hit the continue button to let Blender continue to load. Breakpoints set within the blender add-ons will trigger when being used in Blender! This will trigger the StarFab Blender add-on to connect to the PyCharm debug server when it is loaded. This will trigger a breakpoint, and you can hit the continue button to let Blender continue to load. Breakpoints set within the blender add-ons will trigger when being used in Blender!
## Debug Environment Variables ### Debug Environment Variables
There are a number of environment variables that can be set to adjust how StarFab runs for debugging purporses. There are a number of environment variables that can be set to adjust how StarFab runs for debugging purporses.
| Environment Variable | Example Setting | Description | | Environment Variable | Example Setting | Description |
...@@ -168,4 +168,4 @@ There are a number of environment variables that can be set to adjust how StarFa ...@@ -168,4 +168,4 @@ There are a number of environment variables that can be set to adjust how StarFa
| STARFAB_RELOAD_MODULES | 1 | If set to anything, certain modules will be reloaded every time they are referenced. This is put in strategic places to assist with tweaking the UI without re-running StarFab (search for STARFAB_RELOAD_MODULES in the code to see how this is used) | | STARFAB_RELOAD_MODULES | 1 | If set to anything, certain modules will be reloaded every time they are referenced. This is put in strategic places to assist with tweaking the UI without re-running StarFab (search for STARFAB_RELOAD_MODULES in the code to see how this is used) |
| STARFAB_P4K_LIMIT | 1000 | Stop loading the Data.p4k after N number of records have been read | | STARFAB_P4K_LIMIT | 1000 | Stop loading the Data.p4k after N number of records have been read |
| STARFAB_QUICK | 1 | If set, this will disable some calculations that take a long time to initially process (like folder sizes in the p4k) | | STARFAB_QUICK | 1 | If set, this will disable some calculations that take a long time to initially process (like folder sizes in the p4k) |
| STARFAB_SC_PATH | e:/sc/archive/PTU/Data.p4k | Override which SC directory will automatically be loaded on startup | | STARFAB_SC_PATH | e:/sc/archive/PTU/Data.p4k | Override which SC directory will automatically be loaded on startup |
\ No newline at end of file