Data

Tools

Indexes

Applications

Experiments

Awesome

An open API service indexing awesome lists of open source software.

https://github.com/hacan359/tonkatsu_box

Free open-source app to organize collections of retro games, movies, TV shows & anime. Track progress, rate favorites, create visual boards, share with friends. Flutter · Windows · Android
https://github.com/hacan359/tonkatsu_box

android-app anime-tracker backlog-tracker collection-manager dart flutter game-collection igdb material-design-3 media-library movie-tracker open-source retro-games riverpod sqlite steamgriddb tmdb tv-show-tracker windows-app

Last synced: 4 months ago
JSON representation

Free open-source app to organize collections of retro games, movies, TV shows & anime. Track progress, rate favorites, create visual boards, share with friends. Flutter · Windows · Android

Awesome Lists containing this project

README 

          


  Tonkatsu Box




Tonkatsu Box





  Organize your games, movies, TV shows, and anime — all in one place






  Windows

  Android






  

    Tests

  

  

    License: MIT

  

  

    Flutter 3.38+

  




---



Tonkatsu Box is a free, open-source collection manager for retro games, movies, TV shows, and anime. Search IGDB and TMDB databases with hundreds of thousands of titles, organize them into custom collections, track your backlog and progress, rate everything from 1 to 10, create visual boards with drag-and-drop, and share collections with friends. Available for Windows and Android.



## What You Can Do



### 🎮 Build Collections

Create as many collections as you want — by platform (SNES, PlayStation, PC), genre (RPGs, Sci-Fi), or your own lists (Backlog, Favorites, Couch co-op night). Mix games, movies and anime in a single collection. Switch between list and poster grid view.



### 🔍 Search & Discover

Find games, movies, TV shows, and anime from a database of hundreds of thousands of titles. Filter by year, genre, or platform. Add anything you find to your collections with one tap.



### 📝 Wishlist

No internet right now? Jot down the name of a game or movie to search for later. Tag it with a media type, add a note, and tap it when you're ready — the app opens search with the name pre-filled. Mark items as resolved when you've found them.



### 📊 Track Your Progress

Mark items as Not Started, In Progress, Completed, On Hold, or Dropped. For TV shows and anime, track individual episodes with per-season checkboxes. Rate everything from 1 to 10 stars. See when you started and finished each item.



### 🎨 Visual Boards

Arrange your collection on a free-form board — drag posters around, add text notes, images, and links. Draw connections between items. Browse high-quality game artwork from SteamGridDB and add it to your boards. Each item can also have its own personal board.



### 📤 Share with Friends

Export your collections as `.xcoll` (lightweight) or `.xcollx` (full offline copy with all images and data). Friends can import them and fork to create their own version.



## Getting Started



### Step 1: Get your API keys



The app uses free APIs to search for games, movies, and artwork. You'll need to register for API keys (it's free and takes a few minutes).



🎮 IGDB — for searching games (required)



IGDB is powered by Twitch, so you'll need a Twitch account.



1. Go to **[dev.twitch.tv/console](https://dev.twitch.tv/console)** and log in (or create a free Twitch account)

2. Click **Register Your Application**

3. Fill in the form:

   - **Name:** `Tonkatsu Box` (or anything you like)

   - **OAuth Redirect URLs:** `http://localhost`

   - **Category:** `Application Integration`

4. Click **Create**

5. Open your new application and copy the **Client ID**

6. Click **New Secret** and copy the **Client Secret**



You'll enter both in the app under **Settings → Credentials**.



🎬 TMDB — for searching movies, TV shows & anime (recommended)



1. Go to **[themoviedb.org](https://www.themoviedb.org/)** and create a free account

2. Go to your profile → **Settings** → **API**

3. Click **Request an API Key** → choose **Developer**

4. Fill in the form (for personal/non-commercial use)

5. Copy your **API Key (v3 auth)**



Enter it in the app under **Settings → Credentials**.



> [!TIP]

> Without a TMDB key, game search still works — you just won't be able to search for movies, TV shows, or anime.



🖼️ SteamGridDB — for game artwork on boards (optional)



1. Go to **[steamgriddb.com](https://www.steamgriddb.com/)** and create a free account

2. Go to **Preferences** → **API**

3. Copy your **API Key**



Enter it in the app under **Settings → Credentials**.



> [!TIP]

> This key is only needed if you want to add high-quality game artwork (covers, heroes, logos) to your visual boards.



> [!TIP]

> On first launch, the app will walk you through a **Welcome Wizard** that explains everything — you can also revisit it later from **Settings → Welcome Guide**.



### Step 2: Install and run



```bash

git clone https://github.com/hacan359/tonkatsu_box.git

cd xerabora

flutter pub get

flutter run -d windows    # or: flutter run -d android

```



> [!NOTE]

> You'll need [Flutter SDK](https://flutter.dev/docs/get-started/install) installed. Windows builds require the Windows desktop development tools, Android builds require the Android SDK.

>

> Android release builds require a signing keystore. See the [Contributing Guide](docs/CONTRIBUTING.md#android-release-builds) for setup instructions.



### Step 3: Enter your API keys



Open the app → go to **Settings** → **Credentials** and paste your API keys. You're ready to go!



## Sharing Collections



### Exporting



1. Open a collection → tap the **menu** (⋮) → **Export**

2. Choose a format:

   - **Light export** (`.xcoll`) — small file with just the list of items. The recipient will need internet to load images and details.

   - **Full export** (`.xcollx`) — complete package with all images, board layouts, and media data. Works fully offline.

3. Pick where to save the file



### Importing



1. Go to **Settings** → **Database** → **Import Collection**

2. Select a `.xcoll` or `.xcollx` file

3. The collection appears in your list — you can browse it as read-only or **fork** it to make your own editable copy



## Platforms



| | Windows | Android |

|---|:---:|:---:|

| Collections & search | ✅ | ✅ |

| Progress & episode tracking | ✅ | ✅ |

| Visual boards | ✅ | ✅ |

| VGMaps browser (level maps) | ✅ | — |

| Export & import | ✅ | ✅ |



## Documentation



For developers and contributors:



| Document | Description |

|----------|-------------|

| [Features](docs/FEATURES.md) | Detailed feature list |

| [Architecture](docs/ARCHITECTURE.md) | Project structure, models, database |

| [Getting Started](docs/GETTING_STARTED.md) | Developer setup guide |

| [API Keys Guide](docs/guides/API_KEYS.md) | Detailed API key registration instructions |

| [How It Works](docs/guides/HOW_IT_WORKS.md) | App structure, quick start, sharing |

| [Roadmap](docs/ROADMAP.md) | Development progress and future plans |

| [Export Format](docs/RCOLL_FORMAT.md) | `.xcoll` / `.xcollx` file format spec |

| [Gamepad Support](docs/GAMEPAD.md) | Xbox controller / D-pad navigation |

| [Contributing](docs/CONTRIBUTING.md) | Contribution guidelines |

| [Changelog](CHANGELOG.md) | Version history |



## Tech Stack



Flutter 3.38+ / Dart 3.10+ · Riverpod · SQLite · Dio · Material Design 3



## Contributing



Contributions are welcome! See the [Contributing Guide](docs/CONTRIBUTING.md) for details.



## Code Signing Policy



Windows binaries are signed with a certificate provided by [SignPath Foundation](https://signpath.org).



Free code signing provided by [SignPath.io](https://signpath.io), certificate by [SignPath Foundation](https://signpath.org).



**Team roles:**

- Committers and reviewers: [hacan359](https://github.com/hacan359)

- Approvers: [hacan359](https://github.com/hacan359)



**Privacy policy:** This program will not transfer any information to other networked systems unless specifically requested by the user or the person installing or operating it. The application uses third-party APIs (IGDB, TMDB, SteamGridDB) only when the user explicitly initiates a search or data fetch.



## License



MIT