DOSVault — Project Overview
Draft prepared on 2026-10-05 from a read-only review of the public repo (main, last commit 2026-09-13), the live site, the project's troubleshooting notes (dosvault-jsdos-troubleshooting.md) and previous working sessions. Nothing in the repo was changed while writing it. Items marked (to confirm) could not be verified from the public sources.
1. What DOSVault is
DOSVault is a free, browser-based catalog of classic DOS and abandonware games. Visitors pick a game and play it directly in the browser, with no installation, through one of two WebAssembly emulation engines: js-dos (a full DOSBox PC emulated in the browser) or ScummVM (native re-implementation of classic adventure game engines).
The interface imitates a Norton Commander-style DOS file manager: two blue panels (genres on the left, games on the right), a command line, and an F-key bar at the bottom. Games open in draggable, DOS-styled windows inside the page.
2. Scope
In scope
- MS-DOS games playable through js-dos v7 (
.jsdos bundles).
- Classic graphic adventures (SCUMM, Sierra SCI/AGI, AGOS, Kyra, etc.) playable through ScummVM-WASM.
- Desktop browsers with keyboard and mouse; optional gamepad support via the browser Gamepad API.
- Bilingual UI: Spanish and English.
Out of scope (current decisions)
- Mobile and tablet devices. They are actively blocked with a "desktop required" notice (user-agent check plus coarse-pointer/narrow-screen check).
- Windows 3.x / 9x games.
- Any bundle larger than 300 MB: this is a hard hosting limit (see section 8).
- User accounts, cloud saves, server-side logic. The site is fully static.
3. Architecture at a glance
DOSVault is a static site with no build step: plain HTML, CSS and vanilla JavaScript, served by Netlify straight from the repository. All dynamic behavior happens in the visitor's browser.
Visitor's browser
├─ index.html + css/ + js/ ← served by Netlify (from GitHub repo)
├─ data/games.json, data/genres/* ← catalog, same origin, lazy-loaded per genre
├─ Game bundles (.jsdos / ScummVM) ← Cloudflare R2 (fetched on launch; HEAD for size/date)
├─ js-dos v7 (vendored) ← emulates the DOS PC
├─ ScummVM WASM (vendored, iframe) ← adventure game engines
└─ Third-party lookups (client-side, no keys):
• GitHub API → date of last commit to data/games.json
• Netlify Forms → Help/Contact form submissions
4. Repository structure
dosvault/
├─ index.html Single page: panels, F-key bar, all modals, script loading
├─ favicon.png
├─ css/
│ ├─ style.css Full site styling (DOS/Norton Commander look)
│ └─ fonts/ PxPlus IBM VGA8 (self-hosted, CC BY-SA 4.0) + license
├─ js/
│ ├─ app.js Main application: catalog, navigation, windows, modals,
│ │ key remapping, gamepad, test-bundle tool (~1,700 lines)
│ ├─ i18n.js ES/EN dictionaries, genre labels, language detection
│ ├─ scummvm-engine.js Wrapper that runs ScummVM inside an iframe
│ └─ vendor/
│ ├─ js-dos/ js-dos 7.1.0 (js-dos.js, wdosbox.js/.wasm, css)
│ └─ scummvm/ ScummVM WASM build + launcher.html + fflate + engine plugins
├─ data/
│ ├─ games.json Genre index (name, count, URL of each genre file)
│ └─ genres/*.json One file per genre with its game entries
└─ .github/workflows/
└─ build-scummvm.yml Manual workflow that compiles ScummVM to WASM
5. Catalog data model
5.1 data/games.json — genre index
{
"genres": {
"race": { "name": "Carreras", "count": 17, "url": "data/genres/race.json" }
}
}
name: fallback label (the visible label normally comes from I18N_GENRES in js/i18n.js).count: maintained by hand. It is shown in the Files column only until the genre files finish loading; from then on the column shows the number of visible games of the genre (games whose bundle returned 404/410 on R2 are not counted). Genres with 0 games are hidden.url: genre file, loaded only when the visitor opens that genre (lazy loading with in-memory cache).
Current genre ids: fps, rts, platformer, avg, rpg, sim, arcade, action, race, sports.
5.2 data/genres/<id>.json — game entries
{
"id": "race",
"name": "Carreras",
"games": [
{
"id": "deathrally",
"name": "DEATHRALLY",
"genre": "race",
"added": "2026-08-11",
"year": "1996",
"cover": "https://thumbnails.libretro.com/DOS/Named_Boxarts/Death%20Rally.png",
"bundle": "https://pub-…r2.dev/projects/dosvault/deathrally.jsdos"
}
]
}
| Field | Required | Purpose |
|---|
id | yes | Unique key; also used for window ids and cache keys |
name | yes | Short DOS-style name shown in the list and window title |
title | no | Full display title; preferred over name for sorting and tooltip |
genre | yes | Must match the genre id |
added | yes | YYYY-MM-DD; drives the "New games" popup |
year | yes | Release year, shown in the new-games popup |
cover | yes | Box-art image URL (libretro thumbnails). Not displayed anywhere at the moment (it was only used by the removed Info popup) |
bundle | yes | Absolute URL of the bundle on R2 |
engine | no | "scummvm" to use ScummVM; omitted = js-dos |
lang | no | "es"/"en", shown in the Language column; defaults to EN |
This is the beginning of the README. Read the rest at the original. Read the full README ↗
