- Python 76.1%
- HTML 20.1%
- CSS 3.8%
| Filename | Latest commit message | Latest commit date |
|---|---|---|
| conf | ||
| Configurations | ||
| Database | ||
| scripts | ||
| tracks | ||
| webui | ||
| .gitignore | ||
| app.py | ||
| config.py | ||
| events.py | ||
| music.py | ||
| pfx_to_pem.py | ||
| protocol.py | ||
| ranking.py | ||
| README.cs.md | ||
| README.md | ||
| requirements.txt | ||
| smoke_test.py | ||
| store.py | ||
| unlocks.py | ||
Anesthesia Vibeslop (Python / Flask)
Python implementation of a local server for Groove Coaster 4MAX / 4EX, designed to be protocol- and data-compatible with GC-local-server-rewrite (C#).
It includes game endpoint compatibility, live score rankings, unlock/keys management, a web account/profile system (with per-card profile modes and shared profiles across multiple cards), event support, and a CG-inspired Frutiger Aero web UI.
Highlights
- Unique config/runtime layout (not the C#
Configurations/-style folder structure as the primary system):conf/settings.json— single unified config (paths, server, game counts/rewards, ranking, unlock defaults, events, matching, auth, web accounts)saves/— runtime save data (card.db3, captures)tracks/— music databases (e.g.music474omni.db3)events/— event files served to the gamecerts/— TLS cert/key PEMswebui/— web UI templates/assets- Legacy import/fallback: if
conf/settings.jsonis missing, settings are imported once from legacyConfigurations/*.json(when present). LegacyDatabase/,data/, andwwwroot/events/are also used as fallbacks for existing files to ease migration.
- Accounts, profiles, and card linking (new system, CG-like concept)
- Web account registration/login (
/ui/login,/ui/register,/ui/account) - Multiple profiles per account, each customizable (name + custom fields like nickname/comment/favorites) and set to an unlock mode
- Two profile modes per card (toggle):
- Everything Unlocked — all content treated as available for linked cards
- Progressive — keys/coins/unlocks tracked progressively
- Multiple cards can link to the same profile (shared progressive state: unlock bitsets/coins/key progress are profile-scoped when linked)
- Cards can be linked/unlinked/claimed from the account page and toggled between your full/progressive profiles from the card page
- Unlinked cards follow the configurable default mode (
unlocks.default_modeinconf/settings.json)
- Web account registration/login (
- Score rankings (live, computed from card data): world/global, shop/tenpo, monthly (30 days), and play-number/hit charts (
4098,4119,6657,6661,6663,6664,6665,6666) with C#-compatible behavior; web views for World, Monthly, All-time, Daily (24h), Weekly (7d) - Unlocks/keys base: progressive unlock bitsets, coin storage, unlock rewards/key tracking (
ReadUnlockReward/ReadUnlockKeynum/WriteUnlockKeynum), unlock-all-music actions, key set/grant UI, auto-grant option - Events: C#-compatible
server/data.phpbehavior and event file serving from configured events directory (toggle/preview in UI) - Web UI: CG-inspired sidebar layout with a custom Frutiger Aero theme (not derived from the old server UI). Pages: Home, Cards, Card detail, Rankings, Unlocks & Keys, Events, Music DB, About, Account/Login/Register/Profile edit
- Migration tooling:
scripts/migrate_card_db.py(C# → canonical superset schema) andscripts/migrate_music_db.py(inspect/normalize; omnimix DBs likemusic474omni.db3are compatible)
Project layout
| Path | Purpose |
|---|---|
app.py |
Flask app: game routes, ranking, web UI, accounts/profiles, HTTP/HTTPS launcher |
config.py |
Unified config system (conf/settings.json) with legacy import/fallback |
store.py |
SQLite store (saves/card.db3): card data, C#-compatible tables, accounts/profiles/links, profile-scoped progression state |
unlocks.py |
Unlock modes/bitsets, coins, key rewards, profile-vs-card state resolution |
ranking.py |
Live ranking/hit-chart computation |
events.py |
Event distribution manager |
music.py |
Music DB loader + compatibility inspection |
protocol.py |
XML/wire helpers |
webui/ |
Templates and static assets |
scripts/ |
migrate_card_db.py, migrate_music_db.py |
conf/settings.json |
Primary configuration (created/imported on first run) |
saves/, tracks/, events/, certs/ |
Runtime data, music DBs, event files, TLS certs |
cg.htmlin the repo root (if present) is a confidential layout reference and is not used by the application.
Setup & run
pip install -r requirements.txt
# Optional: create TLS PEMs if you have a PFX bundle (see HTTPS/TLS notes below)
# python3 pfx_to_pem.py certs
# Run (needs privileges for :443/:80)
python3 app.py
# Unprivileged testing
GC_HTTP_PORT=8080 GC_HTTPS_PORT=8443 python3 app.py
- Web UI:
http://<host>/(and/ui/*) - HTTPS starts only if
certs/cert.pemandcerts/cert.keyexist conf/settings.jsoncontrols ports/paths/game settings; env varsGC_HTTP_PORT/GC_HTTPS_PORToverride ports- Request capture for development: files are written to
saves/captures/(gitignored).GC_CAPTURE=write(recommended): record only card write/register requests (/service/card/cardn.cgi, cmd 768/512). Each capture includes parsed metadata and the decoded game payload (.json+ raw.bin+.data.xml/.data.txt), which is ideal for implementing proper write handlers later.GC_CAPTURE=1(orall): record all HTTP requests.- Example:
GC_CAPTURE=write GC_HTTP_PORT=8080 GC_HTTPS_PORT=8443 python3 app.py - To share captures for analysis, zip
saves/captures/(note: captures may contain card IDs, MACs, names, and play/save data).
HTTPS / TLS and certify.php troubleshooting
The game contacts GET /server/certify.php over HTTPS (NESYS-style). If the client/cabinet log shows a request to Alive.txt succeeding but then errcode=12175 / WinHttpSendRequest() 0x00002F8F for access=certify.php, the TLS handshake or certificate validation failed.
-
Provide valid cert/key PEMs
- Place
cert.pemandcert.keyincerts/(HTTPS is not started without them). - To convert the bundled C# server PFX files (same certs used by GC-local-server-rewrite):
This writes# put cert.pfx and root.pfx in certs/, then: python3 pfx_to_pem.py certscerts/cert.pem,certs/cert.key, andcerts/root.pem. - Verify conversion and key/cert pairing:
python3 scripts/check_certs.py- The leaf cert should include NESYS SANs like
cert.nesys.jp,data.nesys.jp,proxy.nesys.jp,nesys.taito.co.jp,fjm170920zero.nesica.netand the private key must match.
- The leaf cert should include NESYS SANs like
- Place
-
Trust the root CA on the client/cabinet
- The server cert is issued by Taito Arcade Machine CA (
certs/root.pem). The client must trust this CA (e.g. importroot.pem/root.pfxinto the machine's trusted root store as done for the C# server). An untrusted chain commonly causes WinHTTP 12175.
- The server cert is issued by Taito Arcade Machine CA (
-
Hostname/DNS/hosts mapping
- Ensure the cabinet resolves the NESYS hostnames it connects to (e.g.
cert.nesys.jp,nesys.taito.co.jp,fjm170920zero.nesica.net) to this server's IP, and that the HTTPS port (default 443) is reachable.
- Ensure the cabinet resolves the NESYS hostnames it connects to (e.g.
-
Legacy TLS compatibility
- The server enables a permissive TLS configuration for legacy clients (TLS 1.0+ and relaxed cipher/security levels where supported by OpenSSL). On startup it logs certificate subject/SAN/fingerprint and HTTPS status.
- If handshakes still fail, confirm the client OS allows TLS 1.0/legacy ciphers (very old Windows images may have them disabled) and check server logs at the time of the
certify.phprequest.
certs/*.pem,certs/*.key, andcerts/*.pfxare gitignored; keep private keys/cert bundles out of commits.
Accounts & profiles
- Create an account in the web UI, then create/use profiles (default "Everything Unlocked" and "Progressive" are created for convenience).
- Link one or more game cards to a profile; cards linked to the same profile share progressive state (unlocks/coins/keys). Toggle a card between your full/progressive profiles from the card page or reassign on the account page.
- Unlinked cards use
unlocks.default_modefromconf/settings.json.
Card DB migration
scripts/migrate_card_db.py migrates/normalizes card DBs (including C# GC-local-server-rewrite DBs) into this server's canonical superset schema (core card tables, C# naming/timestamp normalization, unlock/coin/shop/key tables preserved when present, plus tables required by this server).
python3 scripts/migrate_card_db.py --src /path/to/card.db3 --dst saves/card.db3
python3 scripts/migrate_card_db.py --src /path/to/card.db3 --in-place
Music DB compatibility
Omnimix and standard music DBs from GC-local-server-rewrite (e.g. music474omni.db3) are compatible. Required tables: music_unlock, music_extra, music_aou with core columns; optional columns like calc_flag/RecordId are tolerated.
python3 scripts/migrate_music_db.py --src tracks/music474omni.db3
python3 scripts/migrate_music_db.py --src /path/to/music.db3 --dst tracks/music.db3 --add-calc-flag
Events
Configure events in conf/settings.json (events.enabled, events.files[{file,index}]) or via the Events page. Place files in events/. GET /server/data.php follows C#-compatible behavior (count/nexttime, per-file URL/not_before/not_after/md5/index with index rules).
Properly implementing unlocking, item count tracking, and coins (status & what’s needed)
The server provides a working base (modes/toggles, profile-scoped progressive bitsets and coin storage, key progress read/write/persist/grant hooks, unlock-all-music, UI management, and C#-compatible reads for unlock state/coins/rewards in many paths) but full fidelity requires deeper, protocol-accurate persistence and state transitions:
- Per-item ownership/count state (not just bitsets)
- Store per (profile/card, item_type, item_id): owned/unlocked,
item_num/quantity (for consumable "Item" types),use_flag/equipped,new_flag, timestamps. A scaffold table (profile_item_state) exists, but reads/writes must be wired to it. - Update card read handlers (
avatar/item/skin/title/navigator/sound_effect, etc.) to return the actual stored per-item records/counts (todayitem_num/flags are largely synthesized) matching the client’s expected schema.
- Store per (profile/card, item_type, item_id): owned/unlocked,
- Persist game write requests
- Implement handlers for currently no-op write types (e.g. avatar/item/skin/title/navigator/music/sound_effect/coin/unlock/cond) by parsing the
<data>payloads and applying deltas/sets to stored state. This requires confirming exact per-type field schemas from captures/protocol behavior.
- Implement handlers for currently no-op write types (e.g. avatar/item/skin/title/navigator/music/sound_effect/coin/unlock/cond) by parsing the
- Coins (current/total/monthly) correctness
- Apply coin deltas from gameplay writes, purchases, and reward grants atomically in the correct scope (profile when linked, card otherwise); handle monthly/period resets if the client/protocol expects them; keep read values consistent with writes.
- Key/unlock rewards semantics
- Persist full
unlock_keynumfields as reported/required (reward_count, flags), increment keys according to the actual game-reported events/rules, and grant rewards idempotently with correct side effects (unlock item/song/avatar/navigator or add coins) exactly once per reward, respecting mode/profile scope.
- Persist full
- Song/content unlock details
- Beyond the music unlock bitset and global
use_flag, maintain per-song/card progress rows the game expects (e.g.card_detailpcol1=10 reward/unlock rows, play flags) consistently with unlock/reward actions and gameplay writes.
- Beyond the music unlock bitset and global
- Shop/purchases (if used)
- Validate catalog/shop items, check/unlock ownership, deduct coins, and record purchases transactionally.
- Catalog/config accuracy & migration
- Ensure item/avatar/title/etc counts and unlock reward definitions match the client version; backfill/migrate existing card/profile state from legacy/C# data; keep behavior consistent with captured protocol expectations.
In short: the framework, storage, mode/profile model, and key/coin/unlock plumbing are in place; "proper" completion means replacing synthesized reads and no-op writes with protocol-accurate, fully persisted per-entity state transitions and economy/reward logic, validated against real client traffic.
Notes / limitations
- Online matching/relay is not implemented.
- HTTPS requires compatible PEM certs in
certs/. - Full unlock/item-count/coin fidelity depends on implementing the per-type read/write persistence described above against the game protocol.