Tea 中文

FAQ

Fixes for common problems — games not showing, wrong covers, emulators, downloads and extraction, sync, AI features and updates.

Installing and permissions

Installing says "installing apps from unknown sources is blocked"?

That's Android's security prompt. Follow it into system settings, allow the file manager you're opening the APK with to "install unknown apps", then go back and continue installing. Tea needs Android 10 or newer.

Do I have to grant "all files access"?

Yes. Tea needs it to read your ROMs, to choose folders like Download, and to save covers to the Freedeck folder. Without it, Settings → General shows "File access: not granted". Tap Grant access, turn on Tea's switch on the system page, then go back.

Choosing a folder says "Can't use this folder"?

Android's system folder picker won't let you choose Download or the root of storage, and on some handhelds it can't even open internal storage. Grant all files access first, then tap Choose folder in Settings: Tea uses its own folder browser, which can choose any folder.

Are my settings and covers still there after reinstalling Tea?

Yes. Bookmarks, renames, scrape results, covers and labels are all saved in the Freedeck folder, and uninstalling doesn't delete it. After reinstalling, grant all files access and a Freedeck folder in the default place is found automatically; if you keep it somewhere else, tap Change during first-time setup and choose it again.

Cloud drive logins, AI verification and download history aren't in the Freedeck folder, so you'll need to log in and verify again.

Library

My games don't show up in the library?

Check these in order:

  1. Folder location: games go in the ROM folder for their console. Name folders the ES-DE way (like gba, psx, snes, nes, megadrive, n3ds), or set a folder for that console in Settings → Emulator games → ROM folder per console.
  2. A different folder: if some games for a console are in another folder (a collection of hacks, for example), use Add custom tab to add it as a tab.
  3. Rescan: the library rescans automatically when you open it or come back to it; you can also pull down on the library to refresh.
  4. Files hidden on purpose: BIOS files, Switch and PS Vita updates / patches / DLC, the other discs of multi-disc games and .cue audio tracks aren't listed as games of their own.

Several games in one folder turned into a single "collection"?

That's normal: a folder holding several games (like fc/热血系列/) shows up as one collection, and each game inside can be launched on its own. Multi-disc games (CD1 / CD2, discs listed in an .m3u) are merged into one game. See Library.

Game names show as English abbreviations or odd names?

Turn on Settings → Emulator games → Use local game names: names come first from 天马 (Pegasus) or ES-DE game lists, then from Chinese arcade names, then from the ROM file name. You can also rename a game yourself with ✎ Edit game info on its page.

The interface is too small or too big?

Adjust UI scale under Settings → Interface → Scale; the size of cartridges in the carousel has its own Cartridge size setting. Set how many games per row in the grid with Grid columns.

A and B are swapped?

In Settings → General → Button layout, choose by the letters printed on your controller: if A is on the right, choose Nintendo; if A is at the bottom, choose Xbox. If your handheld's system already has "swap A/B" turned on, choose Xbox.

Covers and labels

The cover is wrong, or it matched the wrong game?

On the game's page:

See Covers and labels.

Lots of games still have no cover?

Covers are scraped one game at a time in the background, so the first round takes a while when you have many games. Also:

I have both Coffee and Tea installed — why can't I change covers in Coffee?

Both editions share the covers and labels in the Freedeck folder. To keep them from overwriting each other, when both are installed Tea takes care of scraping, custom labels and cartridge looks, and Coffee only shows the shared images. Make your changes in Tea, and keep both editions on the same version number, updating them together.

Launching games

It says "No emulator for this game is installed"?

Install the recommended emulator from Utility in the menu, or switch to an installed one under Choose an emulator on the game's page. Any app on your device can launch games through + Custom launch. See Playing games and Utility.

RetroArch opens but doesn't start the game, or shows a black screen?

The emulator opens but stops at its own menu?

Some standalone emulators (like DraStic) need you to add the game's folder inside the emulator once. The game's page tells you which folder to add; add it in the emulator, then tap Play and it goes straight into the game.

Downloads and extraction

I can't find Cloud drive in the menu?

If you've only logged in to a sync drive and not a library drive, Cloud drive doesn't appear in the menu. Go to Settings → General → Library drive and log in to a cloud drive or connect a home NAS (you can just tap Use on the one your sync drive uses).

A download failed — what now?

On the Downloads page, tap Retry on that task. If several failed, tap Failed at the top to see only those, then Retry failed to restart them all at once. After a pause or a dropped connection, retrying picks up where it left off.

If your cloud drive login expired, log in again in Settings → General first, then retry.

It says "can't access the extraction folder" or "can't create the extraction folder"?

Usually Tea doesn't have all files access, or the target folder is on an SD card that's been removed. Check file access in Settings → General, and make sure both the ROM folder and the PC games folder open.

I don't want files like a BIOS to be extracted?

When downloading, choose Other folder under "Download to" (saved as they are, not unpacked), and the files are saved unchanged to the place you choose.

Sync

Both devices changed a save, and it asks me to choose which to keep?

The game's page shows "Saves changed on two devices — pick one to keep". Open it and choose Keep this device's or Use the other device's; your choice syncs right away. If you pick the wrong one, you can get the earlier save back from the save history on the game's page.

The cloud in the side menu shows an exclamation mark?

The last sync failed or your login expired. Tap the cloud to retry now; if Settings → General → Sync drive shows "Login expired — log in again", just log in again. Without a network it shows "Waiting to sync · no network" and syncs automatically once you're back online.

Why didn't my theme and button layout sync to my other device?

That's on purpose: every handheld has a different screen and controller, so those settings stay on each device. Sync covers things like play records, saves, bookmarks, renames, covers and labels.

Can I switch to a different sync drive?

Yes, but don't switch often: sync data lives on the original sync drive, a new drive starts from scratch, and switching back and forth causes sync errors. See Saves and cloud sync.

It says "Quick save over xx MB, not synced"?

Some consoles' quick saves are too big to sync. Normal in-game saves aren't affected and sync as usual.

AI features

The AI buttons are greyed out, and tapping one says "Activate it on the [Settings] / [AI] page"?

AI features need you to verify as a supporter first. Go to Settings → AI and verify once with Verify bilibili 充电 or Verify afdian to unlock them. See AI features.

My AI verification expired, or I changed devices?

Verification lasts a month; verify again when it expires. Each supporter can use AI on 3 devices; verifying on a 4th turns off the one verified earliest, which can verify again when needed. Reinstalling Tea or clearing its data also counts as a new device.

The AI says "The AI took too long" or "Can't reach the AI service"?

Check your network, or try another network a little later. The first description lookup for a game can take from tens of seconds to over a minute; after that it shows up instantly.

Updates and errors

Updating says "Permission needed"?

Tap Open settings, allow Tea to install apps on the system page, go back and tap Update again. You only need to do this once.

Opening Tea shows "Something went wrong last time"?

Tea closed unexpectedly last time. Tap Copy or Share and send the error report to the author to help fix the problem.