repository·v1-dev·Indexed 20 days ago
https://github.com/mewolab/aquadxA multipurpose server providing backend infrastructure for ALL.Net rhythm games, including CHUNITHM, maimai DX, and O.N.G.E.K.I. The project includes AquaNet, a web frontend, and supports features such as web interfaces, data importing, and AES encryption. Documentation covers self-hosting, environment configuration for AquaNet (Vite), SQL migration conventions, and API structures for Maimai user data and playlogs.
AquaDX is a multipurpose game server designed for ALL.Net games. It provides backend services for various rhythm games, supporting features like web interfaces, data importing, and AES encryption.
Key related projects include:
Kaleidx Scope gate visibility is determined by the intersection of three server API responses. A gate is only visible and selectable in the game menu if it meets specific criteria across these endpoints:
GetGameEventApi: Must return open event rows for the gate/course event IDs used by the game's static data.GetGameKaleidxScopeApi: Must return a gameKaleidxScopeList row for each gate the user can see. Known gate IDs include:1..6: Original gates7: Prism/Center Tower8: Post-Prism boss gate9: Hope Gate10: Final challengeGetUserKaleidxScopeApi: Must return a userKaleidxScopeList row for the same gateId.Visibility Requirements:
The client hides a gate if the user row is missing, the event is closed, or the row has isGateFound = false. To be visible and selectable, a gate requires a JSON object state similar to this:
{
"gateId": 8,
"isGateFound": true,
"isKeyFound": true,
"isClear": false
}Progression Logic:
For progression past Prism Tower, UpsertUserAllApi must persist upsertUserAll.userKaleidxScopeList by (userId, gateId). AquaDX automatically unlocks gate 7 after gate 6 is cleared. After gate 7 is cleared, the next GetUserKaleidxScopeApi response must include gate 7 as clear and a gate 8 row with both isGateFound and isKeyFound set to true.
AquaDX is licensed under the CC By-NC-SA (Creative Commons Attribution-NonCommercial-ShareAlike) license.
Key restrictions:
When entering matching mode, the game assigns you to a matching room (or creates a new one). Once 4 players are present or a timer expires, the game starts. If fewer than 4 players are present, the empty slots are filled with bots (which typically select songs under Lv10).
To use games with the AquaDX server, keep the following in mind:
Once your aqua.sql file is prepared, import it into your MariaDB instance.
After the import, you must run a specific SQL query to fix a Flyway checksum. Aqua uses Flyway for schema migrations, and one migration has a case-sensitivity difference between MySQL and MariaDB that will cause a checksum mismatch if not corrected.
# 1. Login to MariaDB
mysql --user={username} --password={password} --host={host} --port={port} {database}
# 2. Import the data (inside the mysql prompt)
source aqua.sql;
# 3. Fix the Flyway checksum (inside the mysql prompt)
UPDATE main.flyway_schema_history t
SET t.checksum = 357127209
WHERE t.installed_rank = 144;To update your self-hosted instance, follow these steps in the AquaDX folder to ensure data safety and version synchronization:
mariadb-dump via Docker to create a backup.sql file.docker compose pull to fetch the latest images.docker compose up to restart the services with the new images.# Backup your database
docker run --rm -it mariadb:latest mariadb-dump -h host.docker.internal --port 3369 --user=cat --password=meow main > backup.sql
# Pull the new repository
docker compose pull
# Run the updated version
docker compose upTo use the hosted public instance at aquadx.net, follow these steps:
Tip: You can identify your card's access code on the title screen of all supported games by pressing the "access code" button and scanning your card.
Chunithm (Chusan) support requires no specific patches. If you are using the public instance and do not have encryption keys set for your game version, no encryption or TLS is required.
Key Behaviors:
When adding new SQL migrations to the database, follow a specific naming convention and folder structure to ensure they are processed correctly and remain easy to navigate.
Files must follow the pattern: V1000_{version}__{description}.sql
{version}: A sequential ID. Always pick the next available number in the sequence.{description}: A short, descriptive text of the change.To prevent long file lists, migrations are grouped into folders containing 40 changes each. Place your file in the folder corresponding to its version number:
db/40: Versions 1-40db/80: Versions 41-80# Example naming and placement:
# For version 42 with description 'add_users_table':
# Path: db/80/V1000_42__add_users_table.sqlIf you are hosting AquaDX behind a reverse proxy, follow these guidelines to ensure connectivity:
TLS_RSA_* ciphers and use a self-signed ib.naominet.jp TLS certificate, or simply disable the billing endpoint.allnet.server.host property in application.properties to your public IP or hostname.80, 8443, 22345).If you do not want to turn off your firewall entirely, you can add specific inbound and outbound rules for chusanApp.exe.
Create a .bat file with the following content, ensuring you run it as an Administrator and provide the correct path to your game executable (e.g., C:\SegaGames\Chunithm\bin\chusanApp.exe).
@echo off
set /p gamedirectory = Make sure this is run as admin and enter game path (e.g. C:\SegaGames\Chunithm\bin\chusanApp.exe)
netsh advfirewall firewall add rule name="Chunithm National Matching Inbound" dir=in action=allow profile=any program="%gamedirectory%" enable=yes
netsh advfirewall firewall add rule name="Chunithm National Matching Outbound" dir=out action=allow profile=any program="%gamedirectory%" enable=yes