Windows Installation

Installing Sapphire on Windows

MAKE SURE YOU HAVE THE DEPENDENCIES LISTED ON THE README FIRST

1. Windows Linux Subsystem
2. Prerequisites
3. Obtaining the Source
   1. Git Command Line
   2. Visual Git client
4. Setup Development Environment
5. Build the Project
6. Build the Launcher
7. Configuration
   1. Configure Sapphire Servers
   2. Import the Database
   3. Generate the nav meshes
8. Running the Server
   1. Connecting to a Server
9. Common Issues

Windows Linux Subsystem

If you're not sure what this is, you can skip this section and continue onto the general Windows installation guide, otherwise keep reading.

Sapphire will also operate correctly (save for unforeseen issues) within the Windows Linux Subsystem (WSL) and is actively tested in this environment. While setup will not covered in this guide, please note that it does work and you may prefer to use this environment for development over the standard Windows development environment. CLion has a very stable integration for WSL which may be preferable over Visual Studio.

Prerequisites

• Visual Studio 2017
• MySQL Server 5.7. MySQL 8.0 is not compatible.
• MySQL client (optional) ex: HeidiSQL
• Git or a graphical Git client like GitKraken

Installation of these will be explained later in the guide.

Obtaining the Source

Git command line

1. Open git bash and navigate to a directory of choice

2. Clone the Sapphire source, including submodules

   git clone --recursive https://github.com/SapphireServer/Sapphire.git
   git checkout develop

   2a. To update the main Sapphire source, open a git bash shell from inside the Sapphire source directory and run the following

   git pull
   git submodule update --init --recursive

   

   2b. If you want to switch to another branch (develop), use git checkout NAMEOFBRANCH to do so.

3. Clone the Sapphire Launcher source

git clone https://github.com/SapphireServer/SapphireLauncher.git

Visual Git client

Using GitKraken as example:

1. Open GitKraken, and select to clone new repository from https://github.com/SapphireServer/Sapphire.git and choose a folder to save the files. We recommend that you switch to the develop branch, as the Master branch may be behind on client compatibility. Especially after a recent patch.

   

2. Choose "yes" to initialize submodules.

   2a. To update the source, you can visually click on a newer commit or use the git pull button. To update the submodules, right click on the submodule and choose the "update" option.

   

3. Clone the Sapphire Launcher repository from https://github.com/SapphireServer/SapphireLauncher.git

Setup Development Environment

Install MySQL 5.7

1. Download the MySQL 5.7 installer (web or full is fine) 1a. If you download the web installer, you will need to manually filter

2. Select Custom as your installation type.

3. Choose the latest version of MySQL 5.7, x64.

   3a. If you only need development headers and libraries, you can deselect everything else.

   3b. Otherwise, make sure to install the server and server data files too.

   3c. NOTE: The architecture matters! If you installed 32-bit MySQL, you must compile Sapphire as x86, which has been dropped from newer commits. Please install 64-bit MySQL, and compile Sapphire for x64.

4. Wait for installation to complete.

   4a. If you installed a server, you will be guided through setup.

   4b. If you only installed development headers and libraries, you can cancel out of product configuration.

Installing Visual Studio 2017 with C++ and C# support

1. Download the Visual Studio 2017 installer and open it. (The community edition is fine!)

   

2. Run the installer selecting the .Net Desktop development and Desktop development with C++ options.

   

3. Switch to Individual components. You'll need to also select NuGet for installation. Select any additional features as needed. You can always add them later.

   

4. Wait for the installation to complete. You will be prompted to restart your computer. ​

Build the Project

1. Open Visual Studio 2017

2. Using the "Open Folder" file option, browse to the Sapphire source code folder. The project should open and CMake may begin generating a cache automatically.

   2a. If you're using external CMake, open the generated SLN file instead.

3. If a CMake cache was not generated, select a Build Configuration. 3a. Your MySQL installation will need to match your Build Configuruation. (x86 requires 32-bit MySQL. x64 requires 64-bit MySQL).

4. Build the solution. Depending on how your Visual Studio is configured, you can build by: CMake menu > Build All Build menu > Build All Right-click the CMakeLists.txt file and select Build

5. Files will be generated according to the buildRoot path specified in your CMakeSettings.json file. By default this is %userprofile%\CMakeBuild{hash}\build{build configuration}. The full path assuming a default installation of Windows 7 or later is C:\Users\[your username here]\CMakeBuild

Build the Launcher

1. Open the Sapphire Launcher source folder.

2. Open the SapphireBootWPF.sln solution file. It should open Visual Studio 2017.

3. Right-click the Solution and select Restore NuGet Packages.

   

4. Set your build target. The defaults are Debug and Win32

5. Build the launcher.

6. You can find the launcher executable files in Sapphire launcher\bin[x86/x64]\[Debug/Release] accordingly.

Configuration

Configure Sapphire Servers

1. Open the Sapphire build\bin\config folder.
2. Copy global.ini.default to global.ini and open your copy to personalize it.
3. Adjust the MySQL settings to match your MySQL server.
   1. Host - the IP of the machine your MySQL server is running on. Default: 127.0.0.1
   2. Port - the port that the MySQL server can be accessed on. Default: 3306
   3. Database - the database name for your Sapphire server. Default: sapphire
   4. Username - the username for your MySQL server. Default: root
   5. Pass - the password for your MySQL server. Use the password you set during MySQL Server installation. If you used a pre-packaged MySQL server, the default root password may be blank or vary.
4. Adjust the DataPath's of the server's settings.xml, to your FFXIV installation's game\sqpack\folder. Double backslashes are required. This will need to be adjusted to C:\\Program Files (x86)\\SquareEnix\\FINAL FANTASY XIV - A Realm Reborn\\game\\sqpack if you have installed FFXIV to its default location.
5. Adjust the ZoneHost, LobbyHost, and RestHost IP addresses if needed. For a local server for testing, keep these as 127.0.0.1
6. Adjust any other server-specific configuration in their appropriate sections.

Import the Database

1. Go to the Sapphire build\bin folder.

2. Use the DBM application to set up your database with the following commands.

   2a. Adjust the user, password by adding a --pass if needed, and database name to fit your environment.

   2b. NOTE: the DBM is still being developed.

   2c. You can find all of the DBM options by running the program in the command line.

.\dbm --mode initialize --user root --database sapphire

3. If you need to delete your sapphire database, run the liquidate command.

.\dbm --mode liquidate --user root --database sapphire --force

Generate the nav meshes

Note: Make sure that you build nav_export in release. You can do this by changing the Debug dropdown in Visual Studio or adding the following argument to your CMake command line: -DCMAKE_BUILD_TYPE=RelWithDebInfo. Not building nav_export in release will make it take several hours to generate all the navmeshes instead of 5-10 minutes.

1. Run nav_export.exe and provide the path to your FFXIV Installation\game\sqpack folder

2. Wait for nav meshes to be generated. This may take some time.

3. Go to the Sapphire build\bin\tools folder.

4. Use the nav_export application to generate obj files with the following commands.

   4a. You will need to run this from a terminal or command line (cmd.exe, powershell, git bash, etc)

   4b. Provide the program with the path to your FFXIV Installation\game\sqpack\ folder.

   4c. Wait for meshes to be generated. You can transfer them to later builds as long as no new maps have been added to the game.

.\nav_export "C:\Program Files (x86)\SquareEnix\FINAL FANTASY XIV - A Realm Reborn\game\sqpack" 

Running the Server

1. Start your MySQL server if it is not running.
2. Start lobby.exe Note: You may be prompted by Windows Firewall to allow access.
3. Start api.exe Note: You may be prompted by Windows Firewall to allow access. Note 2: The REST server requires Port 80 to function. Ensure no other programs are using this port like Skype, Apache/httpd, etc.
4. Start world.exe Note: You may be prompted by Windows Firewall to allow access.
5. Create a folder called "log" if it does not already exist. The servers will crash if your file permissions prevent creating this folder.

Connecting to a Server

1. Open the Sapphire Launcher

2. Click on the gear in the top right to enter the Launcher settings

3. Enter the URL to connect to your REST server. Default: http://localhost/login.html Note: Press Check availability to confirm your URL works.

4. Navigate to your FFXIV installation and select the ffxiv.exe for DirectX9 mode or ffxiv_dx11.exe for DirectX11 mode. Note: the default path is C:\Program Files (x86)\SquareEnix\FINAL FANTASY XIV - A Realm Reborn\game

5. Select your Expansion level and Language.

6. You should be greeted by the Sapphire Login screen.

   

7. Create an account if needed and login.

Common Issues

• The program crashes with "abort" and nothing else.
  1. Are there any files or folders missing? (Log folder, libmysql.dll that matches your build architecture?)
  2. Did you try to run it from Visual Studio from the Debug launcher?
• API and World both crash because of this "DataPath" thing.
  1. Please re-read the configuration guide. The default game path in the configuration is not the default FFXIV install location.
• I logged in, but this game feature isn't working!
  1. Sapphire is in a constant state of development. Is the feature you're trying to use actually implemented? Is it scripted, if needed?