lunar-tear

Lunar Tear

Private server research project for a certain discontinued mobile game. Discord server: https://discord.gg/MZAf5aVkJG

How To Launch The Server

Download & Run (no setup)

Prebuilt binaries are published for Linux, macOS, and Windows on the Releases page.

1. Download the archive for your OS/arch (lunar-tear-server---.{tar.gz,zip}).
2. Run ./wizard (macOS/Linux) or double-click wizard.exe (Windows).

Prerequisites (build from source)

• Go 1.25+
• goose migration tool
• Populated server/assets/ directory

go install github.com/pressly/goose/v3/cmd/goose@latest

Quick Start (Wizard)

The interactive wizard walks you through setup with a few simple questions — no flags or networking knowledge needed. It auto-detects the right IP address for your emulator or phone and launches all services.

cd server
go run ./cmd/wizard

Your choices are saved so next time you just press Enter to relaunch with the same settings. To skip the confirmation prompt entirely (useful for scripts or quick relaunches), pass --prefer-saved:

go run ./cmd/wizard --prefer-saved

If no saved config exists, the flag prints an error and exits.

Custom Ports

By default the wizard uses ports 8003 (gRPC), 8080 (CDN), and 3000 (auth). Override any of them with flags:

go run ./cmd/wizard --grpc-port 9003 --cdn-port 9080

Custom ports are saved to .wizard.json alongside your other settings. On the next run the saved ports are reused automatically — no need to pass the flags again. If you later pass different port flags, the wizard warns you that the ports changed and asks for confirmation before continuing.

Regenerate protobuf stubs

cd server
make proto

Database

Player state is stored in a SQLite database. Run migrations before starting the server:

cd server
make migrate

Or manually:

cd server
mkdir -p db
goose -dir migrations -allow-missing sqlite3 db/game.db up

Backups & Restore

The wizard backs up your save every time you launch it. To roll back to an earlier save:

cd server
make restore

Pick a backup from the list and confirm.

Importing a Snapshot

To import a JSON snapshot into the database, use the import tool. The --uuid flag must match the UUID your game client sends during authentication:

cd server
make import SNAPSHOT=snapshots/scene_1.json UUID=

Or directly:

go run ./cmd/import-snapshot \
  --snapshot snapshots/scene_1.json \
  --uuid  \
  --db db/game.db

Run

The server is split into two binaries: a gRPC game server and an HTTP asset CDN. Both must be running for the client to work.

Start the CDN (serves asset bundles, list.bin, master data, web pages):

cd server
go run ./cmd/octo-cdn \
  --listen 0.0.0.0:8080 \
  --public-addr 10.0.2.2:8080

Start the game server (gRPC, points the client at the CDN):

cd server
go run ./cmd/lunar-tear \
  --listen 0.0.0.0:8003 \
  --public-addr 10.0.2.2:8003 \
  --octo-url http://10.0.2.2:8080

The default listen address is 0.0.0.0:443, which requires sudo (privileged port). Use --listen with a high port to avoid this. If you do need port 443, either use sudo or grant the binary the capability on Linux:

go build -o lunar-tear ./cmd/lunar-tear
sudo setcap cap_net_bind_service=+ep ./lunar-tear
./lunar-tear --public-addr 10.0.2.2:443 --octo-url http://10.0.2.2:8080

The CDN can run on a completely separate machine — just set --octo-url on the game server and --public-addr on the CDN to the externally-reachable address.

Run All Services At Once

Instead of starting each service individually, use the dev runner to launch all three (auth, CDN, game server) with a single command. No Docker required — works on macOS, Linux, and Windows.

cd server
make dev

Or directly:

cd server
go run ./cmd/dev

Each service's output is prefixed with a colored label ([auth], [cdn], [grpc]). Press Ctrl+C to shut everything down.

The dev runner automatically builds each service into bin/ before launching. This means the binaries have stable file paths, so Windows Firewall only prompts once — subsequent runs reuse the same allowed executables. The wizard performs the same build step transparently.

Override defaults with namespaced flags:

go run ./cmd/dev --grpc.listen 0.0.0.0:9000 --grpc.public-addr 10.0.2.2:9000 --cdn.public-addr 192.168.1.50:8080

Or via make:

make dev ARGS="--grpc.listen 0.0.0.0:9000 --grpc.public-addr 10.0.2.2:9000"

Ports

Game Server Flags (lunar-tear)

Live Master Data Reload

The game server reads its master data from assets/release/20240404193219.bin.e at startup. To swap in updated content without restarting the server:

1. Replace assets/release/20240404193219.bin.e on disk with your edited copy.
2. POST to the admin webhook with a Bearer token matching LUNAR_ADMIN_TOKEN:

curl -X POST -H "Authorization: Bearer ${LUNAR_ADMIN_TOKEN}" \
  http://127.0.0.1:8082/api/admin/master-data/reload

The server re-reads the file, atomically swaps every in-memory catalog and derived handler, and bumps the file's mtime. The mtime is folded into GetLatestMasterDataVersion, so connected clients see a new version string and re-download the file from the CDN on their next poll.

Security defaults are fail-closed:

• LUNAR_ADMIN_TOKEN must be set in the environment, or the webhook listener never binds.
• --admin-listen defaults to 127.0.0.1:8082 (loopback only). Bind to 0.0.0.0 only if you intend to expose it.
• Authentication uses constant-time Bearer-token comparison.

CDN Flags (octo-cdn)