How lost-msth/arcaea-server works
Purpose and Runtime
Arcaea-server is a Python/Flask local server that emulates major Arcaea game backend functions: accounts, progression, scores/rankings, purchases, content delivery, cloud saves, and multiplayer. The primary HTTP application entry point is latest version/main.py; Link Play runs as a separate UDP-oriented process via latest version/run_linkplay_server.py and latest version/linkplay_server/main.py.
HTTP API Surface
Game-client endpoints are divided by domain under latest version/api/, including authentication, tokens, users, scores/songs, purchases, presents, redeems, and multiplayer:
• latest version/api/api_auth.py
• latest version/api/users.py
• latest version/api/songs.py
These handlers are the protocol boundary: they parse client requests, apply authentication/rate-limit/error conventions, and delegate game behavior to core.
Domain-Service Layer
latest version/core/ is the business and persistence orchestration layer. It implements player state and game systems rather than exposing routes directly:
• Identity, authentication, and account state: latest version/core/user.py, latest version/core/api_user.py
• Scores, rankings, and potential calculations: latest version/core/score.py, latest version/core/rank.py
• Progression systems: latest version/core/world.py, latest version/core/mission.py, latest version/core/course.py
• Entitlements/content systems: latest version/core/purchase.py, latest version/core/present.py, latest version/core/redeem.py
API requests generally flow API module → core domain operation → SQL/data files → serialized game response.
Persistence and Initialization
SQLite-oriented persistence is centralized behind latest version/core/sql.py, while save serialization and initialization are handled by:
• latest version/core/save.py
• latest version/core/init.py
• latest version/database/database_initialize.py
Schema and baseline game data live in latest version/database/init/tables.sql, latest version/database/init/arc_data.py, and JSON datasets such as latest version/database/init/courses.json. This is a critical boundary: operational user data must be preserved across version updates, while schemas/static catalog data can be refreshed.
Static Game Catalog and Bundles
Game metadata and progression content are file-backed. World maps are JSON resources in latest version/database/map/; song/chart assets are expected under latest version/database/songs/. Bundle acquisition and delivery are represented by:
• latest version/core/bundle.py
• latest version/core/download.py
• latest version/database/bundle/README.md
The server can advertise or serve content updates, but the repository explicitly relies on external song/database sources and no longer distributes full song data.
Link Play / Multiplayer Boundary
Normal multiplayer API behavior is represented in latest version/api/multiplay.py and latest version/core/linkplay.py. Real-time Link Play is separately implemented as a UDP service with encryption, parsing, room/state storage, and outbound packet handling:
• latest version/linkplay_server/main.py
• latest version/linkplay_server/udp_parser.py
• latest version/linkplay_server/store.py
This service depends on Cryptography and should be deployed/configured alongside, but independently from, Flask.
Administration and Operations
A legacy server-rendered admin interface is separate from game APIs, with routes in latest version/web/ and Jinja templates in latest version/templates/web/; its main purpose is inspecting/modifying users, scores, catalog items, purchases, presents, and database state. Cross-cutting operational controls include configuration, background tasks, logging, and request throttling:
• latest version/core/config_manager.py
• latest version/core/bgtask.py
• latest version/core/limiter.py
Material runtime dependencies are Python 3.6+, Flask, Cryptography, and limits, declared in latest version/requirements.txt.
Main entry points: main.py Flask entry point · save.py Save lifecycle · api_auth.py Game API modules · songs.py Songs & scores API
Components 18
HTTP Server
- Flask entry point · Primary game-client HTTP runtime.
latest version/main.py - Game API modules · Authenticated client protocol endpoints.
latest version/api/api_auth.py - Users API
latest version/api/users.py - Songs & scores API
latest version/api/songs.py - Multiplayer API
latest version/api/multiplay.py
Game Core
- Account & player state · Identity, authentication, and account state operations.
latest version/core/user.py - Scores & progression · Rankings, potential, world, mission, and course systems.
latest version/core/score.py - Purchases & rewards · Purchase, present, and redeem operations.
latest version/core/purchase.py - Save lifecycle · Initializes and serializes player saves.
latest version/core/save.py - SQLite access · Central SQL-oriented persistence boundary.
latest version/core/sql.py - Bundles & downloads · Advertises and delivers content updates.
latest version/core/download.py
Data & Content
- User database · Operational player data preserved across updates.
latest version/database/database_initialize.py - Schema & seed data · Refreshable schema and baseline game data.
latest version/database/init/tables.sql - Maps, songs & bundles · Maps and external song assets; full song data is not distributed.
Link Play
- UDP Link Play runtime · Independent real-time multiplayer process.
latest version/run_linkplay_server.py - Encrypted packet handling · Parses packets and maintains room state.
latest version/linkplay_server/udp_parser.py
Operations
- Admin web interface · Legacy inspection and modification interface.
- Runtime controls · Configuration, background tasks, logging, and rate limiting.
latest version/core/config_manager.py
Connections 21
- Flask entry point → Game API modules: serves
- Flask entry point → Users API: serves
- Flask entry point → Songs & scores API: serves
- Flask entry point → Multiplayer API: serves
- Flask entry point → Runtime controls: uses
- Game API modules → Account & player state: auth & accounts
- Users API → Account & player state: player operations
- Songs & scores API → Scores & progression: scores & progression
- Game API modules → Purchases & rewards: commerce & rewards
- Account & player state → Save lifecycle: loads and saves
- Scores & progression → Save lifecycle: updates state
- Purchases & rewards → Save lifecycle: grants state
- Save lifecycle → SQLite access: persists through
- SQLite access → User database: reads and writes
- User database → Schema & seed data: initialized from
- Songs & scores API → Bundles & downloads: content delivery
- Bundles & downloads → Maps, songs & bundles: serves catalog assets
- Multiplayer API → Encrypted packet handling: multiplayer state
- UDP Link Play runtime → Encrypted packet handling: runs
- Admin web interface → SQLite access: inspects and modifies
- Admin web interface → Runtime controls: uses