Custom bridge

Use this guide when the game server is not the exact aCis 409 or Mobius CT_0 revision covered by a reference implementation.

Requirements

• Java 25
• Access to the game server source and build process
• Access to the game database through the pack's existing connection pool
• portal-connector-core-<version>.jar
• minimal-json-0.9.5.jar

Download both JAR files from Admin → Game Servers and place them in the directory included by the pack's build and runtime classpath.

The published core classes use the package net.sf.l2j.gameserver.portal. A custom bridge may use any package, but it must implement net.sf.l2j.gameserver.portal.GameBridge.

1. Select a reference

Compare the target pack with both reference implementations:

• aCis 409: bcrypt credentials, obj_Id character identifier, aCis runtime APIs
• Mobius CT_0: SHA-1/Base64 credentials, charId character identifier, Mobius runtime APIs

Verify all table names, column names, password hashing, item/skill APIs, world lookups, and persistence calls against the target revision.

2. Implement GameBridge

Create a class that implements the core interface:

import net.sf.l2j.gameserver.portal.GameBridge;

public final class MyGameBridge implements GameBridge
{
	@Override
	public String[] capabilities()
	{
		return new String[]
		{
			"GET_SERVER_STATUS",
			"GET_ONLINE_COUNT"
		};
	}

	@Override
	public int onlineCount()
	{
		return World.getInstance().getPlayers().size();
	}

	// Implement the remaining interface methods.
}

Return only implemented capabilities from capabilities(). Do not advertise PLAYER_ONLINE_EVENT; protocol v1 does not define its event message.

If the bridge implements DELIVER_GRANT or CHARACTER_SERVICES, create a durable command journal keyed by commandId. Follow the state rules in Deliver grants.

3. Start the connector

Run the connector after the game world and data tables have loaded:

import net.sf.l2j.gameserver.portal.PortalConfig;
import net.sf.l2j.gameserver.portal.PortalConnector;

PortalConfig.load();
PortalConnector.getInstance().start();

Add best-effort cleanup to the server shutdown sequence:

try
{
	PortalConnector.getInstance().shutdown();
}
catch (Exception ignored)
{
}

4. Configure the connector

Download portal.properties from Admin → Game Servers and set the bridge class:

Bridge = com.yourpack.gameserver.portal.MyGameBridge

Place the file at config/portal.properties. Do not commit it: the PortalToken authenticates this game server.

Available properties:

Enabled=True
GatewayUrl=<generated gateway URL>
PortalToken=gps_<game-server-id>.<secret>
HeartbeatSeconds=15
Bridge=com.yourpack.gameserver.portal.MyGameBridge

The generated file already contains Enabled, GatewayUrl, and PortalToken. HeartbeatSeconds is optional.

5. Build and verify

1. Rebuild and restart the game server.
2. Confirm Connected in Admin → Game Servers.
3. Run Connector check.
4. Verify every advertised capability.

The check performs real connector requests. Grant and character-service checks require an online character. The unstuck check moves an offline character to the bridge's configured recovery coordinates.