DEV Community: Ygor Castor

Building a Ragnarok Online Server in Elixir - Part 3

Ygor Castor — Sat, 30 Aug 2025 07:28:28 +0000

The Secret Sauce - Distributed Session Management

If you've been following along, we've built our Account Server and Character Server. They work great independently, but there's a glaring problem we hinted at in Part 2: How do these servers know about each other?

Think about it, when a player logs in:

They connect to the Account Server on port 6900
After authentication, they disconnect and connect to the Character Server on port 6901
After selecting a character, they disconnect again and connect to the Zone Server on port 5121

Each connection is a completely independent TCP socket. There's no shared memory, no common thread pool, nothing. So how does the Character Server know that the player who just connected is the same one who authenticated with the Account Server moments ago?

The Traditional Approaches (And Why They're Not Great)

Most private server implementations solve this in one of a few ways:

The Database Approach

-- Store sessions in a shared database
INSERT INTO login_sessions (account_id, login_id1, login_id2, ip_address, expires_at)
VALUES (2000000, 123456, 789012, '192.168.1.100', NOW() + INTERVAL '5 minutes');

Every server queries this table to validate sessions. Simple? Yes. Scalable? Not really. You're hitting the database for every single authentication check, and in an MMO, that's a LOT of queries.

The Redis/Memcached Approach

# Store sessions in Redis
redis.setex(f"session:{account_id}", 300, json.dumps({
    "login_id1": login_id1,
    "login_id2": login_id2,
    "ip": client_ip
}))

Better for performance, but now you've added another infrastructure component to manage, monitor, and scale. Plus, what happens when Redis goes down?

The rAthena Approach: Inter-Server Communication Protocol

This is what most Ragnarok emulators actually use. Let's look at how rAthena does it:

When a player successfully logs in, the login server creates an auth node and stores it locally:

// In login server - when authentication succeeds
struct auth_node* login_add_auth_node(struct login_session_data* sd, uint32 ip) {
    struct auth_node* node = &auth_db[sd->account_id];

    node->account_id = sd->account_id;
    node->login_id1 = sd->login_id1;  // Random token
    node->login_id2 = sd->login_id2;  // Another random token
    node->sex = sd->sex;
    node->ip = ip;
    node->clienttype = sd->clienttype;

    return node;
}

Now, when the player connects to the Character Server, the char server needs to verify this is legitimate. It sends packet 0x2712 to the login server:

// Character server - when player connects
if (session_isValid(login_fd)) {
    WFIFOHEAD(login_fd, 23);
    WFIFOW(login_fd, 0) = 0x2712;  // "Please verify this auth"
    WFIFOL(login_fd, 2) = sd->account_id;
    WFIFOL(login_fd, 6) = sd->login_id1;
    WFIFOL(login_fd, 10) = sd->login_id2;
    WFIFOB(login_fd, 14) = sd->sex;
    WFIFOL(login_fd, 15) = session_id;  // Who's asking
    WFIFOL(login_fd, 19) = sd->ip;
    WFIFOSET(login_fd, 23);
}

The login server receives this, checks its auth_db, and responds with packet 0x2713:

// Login server - handling verification request
case 0x2712: // Auth request from char-server
    struct auth_node* node = login_get_auth_node(account_id);

    if (node != nullptr &&
        node->account_id == account_id &&
        node->login_id1 == login_id1 &&
        node->login_id2 == login_id2 &&
        node->sex == sex) {
        // Authentication valid!
        WFIFOHEAD(fd, 21);
        WFIFOW(fd, 0) = 0x2713;  // Auth response
        WFIFOL(fd, 2) = account_id;
        WFIFOL(fd, 6) = login_id1;
        WFIFOL(fd, 10) = login_id2;
        WFIFOB(fd, 14) = sex;
        WFIFOB(fd, 15) = 0;  // 0 = success, 1 = failure
        WFIFOL(fd, 16) = request_id;
        WFIFOB(fd, 20) = node->clienttype;
        WFIFOSET(fd, 21);

        // Remove auth node - it can only be used once
        login_remove_auth_node(account_id);
    } else {
        // Send failure response...
    }
    break;

And the servers need to maintain these connections, handling failures:

// Periodic keepalive between servers
void inter_server_keepalive() {
    WFIFOHEAD(fd, 2);
    WFIFOW(fd, 0) = 0x2719;  // PING packet
    WFIFOSET(fd, 2);

    if (no_response_count > 3) {
        // Server is dead, reconnect
        do_reconnect();
        cleanup_orphaned_sessions();
    }
}

This approach works, but look at the complexity! You're essentially building a distributed system protocol from scratch, handling connection failures, message ordering, state synchronization, and more. The rAthena codebase has thousands of lines dedicated just to this inter-server communication.

Enter the BEAM: A Different Paradigm

But we're using Elixir, which runs on the BEAM (Erlang's virtual machine), and the BEAM was literally built for this kind of problem. Ericsson created Erlang to run telephone switches, systems that need to maintain millions of concurrent sessions across distributed hardware with 99.9999999% uptime (that's nine nines!).

Instead of treating our servers as isolated processes that need external coordination, what if we treated them as nodes in a distributed system that inherently know about each other?

# On the Account Server
{:ok, _} = Aesir.SessionManager.create_session(account_id, session_data)

# On the Character Server - it just knows!
case Aesir.SessionManager.get_session(account_id) do
  {:ok, session} -> # Valid session, proceed
  {:error, :not_found} -> # Invalid, reject
end

No manual packet protocols. No database queries. No Redis. No explicit server-to-server communication code. Just distributed Erlang magic.

What We're Building

In this part, we'll explore:

Distributed Erlang/Elixir - How to make our servers aware of each other
Mnesia - Erlang's built-in distributed database that lives in-memory
Phoenix PubSub - Real-time event broadcasting between servers
Session Management - Keeping track of who's logged in where
Handling Failures - What happens when a node goes down?

By the end, you'll understand why the BEAM is such a powerful platform for building distributed game servers, and why what seems like magic is actually just good engineering.

A Quick Note on Terminology

Before we dive in, let's clarify some terms:

Node: An instance of the BEAM running our code (could be Account Server, Character Server, etc.)
Cluster: Multiple nodes connected together
Process: A lightweight Erlang process (not an OS process, you can have millions of these)
GenServer: A generic server process that maintains state
PubSub: Publish/Subscribe messaging pattern

Ready? Let's dive into the distributed world of the BEAM!

Mnesia: The Database That Comes With Erlang

Before we dive into our implementation, let's talk about Mnesia. It's a database that comes built into Erlang/OTP, and it's unlike any database you've probably used before.

What Makes Mnesia Special?

Most databases are separate services you connect to over a network. Mnesia is different, it runs inside your BEAM application as part of your code. Think of it this way:

# Traditional database approach
defmodule Traditional do
  def get_session(account_id) do
    # Network call to external database
    {:ok, conn} = Postgrex.start_link(...)
    Postgrex.query!(conn, "SELECT * FROM sessions WHERE account_id = $1", [account_id])
    # Network latency, serialization overhead, connection pooling...
  end
end

# Mnesia approach  
defmodule WithMnesia do
  def get_session(account_id) do
    # Direct memory access - it's just a function call!
    :mnesia.dirty_read(:sessions, account_id)
    # Microseconds, not milliseconds
  end
end

But here's where it gets really interesting, Mnesia is distributed by default. When you have multiple BEAM nodes connected, Mnesia automatically replicates data between them:

# On Node A (Account Server)
:mnesia.dirty_write({:sessions, account_id, session_data})

# On Node B (Character Server) - the data is already there!
{:sessions, ^account_id, data} = :mnesia.dirty_read(:sessions, account_id)

No network protocols to write. No replication lag to worry about. No cache invalidation bugs. The BEAM handles it all.

Why Is This Perfect for Game Servers?

Think about what game servers need:

Ultra-low latency - Players notice even 50ms delays
High read throughput - Checking permissions, stats, inventory thousands of times per second
Distributed state - Players move between servers (login → char → zone)
Fault tolerance - If one server dies, others keep running
Eventual consistency is fine - A few milliseconds of lag between servers is acceptable

Mnesia gives us all of this out of the box. But raw Mnesia has a pretty gnarly API from the Erlang days:

% Erlang-style Mnesia - not very Elixir-like
mnesia:create_table(sessions, 
    [{attributes, record_info(fields, session)},
     {ram_copies, [node()]},
     {type, set}]).

Enter Memento: Mnesia for Humans

This is where Memento comes in. It's an Elixir wrapper that makes Mnesia actually pleasant to use:

# Define a table like a normal Elixir struct
defmodule Aesir.Session do
  use Memento.Table,
    attributes: [:account_id, :login_id1, :login_id2, :char_id, :ip, :connected_at],
    index: [:char_id],
    type: :set

  @type t :: %__MODULE__{
    account_id: integer(),
    login_id1: integer(),
    login_id2: integer(),
    char_id: integer() | nil,
    ip: tuple(),
    connected_at: DateTime.t()
  }
end

That's it! Now we can use it like any other Elixir module:

# Write a session
Memento.transaction! fn ->
  Memento.Query.write(%Aesir.Session{
    account_id: 2000000,
    login_id1: :rand.uniform(1_000_000),
    login_id2: :rand.uniform(1_000_000),
    ip: {192, 168, 1, 100},
    connected_at: DateTime.utc_now()
  })
end

# Read it back
Memento.transaction! fn ->
  Memento.Query.read(Aesir.Session, 2000000)
end

# Query with pattern matching
Memento.transaction! fn ->
  Memento.Query.select(Aesir.Session, {:==, :ip, {192, 168, 1, 100}})
end

But here's the killer feature, this automatically works across all connected nodes:

# Start three nodes
iex --name account@localhost -S mix
iex --name char@localhost -S mix  
iex --name zone@localhost -S mix

# Connect them
Node.connect(:"char@localhost")  # From account node
Node.connect(:"zone@localhost")  # From account node

# Tell Mnesia about the cluster
Memento.add_node(:"char@localhost")
Memento.add_node(:"zone@localhost")

# Create table replicated across all nodes
Memento.Table.create!(Aesir.Session, disc_copies: Node.list())

Now any node can read and write sessions, and they all stay in sync automatically!

The Node Discovery Problem

But wait, there's a catch. While Mnesia automatically replicates data once nodes are connected, it doesn't magically discover other nodes on its own. In our examples above, we manually connected nodes with Node.connect/1. That's fine for development, but what about production?

Imagine you're running your game servers in a Kubernetes cluster or across multiple Docker containers. Node names change, IP addresses are dynamic, and servers can restart at any time. How do they find each other?

This is where most Mnesia tutorials stop, they assume you'll manually configure everything. But we're building a real game server, so let's solve this properly.

Enter libcluster: Automatic Node Discovery

libcluster is a brilliant Elixir library that handles automatic node discovery and clustering. It supports multiple strategies, Kubernetes DNS, AWS EC2 tags, Docker Swarm, even simple UDP gossip protocols.

Let's see how we configured it in our config/config.exs:

config :libcluster,
  topologies: [
    aesir: [
      strategy: Cluster.Strategy.Epmd,
      config: [
        hosts: [:"account@127.0.0.1", :"char@127.0.0.1", :"zone@127.0.0.1"]
      ]
    ]
  ]

This tells libcluster to use the EPMD (Erlang Port Mapper Daemon) strategy to discover nodes. In development, we hardcode the node names, but in production, you'd use something like:

# For Kubernetes
config :libcluster,
  topologies: [
    aesir: [
      strategy: Cluster.Strategy.Kubernetes.DNS,
      config: [
        service: "aesir-nodes",
        application_name: "aesir"
      ]
    ]
  ]

# Or for AWS
config :libcluster,
  topologies: [
    aesir: [
      strategy: Cluster.Strategy.Kubernetes.DNSSRV,
      config: [
        query: "aesir.default.svc.cluster.local",
        node_basename: "aesir"
      ]
    ]
  ]

The MementoCluster Manager: Bringing It All Together

Now here's where our architecture gets interesting. libcluster handles node discovery, but we still need to coordinate Mnesia initialization across the cluster. Enter our MementoCluster.Manager , a GenServer that handles the complex orchestration.

Here's how it works in apps/commons/lib/aesir/commons/memento_cluster/manager.ex:

def init(_opts) do
  Logger.info("[MementoCluster:#{node()}] Starting Memento cluster manager...")

  state = %__MODULE__{
    status: :initializing,
    cluster_nodes: [],
    retry_count: 0,
    max_retries: 5
  }

  # Initialize synchronously to ensure tables are ready before SessionManager starts
  case initialize_cluster() do
    :ok ->
      Logger.info("[MementoCluster:#{node()}] Cluster initialized successfully during init")
      Phoenix.PubSub.broadcast(Aesir.PubSub, "cluster:ready", %{node: node(), status: :ready})
      {:ok, %{state | status: :ready}}

    {:error, reason} ->
      Logger.error(
        "[MementoCluster:#{node()}] Failed to initialize cluster during init: #{inspect(reason)}"
      )

      # Still start but schedule retry
      send(self(), :initialize)
      {:ok, state}
  end
end

The manager tries to initialize the cluster synchronously during startup. If it fails (maybe other nodes aren't ready yet), it schedules a retry.

Here's where the magic happens, the cluster setup logic:

defp setup_cluster do
  if Config.auto_cluster?() do
    # First check if we're already connected to nodes (like when using libcluster)
    connected = Node.list()
    configured = Config.cluster_nodes()

    # Find configured nodes we're already connected to
    cluster_candidates =
      Enum.filter(configured, fn node ->
        node != node() and node in connected
      end)

    case cluster_candidates do
      [] ->
        # No connected nodes, try discovery
        cluster_nodes = discover_cluster_nodes()

        case cluster_nodes do
          [] ->
            Logger.info(
              "[MementoCluster:#{node()}] No cluster nodes found, initializing as primary"
            )
            create_schema()

          nodes ->
            Logger.info("[MementoCluster:#{node()}] Found cluster nodes: #{inspect(nodes)}")
            join_cluster(nodes)
        end

      candidates ->
        # We have connected nodes - check if any have Mnesia running
        running =
          Enum.filter(candidates, fn candidate ->
            case :rpc.call(candidate, :mnesia, :system_info, [:is_running], 5_000) do
              :yes -> true
              _ -> false
            end
          end)

        case running do
          [] ->
            Logger.info(
              "[MementoCluster:#{node()}] Connected nodes don't have Mnesia, initializing as primary"
            )
            create_schema()

          [head | _] ->
            Logger.info(
              "[MementoCluster:#{node()}] Found running Mnesia on #{head}, attempting to join"
            )
            join_cluster([head])
        end
    end
  else
    Logger.info("[MementoCluster:#{node()}] Auto-clustering disabled, initializing standalone")
    create_schema()
  end
end

This is the clever part: the manager first checks if libcluster has already connected us to other nodes. If so, it uses RPC calls to see if any of them already have Mnesia running. If yes, we join their cluster. If no, we become the primary node and create a new schema.

Table Configuration: What Gets Replicated Where

Our MementoCluster.Config module defines exactly which tables get created and where they're stored:

def tables do
  [
    {ServerStatus, :disc_copies},      # Persistent - server registry
    {Session, :disc_copies},           # Persistent - player sessions  
    {OnlineUser, :ram_copies},         # In-memory - real-time player list
    {CharacterLocation, :disc_copies}  # Persistent - where characters are
  ]
end

Notice the different storage types:

:disc_copies - Data lives in RAM but is also written to disk
:ram_copies - Data only in RAM, faster but lost on restart
:disc_only_copies - Data only on disk, slower but takes less RAM

This gives us fine-grained control over performance vs persistence trade-offs.

The Session Schema: Distributed Session State

Let's look at our actual session schema in apps/commons/lib/aesir/commons/inter_server/schemas/session.ex:

defmodule Aesir.Commons.InterServer.Schemas.Session do
  use Memento.Table,
    attributes: [
      :account_id,
      :login_id1,
      :login_id2, 
      :auth_code,
      :username,
      :state,
      :current_server,
      :current_char_id,
      :created_at,
      :last_activity
    ],
    index: [:username, :current_server],
    type: :set

  def new(account_id, login_id1, login_id2, auth_code, username) do
    now = DateTime.utc_now()

    %__MODULE__{
      account_id: account_id,
      login_id1: login_id1,
      login_id2: login_id2,
      auth_code: auth_code,
      username: username,
      state: :authenticating,
      current_server: :account_server,
      current_char_id: nil,
      created_at: now,
      last_activity: now
    }
  end

  def transition_to_char_server(session) do
    update_activity(%{session | state: :char_select, current_server: :char_server})
  end

  def transition_to_game(session, char_id) do
    update_activity(%{
      session
      | state: :in_game,
        current_server: :zone_server,
        current_char_id: char_id
    })
  end
end

This schema tracks the complete player journey:

:authenticating on :account_server - just logged in
:char_select on :char_server - picking a character
:in_game on :zone_server - actually playing

And because it's a Memento table, this state is automatically replicated across all nodes in real-time!

The SessionManager: Your Distributed Session API

Now that we have our clustering infrastructure and session schemas set up, we need a clean way to interact with them. Enter the SessionManager, a GenServer that provides a simple API for distributed session management.

Here's how we define it in apps/commons/lib/aesir/commons/session_manager.ex:

defmodule Aesir.Commons.SessionManager do
  @moduledoc """
  GenServer-based session manager for distributed player sessions.
  Uses Memento for distributed state management across the cluster.
  """
  use GenServer

  # Client API

  def create_session(account_id, session_data) do
    GenServer.call(@server_name, {:create_session, account_id, session_data})
  end

  def validate_session(account_id, login_id1, login_id2) do
    GenServer.call(@server_name, {:validate_session, account_id, login_id1, login_id2})
  end

  def set_user_online(account_id, server_type, character_id \\ nil, map_name \\ nil) do
    GenServer.call(@server_name, {:set_user_online, account_id, server_type, character_id, map_name})
  end

The SessionManager wraps all our Memento operations in a clean, typed API. But more importantly, it handles the complex distributed transactions safely:

def handle_call({:validate_session, account_id, login_id1, login_id2}, _from, state) do
  result =
    Memento.transaction(fn ->
      case Memento.Query.read(Session, account_id) do
        nil ->
          {:error, :session_not_found}

        session ->
          if session.login_id1 == login_id1 and session.login_id2 == login_id2 do
            updated_session = Session.update_activity(session)
            Memento.Query.write(updated_session)
            {:ok, updated_session}
          else
            {:error, :invalid_credentials}
          end
      end
    end)

  # Handle transaction result...
end

This is critical, all our session operations are wrapped in Mnesia transactions, which means they're atomic across the entire cluster. Either the operation succeeds on all nodes, or it fails on all nodes. No partial states, no race conditions.

The Account Server: Creating Sessions

Let's see how the Account Server uses the SessionManager. When a player successfully logs in, here's what happens in apps/account_server/lib/aesir/account_server.ex:

defp handle_successful_login(account, session_data) do
  auth_code = :rand.uniform(999_999_999)
  login_id1 = :rand.uniform(999_999_999)
  login_id2 = :rand.uniform(999_999_999)

  updated_session =
    Map.merge(session_data, %{
      account_id: account.id,
      username: account.userid,
      auth_code: auth_code,
      login_id1: login_id1,
      login_id2: login_id2,
      authenticated: true
    })

  session_data_for_cluster = %{
    login_id1: login_id1,
    login_id2: login_id2,
    auth_code: auth_code,
    username: account.userid
  }

  case SessionManager.create_session(account.id, session_data_for_cluster) do
    :ok ->
      Logger.info("Session created in cluster for account #{account.id}")
      SessionManager.set_user_online(account.id, :account_server)
      PubSub.broadcast_player_login(account.id, account.userid)

      sex_atom =
        case account.sex do
          "M" -> :male
          "F" -> :female
        end

      # Generate response with available character servers...
      case get_available_char_servers() do
        {:ok, char_servers} ->
          response = %AcAcceptLogin{
            login_id1: login_id1,
            aid: account.id,
            login_id2: login_id2,
            last_ip: {127, 0, 0, 1},
            sex: sex_atom,
            char_servers: char_servers
          }

          {:ok, updated_session, [response]}

        {:error, reason} ->
          handle_failed_login(:no_char_servers, session_data)
      end

    {:error, reason} ->
      handle_failed_login(reason, session_data)
  end
end

Notice what's happening here:

We generate random tokens (login_id1, login_id2, auth_code)
We store the session in the distributed cluster via SessionManager.create_session/2
We mark the user as online on the account server
We broadcast a player login event via PubSub
We query for available character servers and send them to the client

What makes this powerful is that every other node in the cluster immediately knows about this new session. No message passing, no manual synchronization, it's just there.

The Character Server: Validating Sessions

Now when the player connects to the Character Server, they send the same tokens. Here's how we validate them in apps/char_server/lib/aesir/char_server/character_session.ex:

def validate_character_session(aid, login_id1, login_id2, sex) do
  case SessionManager.validate_session(aid, login_id1, login_id2) do
    {:ok, session} ->
      updated_session_data = %{
        account_id: aid,
        login_id1: login_id1,
        login_id2: login_id2,
        sex: sex,
        authenticated: true,
        username: session.username
      }

      SessionManager.set_user_online(aid, :char_server)

      Logger.info("Character session validated for account: #{aid}")
      {:ok, updated_session_data}

    {:error, reason} ->
      Logger.warning("Character session validation failed for account #{aid}: #{reason}")
      {:error, reason}
  end
end

This is the magic moment! The Character Server doesn't need to ask the Account Server "hey, is this user legit?" It already knows because the session data is right there in its local Mnesia tables.

The validate_session/3 call:

Reads the session from the local Memento table
Compares the provided tokens with the stored ones
Updates the session's last_activity timestamp
Marks the user as online on the character server
Returns the validated session data

All of this happens in microseconds because it's just memory access, not network calls.

Session State Transitions

Our system tracks the complete player journey through different server states. Here's how we handle state transitions:

# Session starts as :authenticating on :account_server
def transition_to_char_server(session) do
  update_activity(%{session | state: :char_select, current_server: :char_server})
end

def transition_to_game(session, char_id) do
  update_activity(%{
    session
    | state: :in_game,
      current_server: :zone_server,
      current_char_id: char_id
  })
end

This gives us incredible visibility into player state across the entire cluster. Any node can query:

"How many players are currently in character selection?"
"Which character is account 2000000 playing right now?"
"What server is this player currently on?"

Server Registry and Load Balancing

The SessionManager also handles server registration and discovery. Here's how character servers register themselves:

defp get_available_char_servers do
  case SessionManager.get_servers(:char_server) do
    [] ->
      {:error, :no_char_servers}

    servers ->
      online_servers =
        servers
        |> Enum.filter(fn server -> server.status == :online end)
        |> Enum.group_by(fn server -> server.metadata[:cluster_id] || "default" end)
        |> Enum.map(fn {_cluster_id, cluster_servers} ->
          # Pick the server with lowest player count
          best_server = Enum.min_by(cluster_servers, & &1.player_count)

          %AcAcceptLogin.ServerInfo{
            ip: best_server.ip,
            port: best_server.port,
            name: best_server.metadata[:name],
            users: best_server.player_count,
            # ...
          }
        end)

      {:ok, online_servers}
  end
end

This automatically load-balances players across available character servers, grouping them by cluster_id for multi-world support.

Cleanup and Session Expiration

The SessionManager also handles cleanup of stale sessions:

defp cleanup_expired_sessions do
  one_hour_ago = DateTime.add(DateTime.utc_now(), -3600, :second)

  Memento.transaction(fn ->
    expired_sessions =
      Memento.Query.select(Session, [
        {:<, :last_activity, one_hour_ago}
      ])

    Enum.each(expired_sessions, fn session ->
      Memento.Query.delete(Session, session.account_id)
      Memento.Query.delete(OnlineUser, session.account_id)
      Logger.info("Cleaned up expired session for account #{session.account_id}")
    end)
  end)
end

This runs periodically across the cluster, cleaning up sessions that haven't been active for over an hour. Since it's a distributed operation, any node can perform the cleanup and it affects the entire cluster.

The Result: Seamless Multi-Server Authentication

With this architecture, we've achieved something remarkable:

No external dependencies - No Redis, no separate database for sessions
Ultra-low latency - Session validation is just memory access
Automatic replication - All nodes stay in sync without explicit synchronization
Fault tolerance - If a node crashes, sessions persist on other nodes
Load balancing - Players are automatically distributed across available servers
Real-time visibility - Any node can query the complete player state

Compare this to the traditional approaches we discussed earlier. Instead of thousands of lines of inter-server protocol code, we have a simple, clean API that "just works" across the cluster.

Handling Failures: Automatic Cleanup and Recovery

But what happens when things go wrong? One of the most impressive aspects of our system is how it handles failures automatically. Let's explore the cleanup mechanisms that keep our cluster healthy.

Session Expiration: Cleaning Up Stale Data

The SessionManager runs periodic cleanup to remove expired sessions:

defp cleanup_expired_sessions do
  one_hour_ago = DateTime.add(DateTime.utc_now(), -3600, :second)

  Memento.transaction(fn ->
    expired_sessions =
      Memento.Query.select(Session, [
        {:<, :last_activity, one_hour_ago}
      ])

    Enum.each(expired_sessions, fn session ->
      Memento.Query.delete(Session, session.account_id)
      Memento.Query.delete(OnlineUser, session.account_id)
      Logger.info("Cleaned up expired session for account #{session.account_id}")
    end)
  end)
end

This runs every 5 minutes, automatically removing sessions that haven't been active for over an hour. Since it's a distributed transaction, any node can perform this cleanup and it affects the entire cluster.

Node Failure Detection: Heartbeat System

Each server sends heartbeats every 10 seconds to update its last_heartbeat timestamp:

defp send_heartbeat do
  current_node = Node.self()

  Memento.transaction(fn ->
    servers = Memento.Query.select(ServerStatus, [{:==, :server_node, current_node}])

    Enum.each(servers, fn server ->
      updated_server = ServerStatus.update_heartbeat(server)
      Memento.Query.write(updated_server)
    end)
  end)
end

Dead Node Cleanup: Automatic Recovery

Every 15 seconds, the system checks for dead nodes and cleans up their data:

defp cleanup_dead_nodes do
  timeout_seconds = 30
  now = DateTime.utc_now()

  Memento.transaction(fn ->
    all_servers = Memento.Query.select(ServerStatus, [])

    dead_servers =
      Enum.filter(all_servers, fn server ->
        DateTime.diff(now, server.last_heartbeat) > timeout_seconds &&
          server.status == :online
      end)

    Enum.each(dead_servers, fn server ->
      Logger.warning("Deleting dead server #{server.server_id} on node #{server.server_node}")
      Memento.Query.delete(ServerStatus, server.server_id)
      cleanup_node_data(server.server_node)
    end)
  end)
end

When a node is detected as dead (no heartbeat for 30+ seconds), the system automatically:

Removes the server from the registry
Cleans up orphaned data - sessions, online users, character locations
Logs the cleanup for monitoring

defp cleanup_node_data(dead_node) do
  # Remove online users from dead node
  online_users = Memento.Query.select(OnlineUser, [{:==, :server_node, dead_node}])
  Enum.each(online_users, &Memento.Query.delete(OnlineUser, &1.account_id))

  # Remove sessions from dead node  
  sessions = Memento.Query.select(Session, [{:==, :node, dead_node}])
  Enum.each(sessions, &Memento.Query.delete(Session, &1.account_id))

  # Remove character locations from dead node
  char_locations = Memento.Query.select(CharacterLocation, [{:==, :node, dead_node}])
  Enum.each(char_locations, &Memento.Query.delete(CharacterLocation, &1.char_id))

  Logger.info("Completed cleanup for dead node: #{dead_node}")
end

What This Means in Practice

Imagine you're running a production cluster:

Character Server A crashes - Maybe out of memory, network partition, whatever
Within 30 seconds, other nodes detect it's not sending heartbeats
Automatically, the cluster removes its server registration and cleans up its data
Players connected to other nodes continue playing normally
Load balancer stops routing new players to the dead server
When Character Server A restarts, it automatically rejoins the cluster and starts accepting new players

No manual intervention. No stale data. No cascading failures. The cluster self-heals.

The BEAM Advantage

This automatic failure handling is what makes the BEAM special. In traditional architectures, you'd need:

External health checkers (like Kubernetes liveness probes)
Manual cleanup scripts
Complex orchestration for node replacement
Careful coordination to avoid split-brain scenarios

With Erlang/Elixir, this is all built-in. The same mechanisms that let Ericsson build telephone switches with 99.9999999% uptime (nine nines!) now protect your game server from failures.

You must be itching to see it working, right? Lets run it!

First, we need to run the account-server in a named manner, so libcluster can find it.

RELEASE_COOKIE=imthecookie iex --name account@127.0.0.1 -S mix run

You will see this:

Since its a new cluster, it will start up the cluster and the mnesia tables, now, lets start the char-server

RELEASE_COOKIE=imthecookie iex --name char@127.0.0.1 -S mix run

Aha, see how it goes? It detects the account server, and instead of bootstrapping a new cluster, it will just copy the schemas that were generated copy the data, and done!

Lets see what happens when we request the server data

iex(char@127.0.0.1)1> Aesir.Commons.SessionManager.get_servers
[
  %Aesir.Commons.InterServer.Schemas.ServerStatus{
    __meta__: Memento.Table,
    server_id: "char_server_default_char@127.0.0.1",
    server_type: :char_server,
    server_node: :"char@127.0.0.1",
    status: :online,
    player_count: 0,
    max_players: 1000,
    ip: {192, 168, 178, 101},
    port: 6121,
    last_heartbeat: ~U[2025-08-13 07:55:49.376615Z],
    metadata: %{name: "Aesir", new: false, type: 0, cluster_id: "default"}
  },
  %Aesir.Commons.InterServer.Schemas.ServerStatus{
    __meta__: Memento.Table,
    server_id: "account_server_account@127.0.0.1",
    server_type: :account_server,
    server_node: :"account@127.0.0.1",
    status: :online,
    player_count: 0,
    max_players: 1000,
    ip: {0, 0, 0, 0},
    port: 6900,
    last_heartbeat: ~U[2025-08-13 07:50:54.864225Z],
    metadata: %{}
  }
]

See? The data that was registered by the account server is right here!

Now the moment y'all want, lets connect our client to our server

Ta-da! We have a working integration between Accounts and Char Server!

With this, the easy part is done and the real challenge begins! The Zone Server, where everything related to the Game Mechanics will be built. On part 4 we will see:

Char to Zone Transition
Map Loading and the GAT format
Fast as Fuck Map representation with ETS

Previous Parts

Part 2 - Persistence, Char Server and Inter Server Communication

Part 1 - Account Server

Building a Ragnarok Online Server in Elixir - Part 2

Ygor Castor — Wed, 13 Aug 2025 06:53:02 +0000

For part 1 (on medium, sorry).

Well, we now have a basic login server in place, so we have a loooooong way to go. In this part, we will focus on 3 aspects:

Persistence
Character Server
Inter Server Communication

Persistence

Right now, we have no persistence at all, and we already have the need of login information, so, lets simply use Postgres together with Ecto, the default Datastore tool for Elixir.

First, let's add the dependencies to our commons project's mix.exs, since we want to share this database configuration between all our umbrella apps:

{:ecto, "~> 3.13"},
{:ecto_sql, "~> 3.13"},
{:postgrex, ">= 0.0.0"},

Now, we can create our Repo module. This is the interface between our application and the database:

defmodule Aesir.Repo do
  use Ecto.Repo,
    otp_app: :commons,
    adapter: Ecto.Adapters.Postgres
end

Simple enough! Now let's configure it. In config/config.exs:

config :commons,
  ecto_repos: [Aesir.Repo]

config :commons, Aesir.Repo,
  database: "aesir_dev",
  username: "postgres",
  password: "postgres",
  hostname: "localhost",
  port: 5432,
  show_sensitive_data_on_connection_error: true,
  pool_size: 10

And for our test environment in config/test.exs:

config :commons, Aesir.Repo,
  database: "aesir_test",
  username: "postgres",
  password: "postgres",
  hostname: "localhost",
  port: 5432,
  show_sensitive_data_on_connection_error: true,
  pool: Ecto.Adapters.SQL.Sandbox  # Important for test isolation

We also need to create some test helpers and an ExUnit.DataCase, which I won't dive into here, but you can check in the code repository.

The Account Model

Now we have our repo, easy as that! Let's create our account model. Since I'm lazy, I'll just copy the same schema our buddies on rAthena use and translate it to Ecto.

First, let's define the schema with all the fields we need:

defmodule Aesir.Commons.Models.Account do
  use Ecto.Schema
  import Ecto.Changeset

  schema "accounts" do
    field :userid, :string
    field :user_pass, :string
    field :sex, :string, default: "M"
    field :email, :string
    field :group_id, :integer, default: 0        # GM level
    field :state, :integer, default: 0           # Account state (banned, etc)
    field :unban_time, :naive_datetime
    field :expiration_time, :naive_datetime
    field :logincount, :integer, default: 0
    field :lastlogin, :naive_datetime
    field :last_ip, :string
    field :birthdate, :date
    field :character_slots, :integer, default: 9
    field :pincode, :string
    field :pincode_change, :naive_datetime
    field :vip_time, :naive_datetime
    field :old_group, :integer, default: 0
    field :web_auth_token, :string
    field :web_auth_token_enabled, :integer, default: 0

    has_many :characters, Aesir.Commons.Models.Character

    timestamps()
  end

That's a lot of fields! Most are self-explanatory, but some are RO-specific like group_id (GM level) and state (account status).

Now let's add our main changeset with all the validations:

  @doc false
  def changeset(account, attrs) do
    account
    |> cast(attrs, [
      :userid, :user_pass, :sex, :email, :group_id, :state,
      :unban_time, :expiration_time, :logincount, :lastlogin,
      :last_ip, :birthdate, :character_slots, :pincode,
      :pincode_change, :vip_time, :old_group, 
      :web_auth_token, :web_auth_token_enabled
    ])
    |> validate_required([:userid, :user_pass, :email])
    |> validate_format(:email, ~r/@/)
    |> validate_inclusion(:sex, ["M", "F"])
    |> validate_length(:userid, min: 4, max: 23)
    |> validate_length(:user_pass, min: 4, max: 255)
    |> validate_length(:pincode, is: 4)
    |> unique_constraint(:userid)
    |> unique_constraint(:email)
  end

We also need a simpler changeset for login - we don't want to require an email just to validate credentials:

  @doc """
  Changeset for login validation without email requirement
  """
  def login_changeset(account, attrs) do
    account
    |> cast(attrs, [:userid, :user_pass])
    |> validate_required([:userid, :user_pass])
    |> validate_length(:userid, min: 4, max: 23)
    |> validate_length(:user_pass, min: 4, max: 255)
  end
end

We also need to create the migration, for the sake of keeping it short, check it in the git repo.

The Auth Module

Good, now what? Well, now we ditch the old memory account manager and implement a new one. Let's do it in commons, not in account-server. Why? There's some cross-cutting authentication that's shared between the servers, so it's easier to do it like that.

Let's start with the module definition and the main authentication function:

defmodule Aesir.Commons.Auth do
  @moduledoc """
  Authentication context for user login and account management.
  """

  alias Aesir.Commons.Models.Account
  alias Aesir.Repo

The heart of our auth system is the authenticate_user function. Notice the security consideration here:

  @doc """
  Authenticates a user with userid and password.

  Returns {:ok, account} on successful authentication or 
  {:error, reason} on failure.
  """
  def authenticate_user(userid, password) when is_binary(userid) and is_binary(password) do
    case get_account_by_userid(userid) do
      nil ->
        # Important: Always verify even when user doesn't exist
        # This prevents timing attacks
        Bcrypt.no_user_verify()
        {:error, :invalid_credentials}

      account ->
        if verify_password(password, account.user_pass) and account_active?(account) do
          {:ok, update_login_info(account)}
        else
          {:error, :invalid_credentials}
        end
    end
  end

See that Bcrypt.no_user_verify()? That's crucial for security - it ensures that authentication takes the same amount of time whether the user exists or not, preventing timing attacks.

Now let's add our account management functions:

  def get_account_by_userid(userid) do
    Repo.get_by(Account, userid: userid)
  end

  def get_account!(id), do: Repo.get!(Account, id)

  def create_account(attrs \\ %{}) do
    attrs =
      Map.put(attrs, :user_pass, hash_password(attrs[:user_pass] || attrs["user_pass"]))

    %Account{}
    |> Account.changeset(attrs)
    |> Repo.insert()
  end

For password handling, we're using bcrypt, which is the industry standard:

  def hash_password(password) when is_binary(password) do
    Bcrypt.hash_pwd_salt(password)
  end

  def verify_password(password, hash) when is_binary(password) and is_binary(hash) do
    Bcrypt.verify_pass(password, hash)
  end

One of the important features is checking if an account is actually allowed to login:

  def account_active?(%Account{} = account) do
    now = NaiveDateTime.utc_now()

    cond do
      account.state == 5 ->  # Blocked by GM
        false

      account.unban_time && NaiveDateTime.compare(now, account.unban_time) == :lt ->
        false  # Still banned

      account.expiration_time && NaiveDateTime.compare(now, account.expiration_time) == :gt ->
        false  # Account expired

      true ->
        true
    end
  end

And when someone successfully logs in, we update their login stats:

  def update_login_info(%Account{} = account) do
    now = NaiveDateTime.utc_now()

    {:ok, updated_account} =
      account
      |> Account.changeset(%{
        logincount: account.logincount + 1,
        lastlogin: now
      })
      |> Repo.update()

    updated_account
  end

Finally, for debugging, we have a helper to understand account states - these are the standard Ragnarok error codes:

  def get_account_state_description(state) do
    case state do
      0 -> "Normal"
      1 -> "Unregistered ID"
      2 -> "Incorrect Password"
      3 -> "This ID is expired"
      4 -> "Rejected from Server"
      5 -> "Blocked by the GM Team"
      # ... more states
      99 -> "This ID has been totally erased"
      _ -> "Unknown state"
    end
  end
end

Good, we have the Auth module, now, lets go back to our AccountServer, where we handle the Login Packet

  @impl Aesir.Commons.Network.Connection
  def handle_packet(0x0064, %CaLogin{} = login_packet, session_data) do
    Logger.info("Login attempt for user: #{login_packet.username}")

    case Auth.authenticate_user(login_packet.username, login_packet.password) do
      {:ok, account} ->
        handle_successful_login(account, session_data)

      {:error, reason} ->
        handle_failed_login(reason, session_data)
    end
  end

Tada, we have a login backed by Ecto! So we are at the same state, but a bit better, now lets take the next step, the Characters server.

Char Server

Lets remember a bit about the architecture, we are building 3 applications, Account Server, Char Server and Zone Server, the first, we got working in part 1, its by far the simplest one, the later, which will deal with the whole MMO stuff, the most complex. In-between them we have the CharServer, this one will be responsible for:

Character Information: The overall character data like Job, Level, Experience, Equipment and so on.
Char creation and deletion, blocking and so on.

Important packets

As with everything on Ragnarok protocol, the communication is with packets, the flow works mostly like this.

Once the login server authorizes the login, it returns the list of available character servers (we will go on how this works in next chapter)
The client sends the 0x0065 (CH_ENTER) packet to the Char Server IP, which echoes the login account_id, login_id1 and 2 and the account sex.
The char-server, then simply echoes back the account_id, pretty much a handshake acknowledging the client, then, it sends 3 Packets in sequence:
- HC_CHARACTER_LIST: This one tells the client how many character slots the user has available.
- HC_BLOCK_CHARACTER: Which Characters are Blocked
- HC_SECOND_PASSWD_LOGIN: This one is for 2FA, it instructs the client to request it, or not.
In the case of an issue in any of these processes, the server responds with a HC_REFUSE_ENTER, with the reason of the refusal.
The user can create chars (CH_MAKE_CHAR) , delete (CH_REQ_CHAR_DELETE), select a char to play (CH_SELECT_CHAR) and request the char listing (CH_CHARLIST_REQ).
Once the player clicks in play, the Char Server returns to the client the IP and ports for the Zone Server, in which the character will be placed at.

So, its a pretty straightforward flow, lets start with the database part.

The Character Model

For this, we will need a character model. As with the login, we will shamelessly copy from rAthena schemas :D

First, let's start with the schema definition. Brace yourself - this is a big one:

defmodule Aesir.Commons.Models.Character do
  use Ecto.Schema
  import Ecto.Changeset

  schema "characters" do
    belongs_to :account, Aesir.Commons.Models.Account

    field :char_num, :integer      # Slot number (0-14)
    field :name, :string
    field :class, :integer          # Job class (Novice, Swordsman, etc)

    # Levels and experience
    field :base_level, :integer, default: 1
    field :job_level, :integer, default: 1
    field :base_exp, :integer, default: 0
    field :job_exp, :integer, default: 0
    field :zeny, :integer, default: 0

Next come the character stats - the famous six attributes of Ragnarok:

    # Base stats
    field :str, :integer, default: 1
    field :agi, :integer, default: 1
    field :vit, :integer, default: 1
    field :int, :integer, default: 1
    field :dex, :integer, default: 1
    field :luk, :integer, default: 1

    # Health and SP
    field :max_hp, :integer, default: 40
    field :hp, :integer, default: 40
    field :max_sp, :integer, default: 11
    field :sp, :integer, default: 11

    field :status_point, :integer, default: 0
    field :skill_point, :integer, default: 0

Then we have all the social and appearance fields:

    # Social features
    field :party_id, :integer, default: 0
    field :guild_id, :integer, default: 0
    field :partner_id, :integer, default: 0  # Marriage system
    field :father, :integer, default: 0      # Family system
    field :mother, :integer, default: 0
    field :child, :integer, default: 0

    # Appearance
    field :hair, :integer, default: 0
    field :hair_color, :integer, default: 0
    field :clothes_color, :integer, default: 0

    # Equipment display (for character selection screen)
    field :weapon, :integer, default: 0
    field :shield, :integer, default: 0
    field :head_top, :integer, default: 0
    field :head_mid, :integer, default: 0
    field :head_bottom, :integer, default: 0
    field :robe, :integer, default: 0

And location information - where the character is and where they respawn:

    # Location
    field :last_map, :string, default: "new_1-1"  # Novice training ground
    field :last_x, :integer, default: 53
    field :last_y, :integer, default: 111
    field :save_map, :string, default: "new_1-1"  # Respawn point
    field :save_x, :integer, default: 53
    field :save_y, :integer, default: 111

    # Various status fields
    field :online, :integer, default: 0
    field :delete_date, :naive_datetime
    field :unban_time, :naive_datetime
    field :last_login, :naive_datetime

    timestamps()
  end

Boy, this is a big chungus indeed! Now let's add the validation functions. First, the main validation orchestrator:

  @doc """
  Validates character creation data.
  """
  def validate_creation(attrs) do
    with {:ok, name} <- validate_name(attrs[:name]),
         {:ok, stats} <- validate_stats(attrs),
         {:ok, slot} <- validate_slot(attrs[:slot]) do
      {:ok, %{name: name, stats: stats, slot: slot}}
    else
      {:error, reason} -> {:error, reason}
    end
  end

Character names have strict rules to prevent abuse:

  @doc """
  Validates character name.
  """
  def validate_name(name) when is_binary(name) do
    cond do
      String.length(name) < 4 ->
        {:error, :name_too_short}

      String.length(name) > 23 ->
        {:error, :name_too_long}

      not String.match?(name, ~r/^[a-zA-Z0-9_]+$/) ->
        {:error, :name_invalid_chars}

      String.contains?(String.downcase(name), ["gm", "admin", "test"]) ->
        {:error, :name_forbidden}  # No impersonating GMs!

      true ->
        {:ok, name}
    end
  end

  def validate_name(_), do: {:error, :name_required}

For stats validation, remember what we said about modern clients:

  @doc """
  Validates character stats for creation.
  Modern clients MUST send all stats as 1 - anything else is packet tampering.
  """
  def validate_stats(attrs) do
    required_stats = [:str, :agi, :vit, :int, :dex, :luk]

    stats =
      required_stats
      |> Enum.map(&{&1, (attrs[:stats] && attrs[:stats][&1]) || 1})
      |> Enum.into(%{})

    # If any stat is not 1, it's packet tampering
    if Enum.all?(Map.values(stats), &(&1 == 1)) do
      {:ok, stats}
    else
      {:error, :stats_invalid_total}
    end
  end

And some utility functions for character management:

  @doc """
  Validates character slot number.
  """
  def validate_slot(slot) when is_integer(slot) and slot >= 0 and slot <= 14 do
    {:ok, slot}
  end

  def validate_slot(_), do: {:error, :invalid_slot}

  @doc """
  Checks if character is marked for deletion.
  """
  def marked_for_deletion?(%__MODULE__{delete_date: nil}), do: false
  def marked_for_deletion?(%__MODULE__{delete_date: _}), do: true

  @doc """
  Checks if character is banned.
  """
  def banned?(%__MODULE__{unban_time: nil}), do: false

  def banned?(%__MODULE__{unban_time: unban_time}) do
    NaiveDateTime.compare(unban_time, NaiveDateTime.utc_now()) == :gt
  end
end

The Characters Context Module

Now, with the model in place, we can implement a module to deal with the character creation shizzles. This is where the real business logic lives:

defmodule Aesir.CharServer.Characters do
  @moduledoc """
  Context module for character operations.

  This module handles the business logic for character management including
  creation, deletion, retrieval, and related operations. It uses atomic
  transactions to ensure data consistency and delegates to existing modules
  for validation and persistence.
  """
  require Logger
  import Ecto.Query

  alias Aesir.CharServer.Auth
  alias Aesir.Commons.InterServer.PubSub
  alias Aesir.Commons.Models.Character
  alias Aesir.Repo

Character Creation

Let's start with the most complex operation - creating a new character. We use Ecto.Multi for atomic transactions:

  @doc """
  Creates a new character with atomic transaction handling.

  This function orchestrates the entire character creation workflow:
  1. Validates account permissions
  2. Checks character slot availability
  3. Validates character data
  4. Creates character in database
  5. Broadcasts creation event

  Returns {:ok, character} on success or {:error, reason} on failure.
  """
  def create_character(account_id, char_data) do
    Ecto.Multi.new()
    |> Ecto.Multi.run(:account_validation, fn _repo, _changes ->
      Auth.validate_account_permissions(account_id)
    end)
    |> Ecto.Multi.run(:character_count, fn _repo, _changes ->
      get_character_count(account_id)
    end)
    |> Ecto.Multi.run(:permission_check, fn _repo,
                                            %{account_validation: account, 
                                              character_count: count} ->
      Auth.can_create_character?(account.id, count)
    end)

Notice how we're building up a chain of operations? Each step depends on the previous one succeeding. If any step fails, the entire transaction is rolled back.

Now let's add the validation steps:

    |> Ecto.Multi.run(:character_validation, fn _repo, _changes ->
      Character.validate_creation(char_data)
    end)
    |> Ecto.Multi.run(:name_availability, fn _repo, %{character_validation: validated_data} ->
      check_name_availability(validated_data.name)
    end)
    |> Ecto.Multi.run(:slot_availability, fn _repo, %{character_validation: validated_data} ->
      check_slot_availability(account_id, validated_data.slot)
    end)

Finally, if everything checks out, we create the character and handle the result:

    |> Ecto.Multi.run(:character_creation, fn repo, %{character_validation: validated_data} ->
      create_character_record(repo, account_id, validated_data, char_data)
    end)
    |> Repo.transaction()
    |> handle_creation_result(account_id)
  end

Character Deletion

Modern Ragnarok clients don't delete characters immediately - they mark them for deletion after a delay (usually 24 hours). This prevents accidental deletions:

  @doc """
  Requests character deletion with a timer (modern client behavior).

  Sets a deletion date instead of immediately deleting the character.
  The character will be deleted after the configured delay (default 24 hours).
  """
  def request_character_deletion(char_id, account_id) do
    deletion_delay = Application.get_env(:char_server, :deletion_delay, 86400)


    Ecto.Multi.new()
    |> Ecto.Multi.run(:character_lookup, fn _repo, _changes ->
      get_character(char_id)
    end)
    |> Ecto.Multi.run(:ownership_check, fn _repo, %{character_lookup: character} ->
      if character.account_id == account_id do
        {:ok, character}
      else
        {:error, :not_found}  # Can't delete someone else's character!
      end
    end)

We also need to check if the character can be deleted - they can't be in a guild or party:

    |> Ecto.Multi.run(:deletion_check, fn _repo, %{character_lookup: character} ->
      cond do
        Character.marked_for_deletion?(character) ->
          {:error, :already_deleting}

        character.guild_id && character.guild_id > 0 ->
          {:error, :cannot_delete}  # Must leave guild first

        character.party_id && character.party_id > 0 ->
          {:error, :cannot_delete}  # Must leave party first

        true ->
          {:ok, :can_delete}
      end
    end)

If all checks pass, we set the deletion date:

    |> Ecto.Multi.run(:set_deletion_date, fn repo, %{character_lookup: character} ->
      delete_date =
        NaiveDateTime.utc_now()
        |> NaiveDateTime.add(deletion_delay, :second)
        |> NaiveDateTime.truncate(:second)

      character
      |> Ecto.Changeset.change(delete_date: delete_date)
      |> repo.update()
    end)
    |> Repo.transaction()
    |> case do
      {:ok, %{set_deletion_date: character}} ->
        delete_timestamp =
          character.delete_date
          |> DateTime.from_naive!("Etc/UTC")
          |> DateTime.to_unix()

        Logger.info(
          "Character #{character.name} (ID: #{character.id}) marked for deletion"
        )

        {:ok, delete_timestamp}

      {:error, :character_lookup, _, _} ->
        {:error, :not_found}

      {:error, reason, _, _} ->
        {:error, reason}
    end
  end

Other Character Operations

We also need functions for listing, selecting, and managing characters:

  @doc """
  Retrieves characters for an account with session validation.
  """
  def list_characters(account_id, session_data) do
    with {:ok, _session} <- validate_session_for_account(account_id, session_data),
         {:ok, characters} <- get_characters_by_account(account_id) do
      {:ok, characters}
    end
  end

  @doc """
  Selects a character and prepares for zone transfer.
  """
  def select_character(account_id, slot) do
    with {:ok, character} <- get_character_by_slot(account_id, slot),
         :ok <- update_character_location(character),
         :ok <- broadcast_character_selected(account_id, character) do
      {:ok, character}
    end
  end

The broadcast_character_selected is particularly interesting - it uses Phoenix PubSub to notify other servers that a character has been selected. We'll dive deep into this in the next chapter!

Helper Functions

And here are some helper functions for querying and checking availability:

  def get_characters_by_account(account_id) do
    query = from c in Character, 
             where: c.account_id == ^account_id, 
             order_by: c.char_num

    {:ok, Repo.all(query)}
  end

  def get_character_by_slot(account_id, slot) do
    query = from c in Character, 
             where: c.account_id == ^account_id and c.char_num == ^slot

    case Repo.one(query) do
      nil -> {:error, :character_not_found}
      character -> {:ok, character}
    end
  end

  def name_available?(name) do
    # Case-insensitive name check
    query = from c in Character, 
             where: fragment("LOWER(?)", c.name) == ^String.downcase(name)

    case Repo.one(query) do
      nil -> true
      _ -> false
    end
  end

  def slot_available?(account_id, slot) do
    case get_character_by_slot(account_id, slot) do
      {:ok, _character} -> false
      {:error, :character_not_found} -> true
    end
  end

Private Helper Functions

The rest of the module contains private helper functions that support the main operations:

  defp create_character_record(repo, account_id, validated_data, char_data) do
    character_attrs = %{
      account_id: account_id,
      char_num: validated_data.slot,
      name: validated_data.name,
      class: 0,  # Everyone starts as Novice
      str: validated_data.stats.str,
      agi: validated_data.stats.agi,
      vit: validated_data.stats.vit,
      int: validated_data.stats.int,
      dex: validated_data.stats.dex,
      luk: validated_data.stats.luk,
      hair: char_data[:hair] || 1,
      hair_color: char_data[:hair_color] || 1,
      clothes_color: char_data[:clothes_color] || 1
    }

    %Character{}
    |> Character.changeset(character_attrs)
    |> repo.insert()
  end

And we have various validation helpers to ensure characters can be deleted safely:

  defp validate_deletion_eligibility(character) do
    cond do
      Character.banned?(character) ->
        {:error, :character_banned}

      character.guild_id && character.guild_id > 0 ->
        {:error, :character_in_guild}  # Must leave guild first

      character.party_id && character.party_id > 0 ->
        {:error, :character_in_party}  # Must leave party first

      true ->
        {:ok, :eligible}
    end
  end

  defp broadcast_character_selected(account_id, character) do
    PubSub.broadcast_character_selected(account_id, character.id, character.name)
    :ok
  end
end

This module handles the whole character lifecycle, so now we have the data layer, let's build the actual CharServer module that will handle the packets.

The CharServer Module

Now comes the fun part - implementing the actual CharServer that handles all the packet communication with the client. Remember from Part 1 that we built a generic Aesir.Commons.Network.Connection behavior? Well, our CharServer will use the same pattern:

defmodule Aesir.CharServer do
  @moduledoc """
  Connection handler for the Character Server.
  Processes character-related packets and manages character operations.
  """
  use Aesir.Commons.Network.Connection

  require Logger

  alias Aesir.CharServer.Characters
  alias Aesir.CharServer.CharacterSession
  # ... packet aliases
end

When a player connects to the Character Server after logging in, the first thing they send is their authentication credentials:

@impl Aesir.Commons.Network.Connection
def handle_packet(0x0065, parsed_data, session_data) do
  Logger.info("Character list requested for account: #{parsed_data.aid}")

  account_id_ack = %AccountIdAck{account_id: parsed_data.aid}

  with {:ok, updated_session} <-
         CharacterSession.validate_character_session(
           parsed_data.aid,
           parsed_data.login_id1,
           parsed_data.login_id2,
           parsed_data.sex
         ),
       {:ok, characters} <- Characters.list_characters(parsed_data.aid, updated_session) do

First, we validate that this is a legitimate session - the login_id1 and login_id2 are tokens that were generated by the AccountServer. If validation passes, we fetch the character list.

Now here's where the Ragnarok protocol gets interesting - we need to send FIVE different packets in a specific order:

    # 1. Configure character slots - tells client how many slots are available
    slot_config = %HcCharacterList{
      normal_slots: 9,
      premium_slots: 0,
      billing_slots: 0,
      producible_slots: 9,
      valid_slots: 15
    }

    # 2. The actual character data
    char_list = %HcAcceptEnter{characters: characters}

And we're not done yet! The client also expects information about blocked characters and PIN codes:

    # 3. Tell client which characters are blocked (none for now)
    blocked_chars = %HcBlockCharacter{
      blocked_chars: []
    }

    # 4. PIN code configuration (we're disabling it with state: 0)
    pincode = %HcSecondPasswdLogin{
      seed: :rand.uniform(0xFFFF),
      account_id: parsed_data.aid,
      state: 0
    }

    # Send all packets in the exact order the client expects
    {:ok, updated_session,
     [account_id_ack, slot_config, char_list, blocked_chars, pincode]}

If anything goes wrong during validation, we send a refusal packet:

  else
    {:error, reason} ->
      Logger.warning("Session validation failed for account #{parsed_data.aid}: #{reason}")
      response = %HcRefuseEnter{reason: 0}
      {:ok, session_data, [response]}
  end
end

Notice how we're sending multiple packets in response? That's the Ragnarok protocol for you - the client expects this specific sequence to properly display the character selection screen. Miss one packet or send them out of order, and the client will either crash or show corrupted data.

Character Creation

Modern Ragnarok clients use packet 0x0A39 for character creation. Let's break down how we handle it:

def handle_packet(0x0A39, parsed_data, session_data) do
  Logger.info("Character creation requested (modern): #{parsed_data.name}")

  account_id = session_data[:account_id]

First, we extract the account ID from our session. Then we build the character data structure:

  char_data = %{
    name: parsed_data.name,
    slot: parsed_data.slot,
    stats: %{
      str: 1, agi: 1, vit: 1,
      int: 1, dex: 1, luk: 1
    },
    hair: parsed_data.hair_style,
    hair_color: parsed_data.hair_color,
    starting_job: parsed_data.starting_job,
    sex: parsed_data.sex
  }

Notice something important here? All stats MUST be 1. Modern clients don't let players allocate stats during character creation anymore - they always send 1 for each stat. If we receive anything else, it's packet tampering and we should reject it.

Now we attempt to create the character:

  case Characters.create_character(account_id, char_data) do
    {:ok, character} ->
      response = %HcAcceptMakechar{character_data: character}
      {:ok, session_data, [response]}

    {:error, reason} ->
      response = creation_error(reason)
      {:ok, session_data, [response]}
  end
end

The creation_error/1 function maps our internal error atoms to the specific error codes the client understands - things like name already taken (0), invalid characters (1), or slot occupied (3).

Character Selection

When a player double-clicks a character to play, the client sends packet 0x0066. This is where things get interesting - we need to tell the client which Zone Server to connect to:

def handle_packet(0x0066, parsed_data, session_data) do
  account_id = session_data[:account_id]

  with {:ok, character} <- Characters.select_character(account_id, parsed_data.slot),
       {:ok, updated_session} <-
         CharacterSession.update_session_for_character_selection(
           session_data,
           character
         ) do

First, we validate that this character belongs to this account and update our session to track which character is being played.

Then comes the crucial part - telling the client where to go next:

    # TODO: Use ZoneServerService when available
    zone_port = Application.get_env(:zone_server, :port, 5121)

    response = %HcNotifyZonesvr{
      char_id: character.id,
      map_name: character.last_map,  # Which map to load
      ip: {127, 0, 0, 1},            # Zone server IP
      port: zone_port                 # Zone server port
    }

    {:ok, updated_session, [response]}

The client will disconnect from the Character Server and immediately connect to the Zone Server at the specified IP and port. But here's the catch - how will the Zone Server know this is a legitimate connection and not someone trying to hack in?

The Missing Piece: Session Management

We have a functional char server now, so lets login! No no no, there's still a missing piece, if you've been following along carefully, you might have noticed something interesting. In the CharServer's handle_packet/3 for 0x0065, we're calling CharacterSession.validate_character_session/4. But wait - how does the CharServer know that this account has already authenticated with the AccountServer?

The client connects to different servers (Account, then Char, then Zone), and each connection is independent TCP socket. So how do we maintain authentication state across these different servers?

This is where things get really interesting, and it's what we'll dive into in the next chapter: Inter-Server Communication and Session Management.

Here's a little teaser of what's coming:

# How does this work?
CharacterSession.validate_character_session(
  parsed_data.aid,
  parsed_data.login_id1,
  parsed_data.login_id2,
  parsed_data.sex
)

The client sends login_id1 and login_id2 - these are session tokens generated by the AccountServer. But the CharServer needs to verify these are valid. In traditional implementations, you might use:

Shared Database: All servers query the same session table
Redis/Memcached: Centralized session storage
Direct Server Communication: CharServer asks AccountServer directly

But we're using Elixir, and we have something much more elegant: Distributed Erlang with Phoenix PubSub and Mnesia.

In the next part, we'll explore how we:

Use Phoenix PubSub for real-time event broadcasting between servers
Implement distributed session management with Mnesia
Handle server clustering and load balancing
Deal with network partitions and split-brain scenarios

Stay tuned for Part 3, where we'll unlock the true power of the BEAM for building distributed game servers!

Git Repo: https://github.com/YgorCastor/aesir