L2JMobius Setup Guide: From Clone to First Login

L2Calendar Team11.09.202611 min read

L2JMobius Setup Guide: Build and Run Your Server

A clean l2jmobius setup takes an afternoon if you follow the order the project expects: build first, database second, configuration third, and only then start the servers. Most first attempts fail because someone skips the database installer, launches the game server before the login server, or compiles with the wrong Java version. This guide walks the full path from cloning the repository to your first character logging in, and lists the errors that stop people at each step. The exact commands reflect the current project layout; your chronicle folder may differ in small details.

Prerequisites: Java, Database, and the Right Chronicle

Get these in place before you touch the source. Missing one of them is the most common cause of a failed build.

Java JDK. Recent L2JMobius releases target a modern JDK — the current C4 line requires JDK 25, and earlier chronicle folders may use a different version. Check the readme.txt in your chronicle folder and install exactly that JDK.
A database engine. MySQL 5.7+ or MariaDB 10.3+. Create a dedicated database with utf8mb4 collation for correct character handling.
A build tool. Apache Ant, driven by the build.xml at the root of the chronicle you are building.
Hardware. At least 4 GB of RAM to test (16 GB+ recommended once players are on), and roughly 10 GB of free disk for the source, build output, and database.

Pick one chronicle folder and work only inside it. L2JMobius ships one self-contained distribution per chronicle, and mixing folders or schemas causes avoidable failures.

Step 1 — Clone the Repository and Build with Ant

Clone the project, open it in your IDE, and run the Ant build.

Clone https://gitlab.com/MobiusDevelopment/L2J_Mobius.git (the full source is on GitLab).
Import the projects into Eclipse or IntelliJ, and make sure the IDE points at the JDK you installed, not a bundled one.
Right-click build.xml and run it as an Ant build. Wait for BUILD SUCCESSFUL.
Collect the packaged distribution from the build directory (a zip you extract to a working folder such as C:\L2J_Mobius, or your chosen path on Linux).

If the build fails immediately, it is almost always the Java version or a missing Ant install. Fix that before investigating anything else.

Step 2 — Set Up MySQL or MariaDB

Install and start the database service, then create the schema and a user for the server.

On Windows, XAMPP is a convenient way to start MySQL, but check that its bundled version still meets the minimum above; a standalone MySQL or MariaDB install is the safer choice. On Linux, use your package manager and systemctl.
Create the database and a dedicated user, and grant it privileges on that database.
Use utf8mb4 for the database so non-Latin character names are stored correctly.

Keep the credentials handy. You will enter them into two configuration files, not one.

L2JMobius Setup Guide: Build and Run Your Server (2) — Lineage II © NCSOFT

Step 3 — Run the Database Installer and Configure Connections

The database installer creates the tables and loads base data. Skipping it is the number one setup mistake.

Open the db_installer folder in your extracted distribution.
Edit config/Database.ini inside the installer with your host, database name, user, and password.
Run the installer (on Windows, the provided DatabaseInstaller.vbs; on Linux, the shell launcher or java -jar DatabaseInstaller.jar).
Choose the option to install both the login and game schemas, then let it create tables and import base data.

Now configure the two servers to reach that database. Edit the same connection block in both login/config/Database.ini and game/config/Database.ini. If these differ from the installer config, the servers will start and then fail to read data.

Step 4 — Start the Login Server, Then the Game Server

Order matters. The game server registers with the login server, so the login server must be up first.

Start the login server from the login folder. Wait for the message that it is listening (default port 2106).
Start the game server from the game folder. Wait for it to report listening (default port 7777) and to register successfully.
Tune the JVM memory in java.cfg for each process. The game server needs substantially more heap than the login server.

If the game server logs a registration failure, the database credentials or the login server state are the usual causes, not the network.

Step 5 — Match the Client Protocol and Log In

A running server is only half the job. The client must speak the same protocol version as the chronicle you compiled.

Verify the client protocol version matches the chronicle folder (Chronicle 4 clients, for example, typically use protocol 656). A mismatch shows up as an immediate disconnect at character select.
Point the client's server address and login port at your machine if you are testing locally.
Create a game account through the login server, then log in and confirm your first character loads.

Common L2JMobius Setup Errors and Fixes

"Cannot connect with client" or instant disconnect. Almost always a protocol mismatch — confirm the client version matches the chronicle.
Build fails on the Java check. Your JDK is the wrong version for that chronicle folder. Install the version the readme specifies.
Game server starts but characters cannot move or load. Correct this usually means the database installer never ran, or login/game point at different databases. Re-run the installer and reconcile both config files.
Connection refused to the database. The database service is not running, or the credentials in Database.ini are wrong.
Server lags with players online. Review JVM heap in java.cfg and your database settings before blaming the code.

After First Login: List Your Server and Get Found

A working L2JMobius setup is the start, not the launch. Verify stability with a private test, then publish an accurate listing — chronicle, rates, and opening hour — on L2Calendar's free listing. When you are ready to compete for attention during launch weeks, VIP placement puts the server in front of players actively browsing new openings. The pack gets you running; discovery is what fills your server.

Frequently asked questions

Which Java version does L2JMobius need?

It depends on the chronicle. Recent releases target a modern JDK, and the current C4 line requires JDK 25. Earlier chronicle folders may specify a different version, so always check the readme.txt in the folder you are building and build that chronicle only.

Do I need XAMPP for L2JMobius setup?

No, but it is a convenient way to get MySQL running on Windows. On Linux you can install MySQL or MariaDB directly. The server only needs a reachable MySQL 5.7+ or MariaDB 10.3+ database with the schema installed.

Why does my client disconnect right after I connect?

The client protocol version does not match the chronicle folder you compiled. Each retail patch changes packet opcodes, so you must pair the right client build with the right chronicle. Confirm the protocol the chronicle expects before troubleshooting further.

Can I run one L2JMobius database for several chronicles?

No. Each chronicle folder ships its own schema and seed data, and they differ enough that mixing them breaks both. Run one database per chronicle deployment and use the bundled db_installer for that chronicle.