Odinsea Elixir

An Elixir/OTP port of the Odinsea Java MapleStory private server.

Project Status

Current Phase: Foundation Complete, Networking In Progress
Overall Progress: ~15%

See PORT_PROGRESS.md for detailed progress tracking.

Architecture

Odinsea Elixir
├── Login Server (port 8584)      - Authentication & character selection
├── Channel Servers (ports 8585+) - Game world (multiple channels)
├── Cash Shop (port 8605)         - Item purchasing
├── World Services                - Cross-server state (parties, guilds)
└── Database                      - MySQL/MariaDB via Ecto

Quick Start

Prerequisites

• Elixir 1.17+
• MySQL/MariaDB
• Redis

Setup

# Install dependencies
mix deps.get

# Configure database (edit config/runtime.exs or use env vars)
export ODINSEA_DB_HOST=localhost
export ODINSEA_DB_NAME=odin_sea
export ODINSEA_DB_USER=root
export ODINSEA_DB_PASS=

# Run database migrations
mix ecto.setup

# Start the server
mix run --no-halt

Environment Variables

Variable	Default	Description
ODINSEA_NAME	Luna	Server name
ODINSEA_HOST	127.0.0.1	Server host
ODINSEA_LOGIN_PORT	8584	Login server port
ODINSEA_CHANNEL_COUNT	2	Number of game channels
ODINSEA_DB_HOST	localhost	Database host
ODINSEA_DB_NAME	odin_sea	Database name
ODINSEA_REDIS_HOST	localhost	Redis host

Project Structure

lib/odinsea/
├── application.ex          # Main supervisor
├── constants/              # Game constants
│   ├── game.ex            # Game mechanics constants
│   └── server.ex          # Protocol constants
├── database/
│   └── repo.ex            # Ecto repository
├── login/                 # Login server
│   ├── listener.ex        # TCP listener
│   └── client.ex          # Client handler
├── channel/               # Game channel servers
│   ├── supervisor.ex      # Channel supervisor
│   ├── server.ex          # Individual channel
│   └── client.ex          # Channel client handler
├── shop/                  # Cash shop server
│   ├── listener.ex        # TCP listener
│   └── client.ex          # Client handler
├── world/                 # Cross-server services
│   ├── supervisor.ex      # World supervisor
│   ├── world.ex           # World state
│   ├── party.ex           # Party management
│   ├── guild.ex           # Guild management
│   ├── family.ex          # Family management
│   ├── expedition.ex      # Expedition management
│   └── messenger.ex       # Messenger/chat
└── net/                   # Networking
    ├── opcodes.ex         # Packet opcodes
    ├── hex.ex             # Hex utilities
    └── packet/
        ├── in.ex          # Packet decoder
        └── out.ex         # Packet encoder

Client Compatibility

• Version: GMS v342
• Patch: 1
• Revision: 1

Key Differences from Java

1. Concurrency: Elixir processes instead of Java threads
2. State: GenServer/ETS instead of mutable fields
3. Networking: gen_tcp instead of Netty
4. Database: Ecto instead of raw JDBC
5. Hot Reloading: Native Elixir code reloading

Development

Running Tests

mix test

Code Quality

# Linting
mix credo

# Type checking
mix dialyzer

# Formatting
mix format

Packet Testing

# Decode a packet
packet = Odinsea.Net.Packet.In.new(<<0x01, 0x00, 0x05, 0x00>>)
{opcode, packet} = Odinsea.Net.Packet.In.decode_short(packet)

# Encode a packet
packet = Odinsea.Net.Packet.Out.new(0x00)
packet = Odinsea.Net.Packet.Out.encode_string(packet, "Hello")
binary = Odinsea.Net.Packet.Out.to_binary(packet)

Roadmap

See PORT_PROGRESS.md for the complete roadmap.

Immediate Next Steps

1. Implement AES encryption (lib/odinsea/net/cipher/aes.ex)
2. Port login handlers (lib/odinsea/login/handler.ex)
3. Create database schemas
4. Implement login packet responses

Contributing

This is a port of the Java Odinsea server. When implementing features:

1. Reference the Java source in /home/ra/lucid/src/
2. Follow Elixir/OTP best practices
3. Update PORT_PROGRESS.md
4. Add tests where applicable

License

Same as the original Odinsea project.

Acknowledgments

• Original Odinsea Java developers
• MapleStory community
• Elixir/OTP team