🍁 MapleStory WASM

A WebAssembly port of MapleStory v83, playable directly in your browser.

MapleStory WASM brings the classic MapleStory v83 client to modern web browsers using WebAssembly. The repository contains the WASM client build, the local web services used by the browser runtime, and Docker entrypoints for running the web stack. The client is designed to run with Cosmic server.

---

🏗️ Architecture

┌───────────────────────────┐       ┌──────────────────────────────────────┐
│     Web Server (Python)   │       │            Browser (Client)          │
│     web/server.py         │──────▶│     MapleStory WASM Client Runtime   │
│     http://localhost:8000 │ HTTP  │        (JS + WASM in browser)        │
└───────────────────────────┘       └───────────────┬──────────────┬───────┘
                                                    │              │
                                                    │ WebSocket    │ WebSocket
                                                    │ (Game        │ (Asset
                                                    │ Packets)     │ Requests)
                                                    ▼              ▼
                                          ┌────────────────┐  ┌───────────────────────────┐
                                          │ WS Proxy       │  │   Assets Server (Python)  │
                                          │ web/ws_proxy.py│  │   ws://localhost:8765     │
                                          │ :8080          │  └───────────────────────────┘
                                          └───────┬────────┘
                                                  │ TCP
                                                  ▼
                                          ┌───────────────────────────┐
                                          │    Cosmic Server (TCP)    │
                                          └───────────────────────────┘

How It Works

1. WASM Client - The original C++ MapleStory client is compiled to WebAssembly using Emscripten, and web/server.py serves the generated JS/WASM bundle to the browser.
2. WebSocket Proxy - Browsers cannot make raw TCP connections, so a Python proxy bridges WebSocket connections to Cosmic server over TCP.
3. LazyFS - A dynamic file system technology that streams game assets (.nx files) on-demand via WebSocket and caches them locally in your browser. Assets are only fetched from the network once, providing native loading times on subsequent loads.
4. Containerized Tooling - Docker can be used both for serving the project and as a fallback way to build the WASM client.

---

⚠️ Required Game Assets

1. Client Assets (.nx files)

To put together the asset set:

1. Take every .wz file from v83 except UI.wz.
2. Take only UI.wz from v153+.
3. Run all of those .wz files through the WZ to NX converter to produce .nx files.
4. Drop the resulting .nx files into maplestory-wasm/assets/.

Treat assets/ as read-only once the files are in place — don't modify anything in it.

---

🚀 Quick Start

Client Build

Prefer the docker build first:

./scripts/docker_build_wasm.sh

Useful variants:

./scripts/docker_build_wasm.sh --debug
./scripts/docker_build_wasm.sh --jobs 4

If the local Emscripten and CMake toolchain is available, you can use the local build:

./scripts/build_wasm.sh

Useful variants:

./scripts/build_wasm.sh --debug
./scripts/build_wasm.sh --jobs 4

Output:

The client build output is written to build/.

Local Deployment

Use local deployment when the toolchain and supporting services are available on the host machine.

Requirements:

Requirement	Version	Purpose
Python	3.9+	Local web services
Emscripten	3.1+	WASM compilation
CMake	3.16+	Build system

1. Build the client with ./scripts/build_wasm.sh.
2. Install the local Python dependency:

pip install -r web/requirements.txt

3. Start the web services from the repository root:

python3 web/server.py
python3 web/ws_proxy.py --ws-port 8080
python3 web/assets_server.py --port 8765 --directory .

4. Open http://localhost:8000.

The websocket proxy is intended to forward traffic to a running Cosmic server instance.

Docker Deployment

Use Docker when local deployment is not practical or when you want the containerized stack.

Requirement	Version	Notes
Docker	20.10+	Includes Docker Compose

Web stack:

./scripts/run_all.sh

Equivalent direct command:

./scripts/docker_web_up.sh -d

Stop all Docker services:

./scripts/stop_all.sh

Open http://localhost:8000 after the containers are up.

---

📂 Project Structure

maplestory-wasm/
├── 📁 build/              # WASM build output
├── 📁 docker/             # Dockerfiles for services
├── 📁 scripts/            # Build & run scripts
├── 📁 src/
│   ├── client/            # C++ MapleStory Client
│   └── nlnx/              # Shared NX loading library
├── 📁 web/                # Web infrastructure
│   ├── server.py          # HTTP server
│   ├── ws_proxy.py        # WebSocket-TCP proxy
│   └── assets_server.py   # NX asset streaming
├── 📄 docker-compose.yml  # Docker orchestration
├── 📄 LICENSE             # AGPL-3.0 License
└── 📄 README.md           # You are here

⚙️ Configuration

Web Client Configuration (web/config.json)

The web/config.json file controls how the browser connects to backend services. If values are missing or null, the client will attempt to auto-detect them or fall back to localhost defaults.

Variable	Description
AssetsServerProtocol	Protocol for the LazyFS assets WebSocket (ws or wss).
AssetsServerIP	IP/Hostname of the LazyFS Assets Server.
AssetsServerPort	Port of the LazyFS Assets Server (defaults to 8765).
ProxyIP	IP/Hostname of the WebSocket Proxy for game traffic.
ProxyPort	Port of the WebSocket Proxy (defaults to 8080).
MapleStoryServerIp	IP address of the target Cosmic Server (forwarded by proxy).
MapleStoryServerPort	Port of the target Cosmic Server (defaults to 8484).

Docker Environment

The docker-compose.yml provides sensible defaults. Key environment variables:

Variable	Default	Description
IS_DOCKER	true	Enables Docker-specific networking

---

🔧 Development

Making Changes

1. Edit files under src/client/, src/nlnx/, web/, scripts/, or docker/
2. Keep assets/ unchanged
3. Rebuild the client with ./scripts/build_wasm.sh
4. If the local build is unavailable, use ./scripts/docker_build_wasm.sh
5. Re-test the relevant local or Docker workflow you changed

Build Commands

Command	Description
./scripts/build_wasm.sh	Build WASM client (Release)
./scripts/build_wasm.sh --debug	Build WASM client with debug symbols
./scripts/build_wasm.sh -j 4	Build with 4 parallel jobs
./scripts/docker_build_wasm.sh	Build WASM client in Docker
./scripts/wz-converter/convert.sh	Convert local .wz files to .nx files in Docker
./scripts/run_all.sh	Start the Docker web services
./scripts/docker_web_up.sh -d	Start the Docker web services directly
./scripts/stop_all.sh	Stop all services

---

🤝 Contributing

Contributions are welcome! Please read the guidelines below before submitting.

How to Contribute

1. Fork the repository
2. Create a branch for your feature: git checkout -b feature/amazing-feature
3. Make changes and verify the relevant build and runtime flow
4. Test your changes locally
5. Commit your changes: git commit -m 'Add amazing feature'
6. Push to your fork: git push origin feature/amazing-feature
7. Open a Pull Request

Code Guidelines

• Follow the existing code style in each project (C++, Python, shell scripts)
• Keep changes focused and well-documented
• Test across multiple browsers when modifying client code
• Update documentation for user-facing changes

Areas for Contribution

• 🐛 Bug fixes and stability improvements
• 🎮 Missing game features (skills, NPCs, quests)
• 📖 Documentation improvements
• 🧪 Testing and QA
• 🎨 UI/UX enhancements

---

⚠️ Disclaimer

This project is for educational and preservation purposes only.

• MapleStory is a trademark of NEXON Korea Corporation.
• All game assets, art, music, and related content are copyright of their respective owners.
• This project does not distribute any copyrighted game assets.
• Users must provide their own legal copies of game assets (.nx or .wz files).
• This project is not affiliated with, endorsed by, or connected to NEXON in any way.

Use responsibly and respect intellectual property rights.

---

📜 License

This project is licensed under the GNU Affero General Public License v3.0 (AGPL-3.0).

See the LICENSE file for full details.

---