From 4fa2b41e4a42f9a4bff7b2022bffabe69865ea7f Mon Sep 17 00:00:00 2001 From: HarkuLi Date: Sat, 4 Apr 2026 19:02:34 +0000 Subject: [PATCH 1/4] Docker: Update Maven version Dev Container requires newer version for GLIBC, GLIBCXX. --- Dockerfile | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/Dockerfile b/Dockerfile index f291adf60d2..fb9ed611f68 100644 --- a/Dockerfile +++ b/Dockerfile @@ -4,7 +4,7 @@ # # Cosmic JAR creation stage # -FROM maven:3.9.6-amazoncorretto-21 AS jar +FROM maven:3.9.14-amazoncorretto-21-al2023 AS jar # Build in a separated location which won't have permissions issues. WORKDIR /opt/cosmic From 7d2333fba9733d20349665cceea385ab4f8593dd Mon Sep 17 00:00:00 2001 From: HarkuLi Date: Sat, 4 Apr 2026 19:08:46 +0000 Subject: [PATCH 2/4] Add Dev Container See https://code.visualstudio.com/docs/devcontainers/containers. --- .devcontainer/devcontainer.json | 57 ++++++++++++++++++++++++++++++++ .devcontainer/docker-compose.yml | 26 +++++++++++++++ Dockerfile | 6 ++-- 3 files changed, 86 insertions(+), 3 deletions(-) create mode 100644 .devcontainer/devcontainer.json create mode 100644 .devcontainer/docker-compose.yml diff --git a/.devcontainer/devcontainer.json b/.devcontainer/devcontainer.json new file mode 100644 index 00000000000..080ca97e5de --- /dev/null +++ b/.devcontainer/devcontainer.json @@ -0,0 +1,57 @@ +// For format details, see https://aka.ms/devcontainer.json. For config options, see the +// README at: https://github.com/devcontainers/templates/tree/main/src/docker-existing-docker-compose +{ + "name": "Existing Docker Compose (Extend)", + + // Update the 'dockerComposeFile' list if you have more compose files or use different names. + // The .devcontainer/docker-compose.yml file contains any overrides you need/want to make. + "dockerComposeFile": [ + "../docker-compose.yml", + "docker-compose.yml" + ], + + // The 'service' property is the name of the service for the container that VS Code should + // use. Update this value and .devcontainer/docker-compose.yml to the real service name. + "service": "maplestory", + + // The optional 'workspaceFolder' property is the path VS Code should open by default when + // connected. This is typically a file mount in .devcontainer/docker-compose.yml + "workspaceFolder": "/workspaces/${localWorkspaceFolderBasename}", + + // Features to add to the dev container. More info: https://containers.dev/features. + "features": { + "ghcr.io/devcontainers/features/common-utils:2": { + "installZsh": "true", + "username": "vscode", + "userUid": "1000", + "userGid": "1000", + "upgradePackages": "true" + } + }, + + // Use 'forwardPorts' to make a list of ports inside the container available locally. + // "forwardPorts": [], + + // Uncomment the next line if you want start specific services in your Docker Compose config. + // "runServices": [], + + // Uncomment the next line if you want to keep your containers running after VS Code shuts down. + // "shutdownAction": "none", + + // Uncomment the next line to run commands after the container is created. + // "postCreateCommand": "cat /etc/os-release", + + // Configure tool-specific properties. + "customizations": { + "vscode": { + "extensions": [ + "redhat.java", + "redhat.vscode-yaml", + "vscjava.vscode-maven" + ] + } + }, + + // Uncomment to connect as an existing user other than the container default. More info: https://aka.ms/dev-containers-non-root. + "remoteUser": "vscode" +} diff --git a/.devcontainer/docker-compose.yml b/.devcontainer/docker-compose.yml new file mode 100644 index 00000000000..baa730f9197 --- /dev/null +++ b/.devcontainer/docker-compose.yml @@ -0,0 +1,26 @@ +version: '3' +services: + # Update this to the name of the service you want to work with in your docker-compose.yml file + maplestory: + # Uncomment if you want to override the service's Dockerfile to one in the .devcontainer + # folder. Note that the path of the Dockerfile and context is relative to the *primary* + # docker-compose.yml file (the first in the devcontainer.json "dockerComposeFile" + # array). The sample below assumes your primary file is in the root of your project. + # + build: + context: . + target: dev + + volumes: + # Update this to wherever you want VS Code to mount the folder of your project + - ..:/workspaces:cached + + # Uncomment the next four lines if you will use a ptrace-based debugger like C++, Go, and Rust. + # cap_add: + # - SYS_PTRACE + # security_opt: + # - seccomp:unconfined + + # Overrides default command so things don't shut down after the process ends. + command: sleep infinity + diff --git a/Dockerfile b/Dockerfile index fb9ed611f68..c829c56bcb9 100644 --- a/Dockerfile +++ b/Dockerfile @@ -1,10 +1,12 @@ # Initial Docker support thanks to xinyifly # Optimisation performed by wejrox +FROM maven:3.9.14-amazoncorretto-21-al2023 AS dev + # # Cosmic JAR creation stage # -FROM maven:3.9.14-amazoncorretto-21-al2023 AS jar +FROM dev AS jar # Build in a separated location which won't have permissions issues. WORKDIR /opt/cosmic @@ -44,5 +46,3 @@ COPY config.yaml ./ # Format for channels: WWCC, where WW is 75 plus the world number and CC is 75 plus the channel number (both zero indexed). EXPOSE 8484 7575 7576 7577 ENTRYPOINT ["java", "-jar", "./Server.jar"] - - From bda46f1e448cab88f2dcb503c39d29a2bc0ef713 Mon Sep 17 00:00:00 2001 From: HarkuLi Date: Thu, 19 Mar 2026 15:37:10 +0800 Subject: [PATCH 3/4] README: Reorganize contents 1. Extract the part of Docker as an independent section (Quick start). 2. Getting started => Local setup. And make it focus on server part. 3. Extract the part of "Client" and "Getting into the game" as independent sections. --- README.md | 69 +++++++++++++++++++++++++++++++++++++++++++------------ 1 file changed, 54 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 366ab226247..2b841283a73 100644 --- a/README.md +++ b/README.md @@ -48,15 +48,57 @@ The project follows the [semantic versioning](https://semver.org/) scheme using * *General changes or improvements* are treated as MINOR: 1.__2__.3 -> 1.__3.0__ * *Major changes* are treated as MAJOR: __1__.2.3 -> __2.0.0__ -## Getting started -Follow along as I go through the steps to play the game on your local computer from start to finish. I won't go into extreme detail, so if you don't have prior experience with Java or git, you might struggle. +## Quick start + +### Prerequisite + +1. [Docker](https://www.docker.com) +2. [Docker Compose](https://docs.docker.com/compose/install) + +### Start services + +To start all services, run: + +```bash +docker compose up -d +``` + +Then you can use + +```bash +docker compose logs -f maplestory +``` + +to check the logs of Cosmic server. + +Once the server is ready, you will see a message like: + +```log +07:24:20.269 [main] INFO server.Server - Cosmic is now online after 14547 ms. +``` + +### Stop services + +```bash +docker compose down +``` + +### Rebuild + +You must rebuild images after any code changes: + +```bash +docker compose build +``` + +## Local setup +You can also run Cosmic on your actual machine. We will set up the following: - Database - the database is used by the server to store game data such as accounts, characters and inventory items. - Server - the server is the "brain" and routes network traffic between the clients. -- Client - the client is the application used to _play the game_, i.e. MapleStory.exe. -### 1 - Database +### 1 - Database You will start by installing the database server and database client. Then you will connect to the server with the client to create a new database schema. #### Steps @@ -88,11 +130,6 @@ You will start by cloning the repository, then configure the database properties Below, I list other ways of running the server which are completely optional. -#### Docker -Support for Docker is also provided out of the box, as an alternative to running straight in the IDE. If you have [Docker Desktop](https://www.docker.com/products/docker-desktop/) installed it's as easy as running `docker compose up`. - -Making changes becomes a bit more tedious though as you have to rebuild the server image via `docker compose up --build`. - #### Jar Another option is to start the server from a terminal by running a jar file. You first need to build the jar file from source which requires [Maven](https://maven.apache.org/). Fortunately, [Maven Wrapper](https://maven.apache.org/wrapper/) is provided so you don't have to install Maven separately. @@ -102,15 +139,17 @@ To run the jar, a ``launch.bat`` file is provided for convenience. Simply double Alternatively, run the jar file from the terminal. Just remember to provide the `wz-path` system property pointing to your wz directory. -### 3 - Client -The client files are located in a separate repository: https://github.com/P0nk/Cosmic-client +## Client +Client is the application used to _play the game_, i.e. MapleStory.exe. + +The files are located in a separate repository: https://github.com/P0nk/Cosmic-client Follow the installation guide in the README. -### 4 - Getting into the game -You have successfully started the client, and you're looking at the login screen. +## Getting into the game +You have successfully started the client, and you're looking at the login screen. -#### Logging in +### Logging in At this point, you can log in to the admin account using the following credentials: * Username: "admin" * Password: "admin" @@ -119,7 +158,7 @@ At this point, you can log in to the admin account using the following credentia You can also create a new regular account by typing in your desired username & password and attempting to log in. This "automatic registration" feature lets you create new accounts to play around with. It is enabled by default (see _config.yaml_). -#### Entering the game +### Entering the game Create a new character as you normally would, and then select it to enter the game. Hooray, finally we're in! If you log in to the "Admin" character, you'll notice that the character looks almost invisible. This is hide mode, which is enabled by default when you log in to a GM character. You won't be visible to normal players and no mobs will move if you're alone on the map. Toggle hide mode on or off by typing "@hide" in the in-game chat. From ba9c892fc6900c9442f02a89dcf0b1ff647572a0 Mon Sep 17 00:00:00 2001 From: HarkuLi Date: Sun, 12 Apr 2026 14:12:43 +0800 Subject: [PATCH 4/4] README: Add Dev Container --- README.md | 6 ++++++ 1 file changed, 6 insertions(+) diff --git a/README.md b/README.md index 2b841283a73..302b2f67ede 100644 --- a/README.md +++ b/README.md @@ -91,6 +91,12 @@ You must rebuild images after any code changes: docker compose build ``` +## Development + +This project provides [Dev Container](https://code.visualstudio.com/docs/devcontainers/containers) +that make setting up the development environment a breeze. +You can check the settings in the [.devcontainer](./.devcontainer) folder. + ## Local setup You can also run Cosmic on your actual machine.