Fractured/contrib/fractured-dev-extras/BUILD-NATIVE.md

# Fractured — Native Build Guide

This is a fork of [AzerothCore](https://www.azerothcore.org/) with a custom
`CLASS_PARAGON` (id 12), the `mod-paragon` server module, and `mod-ale`
(LuaJIT scripting) vendored in-tree. This document covers building the
server **natively** (no Docker). For the Docker workflow, see
`docker-compose.yml` plus `docker-compose.override.yml` at the repo root.

The upstream AzerothCore wiki is the authoritative reference for OS
prerequisites; everything here is just the deltas you need on top of it.

- Linux: <https://www.azerothcore.org/wiki/linux-requirements>
- Windows: <https://www.azerothcore.org/wiki/windows-requirements>
- macOS: <https://www.azerothcore.org/wiki/macos-requirements>

---

## Fractured client + network defaults

Stock-friendly defaults for fresh local installs. A `git clone` ->
`docker compose up` (or native install) lets a single developer log in
from the same machine without any post-install config tweaks.

- **`authserver.conf` -> `RealmServerPort`** = **3724** (stock WoW). A
  patched `Wow.exe` with `set realmlist 127.0.0.1` (no port) reaches
  the auth handshake.
- **`realmlist` table -> `port`** is the **world** port (default
  **8085**, matches `WorldServerPort` in `worldserver.conf.dist`).
  Auth tells the client to handshake to this port for the world hand-off.
- **`realmlist` table -> `address`** defaults to **`127.0.0.1`** in the
  base SQL. The auth server hands this address to clients after login,
  so 127.0.0.1 means "talk to the world server on the same machine
  auth is running on" -- correct for solo dev. **Override on production
  deploys**, see *Production deployment overrides* below.

### Production deployment overrides

Production Fractured runs on a remote VPS at `hsrwow.net` with auth
bound to a non-stock port (47497 -- 3724 was unavailable on that host).
Apply the overrides **once per fresh dbimport** on the production box.

```sql
-- Run against acore_auth on the production database after first dbimport:
UPDATE realmlist
   SET address = 'hsrwow.net',
       port    = 8085          -- world port; leave at 8085 unless changed
 WHERE id = 1;
```

Edit the production `authserver.conf` (NOT `authserver.conf.dist`)
to bind the auth listener to the production port:

```ini
RealmServerPort = 47497
```

Restart the auth server. Production clients connect with:

```text
set realmlist hsrwow.net:47497
```

The Fractured-patched 3.3.5 client supports the `host:port` syntax;
stock 3.3.5 clients do not, so any contributor distributing the
client bundle for production must include the patched `Wow.exe` from
the GitHub release.

---

## What you get when you build this fork

- Worldserver with `CLASS_PARAGON` and Paragon-aware DK rune / sticky
  combo-point logic linked into core.
- `modules/mod-paragon` (statically linked): Paragon player hooks, AE/TE
  currency, gametables, `.paragon` chat commands.
- `modules/mod-ale` (statically linked): the ALE Lua scripting engine,
  which fetches LuaJIT at configure time. **Requires `-DLUA_VERSION`.**
- Tools (`mapextractor`, `vmap4_*`, `mmaps_generator`) for client data.

---

## 1. Install prerequisites

### Linux (Ubuntu 22.04 / Debian 12)

```bash
sudo apt update
sudo apt install -y \
    git cmake make gcc g++ clang \
    libmariadb-dev-compat libmariadb-dev default-libmysqlclient-dev \
    libssl-dev libbz2-dev libreadline-dev libncurses-dev \
    libboost-all-dev \
    mariadb-server p7zip-full
```

If you prefer MySQL 8 over MariaDB, install `mysql-server` instead and
keep `default-libmysqlclient-dev`.

### Windows 10 / 11

Install (any recent versions):

- **Visual Studio 2022** with the *Desktop development with C++*
  workload (MSVC v143 toolset, Windows 10/11 SDK).
- **Git for Windows**.
- **CMake 3.16+** (the GUI is fine).
- **MySQL Server 8** *or* **MariaDB 10.x** with the C connector
  development headers (the MySQL Installer's "Connector C" component).
- **OpenSSL 3.x** (e.g. the [Shining Light](https://slproweb.com/products/Win32OpenSSL.html)
  Win64 build — pick the *full* installer, not "Light"). Set the
  `OPENSSL_ROOT_DIR` env var to its install path if CMake can't find it.
- **Boost ≥ 1.74** prebuilt for MSVC (e.g. from
  <https://sourceforge.net/projects/boost/files/boost-binaries/>). Set
  `BOOST_ROOT` to its install path so CMake can locate it.
- **7-Zip** for extracting client data archives.

### macOS

Use Homebrew:

```bash
brew install cmake boost openssl@3 mysql readline ncurses p7zip
```

---

## 2. Clone the repo

```bash
git clone https://github.com/Dawnforger/Fractured.git
cd Fractured
```

The `mod-paragon` and `mod-ale` modules are already in `modules/`; no
extra `git clone` needed.

---

## 3. Configure with CMake

`mod-ale` requires you to pick a Lua version at configure time. Use
**LuaJIT** to match what the team's Docker image uses:

### Linux / macOS

```bash
mkdir -p build
cd build

cmake .. \
    -DCMAKE_INSTALL_PREFIX=$HOME/azeroth-server \
    -DCMAKE_C_COMPILER=clang   \
    -DCMAKE_CXX_COMPILER=clang++ \
    -DCMAKE_BUILD_TYPE=RelWithDebInfo \
    -DLUA_VERSION=luajit \
    -DTOOLS_BUILD=all \
    -DSCRIPTS=static \
    -DMODULES=static \
    -DWITH_WARNINGS=ON
```

GCC works too (drop the `CMAKE_*_COMPILER` lines or set them to `gcc`/`g++`).

### Windows (CMake GUI)

1. **Source code** → repo root (`Fractured/`).
2. **Build the binaries** → `Fractured/build`.
3. *Configure* → choose **Visual Studio 17 2022** generator, **x64**.
4. After the first configure pass fails or warns about Lua, set:
   - `LUA_VERSION` = `luajit`
   - `CMAKE_INSTALL_PREFIX` = e.g. `C:/azeroth-server`
   - `BOOST_ROOT` (if not already detected)
   - `OPENSSL_ROOT_DIR` (if not already detected)
   - `MYSQL_INCLUDE_DIR` / `MYSQL_LIBRARY` if MySQL wasn't auto-found
5. *Configure* until clean, then *Generate*, then *Open Project*.

### Important flags

| Flag | Recommended | Why |
|------|-------------|-----|
| `LUA_VERSION` | `luajit` | Required by `mod-ale`; matches team Docker image. |
| `MODULES` | `static` | Statically links `mod-paragon` and `mod-ale` into the worldserver. |
| `SCRIPTS` | `static` | Default; static script linkage. |
| `TOOLS_BUILD` | `all` | Builds map/mmap/vmap extractors. Set to `none` once you have client data. |
| `CMAKE_BUILD_TYPE` | `RelWithDebInfo` | Default for production-quality builds with usable backtraces. Use `Debug` only when stepping through code. |

---

## 4. Compile

### Linux / macOS

```bash
make -j$(nproc)        # or: -j$(sysctl -n hw.ncpu) on macOS
make install
```

### Windows

In Visual Studio, set the configuration to **RelWithDebInfo / x64**, then:

1. Build `ALL_BUILD`.
2. Build `INSTALL`.

Or from a *Developer PowerShell for VS 2022* in the `build` directory:

```powershell
cmake --build . --config RelWithDebInfo
cmake --install . --config RelWithDebInfo
```

> If the build OOMs on a low-RAM machine, pass `-j 4` (or fewer) to
> `make` / `cmake --build`. The Docker image hard-caps `-j 4` for the
> same reason.

---

## 5. Set up databases

The standard AzerothCore three-database layout (`acore_auth`,
`acore_world`, `acore_characters`) applies unchanged. Follow:

<https://www.azerothcore.org/wiki/database-installation>

Easiest path: run the worldserver once with empty databases and let
`AC_FORCE_CREATE_DB=1` populate them, **or** use `dbimport` from the
install dir.

The Fractured-specific SQL (mod-paragon) lives under
`modules/mod-paragon/data/sql/db-{world,characters}/base/` — that's the
**AzerothCore-standard module layout**, which means AC's built-in
DBUpdater picks it up automatically on every `worldserver` /
`dbimport` start. New SQL files are applied; previously-applied ones
are skipped via the hash recorded in `acore_world.updates` /
`acore_characters.updates`. No manual `mysql < ...` steps required for
deploys.

Modify-and-redeploy works the same way: change the file, push, pull on
the VPS, and the next `dbimport` run sees the new hash and re-applies.

---

## 6. Configure the server

After `make install`, your install prefix has the layout:

```
<INSTALL_PREFIX>/
  bin/         worldserver, authserver, *extractor tools
  etc/         worldserver.conf.dist, modules/*.conf.dist
  data/        client data (you provide)
  logs/
```

1. Copy each `*.conf.dist` to `*.conf` next to it (or in
   `etc/modules/`).
2. Set the `*DatabaseInfo` lines in `worldserver.conf` and
   `authserver.conf` to point at your DB.
3. In `etc/modules/mod_paragon.conf`, review the Paragon-specific
   options (sticky combo points, multi-resource, Ability/Talent Essence
   settings).
4. In `etc/modules/mod_ale.conf`, set `ALE.Enabled = 1` and (optionally)
   `ALE.ScriptPath` if you want a custom Lua scripts folder.

---

## 7. Extract client data

Same as upstream AzerothCore. Run the extractors against your 3.3.5a
client directory once and copy the results into `<INSTALL_PREFIX>/data/`:

```bash
cd <wow-3.3.5a-client>/
<INSTALL_PREFIX>/bin/mapextractor
<INSTALL_PREFIX>/bin/vmap4_extractor
<INSTALL_PREFIX>/bin/vmap4_assembler  Buildings vmaps
<INSTALL_PREFIX>/bin/mmaps_generator
mv dbc maps vmaps mmaps Cameras  <INSTALL_PREFIX>/data/
```

You can also share data between teammates — these directories are
client-only and don't depend on the build.

---

## 8. Run

```bash
cd <INSTALL_PREFIX>/bin
./authserver &
./worldserver
```

On Windows, run `authserver.exe` and `worldserver.exe` from a console
window so you can see startup output.

---

## 9. Updating from `origin`

```bash
cd Fractured
git pull
cd build
cmake ..   # only needed if CMakeLists.txt changed
make -j$(nproc)
make install
```

If a pull touches `modules/*/sql/`, re-apply those SQL files against
the relevant database.

---

## Troubleshooting

- **`Could NOT find Lua`** at CMake time: you forgot `-DLUA_VERSION=luajit`.
- **`fatal error: 'mysql.h' file not found`** on Linux: install
  `default-libmysqlclient-dev` (or `libmariadb-dev`).
- **`Could NOT find Boost`** on Windows: set the `BOOST_ROOT` env var (or
  the `BOOST_ROOT` CMake cache var) to your prebuilt Boost install.
- **Worldserver crashes on a Paragon character**: confirm the
  `mod-paragon` SQL has been applied to both `acore_world` and
  `acore_characters`. Missing `character_paragon_currency` is the most
  common cause.
- **Action buttons grey out for rune spells on Paragon**: this fork
  expects the matching client UI patch (`patch-enUS-5.MPQ`). The server
  build is correct as-is; the visual issue is client-side.