Guide for running on Steam Deck

[johnoestmannmusic]

I spent a good few hours doing heavily-AI-assisted troubleshooting to get this running on my Steam Deck, and finally reached playable success!
In case helpful to anyone else, here is the summary of what ended up working. Feel free to comment if something doesn't make sense, and I'll try to refine into a more streamlined guide:

Running MapleStory v83 Cosmic Private Server on a Steam Deck

A working setup for playing MapleStory locally on SteamOS, with a controller, in Gaming Mode.

As of August 2026, Official MapleStory can't run on Linux — its anti-cheat (BlackCipher/nProtect) hooks Windows at a level Proton doesn't emulate, and the client dies before a window appears. A local private server allows the game to run on Linux, without infringing on official servers.

Tested on: Steam Deck, SteamOS 3.x, August 2026.

---

Overview

Three components:

Component	Runs where	What it is
Database	podman container on the host	MySQL 8
Server emulator	distrobox (Arch) container	P0nk/Cosmic, Java 21
Client	Bottles, win32 prefix	Patched v83 client

---

1. Prerequisites

SteamOS has an immutable root filesystem — anything installed with pacman on the host is wiped by the next system update. Don't fight this; use containers.

Since SteamOS 3.5, podman and distrobox are preinstalled. Verify from Desktop Mode:

which podman distrobox

Everything below assumes Desktop Mode with a keyboard attached (unless you happen to love typing in long bash with the on-screen keyboard).

Tip: run hostname whenever you're unsure which side you're on. It returns the container name inside distrobox, and your Deck's hostname on the host. Most confusion in this setup comes from running a command while in the wrong container space.

---

2. Database

Run MySQL as its own podman container on the host (not inside distrobox — distrobox containers don't run systemd, which makes a database inside one tedious to start).

podman run -d --name cosmic-db \
  -e MYSQL_ROOT_PASSWORD=yourpassword \
  -e MYSQL_DATABASE=cosmic \
  -p 3306:3306 \
  -v cosmic-db-data:/var/lib/mysql \
  docker.io/library/mysql:8

Watch it initialise and wait for ready for connections:

podman logs -f cosmic-db

Notes:

• MYSQL_DATABASE=cosmic creates the schema automatically, skipping the HeidiSQL step in Cosmic's README.
• The named volume preserves accounts and characters across container rebuilds.
• Without --restart=always, this won't automatically start at boot (which I would recommend to avoid conflicts with other apps when you're not playing MS-Cosmic). Start the database manually with podman start cosmic-db.

---

3. Server

Create a build container and install the toolchain:

distrobox create --image archlinux:latest --name maple
distrobox enter maple
sudo pacman -Syu jdk21-openjdk git git-lfs
java -version        # must report 21

Distrobox mounts your real home directory, so clone somewhere shared:

mkdir -p ~/Games && cd ~/Games
git clone https://github.com/P0nk/Cosmic.git
cd Cosmic

Edit config.yaml:

• Set DB_PASS to your MySQL root password.
• Set any client-facing host/IP to 127.0.0.1

Build:

chmod +x mvnw
./mvnw clean package -DskipTests

(mvnw.cmd in the README is the Windows form. -DskipTests avoids a Surefire failure that doesn't affect a single-player server.)

Run:

java -Djava.awt.headless=true -Dwz-path=./wz -jar target/*.jar 2>&1 | tee server.log

Both flags are mandatory. -Dwz-path because the WZ XML data isn't bundled into the jar; -Djava.awt.headless=true because the server touches java.awt geometry classes and will otherwise crash the moment you try to enter the game world.

Wait for Cosmic is now online, then verify from the host:

ss -ltnp | grep -E '8484|757[0-9]'

You want 8484 (login) plus one port per channel from 7575 up.

---

4. Client

Client files live in a separate repo - you can find the link to the Cosmic-Client on P0nk's GitHub.

⚠️Note. The server emulator is community-written open source (AGPL). The v83 client, art and other game assets and code, is by Nexon.

The client repo uses Git LFS. Without git-lfs installed, git clone silently gives you 135-byte pointer files instead of binaries. Always verify:

file HeavenMS-localhost-WINDOW.exe   # must say "PE32 executable"
ls -lh HeavenMS-localhost-WINDOW.exe # ~9.5 MB, not bytes

If you get pointers:

git lfs install
git lfs pull

If git lfs pull reports the repository has exceeded its LFS budget, the quota is exhausted on the repo owner's side. In this case, I was able to manually download each Cosmic-Client file from the GitHub repo via the browser.

---

5. Bottles prefix

Install Bottles from Discover (Flathub).

Create the bottle:

• + → Custom environment (not Gaming or Application — those filter the runner list to Proton only)
• Advanced options → architecture win32
• Runner: Soda (plain Wine)

⚠️ Do not pick ProtonSoda or anything showing a UMU tag. Those route through Proton, which is the configuration that fails. If you don't see plain Soda in the list, download it from Preferences → Runners first.

Install the game:

• Run Executable (not "Install Programs" — that's Bottles' curated recipe catalogue and doesn't accept arbitrary files)
• Point it at the v83 installer, accept the default C:\Nexon\MapleStory path

Then copy the patched client and its custom .wz files into:

~/.var/app/com.usebottles.bottles/data/bottles/bottles/<bottle-id>/drive_c/Nexon/MapleStory/

Add the patched .exe to the bottle's library as a Shortcut so it appears as a launchable program. You will have removed the original launcher as part of Cosmic's instructions too.

---

6. Launcher script

Save as ~/Games/maple.sh and chmod +x it:

#!/bin/bash

# 1. Database
podman start cosmic-db
until podman exec cosmic-db mysqladmin ping -h localhost --silent 2>/dev/null; do
  sleep 1
done

# 2. Server (background)
cd ~/Games/Cosmic
distrobox enter maple -- java -Djava.awt.headless=true -Dwz-path=./wz \
  -jar target/*.jar > ~/Games/Cosmic/server.log 2>&1 &
SERVER_PID=$!

# 3. Wait for the login port
until ss -ltn | grep -q ':8484'; do
  sleep 1
done

# 4. Client (foreground — Steam tracks this)
flatpak run --command=bottles-cli com.usebottles.bottles run \
  -b "YOUR_BOTTLE_NAME" -p "YOUR_PROGRAM_NAME"

# 5. Tear down
kill $SERVER_PID
podman stop cosmic-db

Find your exact bottle and program names with:

flatpak run --command=bottles-cli com.usebottles.bottles list bottles

The polling loops matter — launching the client before 8484 is listening reproduces connection failures that look like config problems.

---

7. Adding to Steam

• Steam → Games → Add a Non-Steam Game → browse to ~/Games/maple.sh
• Do not set a Proton compatibility tool. It's a Linux shell script and must run natively.
• Test from Desktop Mode first, where errors are visible.

For the controller: Create your own Steam layout to taste! I have personally had success mapping CTRL to A (jump), the attack button to Right bumper, my arrow keys to Left Control Stick, my most essential menus to D-Pad, and a few of the action hotkeys to X, Y, B, buttons.

---

Gotchas

Collected failures from this build, roughly in the order they cost the most time.

Proton does not work. Experimental, GE-Proton 9, and Proton 8.0 all failed — silent exits, or a window flashing and closing. A plain Wine runner in a win32 prefix seems to be required. It seems Steam cannot create 32-bit prefixes, which is why Bottles is required rather than optional.

java.awt crash on entering the world. Login and character creation work, then entering the game world fails with NoClassDefFoundError: Could not initialize java.awt.Rectangle. Fix: -Djava.awt.headless=true. The server uses AWT geometry classes for map bounds, and they can't initialise without a display. This never affects Windows users, so it isn't in any FAQ.

Git LFS pointer files. A 135-byte "executable" that file reports as ASCII text. Causes wildly varied downstream errors — Wine prefix init failures, silent Proton exits, "Exec format error." Run file on every binary you download. This one check would have saved hours.

WARN ... account null is not an error. It's Cosmic's logging preamble printing client context, and a fresh channel connection legitimately has no account yet. The real cause is in the stack trace underneath it. Always read the next line.

BindException: Address already in use at startup. Usually a leftover java process (pgrep -af java on the host — a container can't see host processes), or too many channels configured.

Stuck at character select after a failed attempt. An account can be left flagged as logged in. Clear it using SQL:

UPDATE accounts SET loggedin = 0;

pacman "read-only file system". You're on the host, not in the container. distrobox enter maple first.

Steam shows "Running" after the game exits. A known non-Steam shortcut quirk. pkill -f reaper clears it. Don't mistake it for the game still running.

Bottles "Unable to create bottle" / "Wine prefix initialization failed". Check disk space, then that the runner downloaded completely (du -sh ~/.var/app/com.usebottles.bottles/data/bottles/runners/* — a real runner is ~1.8 GB), then delete any half-created bottle directories before retrying.

---

Credits

• Nexon for creating one of the most charming video games, even 25 years on
• P0nk/Cosmic — server emulator, descended from OdinMS (2008) → MapleSolaxia → HeavenMS (2019)
• Everyone in that lineage who kept it alive for eighteen years