L2JServer Guide: Build, Configure and Run a Lineage 2 Server

L2Calendar Team18.09.202610 min read

L2JServer Guide: Build and Run a Java Lineage 2 Server

This l2jserver guide walks server owners through building, configuring and launching a complete Lineage 2 server from source. L2J Server is a free, open-source emulator written in Java and released under GPLv3, and it remains one of the oldest and most widely forked projects in the private server scene. The stack splits into a login server and a game server, with the game side further split into the core and the datapack. This article covers prerequisites, the Maven build, the database, configuration, server registration, ports and the first client connection, so you can go from a clean machine to a running world.

What L2J Server Is and When to Use It

L2J Server is a free, open-source Lineage 2 server emulator fully written in Java and released under the GPLv3. It is one of the oldest L2J projects and has been forked many times over the years. The official documentation lives at the L2J Server docs, and it is the first place to check when a step here differs from your environment.

The project is an ecosystem rather than a single binary. It breaks down into three parts:

Login Server — authenticates accounts and points the client at the game server.
Game Server core — the l2j_server core repository, the engine itself.
Datapack — the l2j-server-datapack repository, holding scripts, spawns, quests and static data.

On fit: L2J Server is the classic line. In practice, owners running Interlude usually reach for aCis, while High Five worlds often choose L2J Server or L2JMobius. Mobius covers many chronicles and is very active; aCis is Interlude-focused. Pick L2J Server when you want the well-documented, classic Java stack on High Five.

Prerequisites Before You Build

Set these up first so the build and boot do not stall halfway:

A recent JDK. Current L2J Server builds target Java 11 or newer, and Java 21 is a safe modern choice.
MySQL or MariaDB. The official MariaDB download page has packages for every major OS.
A matching Lineage 2 client plus a system patch built for your server revision.
Git, and handy utilities such as HeidiSQL for the database and 7-Zip for archives.

Run all of it on a machine you control. A small VPS is fine for testing; production usually wants more RAM once players and spawns scale up.

Get the Source and Build with Maven

Clone both repositories from Bitbucket. An old GitHub mirror still exists, but the project moved to Bitbucket, so treat Bitbucket as the canonical source and ignore stale forks elsewhere.

Three branches matter:

master — the latest High Five release.
develop — current High Five development, newer and slightly less battle-tested.
Interlude — a maintained legacy branch, still updated.

The modern build uses the Maven wrapper, so you do not need a system-wide Maven install. On Linux run ./mvnw clean install; on Windows run mvnw.cmd clean install. Older tutorials used Gradle and Eclipse, so treat those as historical rather than current instructions.

If you would rather skip the build entirely, a maintained container image is published at the L2J Server Docker image.

L2JServer Guide: Build and Run a Java Lineage 2 Server (2) — Lineage II © NCSOFT

Set Up the MySQL or MariaDB Database

Create the schemas. A common layout uses two databases, for example l2jls for the login server and l2jgs for the game server, though some setups keep a single l2jdb for both. Either works as long as your config files agree with it.

The database installers live in server/tools: dbinst_ls for the login schema and dbinst_gs for the game schema. The datapack also ships its own database installer. Run the matching installer against each schema and confirm the tables were created before moving on.

Create a dedicated database user for the server rather than using root. Grant it rights only on the schemas the server needs, and give it a strong password.

Configure the Login and Game Servers

Two files drive the connection to your database: config/loginserver.properties and config/server.properties. In each, set the JDBC URL plus the Login and Password keys so they match the database user you just created.

Also review, while you are in there:

The host and port the login server binds to.
The game server's external and internal addresses, which must match how players reach you.
Rates, spawn multipliers and player limits — leave defaults until the server boots cleanly, then tune.

Keep both config files under version control. When something breaks after a change, a quick diff beats guessing.

Register, Start and Connect

Before the game server can talk to the login server, register it. Run the register-game-server tool to generate a hexid.txt file, then copy that file into the login server's config folder. Skipping this is the most common reason a fresh install refuses to connect.

Start in order. Bring up the login server first with startLoginServer.bat on Windows or startLoginServer.sh on Linux, then start the game server with startGameServer.bat or startGameServer.sh. Watch both consoles for errors during boot; they are far easier to fix now than after launch.

Ports: the login server and game server use default ports of 2106 and 7777. Both must be reachable. On a local test machine the defaults are fine, but for non-localhost play open them in the OS firewall and any cloud security group, then test from an outside network.

Before You Open to Players

Once the client connects, do a pass on the basics: verify account creation, log in with a test character, and confirm rates and NPCs behave the way you expect. Change every default password and disable anything you do not need exposed.

Start with a private build, prove the full login and game loop on your own machine, and only then open the firewall. Debugging one layer at a time saves hours.

When you are ready to attract players, list your world through the free server submission form, or take a VIP placement for more visibility. You can also browse the full server directory to see how other owners present their rates, chronicle and features before you write your own listing.

Frequently asked questions

Is L2J Server free to use commercially?

L2J Server is released under the GPLv3, so the emulator itself is free and open-source. You are responsible for the Lineage 2 client, trademark and licensing side, and for how you run your own server.

Which branches should I use?

Use master for the latest High Five release, develop for current High Five development, or the maintained Interlude branch if you are targeting that chronicle. Match your client and system patch to the branch you build.

Do I need Maven installed?

No. The project ships a Maven wrapper, so run mvnw clean install on Linux or mvnw.cmd clean install on Windows. Older Gradle and Eclipse instructions are historical.

Why does my game server not appear on the login server?

You almost certainly skipped server registration. Run the register-game-server tool to produce hexid.txt, then copy it into the login server config folder and restart both servers.

What ports must be open?

The login server and game server use defaults of 2106 and 7777. Open both in your OS firewall and any cloud security group, and verify them from a network outside your host.