GalAid

Drop a VN package. Get a launch route.

_{A launch assistant for visual novels, galgame folders, archives, disc images, and stubborn startup errors.}

Drag in a folder, archive, or old disc image.
GalAid prepares the package, finds the likely launcher, starts the desktop route, and turns failures into concrete next steps.

Languages: English / 简体中文 / 日本語

GalAid is a launch doctor for visual novel and galgame folders. It helps players answer the first painful question: "Which file do I run, and why is this game not starting?"

01 Drop Folders, `.zip/.rar/.7z/.lzh`, self-extracting `.exe` packages, split archives, `.iso`, CUE sheets with referenced `.bin` tracks, `.mds/.mdf`, and older VN layouts all enter one flow.

02 Prepare GalAid groups packages, asks for a password when needed, extracts or mounts, then rescans the prepared folder.

03 Launch The desktop beta can turn the main launch button into prepare, rescan, pick the top entry, and start compatible Windows `.exe/.com/.bat/.cmd/.lnk` files with the right working directory.

04 Fix If it fails, paste text or read a screenshot. GalAid turns the error into a DirectX, DirectPlay, VC++, locale, RTP, path, or package route.

_{One intake flow for packages, disc images, launch candidates, and startup errors.}

What It Feels Like

download.zip / game.iso / extracted-folder
        |
        v
   GalAid reads the layout
        |
        +--> prepare package or image automatically
        +--> find the likely launcher
        +--> launch from the right folder
        +--> read screenshots or logs when it fails
        |
        v
  one clear next action instead of guesswork

The web app is still useful for quick file-list diagnosis. The desktop beta is the main path for real users because it adds native scanning, package preparation, one-click launch, shortcuts, launch history, and Screenshot OCR.

Who It Helps

Many visual novel players get stuck before the game even opens:

• archives are not fully extracted
• disc images such as .iso, .cue, .bin, .mds are confusing
• Japanese locale, fonts, and path encoding cause mojibake or crashes
• old DirectX, DirectPlay, VC++, VB6, .NET, QuickTime/video, or RPG Maker RTP dependencies are missing
• folders contain many .exe files and it is unclear which one starts the game
• Win95/Win98/WinXP-era entries may actually be DOS, Win16, old installer media, or normal Win32
• a startup dialog appears, but the user cannot copy the text

GalAid turns that mess into a guided launch route.

Current Beta

Surface	Use it for	What you get
Windows desktop beta	Real player use	Native folder selection, recursive scan, one-stop launch guide, archive/image preparation, one-click launch, local runtime checks, shortcuts, launch history, Screenshot OCR.
Web demo	Quick preview	File-list diagnosis, engine clues, package stage hints, error recipe matching, report export.
Rule data	Community contribution	Engine fingerprints, startup error recipes, package patterns, and smoke-tested examples.

Download And Verify

File	Link
Windows portable beta	GalAid-0.1.9-win-x64.exe
SHA-256 sidecar	GalAid-0.1.9-win-x64.exe.sha256
Release manifest	GalAid-0.1.9-win-x64.exe.release.json
Release page	v0.1.9-beta

Maintainers can verify the published sidecars without downloading the large .exe:

npm run verify:release -- v0.1.9-beta --commit 60cafbc936bdbb31f16a78d3fc9da50b4c6ccb98 --json

Feature Map

Package to folder Split archives, normal archives, self-extracting EXE packages, disc-image pairs, legacy image formats, runtime repair tools, and password prompts are folded into one prepare-and-rescan flow.	Folder to launcher Launch candidates are ranked against installers, redists, config tools, engine files, executable headers, working directories, and commercial/self-developed layouts. Setup/autorun/MSI entries, including `autorun.inf` targets, become a separate install-media route when no game launcher is ready.	Error to next step Pasted logs, screenshot OCR, and optional desktop runtime checks feed the roadmap for DirectX, DirectPlay, VC++, Japanese locale, RPG Maker RTP, missing files, damaged archives, and web VN restrictions.
Engine clues Ren'Py, KiriKiri, NScripter, Unity, RPG Maker, Siglus, TyranoScript, and private commercial structures get evidence explanations.	Support bundle Reports, roadmaps, profiles, recipe matches, launch-failure notes, environment checks, and file-list summaries are exportable.	Contributor loop Most improvements are small JSON rules, reproducible examples, documentation polish, and Playwright smoke tests.

Quick Start

Surface	Start here	Best for
Live demo	TonyNa-code.github.io/GalAid	Trying GalAid instantly in a browser.
Windows beta	v0.1.9-beta release	Drag a folder/archive/image, enter a password if needed, press one launch button, OCR error screenshots, and export support context.
Chinese install guide	docs/INSTALL.zh-CN.md	Direct exe link, first-run steps, and QQ/group-share copy for non-technical players.
Local web app	Open index.html or run python3 -m http.server 4173	Offline use, development, and quick source inspection.

Launch Profiles

The launch button is the user-facing goal. The diagnosis engine is the part that decides which button should exist, what folder it should run from, and what to do when that button does not work.

GalAid can generate a launch profile from the best executable candidate. A profile includes:

• entry file and working directory
• a Windows command hint
• engine and locale notes
• a portable .galaid-profile.json file

Profiles do not auto-run games by themselves. In the web app, commands use relative paths. Locale-sensitive profiles can include optional Locale Emulator, Wine, and Proton templates that users can inspect and copy. In the desktop beta, copying a command can use the local path from the folder picker, a deliberate click can launch a scanned compatible Windows .exe/.com/.bat/.cmd/.lnk entry with the correct working directory, and users can create a Windows shortcut for normal executable entries. DOS MZ/COM, Win16 NE, and LE/LX legacy executables are routed to old-runtime guidance instead of direct launch. Old Win32 PE entries that target Win95/NT4/Win2000/XP stay launchable but add compatibility-mode guidance.

Next-Step Roadmap

The launch page now starts with a one-stop guide: import, prepare, launch, then collect failure evidence if the game still does not open. In the desktop beta, the primary button can prepare a trusted archive/image into a fresh *-prepared folder beside the package, rescan it, and launch the top entry without sending the user through the package tab. Package and image preflight cards highlight launch, install-media, and runtime-repair samples separately from generic file samples. When prepared media only exposes setup.exe, install.exe, autorun.exe, .msi, or an autorun.inf target such as Start.exe / SetupJP.exe / Setup.cmd, including shell install commands, GalAid keeps that installer out of the game-launch list but promotes it as the install-media next click. Windows Installer packages are opened through the system installer flow. When the pasted error points to DirectX, VC++, or RPG Maker RTP and a matching bundled repair tool is present, the same guide prioritizes opening that repair tool before retrying the game launcher. The 路线 tab combines the same archive/image state, launch candidates, installer entries, runtime checks, error recipes, and engine clues into an ordered checklist. It can be copied as Markdown and is also included in support bundles as roadmap.json and roadmap-checklist.md.

After a launch attempt fails, the 启动 tab can walk the user through a quick triage tree: what appeared, where the launch came from, and whether the error can be copied or needs screenshot OCR. The answers become structured evidence in the roadmap, reports, and support bundle alongside manual symptoms such as no response, immediate crash, mojibake, black screen, or missing DLL/runtime.

Environment Checks

The environment page turns common "why won't this start?" issues into a checklist before the user starts changing system settings.

It checks whether the folder appears fully extracted, whether a launch entry exists, whether bundled DirectX/VC++/.NET/VB6/QuickTime/RPG Maker RTP repair tools are present, and whether the metadata, PE imports, or pasted error text points to a commercial/private engine startup chain, Japanese locale, path encoding, old executable formats, old DirectX or DirectPlay components, VC++ redistributables, VB6, .NET Framework, QuickTime/video components, RPG Maker RTP, permissions, or web VN browser restrictions.

For many commercial Japanese VNs, GalAid does not need to name the exact private engine to be useful. A root .exe plus large .arc/.dat/.pak/.pck/.cpk/.pac/.vol resource archives, nearby DLL plugins, and config files is enough to trigger the commercial/self-developed engine route. That route focuses on preserving the original folder structure, keeping the working directory correct, and checking locale/runtime problems before assuming the game itself is broken.

GalAid explains likely prerequisites; runtime installers, locale changes, and system settings remain user-controlled.

Screenshot OCR

Startup dialogs are often screenshots, photos, or mojibake windows that cannot be copied. The error panel now accepts an error screenshot and converts recognized text into the same input used by the recipe matcher.

Desktop OCR uses Tesseract.js with English, Japanese, and Simplified Chinese recognition. The first OCR run may download language data into the desktop app cache. The web version uses browser text detection when available and falls back to loading Tesseract.js in the page.

Error Recipes

Common startup errors live in data/error-recipes.json as small data objects. The app can match pasted logs against recipes for DirectX, DirectPlay, VC++ redistributables, VB6, .NET Framework, QuickTime/video components, RPG Maker RTP, locale issues, missing files, archive damage, web VN local-file restrictions, Unity runtime files, and mounted-disc checks.

After editing recipes, run:

npm run build:recipes
npm run check

See docs/ERROR_RECIPES.md for the recipe format and contribution notes.

Engine Rules

Engine and structure fingerprints live in data/engine-rules.json. Contributors can improve KiriKiri, Ren'Py, NScripter, Unity, RPG Maker, Siglus, TyranoScript, and commercial/self-developed route detection with narrow file-structure evidence and regression checks.

The engine panel explains why each route matched, shows the confidence score, lists the metadata evidence, and gives a concrete next step. This keeps commercial/self-developed detection useful without pretending to know a private engine name.

After editing engine rules, run:

npm run build:engines
npm run check

See docs/ENGINE_RULES.md for the rule format and contribution notes.

CI runs the same check on pull requests and pushes to main.

Browser smoke tests run in GitHub Actions after installing Chromium. Run them locally with:

npm run test:smoke

Contributing

Recipe improvements, engine fingerprints, docs, and redacted false-positive reports are welcome. Start with docs/CONTRIBUTING.md.

High-signal pull requests usually land in one of these lanes:

Lane	Good contribution
Engine evidence	Add a narrow fingerprint with sample filenames and a regression check.
Error recipes	Improve a startup-error pattern with clearer evidence and a beginner action.
Package guidance	Make archive, split-volume, or disc-image diagnosis less confusing for real users.
UX and docs	Make the beginner flow, release notes, screenshots, or issue templates easier to follow.

For new startup-error rules, open a "New error recipe" issue or edit data/error-recipes.json directly in a pull request.

For engine and commercial/self-developed structure clues, edit data/engine-rules.json.

Starter tasks live in docs/GOOD_FIRST_ISSUES.md.

Please also read SECURITY.md and CODE_OF_CONDUCT.md. Release notes and repository topic suggestions live in docs/RELEASE_DRAFT.md and docs/REPO_TOPICS.md.

Support Bundle

The support bundle is a local .zip for asking for help in an issue, forum, or chat. It includes:

• galaid-report.md
• manifest.json
• privacy-summary.md, human-readable local absolute-path redaction counts
• privacy-summary.json, machine-readable local absolute-path redaction counts
• file-manifest.json, including package/image preflight signal samples and encrypted-entry counts when available
• package-previews.md, a human-readable package/image preflight summary
• package-previews.json, a compact view of archive/disc-image launch, install-media, repair, and password-protected package clues
• launch-decision.md, a human-readable primary action and fallback route summary
• launch-decision.json, ranked launch/install/repair decision metadata
• environment-checks.json
• roadmap.json
• roadmap-checklist.md
• error-recipes.json
• launch-failure.json when manual follow-up evidence exists
• launch-profiles.json
• individual profiles/*.galaid-profile.json files

The 求助 tab also shows exactly what will be included and can copy a short issue-ready summary. If package preflight sees encrypted entries, the support bundle README.txt, manifest.json, file-manifest.json, and copyable summary all surface the encrypted-entry and likely password-protected package counts without storing the password. Shareable reports, chat help text, and support bundles redact pasted local absolute paths such as Windows user folders or macOS home folders to [absolute-path] while keeping the diagnostic wording around them. Support bundles also include privacy-summary.md and privacy-summary.json, which count redaction markers per exported file without storing the original local paths.

Diagnosis Output Language

The default repository README stays in English, with Chinese and Japanese translations linked at the top. Inside the app, the assistant output language can be switched between Chinese, English, and Japanese. The setting affects copied reports, downloaded reports, roadmap checklists, support bundle README files, and issue-ready support summaries.

Large Games

The web app is designed around file-list scanning, so a 10GB extracted game folder is usually fine. Total bytes matter much less than the number of entries the browser needs to index.

The main limit is file count, not total bytes:

• under 20,000 files: normal full metadata scan
• 20,000+ files: large folder mode with compact rendering
• 50,000+ files: large folder mode skips full path sorting to keep the browser responsive

Single large archives or disc images such as .zip, .rar, .7z, .lzh/.lha, .arj, .cab, .tar/.tgz/.tar.gz, self-extracting .exe packages, .iso, .cue, .bin, .mds/.mdf, .ccd/.img/.sub, .nrg, .isz, .cdi, BlindWrite images, .mdx, .daa, .uif, and .pdi can be identified in the web app when their metadata is present. The desktop beta can additionally preflight ZIP central-directory metadata, list RAR/7z/LZH/LHA/ARJ/CAB/TAR-style and self-extracting EXE metadata through the bundled or local 7z-compatible command, read small CUE sheets to group referenced .bin/.img tracks even when names differ, list supported disc-image directories without extraction, and flag disc-image descriptor/media roles. It can spot likely launchers, installers, bundled DirectX/VC++/.NET/VB6/QuickTime/RPG Maker RTP repair tools, split-volume status, old install-media clues, autorun.inf + Start.exe + data1.cab install-disc layouts, bonus discs, patch-like packages, engine clues, DOS/Win16/Win32/Win64 executable headers, old Win32 subsystem-version hints, and legacy DirectDraw/DirectSound/DirectInput/DirectPlay/WinMM/VC++/VB6/.NET/QuickTime/Borland import hints before extraction.

When the user clicks the one-stop launch button, the desktop beta can use a bundled 7z-compatible helper first, then local 7zz / 7z / 7za if needed. It extracts supported archive packages and detected self-extracting EXE packages into a new sibling *-prepared folder, asks for a known password when needed, expands compressed tar packages such as .tar.gz/.tgz in two passes, mounts Windows .iso images through the system mount command, or best-effort extracts common disc-image files before automatically rescanning the prepared folder and launching the top entry. If no game launcher exists but an install-media entry does, including .msi, the same flow opens that installer and tells the user to rescan the installed game folder afterward. The manual Extract and rescan and Mount/extract and rescan actions remain available when the user wants to choose the output parent folder first. If launch still fails, the desktop beta asks the user to mark the visible symptom and folds that into the roadmap.

Archive and Disc Image Guidance

The web MVP can recognize common package stages and tell the user what to do next:

• split archives: keep every part together and start from part1.rar, .7z.001, .zip.001, or the main .zip for .z01/.z02 sets
• plain and legacy archives: extract fully before running the game, including .lzh/.lha, .arj, .cab, and tar-style packages when supported by the local helper
• ISO/NRG/ISZ/CDI images: mount or unpack the image first
• CUE/BIN, MDS/MDF, CCD/IMG/SUB sets: keep paired files together before mounting. Desktop scans read small .cue sheets and can warn when a referenced .bin/.img track is missing.

The one-stop launch action prepares beside the package automatically. The manual prepare action still asks for an output folder, uses the entered password for that attempt, and returns to scanning after extraction or image preparation finishes.

Run

Web App

Open this file directly:

index.html

Or serve it locally:

cd GalAid
python3 -m http.server 4173

Then open:

http://localhost:4173

GitHub Pages Demo

For a public repository, enable GitHub Pages with GitHub Actions as the source. The Deploy Pages workflow builds the static demo from index.html, src/, data/error-recipes.json, data/engine-rules.json, and LICENSE, then publishes the dist/ artifact. The demo URL is usually https://TonyNa-code.github.io/GalAid/.

Build the same artifact locally:

npm run build:pages

Desktop Beta

Download the Windows portable beta from Releases, or run the Electron shell locally:

npm install
npm start

Clean generated local artifacts when the workspace gets noisy:

npm run clean:dry
npm run clean

Use npm run clean:deps only when you also want to remove node_modules/; run npm install again before testing or packaging.

The desktop beta uses the same UI and diagnosis engine as the web app, but the folder/file picker and drag/drop path scan are native and can recursively scan local folders without browser directory limitations. It can launch scanned compatible Windows .exe/.com/.bat/.cmd/.lnk entries after the user clicks Launch; install-media .msi entries are opened through Windows Installer. DOS COM/MZ, Win16 NE, and LE/LX entries are detected from headers and kept on a DOSBox/old-OS/VM route instead of direct launch. Win95/NT4/Win2000/XP-era Win32 PE entries remain launchable, while the roadmap suggests compatibility mode, fullscreen fixes, short paths, and legacy DirectX/runtime/video component checks if launch fails. When the current input is a trusted package/image, that same launch flow can prepare, rescan, and launch the top entry when it is compatible. GalAid sets the working directory to the entry's folder. The profile tab can create a Windows shortcut for normal executable entries and shows a recent-launch history.

Windows portable release builds are handled by .github/workflows/desktop-release.yml on manual runs or v* tags:

npm run dist:win

See docs/DESKTOP.md for packaging notes.

Roadmap

v0.1.9-beta is already shipped as a live web demo and Windows desktop beta. Current priorities are:

• more metadata-only engine rules and startup error recipes from redacted reports
• more archive, split-volume, disc-image, and install-media smoke fixtures
• clearer screenshots, install docs, and beginner-facing copy
• 1.0 hardening such as signed Windows builds and better recovery wording

See docs/ROADMAP.md for the full state, and docs/GOOD_FIRST_ISSUES.md for the current priority queue.

License

MIT. See LICENSE.