ddon-server/README.adoc

:toc:
:toclevels: 1
:toc-placement!:

= Dragons Dogma Online - Server

image::https://github.com/sebastian-heinz/Arrowgene.DragonsDogmaOnline/actions/workflows/build.yaml/badge.svg[]

Server Emulator for the Game Dragons Dogma Online.

'''

toc::[]

'''

== Disclaimer
The project is intended for educational purpose only.

== Quick Start

=== Developer Setup

. Clone: `git clone https://github.com/sebastian-heinz/Arrowgene.DragonsDogmaOnline.git`
. Install https://dotnet.microsoft.com/download[.NET 10.0 SDK] or later
. Open the project in your IDE of choice:
.. *Visual Studio* -- Open `DragonsDogmaOnline.sln` (minimum Visual Studio 2022)
.. *VS Code* -- Install the https://marketplace.visualstudio.com/items?itemName=ms-vscode.csharp[C# plugin], then open the project folder
.. *IntelliJ Rider* -- Open `DragonsDogmaOnline.sln` (minimum Rider 2021.3)
. Run the `Ddon.Cli` project with arguments `server start`

=== User Setup

. Clone: `git clone https://github.com/sebastian-heinz/Arrowgene.DragonsDogmaOnline.git`
. Install https://dotnet.microsoft.com/download[.NET 10.0 SDK] or later
. Run `publish.cmd` (Windows) or `publish.sh` (Linux/macOS) to build
. Launch with `StartServer.cmd` from the publish output directory
. See the https://github.com/sebastian-heinz/Arrowgene.DragonsDogmaOnline/blob/develop/docs/faq.md[FAQ] for common questions

NOTE: When updating from a previous build, ensure `db.sqlite` is in `publish/win-x64-\#.#.\#.#/Server/Files/Database` and run `MigrateDatabase.cmd` if needed.

== Architecture

The server consists of four components, all started automatically with the default configuration:

[cols="1,1"]
|===
| Web Server     | HTTP/download on port `52099`
| Login Server   | TCP on port `52100`
| Game Server    | TCP on port `52000`
| Database       | SQLite (file or in-memory) or PostgreSQL
|===

=== Persistence

* **SQLite** via System.Data.SQLite -- file-based or in-memory with auto-backup on start/close. Best for development.
* **PostgreSQL** via Npgsql -- recommended for production and parallel write operations.

Sample configurations, schemas, and containerization setups are provided for both.

=== Container Setup

A xref:./Dockerfile[Dockerfile] builds & publishes the server from source. Docker Compose files:

* `docker-compose up` -- SQLite (xref:./docker-compose.yml[config])
* `docker-compose -f docker-compose.psql.yml up` -- PostgreSQL (xref:./docker-compose.psql.yml[config])

.Useful commands
[source,bash]
----
docker-compose up --build                    # force rebuild
docker-compose down -v                       # clean up with volumes
RUNTIME=linux-arm64 docker-compose build     # build for arm64
----

== Client

Launch the client with:

[source]
----
"DDO.exe" "addr=localhost port=52100 token=00000000000000000000 DL=http://127.0.0.1:52099/win/ LVer=03.04.003.20181115.0 RVer=3040008"
----

== Server Settings Reference

Configuration properties defined in `ServerSetting.cs`. These control server identity, networking, and diagnostic logging.

[cols="2,3,5", options="header"]
|===
| Purpose | Description | Use Case / Example

| `Id`
| Unique server identifier (int)
| Distinguishes server instances. Defaults to `-1` (invalid). Set to a positive integer when registering the server, e.g. `1` for a primary game server.

| `Name`
| Human-readable server name
| Displayed in server lists or logs. For example `"Lestania-01"` to label a game world instance.

| `ListenIpAddress`
| IP address the server binds to
| Defaults to `IPAddress.Any` (all interfaces). Set to a specific IP like `192.168.1.100` to restrict which network interface accepts connections.

| `ServerPort`
| TCP port the server listens on
| Defaults to `52100`. Change to avoid port conflicts or run multiple instances, e.g. `52101` for a second login server.

| `LogLevel`
| Verbosity of log output (int)
| `0` = default. Increase for more verbose output during development and debugging.

| `LogUnknownPackets`
| Log packets with no registered handler
| Defaults to `true`. Useful for reverse engineering new packet types. Disable in production to reduce log noise.

| `LogOutgoingPackets`
| Log headers of sent packets
| Defaults to `true`. Helps trace server responses. Disable for performance in high-traffic environments.

| `LogOutgoingPacketPayload`
| Log full payload of sent packets
| Defaults to `false`. Enable to inspect exact bytes sent to clients, e.g. when debugging malformed response data.

| `LogOutgoingPacketStructure`
| Log structured breakdown of sent packets
| Defaults to `false`. Enable to see field-by-field decoded output of outgoing packets during protocol development.

| `LogIncomingPackets`
| Log headers of received packets
| Defaults to `true`. Helps trace client requests. Disable in production to reduce log volume.

| `LogIncomingPacketPayload`
| Log full payload of received packets
| Defaults to `false`. Enable to inspect raw bytes from clients, e.g. when reverse engineering a new client action.

| `LogIncomingPacketStructure`
| Log structured breakdown of received packets
| Defaults to `false`. Enable to see decoded fields of incoming packets, useful for verifying parser correctness.

| `ConsumerQueueCapacityPerLane`
| Max queued items per consumer lane
| Defaults to `100000`. Increase if the server handles high throughput and packets are being dropped due to queue saturation.

| `TcpServerSettings`
| Low-level TCP socket configuration https://github.com/sebastian-heinz/Arrowgene.Networking?tab=readme-ov-file#configuration[(Link to Configuration)]
| Wraps `Arrowgene.Networking.SAEAServer.TcpServerSettings`. Tune buffer sizes, backlog, and socket options for production deployments.
|===

.Suggested settings for DDON:
[cols="2,1,3", options="header"]
|===
| Setting | Value | Note

| `TcpServerSettings.OrderingLaneCount`
| `1`
| Must remain at 1 as the DDON server is single-threaded and not threadsafe

| `TcpServerSettings.MaxQueuedSendBytes`
| `8388608`
| Maximum bytes (~8 MB) that can be buffered for sending before back-pressure is applied

| `ConsumerQueueCapacityPerLane`
| `100000`
| Maximum number of events that can be queued per lane before networking stalls
|===

== Progress
See the https://github.com/sebastian-heinz/Arrowgene.DragonsDogmaOnline/wiki/What-Works%3F[wiki].

== Guidelines

=== Git Workflow
Work via feature branches:

. Create `feature/feature-name` or `fix/bug-fix-name` from master
. Push changes to that branch
. Create a Pull Request into `master`

=== Best Practices
* Use the project logger -- not `Console.WriteLine`
* Own the code: extract solutions, discard libraries
* Annotate with https://docs.microsoft.com/en-us/dotnet/csharp/language-reference/language-specification/documentation-comments[documentation comments]

=== Naming Conventions

[cols="1,1,1,1", options="header"]
|===
| Object          | Notation   | Char Mask  | Underscores
| Class            | PascalCase | [A-z][0-9] | No
| Constructor      | PascalCase | [A-z][0-9] | No
| Method           | PascalCase | [A-z][0-9] | No
| Method arguments | camelCase  | [A-z][0-9] | No
| Local variables  | camelCase  | [A-z][0-9] | No
| Constants        | PascalCase | [A-z][0-9] | No
| Fields           | _camelCase | [A-z][0-9] | Yes
| Properties       | PascalCase | [A-z][0-9] | No
| Delegates        | PascalCase | [A-z]      | No
| Enum types       | PascalCase | [A-z]      | No
|===

== Attribution

=== Contributors
* **Nothilvien** https://github.com/sebastian-heinz[@sebastian-heinz] -- Reverse Engineering & Server Code
* **Ando** -- Reverse Engineering & Tooling (Session Splitter, Camellia Key Cracker)
* **David** -- Reverse Engineering (unpacking PC Executable, defeating Anti Debug and CRC checks)
* **The White Dragon Temple**

=== Libraries
* https://github.com/sebastian-heinz/Arrowgene.Networking[Arrowgene.Networking] -- TCP networking
* https://github.com/sebastian-heinz/Arrowgene.Networking[Arrowgene.Buffers] -- Binary buffer handling
* https://github.com/sebastian-heinz/Arrowgene.Networking[Arrowgene.Logging] -- Logging framework
* https://github.com/sebastian-heinz/Arrowgene.Networking[Arrowgene.WebServer] -- Embedded web server
* https://system.data.sqlite.org/[System.Data.SQLite] -- SQLite database provider
* https://learn.microsoft.com/en-us/ef/core/providers/sqlite/[Microsoft.Data.Sqlite] -- SQLite (Microsoft)
* https://www.npgsql.org/[Npgsql] -- PostgreSQL database provider
* https://mysqlconnector.net/[MySqlConnector] -- MySQL database provider
* https://github.com/dotnet/roslyn[Microsoft.CodeAnalysis.CSharp.Scripting] -- C# scripting support
* https://icsharpcode.github.io/SharpZipLib/[SharpZipLib] -- Compression library
* https://github.com/aaubry/YamlDotNet[YamlDotNet] -- YAML parsing