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 — the recommended AstroDX import format. On Android, open or share it with AstroDX. On iOS, move it into the AstroDX folder itself, then reopen the game. No extraction is needed.
- .zip — a plain archive any system can open. Good when you want to sort things out on a computer first.
- .tar.gz — for command-line use or archiving. Renaming it to .adx does not make it importable; download the .adx format to import into the game.
Charts with a BGA include a background-animation video (pv.mp4). It changes the background only, never the judgement. Turn off “Include BGA video” to reduce the download size. If one chart is still large on a phone, omit the BGA or download it on a computer.
- Phones split bulk downloads into independent small batches. Keep the page open, wait for the current batch to finish packing, then select Save file for each archive.
- Check your browser's downloads to confirm every file in this batch has finished downloading. If a file is missing or needs another attempt, select Save again before confirming release.
- Select Files saved — continue downloading to release this batch's cache and start the next. For the final batch, select Confirm saved and release cache. Save and import each archive separately; the import instructions remain available after release.
After a page reload, downloaded data can be repacked only while its job and cache have not been removed. Releasing the cache removes Save again for that data. Once the whole selection is complete, use Recent downloads in the download tray to download it again. Until then, finish the remaining batches or select the charts again.
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.
- My phone's bulk download is waiting at the save step. Why doesn't the next batch start?
- It is waiting for you to confirm this batch was saved. Save every file, confirm they have finished downloading in your browser, then select Files saved — continue downloading. For the final batch, select Confirm saved and release cache. After release, Save again is unavailable. Once the whole selection is complete, use Recent downloads in the tray to download again; until then, finish the remaining batches or select the charts again. Keep the page open while downloading.
- Save was requested, but I cannot find the file, or it downloaded as .bin.
- Save requested means the browser received the request, not that the file is already on disk. Check the browser's downloads, then find the completed file in Files or your file manager. Before releasing the cache, select Save again. For an unexpected .bin, retry saving or download .zip and follow the import rename steps; do not simply rename .bin to .adx. After release, use Recent downloads in the tray once the whole selection is complete; until then, finish the remaining batches or select the charts again.
- The archive won't open, or reports corrupt files.
- Check your browser's downloads to confirm saving finished. Try Save again while the cache is still available; download again if the file is still corrupt or the cache was released. Do not extract .adx manually. Rename .zip to .adx or filename.adx.zip to import it. Renaming .tar.gz does not make it importable: download .adx for the game, or use a TAR.GZ-compatible tool to extract an archive.
- 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