Installing AstroDX
AstroDX is a community-built maimai-style simulator. This archive only hosts charts — it does not distribute the app itself. The two platforms get it from different places, so follow the one that matches your device.
- iOS / iPadOS: install AstroDX straight from the App Store — that is the stable release the project recommends. (Older guides describing TestFlight or a sideloaded IPA are out of date.)
- Android: download the latest APK from GitHub Releases. Android will ask you to allow installs from unknown sources, which you have to grant by hand.
Launch the game once before importing anything. AstroDX sets up its own folders on that first run, and skipping it leaves the charts you import with nowhere to go. An empty song list on that first launch is expected.
- App Store — iOS / iPadOS stable release (recommended)
- GitHub Releases — latest Android APK
- AstroDX Wiki — the official docs this page follows
Finding and downloading charts here
The catalog searches titles, artists and community aliases (romaji works too), and filters by version, genre, level, BPM and which assets a chart ships. Open a chart's page to download it.
The menu next to the download button picks the archive format. All three contain the same files — only the container differs:
- .adx — AstroDX's own import format. Tap it on your phone and it imports straight away; prefer this one.
- .zip — a plain archive any system can open. Good when you want to sort things out on a computer first.
- .tar.gz — also a plain archive, usually a bit smaller. Handy on the command line or for bulk storage.
Charts that ship a BGA include an extra background-animation video (pv.mp4). It only changes what plays behind the notes — never the judgement — but it is often several times the size of the chart itself, so batch downloads let you turn “include background video” off to save bandwidth.
Several download mirrors are available. If the current one is slow, switch the default mirror in the settings panel or pick another one for a single download.
Importing charts
What AstroDX installs is an .adx file — really just a zip with the song folder inside it and the extension changed. The .adx you download here is already packaged, so use it as-is. If you ever have a plain .zip, renaming it to .adx is the whole job (and where the extension can't be changed, "name.adx.zip" works too).
- iOS / iPadOS: open the Files app and move the .adx into the AstroDX folder — the one marked with the app's icon. Into that folder itself, not the levels or collections folders inside it.
- Android: tap the .adx in your file browser and pick AstroDX from the "open with" menu. If AstroDX isn't listed, long-press the file, choose Share, and pick AstroDX there.
- Downloading on a desktop: no need to extract anything — move the .adx to the phone as-is. AirDrop on a Mac; LocalSend (what the wiki recommends), a cable or cloud storage on Windows and Linux. Then follow your platform's step above.
Open AstroDX and a progress bar appears; once it finishes, the new charts are in song select. On iOS the game sorts them out the next time you launch it, on Android it starts as soon as you hand the file over.
The levels and collections folders inside AstroDX belong to the game: levels holds the chart files, collections holds one manifest.json per collection. Editing a collection by hand is documented on the wiki, but ordinary imports never need to touch either.
- Video walkthrough · importing charts — screen recording on Bilibili, narrated in Chinese
- Wiki · iOS / iPadOS import guide — the official step-by-step
- Wiki · Android import guide — includes a video walkthrough
Troubleshooting
- The download stalls or crawls. What now?
- That usually means the current mirror routes badly to your network. Open the settings panel, re-measure latency under Downloads, switch to a faster mirror and restart the job. Interrupted jobs can be retried from the download tray; files that already finished are not fetched again.
- The archive won't open, or reports corrupt files.
- First check that the download actually finished — a truncated file cannot be extracted, so delete it and fetch it again. iOS's built-in extractor handles some .tar.gz archives poorly; download the .zip instead, or use a tool that supports the format.
- The chart doesn't show up in AstroDX after importing.
- Almost always because the archive was dropped into the levels folder — the wiki lists that specifically as a known mistake. Put the .adx in the AstroDX folder itself (iOS) or hand it to the app via open-with / share (Android) and let the game unpack it. Also make sure you launched the game once after installing it, or its folders don't exist yet; if it still doesn't appear, restart the app.
- My Android file manager has no “open with” or “share”.
- Use a different file manager — the wiki suggests ZArchiver or Android SAF. Relatedly, an “IOException: Permission denied” usually means a file manager with elevated permissions rewrote the chart files so AstroDX can no longer read them; re-importing the normal way clears it up.
- iOS won't let me change the file extension.
- In the Files app open the more menu (the three dots) → View Options and turn on “Show All Filename Extensions”, then long-press the file to rename it. If that still isn't possible, name it “something.adx.zip” — AstroDX accepts that too.
- There's no audio, or the cover is blank.
- The song folder is missing track.mp3 or bg.png. Some upstream charts genuinely ship without audio or cover art, and the badges at the top of the chart page say so. If the page claims they exist but your copy lacks them, download the archive again.
Still stuck? Tell us the chart name and what you're seeing:
- GitHub Issues — problems with this site
- AstroDX app issues — bugs in the game itself belong upstream
- QQ Group — the main group for players in China
- Telegram Group — international players and site news