mirror of Walter-Sparrow / lunar-tear
1# Lunar Tear
2
3Private server research project for a certain discontinued mobile game.
4Discord server: https://discord.gg/MZAf5aVkJG
5
6## How To Launch The Server
7
8### Prerequisites
9
10- Go 1.25+
11- [goose](https://github.com/pressly/goose) migration tool
12- Populated `server/assets/` directory
13
14```bash
15go install github.com/pressly/goose/v3/cmd/goose@latest
16```
17
18### Quick Start (Wizard)
19
20The 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.
21
22```bash
23cd server
24go run ./cmd/wizard
25```
26
27Your 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`:
28
29```bash
30go run ./cmd/wizard --prefer-saved
31```
32
33If no saved config exists, the flag prints an error and exits.
34
35#### Custom Ports
36
37By default the wizard uses ports 8003 (gRPC), 8080 (CDN), and 3000 (auth). Override any of them with flags:
38
39```bash
40go run ./cmd/wizard --grpc-port 9003 --cdn-port 9080
41```
42
43| Flag | Default | Description |
44| ---------------- | ------- | ---------------------------------- |
45| `--prefer-saved` | `false` | Reuse saved config without prompting |
46| `--grpc-port` | `8003` | gRPC server port |
47| `--cdn-port` | `8080` | CDN server port |
48| `--auth-port` | `3000` | Auth server port |
49| `--admin-port` | `0` | Admin webhook port (`0` = disabled). Bound on `127.0.0.1`; only takes effect when `LUNAR_ADMIN_TOKEN` is set in the env. |
50
51Custom 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.
52
53### Regenerate protobuf stubs
54
55```bash
56cd server
57make proto
58```
59
60### Database
61
62Player state is stored in a SQLite database. Run migrations before starting the server:
63
64```bash
65cd server
66make migrate
67```
68
69Or manually:
70
71```bash
72cd server
73mkdir -p db
74goose -dir migrations -allow-missing sqlite3 db/game.db up
75```
76
77### Importing a Snapshot
78
79To import a JSON snapshot into the database, use the import tool. The `--uuid` flag must match the UUID your game client sends during authentication:
80
81```bash
82cd server
83make import SNAPSHOT=snapshots/scene_1.json UUID=<your-client-uuid>
84```
85
86Or directly:
87
88```bash
89go run ./cmd/import-snapshot \
90 --snapshot snapshots/scene_1.json \
91 --uuid <your-client-uuid> \
92 --db db/game.db
93```
94
95| Flag | Default | Description |
96| ------------ | ------------ | --------------------------------------------- |
97| `--snapshot` | *(required)* | Path to JSON snapshot file |
98| `--uuid` | *(required)* | UUID to assign (must match the client's UUID) |
99| `--db` | `db/game.db` | SQLite database path |
100
101### Run
102
103The server is split into two binaries: a gRPC game server and an HTTP asset CDN. Both must be running for the client to work.
104
105**Start the CDN** (serves asset bundles, list.bin, master data, web pages):
106
107```bash
108cd server
109go run ./cmd/octo-cdn \
110 --listen 0.0.0.0:8080 \
111 --public-addr 10.0.2.2:8080
112```
113
114**Start the game server** (gRPC, points the client at the CDN):
115
116```bash
117cd server
118go run ./cmd/lunar-tear \
119 --listen 0.0.0.0:8003 \
120 --public-addr 10.0.2.2:8003 \
121 --octo-url http://10.0.2.2:8080
122```
123
124The 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:
125
126```bash
127go build -o lunar-tear ./cmd/lunar-tear
128sudo setcap cap_net_bind_service=+ep ./lunar-tear
129./lunar-tear --public-addr 10.0.2.2:443 --octo-url http://10.0.2.2:8080
130```
131
132The 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.
133
134### Run All Services At Once
135
136Instead 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.
137
138```bash
139cd server
140make dev
141```
142
143Or directly:
144
145```bash
146cd server
147go run ./cmd/dev
148```
149
150Each service's output is prefixed with a colored label (`[auth]`, `[cdn]`, `[grpc]`). Press Ctrl+C to shut everything down.
151
152The 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.
153
154Override defaults with namespaced flags:
155
156```bash
157go 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
158```
159
160Or via `make`:
161
162```bash
163make dev ARGS="--grpc.listen 0.0.0.0:9000 --grpc.public-addr 10.0.2.2:9000"
164```
165
166| Flag | Default | Description |
167| --------------------- | ------------------ | ---------------------------------------- |
168| `--auth.listen` | `0.0.0.0:3000` | auth-server listen address |
169| `--auth.db` | `db/auth.db` | auth-server SQLite database path |
170| `--cdn.listen` | `0.0.0.0:8080` | octo-cdn local bind address |
171| `--cdn.public-addr` | `10.0.2.2:8080` | octo-cdn externally-reachable addr |
172| `--grpc.listen` | `0.0.0.0:8003` | lunar-tear gRPC listen address |
173| `--grpc.public-addr` | `10.0.2.2:8003` | lunar-tear externally-reachable addr |
174| `--grpc.octo-url` | `http://10.0.2.2:8080` | Octo CDN base URL passed to lunar-tear |
175| `--grpc.auth-url` | `http://localhost:3000` | auth server base URL passed to lunar-tear |
176| `--admin.listen` | *(empty)* | lunar-tear admin webhook bind. Empty = leave default; webhook only binds when `LUNAR_ADMIN_TOKEN` is set in the env. |
177| `--no-color` | `false` | disable colored output |
178
179### Ports
180
181| Protocol | Port | Binary | Notes |
182| -------- | ---- | ------------- | ----------------------------------------------------------- |
183| gRPC | 443 | `lunar-tear` | default; configurable with `--listen` (requires patched client) |
184| HTTP | 8080 | `octo-cdn` | Octo asset API + game web pages |
185| HTTP | 8082 | `lunar-tear` | admin webhook (`/api/admin/master-data/reload`); loopback by default, only binds when `LUNAR_ADMIN_TOKEN` is set |
186| HTTP | 3000 | `auth-server` | account registration and login |
187
188### Game Server Flags (`lunar-tear`)
189
190| Flag | Default | Description |
191| ---------------- | ----------------- | ---------------------------------------------------- |
192| `--listen` | `0.0.0.0:443` | gRPC listen address (host:port) |
193| `--public-addr` | `127.0.0.1:443` | externally-reachable host:port advertised to clients |
194| `--octo-url` | *(required)* | CDN base URL the client uses for assets (e.g. `http://10.0.2.2:8080`) |
195| `--db` | `db/game.db` | SQLite database path |
196| `--auth-url` | *(empty)* | Auth server base URL (e.g. `http://localhost:3000`) |
197| `--admin-listen` | `127.0.0.1:8082` | Admin webhook listen address. Only binds when `LUNAR_ADMIN_TOKEN` is set. |
198
199### Live Master Data Reload
200
201The game server reads its master data from `assets/release/20240404193219.bin.e` at startup. To swap in updated content **without restarting** the server:
202
2031. Replace `assets/release/20240404193219.bin.e` on disk with your edited copy.
2042. POST to the admin webhook with a Bearer token matching `LUNAR_ADMIN_TOKEN`:
205
206```bash
207curl -X POST -H "Authorization: Bearer ${LUNAR_ADMIN_TOKEN}" \
208 http://127.0.0.1:8082/api/admin/master-data/reload
209```
210
211The 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.
212
213Security defaults are fail-closed:
214
215- `LUNAR_ADMIN_TOKEN` **must** be set in the environment, or the webhook listener never binds.
216- `--admin-listen` defaults to `127.0.0.1:8082` (loopback only). Bind to `0.0.0.0` only if you intend to expose it.
217- Authentication uses constant-time Bearer-token comparison.
218
219### CDN Flags (`octo-cdn`)
220
221| Flag | Default | Description |
222| --------------- | ----------------- | -------------------------------------------------------- |
223| `--listen` | `0.0.0.0:8080` | local bind address |
224| `--public-addr` | `127.0.0.1:8080` | externally-reachable address (used in list.bin rewriting) |
225| `--assets-dir` | `.` | root directory containing the `assets/` tree |
226
227### Docker
228
229Three services are available via Docker Compose: the game server (`lunar-tear`), the CDN (`octo-cdn`), and the auth server (`auth-server`). Migrations run automatically on game server start.
230
231```bash
232cd server
233docker compose up -d
234```
235
236The `db/` directory is mounted as a volume so both `game.db` and `auth.db` persist across restarts. Make sure `assets/` is populated before starting.
237
238Each service has its own image and can be deployed independently:
239
240| Service | Image | Default Port | Notes |
241| -------- | --------------------------- | ------------ | ------------------------------ |
242| `server` | `kretts/lunar-tear:latest` | 8003, 8082 | gRPC game server + admin webhook |
243| `cdn` | `kretts/octo-cdn:latest` | 8080 | HTTP asset CDN |
244| `auth` | `kretts/auth-server:latest` | 3000 | Account registration and login |
245
246The game server is configured via environment variables in the compose file:
247
248| Env var | Description |
249| --------------------- | -------------------------------------------------------------------------------------------- |
250| `LUNAR_LISTEN` | gRPC bind address |
251| `LUNAR_PUBLIC_ADDR` | Client-facing address advertised to the game |
252| `LUNAR_OCTO_URL` | CDN base URL the client uses for assets |
253| `LUNAR_AUTH_URL` | Auth server base URL (optional) |
254| `LUNAR_ADMIN_LISTEN` | Admin webhook bind address inside the container (compose default: `0.0.0.0:8082`) |
255| `LUNAR_ADMIN_TOKEN` | Bearer token for the admin webhook. **The webhook does not bind unless this is set.** |
256
257Auth is optional — if `LUNAR_AUTH_URL` is unset the game server starts without it. The admin webhook is published to `127.0.0.1:8082` on the host so the master-data reload endpoint stays loopback-only by default; set `LUNAR_ADMIN_TOKEN` (e.g. via a `.env` file) before bringing the stack up.
258
259### Makefile Targets
260
261All targets run from the `server/` directory.
262
263| Target | Description |
264| -------------- | ------------------------------------------------------- |
265| `make proto` | Regenerate protobuf stubs |
266| `make build` | Build the game server binary |
267| `make build-cdn` | Build the CDN binary |
268| `make build-auth` | Build the auth server binary |
269| `make build-dev` | Build the dev runner binary to `bin/` |
270| `make build-all` | Build all service binaries to `bin/` |
271| `make build-import` | Build the import-snapshot tool |
272| `make build-claim-account` | Build the claim-account tool |
273| `make clean` | Remove the `bin/` directory |
274| `make dev` | Run all three services with one command |
275| `make migrate` | Run goose migrations on `db/game.db` |
276| `make import` | Import a snapshot (`SNAPSHOT=... UUID=...` required) |
277
278## Claim Account
279
280Transfers an existing game account to the most recently connected client. Looks up a player by their in-game name, assigns the new client's UUID to that account, and deletes the empty account the new client created.
281
282Useful when a new client connects and creates a throwaway account, but you want it to load an existing account instead.
283
284```bash
285cd server
286go run ./cmd/claim-account --name "PlayerName" --db db/game.db
287```
288
289| Flag | Default | Description |
290| -------- | ------------ | ---------------------------------------------------- |
291| `--name` | *(required)* | In-game player name to claim |
292| `--db` | `db/game.db` | SQLite database path |
293
294## Auth Server
295
296A separate HTTP server that handles player account registration and login. The patched client's Facebook login button is redirected to this server, which presents a username/password form. Tokens issued here are validated by the game server to link or recover accounts.
297
298### Run
299
300```bash
301cd server
302go run ./cmd/auth-server \
303 --listen 0.0.0.0:3000 \
304 --db db/auth.db
305```
306
307The `--secret` flag accepts a hex-encoded HMAC key. If omitted, a random key is generated on startup and printed to the console — pass it back on the next restart to keep existing tokens valid.
308
309### Flags
310
311| Flag | Default | Description |
312| ---------- | --------------- | -------------------------------------------- |
313| `--listen` | `0.0.0.0:3000` | HTTP listen address (host:port) |
314| `--db` | `db/auth.db` | SQLite database path for auth users |
315| `--secret` | *(generated)* | Hex-encoded HMAC secret for token signing |
316
317## ⚠️ Legal Disclaimer
318
319**Lunar Tear** is a fan-made, non-commercial **preservation and research project** dedicated to keeping a certain discontinued mobile game playable for educational and archival purposes.
320
321- This project is **not affiliated with**, **endorsed by**, or **approved by** the original publisher or any of its subsidiaries.
322- All trademarks, copyrights, and intellectual property related to the original game and its associated franchises belong to their respective owners.
323- All code in this repository is original work developed through clean-room reverse engineering for interoperability with the game client.
324- No copyrighted game assets, binaries, or master data are distributed in this repository.
325
326**Use at your own risk.** The author assumes no liability for any damages or legal consequences that may arise from using this software. By using or contributing to this project, you are solely responsible for ensuring your usage complies with all applicable laws in your jurisdiction.
327
328This project is released under the [MIT License](LICENSE).
329
330**If you are a rights holder with concerns regarding this project**, please contact me directly.