Join us in accelerating the development of this open-source project.

See our Contributing section to get started.

MS2EX is an open-source server emulator for MapleStory 2, a retired Korean MMORPG.

The project aims to recreate the server infrastructure using Elixir, a functional programming language known for building scalable and fault-tolerant applications.

• Concurrent Architecture: Built on the Erlang VM (BEAM) for excellent handling of concurrent connections
• Hot Code Reloading: Update code without restarting the server
• Fault Tolerance: Isolated processes ensure crashes don't bring down the entire system
• Scalable Design: Easily scale horizontally across multiple nodes

• Elixir 1.18
• Docker & Docker Compose (optional, but recommended)
• PostgreSQL
• Redis - Required for game client metadata
• LuaJIT dependencies - Required to run Game Client scripts

1. Clone the repository

   git clone https://github.com/sgessa/ms2ex.git
   cd ms2ex

2. Install Elixir and Erlang Follow the instructions on the Elixir installation page to install Elixir and Erlang.

   If you are using asdf you can simply do:

   asdf plugin add elixir
   asdf plugin add erlang
   asdf install

3. Install Lua dependencies

   # For Ubuntu/Debian
   apt install libluajit-5.1-dev
   
   # For OSX
   brew install luajit

4. Configure environment variables

   # Copy the example .env file and modify if needed
   cp .env-example .env

   The default values are configured to work with the Docker Compose setup.

5. Set up PostgreSQL and Redis

   Download Game Client Metadata

   Download the latest dump.rdb file from GitHub Releases first.

   Place it in the priv/redis-data/ directory of the project.

   Option A: Using Docker (Recommended)

   # Start PostgreSQL and Redis
   docker compose up -d

   Option B: Manual Setup (Linux)

   • Install and configure PostgreSQL and Redis manually
   • Stop Redis
   • Copy dump.rdb to /var/lib/redis/dump.rdb
   • Start Redis

6. Install Elixir dependencies and set-up the database

   mix setup

7. Start the server

   mix phx.server

ms2ex-server/
├── config/             # Configuration files
├── lib/                # Source code
│   ├── ms2ex/          # Core game logic
│   └── ms2ex_web/      # Web interface and API endpoints
├── priv/               # Assets and database migrations
│   ├── repo/           # Database migrations and seeds
│   └── static/         # Static assets
└── test/               # Test files

• Elixir - Primary programming language
• Phoenix - Web framework
• Ecto - Database wrapper and query generator
• PostgreSQL - Persistent data storage
• Redis - In-memory data structure store
• LuaPort - Lua integration
• Ranch - TCP socket acceptor pool

This project is actively seeking contributors to accelerate development!

Whether you're interested in fixing bugs, adding new features, or improving documentation, your help is appreciated.

Even if you're new to Elixir or are just passionate about MapleStory 2, we welcome your contributions!

The project offers a great opportunity to learn Elixir while working on something fun.

See our contributing guidelines for detailed instructions on how to get started.

• Complete core server functionalities
• Implement all game mechanics
• Add unit and integration tests
• Create comprehensive documentation
• Develop admin interface
• Support for custom plugins

Want to make an impact? Choose an area that matches your interests and skills! Please reach out via our Discord or open an issue to discuss how you can contribute.

This project is licensed under the MIT License - see the LICENSE file for details.

• The MapleStory 2 community for their research and documentation
• Contributors to the project
• The Elixir community for their excellent tools and libraries

For questions or to connect with the community:

• Open an issue on this repository for bug reports or feature requests
• Join our Discord - The community gathering spot for MS2 fans where you can also find MS2EX maintainers