Installation Windows

Windows Installation

This guide covers what you need to install and run the fb server stack on Windows for local development.

For architecture overview, see Architecture and Technology Stack.

Overview

A full local stack includes:

Layer	Components
Infrastructure	MySQL 8.x, Redis, RabbitMQ
C++ services	Gateway, Login, Game, Bot
.NET services	Internal, Write-back, Log, Marketplace, Admin Tool
Runtime assets	Map files, Lua scripts, generated JSON/model data

There are two common workflows on Windows:

Run prebuilt binaries — use the Runner tool and the Patch feature (fastest way to start servers).
Build from source — required for C++ / protocol / game-data development.

Requirements

Operating system

Windows 10 or Windows 11 (64-bit)

Required for all workflows

Requirement	Version / notes
Git for Windows	Submodule support (`tools/data-converter`, `tools/flatbuffer-ex`)
.NET 8 SDK	Backend services and build tools (SDK, not runtime only)
Network access	Submodule fetch; optional Runner patch download

Required to build C++ from source

Requirement	Version / notes
CMake	3.28+ (`CMakeLists.txt` minimum)
Visual Studio 2022	Desktop development with C++ workload
MSVC toolset	C++20 (`/std:c++20`)
Disk space	Several GB free; `tools/update-modules.bat` clones and builds Boost and other native libraries under `tools/library/`

Native libraries are installed into dependency/ (gitignored, generated locally):

jsoncpp, rabbitmq-c, Lua, zlib, FlatBuffers, cpp-async, aho_corasick, Boost

Required to run servers locally

Service	Purpose	Default dev port
MySQL 8.x	Unified DB, per-world global/data/log databases	`3306`
Redis	Cache, sessions, distributed locks	`6379`
RabbitMQ	Internal events, write-back queue, log pipeline	`5672` (AMQP)

Example connection layout (see server/internal/appsettings.Development.json):

Unified MySQL: fb-unified
World 1: fb-1-global, fb-1-data-0 … fb-1-data-2
Log shards: created by migrations under infra/db/migrations/

Database:AutoMigration is enabled in development configs. On first start, Internal (and other .NET services) apply SQL migrations from infra/db/migrations/ when the MySQL user can create databases and tables.

Optional

Tool	Purpose
Runner (`tools/runner`)	WPF launcher: Patch download, config generation, start/stop processes
Visual Studio	Debug C++ services; local `*.vcxproj` files (gitignored)
Excel	Only if you edit game tables in `resources/table/` and rerun `tools/update-data.bat`

Note: tools/setup.bat is outdated (old directory layout, removed infra/db/latest.sql). Do not use it. Follow this guide or the CI steps in .github/workflows/build.yml (build-windows job) instead.

1. Clone the repository

git clone --recurse-submodules https://github.com/boyism80/fb.git
cd fb

If already cloned without submodules:

git submodule update --init --recursive

Submodules used for development:

tools/data-converter — Excel → C++/C#/JSON
tools/flatbuffer-ex — FlatBuffer protocol codegen
wiki — project wiki (optional for running servers)

2. Set up infrastructure

Install and start MySQL, Redis, and RabbitMQ on the same machine or update the connection settings in:

server/internal/appsettings.Development.json
server/write-back/appsettings.Development.json
server/log/appsettings.Development.json
server/marketplace/appsettings.Development.json
server/gateway/config/config.dev.json
server/login/config/config.dev.json
server/game/config/config.dev.json

Default development ports (C++ config examples):

Service	Port
Internal (HTTP)	`3000`
Gateway (TCP)	`3001`
Login (TCP)	`3002`
Game (TCP)	`3004` (see `server/game/config/config.dev.json`)

Ensure Windows Firewall allows inbound connections on the ports clients and services use.

Path A — Run prebuilt binaries (Runner)

Best when you only need a running server and do not need to compile C++.

A.1 Build Runner

cd tools\runner
dotnet publish -c Release -o bin

Or use tools\run.bat from the tools directory.

A.2 Download server binaries (Patch)

Start tools\runner\bin\runner.exe
Set Working directory to your fb repository root
Click Patch — downloads dist.zip and extracts to build\dist\

The Patch step provides prebuilt executables:

gateway.exe, login.exe, game.exe
internal\, write-back\, log\, marketplace\, admin-tool\

A.3 Refresh local assets (recommended)

After patching, update maps, generated JSON, and scripts from the repo:

Runner menu	Source in repo	Output
파일 → 업데이트 → 맵	`resources/maps/maps.zip`	`build/dist/maps/`
파일 → 업데이트 → 데이터	runs `tools/update-data.bat`	`build/dist/json/`, `build/dist/internal/json/`
파일 → 업데이트 → 스크립트	`server/game/scripts/`	`build/dist/scripts/`

If 스크립트 update fails, copy manually:
server\game\scripts → build\dist\scripts

A.4 Configure and run

In Runner, configure:

External IP — address clients connect to (LAN IP or 127.0.0.1 for local-only)
MySQL / Redis / RabbitMQ — must be reachable (Runner checks TCP ports before start)
Login and Game server entries with ports
Internal port (default 3000)

Click Run to generate configs under build\dist\config\ and start:

Gateway, Login, Game (C++)
Internal, Write-back (.NET)

MySQL / Redis / RabbitMQ must already be running.

Path B — Build from source

Required for C++, protocol, or game-table changes. Matches the build-windows job in .github/workflows/build.yml.

B.1 Build native dependencies

Open Developer PowerShell for VS 2022 (or a shell with cl.exe on PATH):

cd tools
.\update-modules.bat

This clones third-party sources into tools\library\, builds them, and copies headers/libs into dependency\.
Boost in particular can take a long time on first run.

B.2 Generate game data (optional)

Only needed after changing Excel files in resources/table/:

cd tools
.\update-data.bat

Outputs include:

include/fb/model/model.h
server/game/json/, server/login/json/, server/bot/json/
server/http/Model/Model.cs and JSON for .NET services

B.3 Generate protocol (optional)

Only needed after changing files under protocol/:

cd tools
.\update-flatbuffer.bat

B.4 Build C++ servers

mkdir build -ErrorAction SilentlyContinue
cd build
cmake ..
cmake --build . --config Debug

Outputs (Debug):

build\server\gateway\Debug\gateway.exe
build\server\login\Debug\login.exe
build\server\game\Debug\game.exe
build\server\bot\Debug\bot.exe

CMake also generates a Visual Studio solution under build\ if you prefer IDE debugging.

B.5 Build .NET services

From the repository root:

dotnet publish server/internal/internal.csproj -c Release -o build/dist/internal
dotnet publish server/write-back/write-back.csproj -c Release -o build/dist/write-back
dotnet publish server/log/log.csproj -c Release -o build/dist/log
dotnet publish server/marketplace/marketplace.csproj -c Release -o build/dist/marketplace
dotnet publish server/admin-tool/admin-tool.csproj -c Release -o build/dist/admin-tool

Set ASPNETCORE_ENVIRONMENT=Development when using appsettings.Development.json (Runner sets ASPNETCORE_ENVIRONMENT to the service folder name).

B.6 Prepare runtime layout

Create a build\dist layout similar to the Patch output:

# C++ binaries
Copy-Item build\server\gateway\Debug\gateway.exe build\dist\
Copy-Item build\server\login\Debug\login.exe build\dist\
Copy-Item build\server\game\Debug\game.exe build\dist\

# Maps
Expand-Archive -Path resources\maps\maps.zip -DestinationPath build\dist\maps -Force

# Scripts and JSON
Copy-Item -Recurse server\game\scripts build\dist\scripts
Copy-Item -Recurse server\game\json build\dist\json

Configs: copy or symlink server/*/config/config.dev.json, or use Runner to generate build\dist\config\ at runtime.

B.7 Run services

Minimal stack for one world:

Start MySQL, Redis, RabbitMQ
Internal — applies DB migrations, central HTTP API
Write-back — persists Redis cache to MySQL
Log — optional but recommended for structured logs
Marketplace — required for in-game marketplace features
Gateway → Login → Game — client-facing TCP services

Example (Internal):

$env:ASPNETCORE_ENVIRONMENT = "Development"
$env:ASPNETCORE_HTTP_PORTS = "3000"
dotnet build/dist/internal/internal.dll

C++ example (Game):

cd build\dist
.\game.exe -c config\game\config_game_0.json

Using Runner after building into build\dist is still the easiest way to manage multi-process startup.

Visual Studio notes

server/**/*.vcxproj files are local and gitignored
CMake GLOB picks up new C++ sources automatically; Visual Studio projects must be updated manually (see tools/codegen/integration_protocol/README.md for Bot)
Do not run cmake to regenerate vcxproj unless you intentionally want to refresh the CMake solution

Troubleshooting

Problem	Check
`dependency\lib\*.lib` not found	Run `tools\update-modules.bat`
CMake version error	Install CMake 3.28 or newer
`dotnet` not found	Install .NET 8 SDK
MySQL connection failed	Server running, credentials match `appsettings.Development.json`, port open
Runner: port not open	Redis / RabbitMQ / MySQL not listening on configured host:port
`game.exe` not found in `build\dist`	Complete Path B build or use Runner Patch
Korean text garbled in scripts	Source files are UTF-8; ensure editor and console use UTF-8

Related pages

Home

Server

Setup

Windows
- Runner
- Build from source
Linux
- Docker Compose
- Kubernetes
- Pulumi (optional)

Scripting

Builtin functions

Installation Windows

Windows Installation

Overview

Requirements

Operating system

Required for all workflows

Required to build C++ from source

Required to run servers locally

Optional

1. Clone the repository

2. Set up infrastructure

Path A — Run prebuilt binaries (Runner)

A.1 Build Runner

A.2 Download server binaries (Patch)

A.3 Refresh local assets (recommended)

A.4 Configure and run

Path B — Build from source

B.1 Build native dependencies

B.2 Generate game data (optional)

B.3 Generate protocol (optional)

B.4 Build C++ servers

B.5 Build .NET services

B.6 Prepare runtime layout

B.7 Run services

Visual Studio notes

Troubleshooting

Related pages

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Clone this wiki locally