Tea 中文

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

  1. Open Settings → General → Sync drive.
  2. 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.
  3. Once you're logged in, the Sync switch beside the group title is on by default and Tea starts the first sync right away.
  4. 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:

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:

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

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

The right way to play

  1. 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.
  2. Press Play: the game starts right away, no waiting.
  3. Quit the emulator properly: with the floating button's Save+quit or Quit, or the emulator's own quit.
  4. 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:

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":

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

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:

  1. In Settings → General → Sync drive, tap Log out (if it's also a library drive, the account stays logged in and just stops syncing).
  2. Log in to the new drive.
  3. 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.