Sync
Use your own cloud drive or home NAS to sync play time, beaten records, bookmarks, scraped art and game saves between devices, and pick up where you left off on another handheld.
Tea can keep your game profile and saves on your own cloud drive (天翼云盘 (Tianyi Cloud), 百度网盘 (Baidu Netdisk), 夸克网盘 (Quark Drive) or a home NAS), shared by several handhelds (and the Steam Deck). It only uses your own drive space and goes through no third-party server.
#What syncs
| Kind | Contents |
|---|---|
| Game records | Play time (added up across devices), beaten records |
| Game profile | Bookmarks, renames, the edition line and description edited in game info, scrape names, custom labels and custom covers (images included), cartridge looks, the arcade cabinet's landscape/portrait choice, cheat choices, custom launch commands |
| Scraped art | Covers, game info, ScreenScraper labels, arcade cabinet images; other devices don't need to scrape again |
| Game saves | In-game saves and quick saves; see Game save sync below |
Settings don't sync: language, theme, UI scale, button layout, video and sound stay on each device.
#Setting up the sync drive
- Open Settings → General → Sync drive.
- Pick one of the four drives:
- Tianyi Cloud, Baidu Netdisk, Quark Drive: tap Log in and scan with the phone app to confirm.
- Home NAS: tap Connect, pick or type the NAS address, fill in the user name and password, then choose a shared folder in Sync into. Step by step: Cloud drive and downloads.
- A drive already logged in as a library drive shows Use on its card; tap it, no second login needed.
- Once you're logged in, the Sync switch beside the group title is on by default and Tea starts the first sync right away.
- On another device, log in to the same drive with the same account, and the two sync on their own.
Sync data lives in the Freedeck Sync folder at the top of your drive (on a NAS, inside the shared folder you chose). Please don't delete, move or rename this folder.
Tip The sync drive and the library drive can be the same or different, for example Tianyi Cloud for sync and the NAS for games.
#Sync switch and status
Once the sync drive is logged in, Settings → General → Sync drive shows only that drive's card:
- Left: the drive name, account and sync status.
- Right: Sync now (it shimmers while syncing, then shows "Sync complete" or why it failed), with Log out below it (asks first).
- Beside the group title: the Sync switch. Turned off, game records, profile and saves all stop syncing.
The status line can show:
| Status | Meaning |
|---|---|
| Synced · 2 min ago | All good |
| Synced · 2 min ago · syncing labels 3/20 | Records are synced; label images are still uploading |
| Syncing… | Syncing now |
| Waiting to sync · no network | Can't reach the drive; changes are kept and catch up once you're online |
| Login expired — log in again | Tap it to scan and log in again |
| Sync is off | The Sync switch is off |
| Other red text | Why sync went wrong; tap Sync now to try again |
#When it syncs
Nothing to do by hand; Tea syncs on its own:
- When you open Tea.
- When you come back to Tea after playing.
- About 20 seconds after a change such as a bookmark, beaten mark or rename.
- When Tea goes to the background (only if there are changes not yet uploaded).
- While Tea is in front, every 2 minutes it checks for new changes from other devices; coming back after more than a minute away also checks right away.
Tea doesn't sync in the background once closed.
To sync right now, tap Sync now, or tap the little cloud in the side menu.
#Where to see sync status
#The little cloud in the side menu
A little cloud sits to the right of the "Settings" item in the side menu:
| Icon | Meaning |
|---|---|
| Cloud with ✓ | Synced |
| Cloud with a spinning arrow | Syncing |
| Cloud with ! | Sync error or expired login |
| Plain cloud | No network, waiting to sync |
Tap the cloud to sync right away. With a controller, press → on the "Settings" item to reach the cloud, then press A. The bottom navigation bar in portrait has no cloud.
#Cloud marks on games
Games with game records get a small extra mark after marks such as bookmark and beaten (in grid, list, carousel and on the game page):
| Mark | Meaning |
|---|---|
| Spinning sync icon | This game has changes waiting to upload |
| Cloud | Uploaded |
| Cloud with ! | Changes didn't upload; the last sync failed |
#Library messages
- When records from other devices arrive from the drive, the bottom of the library shows "Synced records of N games from your drive".
- When the drive's login expires, it shows "Your drive's login has expired"; tap Log in again.
The "Played" time on the game page includes time played on every device.
#Game save sync
Saves use the same Sync switch as game records; nothing else to set up. Save on one device, open the same game on another and carry on.
#Supported emulators
| Platform | Emulators |
|---|---|
| Multi-platform | RetroArch, RetroArch G (all cores) |
| GBA | My Boy! |
| NDS | melonDS, WatermelonDS, DraStic |
| 3DS | AzaharPlus, Citra MMJ, Pegasus pack Citra |
| N64 | M64Plus FZ / Pro |
| GameCube / Wii | Dolphin, Dolphin MMJR |
| Wii U | Cemu (and RetroArch's Cemu core) |
| Switch | Eden, Eden Nightly, Lemon and Eden's forks |
| PS1 | DuckStation |
| PS2 | ARMSX2, NetherSX2 |
| PSP | PPSSPP |
| PS Vita | Vita3K, Vita3K+ (and RetroArch's Vita3K core) |
| Dreamcast | Flycast (new version) |
#Which saves sync
- In-game saves: saves made inside the game, at save points, save crystals and the like.
- Quick saves: RetroArch syncs only the auto quick save and slot 0; other slots stay on the device. Standalone emulators follow their own rules (3DS, for example, syncs only slot 00).
- Saves are kept apart by emulator → core → game, so switching cores never overwrites anything.
- Between RetroArch and RetroArch G (the kind that comes with the handheld), in-game saves are shared; quick saves are kept separately, because different versions can't read each other's.
- PS2: NetherSX2, ARMSX2 and PCSX2 on the Steam Deck share the same latest save.
- Switch: Eden and Lemon share saves, so you can switch emulators and carry on.
- Older RetroArch can't read quick saves from newer RetroArch; Tea converts them while downloading to a format your device can read.
#The right way to play
- Open the game page: Tea fetches newer saves from the drive in the background. The game page shows "Syncing saves…", then "Saves synced · N min ago" when done.
- Press Play: the game starts right away, no waiting.
- Quit the emulator properly: with the floating button's Save+quit or Quit, or the emulator's own quit.
- Come back to Tea: this session's saves upload on their own.
Before switching to another device, come back to Tea on this one and let the saves upload.
Note If you leave with Home or swipe the emulator away in recent apps, the saves may never be written to file, and nothing uploads. RetroArch only writes in-game saves to file when you quit the game properly; the floating button's Quit keeps only in-game saves, so use Save+quit to keep your quick save.
Tip If you start a game before the saves finish downloading (offline, say), that session uses the device's own saves. Back in Tea, the newer saves on the drive and the newer saves on the device become a "conflict" and you choose which to keep; nothing is quietly overwritten.
#First-time setup: "Save sync" in Utility
Many standalone emulators keep saves where Tea can't read them, so they need setting up once. Open Utility: each emulator card has a Save sync row; follow its steps: Allow → Log in to your sync drive → Save sync is ready.
| Emulator | What to do |
|---|---|
| Dolphin, Eden / Lemon, Cemu, My Boy! | Tap Allow on the card, then "Use this folder" on the page that opens (only once) |
| DuckStation, NetherSX2 | Tap Allow and choose its Android/data folder. This usually works on Android 13 and earlier; newer systems may not allow it, and then saves can't sync |
| DuckStation | In its Settings › Memory Cards, set card 1's type to one card per game (by serial) |
| NetherSX2 | In Memory Cards settings, turn on per-game memory cards |
| ARMSX2 | Set the data folder to a custom folder (any folder in internal storage); for each game, make a memory card named after the game's serial (such as SLUS-21065) in Slot 1; the game page tells you the name to use |
| melonDS / WatermelonDS | Turn on saving next to the ROM; or pick the same folder as in the emulator's settings in the card's save folder |
| M64Plus FZ / Pro | In Settings › Data, set the game data storage location to external storage and pick a folder in internal storage |
| Flycast | On first start, choose a main folder in internal storage (such as internal storage/Flycast), or tap Allow. Old Flycast has no per-game memory cards and can't sync; install the new version from Utility |
| DraStic | When it asks for a folder, choose internal storage › DraStic |
| Vita3K | Choose the game storage folder on the card |
While a step is still missing, a yellow line appears under the emulator choice on the game page; follow it to finish. Tap Got it to stop it from showing again. If you've played for more than 10 minutes and the saves haven't changed at all, Tea also reminds you to check the setup.
#Save status on the game page
After "Played" at the top of the game page, you'll see:
| Shown | Meaning |
|---|---|
| Syncing saves… | Downloading or uploading |
| Waiting to sync saves | In the queue |
| Saves synced · N min ago | Synced; tap "Saves synced" to open the save history |
| Saves changed on two devices — pick one to keep | A conflict; see below |
| Quick save over N MB, not synced | The file is too big and didn't sync |
#Handling conflicts
Game records and profile merge on their own, nothing for you to do:
- Play time: added up across devices.
- Beaten: the later record wins.
- Bookmarks, renames, labels and so on: for each game, the most recent change wins. On the first sync, both devices' bookmarks are combined.
Saves are never quietly overwritten. If only one side changed, the newer one is used. If both devices changed (say, both played offline), the game page shows the conflict in yellow; tap it and choose in "Pick the saves to keep":
- Keep this device's: this device's saves upload at the next sync.
- Use the other device's: swapped for the other device's saves before the next start.
A copy of each replaced save file is kept with the .freedeck-bak suffix (only the most recent one).
#Save history
Tap "Saves synced" on the game page, or Save history in the game page's ⋯ menu, to see the last 3 uploads: time, device and emulator version, with the latest marked "Newest". Tap Pick to switch back to that one; your current saves are kept as .freedeck-bak.
#Upload local saves
Upload local saves in the game page's ⋯ menu: once you confirm, this device's saves upload as the latest, even if they're older than the ones on the drive. The drive's previous copy can still be found in the save history. Sync is normally automatic, so you'll rarely need this.
While saves are syncing, these two items are greyed out for a moment; they come back once sync finishes.
#Limits
- A single save file can be up to 64 MB; bigger ones don't sync, and the game page tells you.
- Free Baidu Netdisk and Quark Drive accounts upload label images one at a time, so a first sync with lots of labels is slower; members upload two at once.
- Labels newly scraped on another device may take up to 10 minutes to arrive.
- Tea never deletes sync data from your drive; the
Freedeck Syncfolder slowly grows, but it's all small files. - A home NAS only syncs on your home network; when you're out it shows "Waiting to sync · no network" and catches up once you're home.
- Sync needs Tea running: once Tea is closed, nothing syncs in the background.
#Changing the sync drive
Note Sync data lives in the sync drive. Switching to another sync drive means starting over: records and saves on the old drive don't move across, and the new drive only has this device's data. Your other devices must switch to the same drive too, or each side syncs on its own and the data splits apart. Try to stick with one sync drive.
If you really need to switch:
- In Settings → General → Sync drive, tap Log out (if it's also a library drive, the account stays logged in and just stops syncing).
- Log in to the new drive.
- Switch every device to this new drive, with the same account.
#Steam Deck
The Steam Deck version shares the same sync drive with Android handhelds: game records, profile and in-game saves all carry across. Quick saves stay separate on each side, because the emulators on the Deck differ from the Android ones and can't read each other's. See Steam Deck.
