odinsea-elixir/docs/PACKET_LOGGING.md

Packet Logging System

Overview

Comprehensive packet logging system for debugging the MapleStory protocol, matching the Java version's logging format.

Features

• Direction Indicators: [client] for incoming packets, [loopback] for outgoing packets
• Opcode Names: Human-readable packet names (e.g., CP_CheckPassword, LP_ServerList)
• Opcode Values: Both decimal and hexadecimal (e.g., 2 / 0x02)
• Raw Hex Data: Space-separated hex bytes
• ASCII Text: Printable characters with dots for non-printable
• Context Information: IP address, server type, packet size

Configuration

Enable/disable packet logging in config/config.exs:

config :odinsea, :features,
  log_packet: true  # Set to false to disable

Example Output

[client] [CP_PermissionRequest] 1 / 0x01
[Data] 01 00 07 70 00 04 00
[Text] ...p...
[Context] IP=127.0.0.1 Server=login Size=7 bytes

[loopback] [RSA_KEY] 32 / 0x20
[Data] 20 00
[Text]  .
[Context] IP=127.0.0.1 Server=login Size=2 bytes

Implementation Details

Files Added

• lib/odinsea/net/packet_logger.ex - Main packet logging module

Files Modified

• lib/odinsea/login/client.ex - Added packet logging for incoming client packets
• lib/odinsea/login/handler.ex - Added packet logging for outgoing server packets
• lib/odinsea/net/processor.ex - Fixed handler function name mismatches

Key Functions

PacketLogger.log_client_packet/3

Logs incoming packets from the client with opcode, data, and context.

PacketLogger.log_server_packet/3

Logs outgoing packets to the client with opcode, data, and context.

PacketLogger.log_raw_packet/4

Logs raw packets (e.g., hello handshake) that don't follow the standard opcode format.

Opcode Name Resolution

The logger includes comprehensive opcode name mappings for:

• Client Opcodes (CP_*): Login, authentication, character management, gameplay, etc.
• Server Opcodes (LP_*): Responses, server lists, character data, game state, etc.

Unknown opcodes are displayed as UNKNOWN.

Usage Tips

1. Enable during development: Keep log_packet: true to debug connection issues
2. Disable in production: Set log_packet: false to reduce log noise and improve performance
3. Compare with Java logs: Use this to verify protocol compatibility with the Java server
4. Debug handshake issues: Check that HELLO packet is sent before CP_PermissionRequest

Debugging Login Issues

The login sequence should look like this:

1. [loopback] HELLO - Server sends handshake with IVs
2. [client] CP_PermissionRequest - Client sends version check
3. [loopback] RSA_KEY / LOGIN_AUTH - Server sends RSA key and login background
4. [client] CP_CheckPassword - Client sends login credentials
5. [loopback] LOGIN_STATUS - Server sends authentication result

If packets are missing or out of order, check:

• Network connectivity
• Client version compatibility (v342)
• Opcode mappings in opcodes.ex
• Handler routing in processor.ex