# LunarCore setup, architecture, and feature limits

> LunarCore is a Java reimplementation of a turn-based game server, aimed at developers studying server behavior and running local game systems. It covers substantial gameplay, but several modes remain incomplete and its documented client setup depends on Fiddler Classic.

**Melledy/LunarCore** — A game server reimplementation for a certain turn-based anime game

- Repository: https://github.com/Melledy/LunarCore
- Stars: 1,432 · Forks: 277
- Language: Java
- License: AGPL-3.0
- Published: 2026-10-16 · Updated: 2026-10-16 · Language: en
- Canonical page: https://hysenlabs.com/projects/melledy-lunarcore

## LunarCore's server reimplementation scope

LunarCore targets version 4.2.0 of a particular turn-based anime game, but the README does not name that game directly. It is a server implementation written primarily in Java and described as being for educational purposes, rather than a conventional application with a public API or hosted service. Its intended users are developers who want to inspect or operate game-server logic and players who want to connect a client to a locally controlled server.

The documented feature set extends beyond login and account handling. LunarCore supports team setup, inventory management, scene and entity management, monster battles, world spawns, character techniques, crafting, consumables, NPC shops, gacha, mail, the Forgotten Hall, and Pure Fiction. These entries indicate a substantial content-oriented server, not a small authentication mock.

Feature availability still has boundaries. The README says assists are not working, while Simulated Universe runs can be completed but many features are missing. The documentation does not claim parity with every official server function. Its value for engineers lies in having a broad implementation that can be compiled and run as a Java server, but the feature list should be treated as a map of implemented systems rather than a promise of complete behavior.

## Build, data, and database flow in LunarCore

The repository layout follows a conventional Gradle Java project. The top level includes `build.gradle`, `settings.gradle`, the `gradlew` and `gradlew.bat` launchers, a `gradle` directory, `src`, `lib`, and `data`. Based on this layout, source code is separated from build configuration and bundled libraries. The README does not document an API surface, plugin model, deployment container, or external service configuration.

Compilation creates a runnable server archive. At runtime, the server expects three external data directories named `Config`, `TextMap`, and `ExcelBin` under its `resources` directory. The README directs users to obtain those folders from the linked StarRailData repository. This dependency means a successful source build is not the entire setup: LunarCore still needs game data that the build process does not appear to include automatically.

Persistence is handled through MongoDB. The README says the server includes an internal MongoDB implementation, so a separate installation is not required to start it. It still recommends MongoDB 4.0 or newer, which presents external database deployment as the more conventional route for some operators. However, the README does not document connection keys, database schemas, authentication settings, backup procedures, or migration commands. Those operational details must be verified in the configuration after obtaining the required data directories.

## Building LunarCore and creating the first account

Install the Java 21 JDK first. The README recommends Java 25 but lists Java 21 as the prerequisite. From the repository root, compile the server with the included Gradle wrapper:

```bash
./gradlew jar
```

The command produces the server archive used by the documented launch process. Windows installations are not given an explicit command, although the repository includes `gradlew.bat`. The README does not state the generated archive path, so operators should confirm where `build.gradle` places `LunarCore.jar` before trying to launch it.

Create a directory named `resources` in the server directory:

Download the `Config`, `TextMap`, and `ExcelBin` folders from the documented StarRailData location and place all three inside `resources`. After that data is present, start the server from the terminal:

```bash
java -jar LunarCore.jar
```

The README says LunarCore uses its built-in internal MongoDB server. If `autoCreateAccount` is set to `true` in the configuration, account creation can be skipped. Otherwise, create an account from the server console with the documented command:

```text
/account create [account name]
```

Replace `[account name]` with the desired login name. The server ignores the client's password field, so the README says it can contain anything. That behavior suits the documented local setup, but it also makes network exposure inappropriate without independent access controls, none of which the README specifies.

## Connecting a client through Fiddler Classic

The documented client workflow begins with an official-server login so the client downloads game data. It then uses Fiddler Classic to redirect selected service hosts to `localhost`. This is not an ordinary browser-based application with a configurable server address. The operator must have the game client, Fiddler Classic, and the required downloaded game data available.

The following FiddlerScript changes matching `.starrails.com`, `.hoyoverse.com`, `.mihoyo.com`, and `.bhsr.com` requests to HTTP on `localhost`. The README notes that the address may instead be another IP.

```csharp
import System;
import System.Windows.Forms;
import Fiddler;
import System.Text.RegularExpressions;

class Handlers
{
    static function OnBeforeRequest(oS: Session) {
        if (oS.host.EndsWith(".starrails.com") || oS.host.EndsWith(".hoyoverse.com") || oS.host.EndsWith(".mihoyo.com") || oS.host.EndsWith(".bhsr.com")) {
            oS.oRequest.headers.UriScheme = "http";
            oS.host = "localhost";
        }
    }
};
```

Save the script in Fiddler Classic before attempting login. The README does not document certificate handling, firewall configuration, host exclusions, troubleshooting, or how to restore normal routing afterward. Those omissions make the client connection less straightforward than the Java build itself. They also mean the documented happy path should not be mistaken for a complete deployment guide.

## Administrative commands and unfinished game systems

LunarCore exposes administrative commands in the server console and, through a dummy friend named `Server`, inside the game. These commands cover account operations, inventory grants, progression, teleportation, spawning, lineup changes, mail, permissions, and server control. That makes the project useful for local inspection of command handling and game-state mutation, but it also gives administrators broad control over player state.

Several commands are explicitly hazardous or specialized. The `/lineup` command says to use it at the caller's own risk. `/unstuck` exists for a player left in a scene that does not load, showing that scene-state problems are anticipated. Commands such as `/reload` and `/stop` affect the server as a whole, while `/give`, `/giveall`, `/spawn`, and `/permission` alter player or environmental state.

The feature boundary is clearest in social and endgame systems. Friend functionality exists, but assists do not work. Simulated Universe runs can finish, yet many features are absent. Neither the README nor the release list explains a roadmap for those gaps, a compatibility matrix, or which versions of each feature are complete. A prospective user who requires those exact systems should not infer production equivalence from the names appearing in the feature list.

## AGPL-3.0 obligations and release considerations

LunarCore is licensed under AGPL-3.0. That matters for anyone planning to modify, redistribute, or offer the software as a network service, although this article does not provide legal advice. The repository includes a `LICENSE` file, and the license identifier is also displayed in the README. Operators should read that file for the actual obligations rather than infer compliance from the project name or release version.

The repository is not archived, and its last push was on 2026-05-27. Releases include `v2.0.0` on 2026-04-23, `v1.3.0` on 2024-06-16, and `v1.2.0` on 2024-03-13. The gap between the recent `v2.0.0` release and the later push indicates post-release repository changes may exist. No release notes or README section explains a `v2.0.0` migration, configuration compatibility guidance, or a documented upgrade procedure, so switching an existing installation would require checking the repository and configuration directly.

External data is another upgrade concern. Because `Config`, `TextMap`, and `ExcelBin` must be supplied separately, changing LunarCore versions may also require data from a compatible upstream source. The README does not state whether LunarCore checks data versions, handles incompatible files, or includes an automated conversion step.

## LunarCore versus a conventional application server

LunarCore's practical alternative is a general-purpose Java backend framework combined with separately implemented game modules. The difference is architectural. LunarCore already organizes the documented game-specific systems, including battles, spawns, inventory, shops, mail, friends, and game modes. A general-purpose server supplies runtime and networking infrastructure but leaves those domain rules and content structures unbuilt.

That makes LunarCore more relevant for local protocol and game-state experimentation. It is less suitable when the priority is a documented API, conventional service deployment, database administration, or independent module ownership. LunarCore's README focuses on compiling and connecting a game client, while its repository layout is centered on Java source and game data rather than a published SDK.

Another realistic alternative is using the official service when complete behavior, support, and account integrity matter. LunarCore does not claim to reproduce every feature and explicitly marks important gaps. Its educational reimplementation should therefore be judged as a code and experiment platform, not as a transparent substitute for the official server.

## Conclusion

LunarCore fits developers studying this game server or local experimentation with its Java implementation. It is a poor choice for users who need a complete private server, particularly because assists do not work and Simulated Universe lacks many features. Adoption decisions should first verify Java 21 compatibility, acquisition and placement of the required game data, intended use under AGPL-3.0, and whether the incomplete game modes affect the intended workload.

## FAQ

### What Java version does LunarCore require?

The README lists Java 21 JDK as the prerequisite and recommends Java 25 JDK. It does not provide compatibility notes for older Java releases.

### Does LunarCore require a separate MongoDB installation?

No. The README states that LunarCore includes an internal MongoDB server, although MongoDB 4.0 or newer is recommended. It does not explain how to configure an external instance.

### Which LunarCore game features are incomplete?

The README says friend assists are not working. Simulated Universe runs can be completed, but many features are missing.

## Sources

- [Issues](https://github.com/Melledy/LunarCore/issues)
- [License: AGPL-3.0](https://github.com/Melledy/LunarCore/blob/lite/LICENSE)
- [Melledy/LunarCore on GitHub](https://github.com/Melledy/LunarCore)
- [README](https://github.com/Melledy/LunarCore/blob/lite/README.md)
- [Releases](https://github.com/Melledy/LunarCore/releases)

---

Hysen Labs editorial analysis, written from the project's own repository and release notes. Cite the canonical page: https://hysenlabs.com/projects/melledy-lunarcore