david.alvarez
@@ -1,4 +1,4 @@
|
||||
# DOSTalgia 🕹️
|
||||
# DOSTALGIA 🕹️
|
||||
|
||||
A nostalgic DOS game hub. Upload your old DOS games, auto-scrape artwork and metadata from IGDB, and play them directly in your browser via js-dos (DOSBox compiled to WebAssembly).
|
||||
|
||||
@@ -9,15 +9,6 @@ Every uploaded game is packaged into a `.jsdos` bundle — a standard ZIP with e
|
||||
|
||||
**Save states are automatic** — js-dos persists your game progress to the browser's storage. Come back anytime and pick up where you left off.
|
||||
|
||||
### 📡 IGDB metadata & media
|
||||
Dostalgia integrates with [IGDB](https://www.igdb.com/) (via Twitch OAuth2) to auto-populate game info:
|
||||
|
||||
- **Auto Scrape** — On upload, Dostalgia searches IGDB by title and fills in year, genre, developer, publisher, description, and cover art. If IGDB finds a DOS result, it prioritises it.
|
||||
- **Manual Search** — From the game detail page you can search IGDB by any query, browse results with cover thumbnails and DOS badges, and apply the one you want.
|
||||
- **Media** — Videos (YouTube embeds) and screenshots (1080p) are fetched and displayed in a scrollable media gallery with a preview player.
|
||||
|
||||
Everything degrades gracefully — if Twitch credentials aren't configured, uploads and editing work fine, just without auto-scrape.
|
||||
|
||||
### 📦 Handles any file structure
|
||||
DOS games come in all shapes. Dostalgia handles them transparently:
|
||||
|
||||
@@ -27,6 +18,8 @@ DOS games come in all shapes. Dostalgia handles them transparently:
|
||||
- **CD-only games** — If the archive contains only CD images with no executable, a CD-only bundle is created that mounts the disc and drops you at the DOS prompt.
|
||||
- **Hardcoded paths** — `ConfigPatcher` scans game config files for hardcoded absolute paths (e.g. `C:\FALLOUT1\MASTER.DAT`) that broke after flattening, and rewrites them to relative paths.
|
||||
|
||||
Other solutions such as [RomM](https://www.romm.app/) generate raw ZIP bundles and require you to write your own `dosbox.conf` with manual `mount` and `imgmount` commands. Dostalgia automates all of this for you.
|
||||
|
||||
### 🔍 Smart executable detection
|
||||
On upload, Dostalgia scans every `.exe`, `.com`, and `.bat` file and picks the best candidate as the main executable using a scoring system:
|
||||
|
||||
@@ -38,6 +31,8 @@ On upload, Dostalgia scans every `.exe`, `.com`, and `.bat` file and picks the b
|
||||
|
||||
All discovered executables are stored and available in the **Edit** page, where you can pick a different one via radio buttons.
|
||||
|
||||
Again, RomM requires you to manually specify the executable in a custom `dosbox.conf`, while Dostalgia detects and configures it for you.
|
||||
|
||||
> **⚠️ Cache note:** If you change the executable, the `.jsdos` bundle is patched in-place. Your browser may serve a cached version of the old bundle — if the game doesn't launch with the new executable, **hard-refresh** the play page (Ctrl+Shift+R / Cmd+Shift+R).
|
||||
|
||||
### 🛠 One-click Setup launcher
|
||||
@@ -47,6 +42,8 @@ Many DOS games include a `SETUP.EXE`, `INSTALL.EXE`, or `CONFIG.EXE` used to con
|
||||
- Clicking it launches the setup executable *without modifying the main game bundle*
|
||||
- The setup bundle is generated **on-the-fly** by the server — a modified `.jsdos` is streamed with the setup executable in the autoexec, then discarded. Nothing is written to disk.
|
||||
|
||||
This is not supported in RomM, where you would have to run the setup manually from the DOS prompt every time.
|
||||
|
||||
### 🪟 Windows game detection
|
||||
DOSBox can't run Windows executables. Dostalgia's `PlatformDetector` reads MZ/PE/NE headers to detect Windows executables:
|
||||
|
||||
@@ -55,41 +52,33 @@ DOSBox can't run Windows executables. Dostalgia's `PlatformDetector` reads MZ/PE
|
||||
- If you click Play anyway, a warning overlay explains the limitation with a **Try anyway** fallback
|
||||
- Setup executables that are Windows-native are also filtered out from the Setup button
|
||||
|
||||
## How it works
|
||||
### 📡 IGDB metadata & media
|
||||
Dostalgia integrates with [IGDB](https://www.igdb.com/) (via Twitch OAuth2) to auto-populate game info:
|
||||
|
||||
```
|
||||
┌──────────────────────────────────────────┐
|
||||
│ Upload ZIP (multipart) │
|
||||
└────────────┬─────────────────────────────┘
|
||||
▼
|
||||
┌──────────────────────────┐
|
||||
│ Unzip & flatten dirs │
|
||||
│ Fix .cue references │
|
||||
│ Fix absolute paths │
|
||||
└────────────┬─────────────┘
|
||||
▼
|
||||
┌──────────────────────────┐
|
||||
│ Detect executables │
|
||||
│ Detect CD images │
|
||||
│ Detect platform (DOS/W) │
|
||||
└────────────┬─────────────┘
|
||||
▼
|
||||
┌──────────────────────────┐
|
||||
│ Build .jsdos bundle │
|
||||
│ (ZIP + dosbox.conf + │
|
||||
│ jsdos.json) │
|
||||
└────────────┬─────────────┘
|
||||
▼
|
||||
┌──────────────────────────┐
|
||||
│ Auto-scrape IGDB │
|
||||
│ (year, genre, cover, │
|
||||
│ videos, screenshots) │
|
||||
└────────────┬─────────────┘
|
||||
▼
|
||||
┌──────────────────────────┐
|
||||
│ Save game.json │
|
||||
└──────────────────────────┘
|
||||
```
|
||||
- **Auto Scrape** — On upload, Dostalgia searches IGDB by title and fills in year, genre, developer, publisher, description, and cover art. If IGDB finds a DOS result, it prioritises it.
|
||||
- **Manual Search** — From the game detail page you can search IGDB by any query, browse results with cover thumbnails and DOS badges, and apply the one you want.
|
||||
- **Media** — Videos (YouTube embeds) and screenshots (1080p) are fetched and displayed in a scrollable media gallery with a preview player.
|
||||
|
||||
**Setup:**
|
||||
|
||||
1. Go to https://dev.twitch.tv/console/apps → **Register Your Application**
|
||||
2. Name: `Dostalgia` (or anything), OAuth Redirect URL: `http://localhost`, Category: **Other**
|
||||
3. Copy the **Client ID** and generate a **Client Secret**
|
||||
4. Provide them via environment variables:
|
||||
|
||||
Method | How
|
||||
--- | ---
|
||||
Docker run | `-e TWITCH_CLIENT_ID=xxx -e TWITCH_CLIENT_SECRET=yyy`
|
||||
Docker Compose | Copy `.env.example` to `.env` and fill in the values
|
||||
Local dev | `export TWITCH_CLIENT_ID=xxx TWITCH_CLIENT_SECRET=yyy`
|
||||
|
||||
IGDB features degrade gracefully — if credentials aren't set, uploads and metadata editing still work, just without auto-scrape.
|
||||
|
||||
### 📷 Screenshots
|
||||
|
||||
|
||||
|
||||
|
||||
|
||||
## Quick Start
|
||||
|
||||
@@ -143,103 +132,4 @@ java -jar target/quarkus-app/quarkus-run.jar
|
||||
- **Frontend**: Svelte 5 SPA with hash-based routing
|
||||
- **Emulation**: js-dos v8 loaded from CDN, runs DOSBox in WebAssembly
|
||||
- **Storage**: JSON-per-game under `/data/games/{id}/game.json`
|
||||
- **Saves**: Browser localStorage / indexedDB (managed by js-dos)
|
||||
|
||||
## API
|
||||
|
||||
Method | Path | Description
|
||||
--- | --- | ---
|
||||
GET | `/api/games` | List all games
|
||||
GET | `/api/games/:id` | Get game details
|
||||
PATCH | `/api/games/:id` | Update game metadata
|
||||
DELETE | `/api/games/:id` | Delete a game
|
||||
POST | `/api/upload` | Upload a game ZIP (multipart)
|
||||
POST | `/api/games/:id/cover` | Upload cover art
|
||||
GET | `/api/games/:id/setup-bundle` | Stream a setup .jsdos bundle (on-the-fly)
|
||||
GET | `/api/games/:id/download` | Download the game's .jsdos bundle
|
||||
GET | `/api/igdb/status` | Check if IGDB is configured
|
||||
GET | `/api/igdb/search?q=` | Search IGDB for a game
|
||||
POST | `/api/igdb/scrape/:id` | Auto-scrape or apply specific IGDB result
|
||||
|
||||
## Game JSON Schema
|
||||
|
||||
```json
|
||||
{
|
||||
"id": "doom",
|
||||
"title": "Doom",
|
||||
"year": 1993,
|
||||
"genre": "FPS",
|
||||
"developer": "id Software",
|
||||
"publisher": "id Software",
|
||||
"description": "You've signed up for...",
|
||||
"bundle_file": "doom/doom.jsdos",
|
||||
"executable": "DOOM.EXE",
|
||||
"executables": ["DOOM.EXE", "SETUP.EXE"],
|
||||
"setup_exe": "SETUP.EXE",
|
||||
"has_setup": true,
|
||||
"platform": "dos",
|
||||
"bundle_size": 4194304,
|
||||
"has_cover": true,
|
||||
"screenshots": ["https://..."],
|
||||
"videos": ["dQw4w9WgXcQ"],
|
||||
"igdb_id": 3498,
|
||||
"ready": true,
|
||||
"created_at": "2026-05-27T10:00:00Z",
|
||||
"updated_at": "2026-05-27T10:00:00Z"
|
||||
}
|
||||
```
|
||||
|
||||
## IGDB Metadata (Optional)
|
||||
|
||||
Dostalgia can auto-populate game metadata (year, genre, developer, publisher, cover art, screenshots, videos) from the [IGDB](https://www.igdb.com/) database. This requires a Twitch API application.
|
||||
|
||||
**Setup:**
|
||||
|
||||
1. Go to https://dev.twitch.tv/console/apps → **Register Your Application**
|
||||
2. Name: `Dostalgia` (or anything), OAuth Redirect URL: `http://localhost`, Category: **Other**
|
||||
3. Copy the **Client ID** and generate a **Client Secret**
|
||||
4. Provide them via environment variables:
|
||||
|
||||
Method | How
|
||||
--- | ---
|
||||
Docker run | `-e TWITCH_CLIENT_ID=xxx -e TWITCH_CLIENT_SECRET=yyy`
|
||||
Docker Compose | Copy `.env.example` to `.env` and fill in the values
|
||||
Local dev | `export TWITCH_CLIENT_ID=xxx TWITCH_CLIENT_SECRET=yyy`
|
||||
|
||||
IGDB features degrade gracefully — if credentials aren't set, uploads and metadata editing still work, just without auto-scrape.
|
||||
|
||||
## Comparison with RomM
|
||||
|
||||
[RomM](https://www.romm.app/) is a popular ROM manager with web-based emulation. Here's how Dostalgia compares specifically for MS-DOS games:
|
||||
|
||||
| Feature | Dostalgia | RomM |
|
||||
|---|---|---|
|
||||
| **Emulator** | js-dos v8 (dedicated DOSBox WebAssembly) | EmulatorJS with dosbox-pure core |
|
||||
| **Bundle format** | Auto-generated .jsdos with embedded config | Raw ZIP + manual .conf file |
|
||||
| **Executable detection** | Automatic (smart scoring: depth, size, platform, installer filtering) | Manual — user must type `mount`, `cd`, and `exe` commands or write a .conf |
|
||||
| **CD mounting** | Automatic — detects .iso/.cue/.img/.ccd/.bin, fixes broken cues, mounts in config | Manual — user must write `imgmount` commands in .conf |
|
||||
| **Setup executable** | Auto-detected, one-click launch via on-the-fly streaming bundle | Not supported — user must run setup manually from DOS prompt |
|
||||
| **Windows detection** | PE/NE header analysis, UI badge, disabled play button with fallback | Not supported |
|
||||
| **IGDB integration** | Yes — auto-scrape, manual search, cover, genre, dev, publisher, videos, screenshots | Not for DOS specifically |
|
||||
| **Config patching** | Automatic — `ConfigPatcher` rewrites hardcoded `C:\` paths in game configs | Not available |
|
||||
| **GOG DOS games** | Supported (after flattening + path patching) | Explicitly NOT supported |
|
||||
| **Database** | None — JSON files per game | PostgreSQL |
|
||||
| **Upload size** | 2 GB limit | Depends on configuration |
|
||||
| **Save states** | Yes (browser storage via js-dos) | Yes (via EmulatorJS) |
|
||||
| **Target audience** | DOS-only, streamlined | Multi-platform, general-purpose |
|
||||
|
||||
**When to use RomM:** If you're managing ROMs across many platforms (NES, SNES, Genesis, PS1, etc.) alongside DOS games.
|
||||
|
||||
**When to use Dostalgia:** If you have a focused DOS collection and want a zero-fuss experience where you upload a ZIP and everything just works — executable detection, CD mounting, metadata, screenshots.
|
||||
|
||||
## Publishing the Docker image
|
||||
|
||||
The Docker image is fully self-contained (Java JAR + static frontend, no database). To publish:
|
||||
|
||||
```bash
|
||||
docker build -t dostalgia .
|
||||
docker tag dostalgia ghcr.io/yourname/dostalgia:latest
|
||||
docker push ghcr.io/yourname/dostalgia:latest
|
||||
```
|
||||
|
||||
Secrets are never baked into the image — users provide `TWITCH_CLIENT_ID` / `TWITCH_CLIENT_SECRET` at runtime via environment variables (or skip IGDB entirely).
|
||||
- **Saves**: Browser localStorage / indexedDB (managed by js-dos)
|
||||
Reference in New Issue
Block a user