Imlight

Appearance

Quickstart Guide ​

Addressing The Gap ​

In the shared data article, it's discussed that the server and game client share the same data for mutual understanding. This does, however, lead to plenty of gaps in data where only the server uses a section of data. Sometimes this data still ships with the game client, other times it does not.

There is no way for the server to know the missing information unless it is manually created.

Creating a server using Imlight requires filling in these gaps with your own data. Imlight uses a second database, WorldData, to store this information.

This separate database and the data it contains is referred to as a "data pack".

If you do not recreate this data, you will notice missing functionality in your server:

  • Where gateways lead (zone transfers)
  • NPC spell decks
  • NPC shopkeeper inventories
  • Drop tables
  • Quests

Bring Your Own Data ​

Imlight does not, and never will ship with a "data pack" of this information. Implementation teams must create and maintain their own data packs to fill these gaps.

Implementations and derivatives using Imlight are required to follow the same BYOD philosophy and must not distribute any copyrighted game files, game data, or data packs.

Data Pack Disclaimers ​

TIP

Revive101 has developed a tool to help manually recreate this data called Imview. This tool is an over-arching tool to manage Imlight as a whole, but includes a subset of features to help with data creation. It is highly recommended to use this tool to help with data creation.

Imview can connect to your WorldData database. If you are a part of a team, you can share your data pack with other team members by sharing the database.

WARNING

It is impossible to know precisely how the original servers handled server-side data. Imlight must make informed assumptions about the original server behavior. Consequently, certain data or the way it is processed may differ from the original implementation and may not be entirely accurate.

INFO

In may be possible in the future that zone transfers can be automatically generated by analyzing game data. It has not been explored yet.

INFO

It's been observed that in some game revisions, NPC spell decks are shipped with the client. However, this does not always happen and cannot be relied upon.

Prerequisites ​

Development Environment

  • .NET 9.0 SDK - Required for building Imlight and Imcodec
  • Git - For cloning repositories and managing submodules

External Tools

  • WizType - Extract type definitions from game client
  • Aurorium - Self-hosted patch server

Core Setup ​

1. Clone Imlight Repository ​

bash
# Clone with Imcodec submodule
git clone --recurse-submodules https://github.com/Revive101/Imlight.git

# Or if already cloned, initialize submodules
cd Imlight
git submodule update --init --recursive
# Clone with Imcodec submodule
git clone --recurse-submodules https://github.com/Revive101/Imlight.git

# Or if already cloned, initialize submodules
cd Imlight
git submodule update --init --recursive

2. Prepare Imcodec Source Generation ​

Imcodec requires game data files to generate strongly-typed C# classes at compile time. If you'd like an in-depth reading on why, see the Imcodec documentation.

Type Definitions

  1. Use WizType to extract type definitions from your game client
  2. Save the generated JSON file to:
    /submodule/Imcodec/src/Imcodec.ObjectProperty/GeneratorInput/
    /submodule/Imcodec/src/Imcodec.ObjectProperty/GeneratorInput/

Message Definitions

  1. Extract Root.wad from your game client using Imcodec itself:
    bash
    dotnet run --project submodule/Imcodec/src/Imcodec.Cli wad unpack Root.wad
    dotnet run --project submodule/Imcodec/src/Imcodec.Cli wad unpack Root.wad
  2. Locate XML files matching *Messages*.xml pattern
  3. Copy all message XML files to:
    /submodule/Imcodec/src/Imcodec.MessageLayer/GeneratorInput/
    /submodule/Imcodec/src/Imcodec.MessageLayer/GeneratorInput/

3. Build Imlight ​

bash
# From Imlight root directory
dotnet build

# Or for release build
dotnet publish -c Release
# From Imlight root directory
dotnet build

# Or for release build
dotnet publish -c Release

TIP

Imlight may fail to build with errors about missing types or messages. If you certain you've put the correct files in the GeneratorInput directories, build the Imcodec project first to ensure the source generation completes successfully.

Database Configuration ​

Imlight uses RavenDB with two separate databases for different data types. There are two different modes of operation: remote database connections or an embedded fallback database. The embedded database will be used if you do not supply remote database URL.

Database Types ​

PlayerDatabase

  • Purpose: User accounts and character data
  • Access: Production deployment only (highly sensitive)

WorldDatabase

  • Purpose: Server-specific world data and gap-fill information
  • Access: Development teams should have access for data creation

Configuration ​

Edit /src/Imlight.Director/Config/Imlight.ini:

ini
[Database]
# Leave empty for embedded database
PlayerDatabaseUrl = 
PlayerDatabaseName = Playerdata

# Production WorldData URL or empty for embedded
WorldDatabaseUrl = https://your-worlddata-server.com
WorldDatabaseName = WorldData

# Certificate paths (required for remote databases)
PlayerDatabaseCertificatePath = ../Certificates/playerdb.pfx
WorldDatabaseCertificatePath = ../Certificates/worlddb.pfx

# Embedded database settings
EmbeddedDatabaseDataDirectory = ../ImlightEmbeddedDatabase/
EmbeddedDatabasePort = 8080
EmbeddedDatabaseUseFull = False
[Database]
# Leave empty for embedded database
PlayerDatabaseUrl = 
PlayerDatabaseName = Playerdata

# Production WorldData URL or empty for embedded
WorldDatabaseUrl = https://your-worlddata-server.com
WorldDatabaseName = WorldData

# Certificate paths (required for remote databases)
PlayerDatabaseCertificatePath = ../Certificates/playerdb.pfx
WorldDatabaseCertificatePath = ../Certificates/worlddb.pfx

# Embedded database settings
EmbeddedDatabaseDataDirectory = ../ImlightEmbeddedDatabase/
EmbeddedDatabasePort = 8080
EmbeddedDatabaseUseFull = False

Certificate Setup ​

For remote database connections, place certificates in:

./Imlight/Certificates/
├── playerdb.pfx
└── worlddb.pfx
./Imlight/Certificates/
├── playerdb.pfx
└── worlddb.pfx

Patch Server Setup ​

Imlight and the game client must source files from the same location.

Self-Hosted Patch Server ​

  1. Set up Aurorium patch server
  2. Update configuration:
    ini
    [Patch Server]
PatchServerInternalUrl = http://your-patch-server.com
    [Patch Server]
PatchServerInternalUrl = http://your-patch-server.com