Development

Note

This page assumes development on Windows.

Get the THRotator source code

Clone the THRotator repository by git.

Next, change directory to cloned directory and run git submodule update --init. This command downloads the source code of external libraries, fmt, json.hpp, and ImGui.

Build THRotator

This section gives you an instruction to build THRotator from source code.

The prerequisites are the following:

  • Microsoft Visual C++ (2015 or later)
  • Boost C++ Libraries
  • CMake

Install Microsoft Visual C++

Note

If you have installed Visual C++, skip this step.

Download Visual Studio from Home page of Visual Studio. Community Edition is just enough.

Since the installer of Visual Studio 2015, Visual C++ is not installed by default. Edit the installation option so that Visual C++ is installed.

Install Boost C++ Libraries

Note

If you have built filesystem modules, skip this step.

Access to Boost C++ Libraries and download the latest release from Current Release. Then extract ZIP archive to some location (for example C:\boost\).

Next, build filesystem modules by following the steps given below.

  1. If your system is x64-based, Start MenuVisual Studio 20XXVS20XX x64 Native Tools Command Prompts. If your system is x86-based, launch VS20XX x86 Native Tools Command Prompts.
  2. On the opened command prompt, change directory to the location where extracted bootstrap.bat exists.
  3. Run bootstrap.bat.
  4. b2.exe will be generated, then run b2 --with-filesystem runtime-link=shared,static.

Install CMake

Note

If you have installed CMake 3.5 or later, skip this step.

Access to Home page of CMake. Then download one of the following from Download page.

  • Windows win64-x64 Installer
  • Windows win64-x64 ZIP
  • Windows win32-x86 Installer
  • Windows win32-x86 ZIP

If you are using x64-based system, you can use both win64-x64 and win32-x86. If you are using x86-based system, you can use only win32-x86.

Generate project files

  1. If you have installed CMake from installer, Start MenuCMakeCMake (cmake-gui). If you have downloaded CMake directly, run bin\cmake-gui.exe.
  2. Fill Where is the source code: by the location of THRotator source code.
  3. Fill Where to build the binaries: by the location of project files you want to generate.
  4. Press Configure. Then generator selection window appears. Choose Visual Studio XX 20XX and press Finish. Don’t choose a generator name with Win64 or ARM.
  5. Set the boost installation directory (where bootstrap.bat exists) to BOOST_INCLUDE_DIR.
  6. Set the boost library directory (<boost install directory>\stage\lib by default) to BOOST_LIB_DIR.
  7. Press Configure again. If you don’t see any errors, press Generate.

Build

  1. Open generated THRotator.sln.
  2. Five projects are loaded.
  • ALL_BUILD (project to build all the other projects)
  • d3d8 (THRotator based on Direct3D 8)
  • d3d9 (THRotator based on Direct3D 9)
  • localization_en-US (English resource DLL of THRotator)
  • ZERO_CHECK (automatically generated by CMake)
  1. Build d3d8 for THRotator based on Direct3D 8, build d3d9 for THRotator based on Direct3D 9.

Localization

THRotator supports dialog boxes and error messages in multiple languages by Multilingual User Interface (MUI).

You can easily add new language based on English localization resource. Let’s look at how to add a new language with French example.

Note

This section doesn’t refer to the actual translation.

1 Copy template

  1. Create localization_<language name> folder in the directory where localization_en-US exists. Language name is one of Language/culture name found in Available Language Packs for Windows. This page also provides language ID in Language hexadecimal identifier, which should be memorized for a later step. Since example is French, folder name is localization_fr-FR and memorize language ID 0x040c.
  2. From localization_en-US, copy CMakeLists.txt, resource.h, and THRotator_en-US.rc folder to localization_<language name> (in current example, copy to localization_fr-FR).
  3. Rename localization_<language name>\THRotator_en-US.rc to localization_<language name>\THRotator_<language name>.rc (in current example, rename to THRotator_fr-FR.rc).

2 Prepare for CMake

  1. Open localization_<language name>\CMakeLists.txt and replace all en-US occurrences with <language name>. Then replace 0x0409 in set(language_id 0x0409) to the memorized language ID. In current example replace with 0x040c. This is the end of editing localization_<language name>\CMakeLists.txt.
  2. Open CMakeLists.txt in the root directory of THRotator, add add_subdirectory(localization_<language name>) to the final line.

In current French example, localization_fr-FR\CMakeLists.txt finally looks like the following:

# resource language and its ID
# for a list of languages and IDs, visit https://msdn.microsoft.com/en-us/library/hh825678.aspx
set(language fr-FR) # Edited
set(language_id 0x040c) # Edited

include(../internationalization/THRotator_i18n.cmake)

CMakeLists.txt finally looks like the following:

# Abbreviated

add_subdirectory(d3d9)
add_subdirectory(d3d8)
add_subdirectory(localization_en-US)
add_subdirectory(localization_fr-FR) # Added

3 Generate project files

Generate project files as described in Generate project files.

4 Translate

After reopening or reloading THRotator.sln, you can find that a project localization_<language name> is added.

From Resource View of Visual Studio, you can start to translate string table and dialog box resources that belong to localization_<language name>. On property window, change language of string table and dialog boxes from English (United States) to the language name you want to translate into. In French example, change to French (France).

5 Build and launch

By building localization_<language name>, .mui files are generated to the <language name> folder located in the output directories of d3d8.dll and d3d9.dll.

Copy d3d8.dll or d3d9.dll and <language name> folder to the directory where the executable of the game is located. If your system supports the language you are trying to add, GUI and messages are now in that language.

Note

The respective checksum of d3d8.dll and d3d9.dll is embedded to d3d8.dll.mui and d3d9.dll.mui. If the embedded checksum doesn’t match that of .dll, that language will not be loaded.

Build manual

Sphinx is used to build the manual of THRotator.

The prerequisites are the following:

  • Python
  • Sphinx
  • Items below are required for internationalization.
    • Sphinx-intl

Install Sphinx-intl

Sphinx-intl is a package for internationalization of sphinx. To install it, run python -m pip install sphinx-intl.

Build (English)

Open command prompt, change directory to docs/, and run make.bat html.

Then html files are generated in docs/_build/html/.

Build (other languages)

Build manual in another language involves a bit complicated process.

1 Collecting texts to be translated

Open command prompt, change directory to docs/, and run make.bat gettext.

2 Create or update .po file

Run sphinx-intl.exe update -p .\_build\gettext -l <language> to create or update .po files that will be located in doc/locale/<language>/LC_MESSAGES/.

<language> is one of strings listed in Sphinx Documentation.

.po file contains pairs of original English text and translated text.

Note

sphinx-intl.exe is located in <Python installation>/Scripts/

3 Edit .po file

Add your translation to generated or updated .po file.

Single line translation example for Japanese:

msgid "THRotator User's Manual"
msgstr "THRotator ユーザーマニュアル"

Multi line translation example:

msgid ""
"If you would like to build the manual in a specific language,"
"run ``docs-source/<language>/make.bat html``."
msgstr ""
"特定の言語に対してマニュアルをビルドしたいときは、"
"``docs-source/<言語>/make.bat html`` を実行してください。"

4 Build

Before actual build, run set SPHINXOPTS=-D language=<language> to specify the final language of manual.

Then run make.bat html. Html files will be generated in docs/_build/html/.

Continuous integration

THRotator owns two continuous integration (CI) projects on AppVeyor.

THRotator

https://ci.appveyor.com/project/massanoori/throtator

Simple build and packaging project.

This project builds INSTALL.vcxproj generated by CMake. Files copied by building INSTALL.vcxproj will be treated as an artifact of the project.

THRotator-cov

https://ci.appveyor.com/project/massanoori/throtator-n7skl

This project builds cov-int tarball required by Coverity Scan to launch static analysis. The built cov-int directory is treated as an artifact of the project.

The project of Coverity Scan can be found here. If you are permitted to submit a build, you can launch a static analysis by following steps:

  • Visit Submit a Project Build via URL.
  • Fill File URL by https://ci.appveyor.com/api/projects/massanoori/throtator-n7skl/artifacts/build%2Fcov-int.zip.
  • Click Upload URL for analysis.

Note

You can also upload cov-int.zip downloaded from AppVeyor to Coverity Scan. But it can take several minutes or hours to upload a file depending on your internet connection.

Incrementing version

The version format of THRotator adheres to Semantic Versioning 2.0.

Major version is incremented when:

  • You have made huge design changes that affect user interactions.
  • New data format is incompatible with older versions.
  • You have made other revolutionary changes.

Minor version is incremented when:

  • You have added new relatively big features or improvements.
  • New data format is upgradable from, but irreversible to, older versions.

Patch version is incremented when:

  • You have fixed small but important issues that should be released as soon as possible.
  • You have added new relatively small features or improvements.
  • Changes above don’t break forward- and backward-compatibility of data format.