Rezept-Authoring (Rezeptor)¶

Tiefenreferenz für recipe.yml, install_steps und Hooks.
Schnellstart & Muster (Portable, Installer, Steam, Trainer): ENTWICKLER.md.

Vorlagen: recipes/_template/, recipes/_template-installer/.

Architektur¶

recipes/<id>/
  recipe.yml          ← Metadaten + install_steps + uninstall:
  install.sh          ← recipe_hooks::load + recipe_install_steps::run
  launch.sh / validate.sh / repair.sh / kill.sh / uninstall.sh

core/
  recipe-hooks.sh           ← Einstieg (+ purge_recipe_data)
  recipe-install-steps.sh   ← führt install_steps aus
  recipe-<id>.sh            ← App-Logik (module:)
recipes/recipe.schema.json  ← Vertrag

uninstall.sh (Pflicht — vollständig)¶

Immer recipe_hooks::load minimal und recipe_hooks::purge_recipe_data (Desktop + DATA_ROOT + kanonischer data_root inkl. data_root.path).
Nicht nur prefix/ oder recipe.env löschen — sonst bleibt die GUI bei „installiert“.
Kein load kill in uninstall (Proton/Hang). Portable/Spielordner außerhalb von DATA_ROOT bleiben.

App-/Spielordner-Verknüpfung (`DATA_ROOT`)¶

Nach Install/Repair legt Core unter DATA_ROOT einen absoluten Symlink an, der direkt in den echten Programm-/Spielordner zeigt (ohne durch prefix/drive_c/... zu klicken). Der Ordner-Button in der GUI öffnet weiterhin DATA_ROOT; die Verknüpfung liegt darin.

State / Quelle (Priorität)	Typische Rezepte
`GAME_ROOT` → `GAME_DIR`	Halo, Steam-Templates
`WISO_PORTABLE_ROOT` (`portable.env`)	WISO
`WORK_ROOT` (Ordner)	Photoshop, Premiere, Portable, MSI

Optional in recipe.yml: app_link_name: MeinOrdner (Default: Rezept-id). Core: recipe_app_link::ensure / ::validate (Validate = OK/WARN, überschreibt keine echte User-Datei). Purge entfernt nur den Link in DATA_ROOT, nicht den Ordner außerhalb.

install.sh (immer dünn)¶

PROJECT_ROOT kommt vom Launcher (setup.sh / GUI). Overlay-Rezepte unter ~/.local/share/rezeptor/recipes/ haben kein ../../core — deshalb zuerst $PROJECT_ROOT/core, Fallback nur fürs Repo-Checkout.

RECIPE_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
# shellcheck source=/dev/null
if [ -f "${PROJECT_ROOT:-}/core/recipe-hooks.sh" ]; then
    source "$PROJECT_ROOT/core/recipe-hooks.sh"
elif [ -f "$RECIPE_DIR/../../core/recipe-hooks.sh" ]; then
    source "$RECIPE_DIR/../../core/recipe-hooks.sh"
else
    echo "ERROR: core/recipe-hooks.sh not found (set PROJECT_ROOT)" >&2
    exit 1
fi
recipe_hooks::load install
recipe_install_steps::run

`install_steps` (Pflicht)¶

install_steps:
  - prepare_source
  - require_portable   # portable
  - prefix
  - winetricks         # aus winetricks: in yml
  - winetricks: [corefonts, gdiplus]
  - module: recipe_meine_app::post_deploy
  - copy_asset:
      src: assets/foo.sh
      dest: "{data_root}/bin/foo.sh"
  - run_installer      # installer_offline
  - apply_updates      # optionale nummerierte Patches (siehe UPDATES.md)
  - win10
  - fonts_registry

Schritt	Rolle
`prepare_source`	Quelle → `RECIPE_WORK_ROOT` (Ordner/Archiv/Installer)
`require_portable`	erwartet `portable_folder`
`prefix`	Proton + Prefix
`winetricks`	Pakete (yml oder Liste); `vcrun`/`dotnet`/`win10` speziell
`deploy_graphics`	Proton-Grafik-DLLs
`run_installer`	Setup.exe
`apply_updates`	Nummerierte Updates (`recipe_updates::apply_all`) — siehe UPDATES.md
`module`	`recipe_*::funktion` aus Core
`copy_asset`	Datei deployen
`env_set`	Key in portable.env / Datei
`stabilize_prefix` / `win10` / `fonts_registry`	Hilfsschritte

Parser: scripts/recipe-yaml-read.py · Schema: scripts/recipe-schema-check.py (embedded; optional jsonschema).

`recipe.yml` Pflicht¶

id, name, icon, data_root, runtime, install_type, source_kind, fix_kind, Hooks (inkl. uninstall; bei fix_kind: optional|required auch update), install_steps.

Quellen-Dialog — Baukasten¶

Baustein	Wann	YAML / Env
Quelle	fast immer	`source_kind`, `source_label`, `source_formats`
Ziel	Installer, Portable, Copy-Deploy	`target_`, frei wählbar — nicht* bei `deploy_mode: link`
Updates	nummerierte Patches nach Install (z. B. Halo)	`fix_kind: optional` \| `required` + Hook `update:` + `update.sh` → `RECIPE_UPDATE_ROOT`
Online-Fix	Steam-Link + BYOS-Fix-Ordner	`fix_kind: online_fix_optional` \| `online_fix_required` + `fix_merge_path` → `RECIPE_FIX_ROOT` / `RECIPE_FIX_MERGE_PATH`

fix_kind: none — kein zusätzliches Feld im Dialog.

Online-Fix: Rezeptor verteilt keine Fix-Dateien. Optionaler Ordner im Dialog; Core: recipe_online_fix::merge in install.sh / repair.sh. Liegen Fix-Dateien schon im Spielordner, kann das Feld leer bleiben.

Updates ≠ Online-Fix: Updates nutzen recipe_updates::apply_all und nummerierte .exe-Pakete; Online-Fix kopiert .dll/.ini in einen festen Unterpfad des Spiels.

Icon (Pflicht)¶

icon: "{repo}/images/<id>-icon.png"

Datei unter images/ (PNG oder SVG), empfohlen 256×256
GUI: Sidebar + Header; Notify kann dasselbe Icon nutzen
Lint prüft: Feld gesetzt und Datei existiert
Quelle z. B. EXE-Icon (wrestool/icotool) oder Steam-Library-Art

Proton-GE (optional, pro Rezept)¶

runtime: proton-ge
proton_ge_tag: GE-Proton11-3          # sonst core/runtime.lock (Default)
# proton_ge_url: https://...          # nur wenn nicht Default und nicht PROTON_GE_ALT_*
# proton_ge_sha256: <64 hex>

Medizin-Alternative nur als generisches PROTON_GE_TAG (Choice), nicht als Photoshop-Bool. Details: ENTWICKLER.md.

Empfohlen¶

Feld	Rolle
`schema_version`	Format-Version (aktuell `1`; fehlend = 1)
`category`	Sidebar-Gruppe. Offiziell: `Finanzen & Steuer`, `Grafik & Design`, `Video & Schnitt`, `Dokumente & PDF`, `Spiele` (sonst Freitext / `Sonstige`)
`author`	Anzeige in der Übersicht
`notify_title`	Desktop-Notify `-a` / Titel; sonst `name`
`version_label` / `version_guaranteed`	Getestete Version (Anzeige + Heilung in der GUI; YAML-Key unverändert)
`tested_on`	Optional: `YYYY-MM-DD` – Datum der letzten bewussten Heilungsprüfung (Autor). GUI zeigt es neben Proton-GE. Manuell pflegen; bei geänderter Version/Pin aktualisieren. Nicht aus CI/Git-mtime ableiten.
`version_detect`	Pflicht bei `version_guaranteed` — deklarative Erkennung (siehe unten)
`source_hints`	Optional: Suchtexte / Pack-Titel für BYOS (keine URLs)
`sidebar_label`	Optional: kurzer Titel in der Seitenleiste; Version/Pack erscheinen bei Bedarf in einer zweiten kleinen Zeile
`steam_appid`	Steam AppID: Trainer-Zielordner oder Spielordner bei `deploy_mode: link`
`steam_target_folder`	Unterordner im Spielverzeichnis (Default `Trainer`; nur bei copy/Trainer)

Notify-Titel: manuell (notify_title) oder Fallback name — kein Auto-Detect aus EXE-Namen.

Versionserkennung (`version_detect`)¶

Rezeptor prüft die gewählte Quelle gegen version_guaranteed. Die Regeln stehen im Rezept — der Launcher liefert die Engine.

version_guaranteed: "22.0.0.35"
version_detect:
  - kind: json_key
    glob: "products/PHSP/application.json"
    key: ProductVersion
  - kind: pe_field
    glob: "*.exe"
    field: FileVersion

`kind`	Zweck
`json_key`	JSON-Datei (`glob` + `key`)
`text_regex`	Textzeile (`glob` + `regex` mit Gruppe)
`path_regex`	Ordner-/Dateiname
`pe_field`	PE `FileVersion` / `ProductVersion`
`pe_contains`	Byte-Marker in EXE → `value` (z. B. Trainer-Familie)
`filename_regex`	Dateiname → `value`
`stack`	Mehrere Dateien + INI-Keys (Steam+Fix)

Signale werden der Reihe nach versucht; erstes Ergebnis gewinnt. stack kann bei Teilerkennung eine Abweichungs-Meldung liefern.

Lint: version_guaranteed ohne version_detect → ERROR.

Quellen-Hinweise (`source_hints`)¶

Für Offline-/BYOS-Rezepte: dem Nutzer sagen, wonach er suchen soll — ohne Downloads und ohne Links.

version_guaranteed: "22.1.1.138"
source_hints:
  - "Adobe Photoshop 2021 22.1.1.138 Multilingual + Neural Filters [Multi + RUS] RePack m0nkrus"
  - "rutracker"
  - "m0nkrus"

Regel
Erlaubt	Pack-Titel, Version, Keywords (Forenname, Repack-Autor)
Verboten	`http://`, `https://`, Magnet-Links

Anzeige in Quellen-Dialog und Rezept-Übersicht. Ein Rezept = ein getestetes Pack — abweichende Builds lieber als eigenes Rezept mit eigenen source_hints, statt mehrere Garantien zu mischen.

Lint: URL/Magnet in source_hints → ERROR.

Release-Index (`source_refs`)¶

Optional: Link zu einem erlaubten Release-Index (aktuell nur xrel.to) — Anzeige in der Rezept-Ansicht, kein Download von Rezeptor.

source_refs:
  - label: "xrel (Suche)"
    url: "https://www.xrel.to/search.html?xrel_search_query=Halo.Campaign.Evolved.Premium.Edition.MULTi13-ElAmigos"

Lint: andere Hosts → ERROR. Details: UPDATES.md / Pack-Identität wie bei Photoshop.

Info-Layout (`info.de.txt` / `info.en.txt` oder `.md`)¶

GUI-Übersicht: Pflicht mindestens info.de.txt oder info.de.md (EN empfohlen). Markdown-Lite (#, ##, **fett**) wird gerendert.

# <Titel>

Autor: …
Version: …

## Kurzbeschreibung
…

## Voraussetzungen
• …

## Installation
1. …

## Nutzung
• …

## Hinweise
• …

Schreibstil: professionell und klar, locker lesbar, Business-Ton — auch für Einsteiger verständlich. Struktur und Aussage beibehalten; nur Formulierungen glätten. Fachbegriffe nur wenn nötig, kurz erklären. Keine inhaltliche Aufblähung.

Schema: recipes/recipe.schema.json.

Portable:

install_type: portable_launch
deploy_mode: copy
source_kind: folder
source_formats: zip,tar.gz,tgz,7z,rar
target_default: "~/Dokumente/Meine App"
winetricks: [win10, vcrun2019]
install_steps:
  - prepare_source
  - require_portable
  - prefix
  - winetricks

Installer (entspricht recipes/_template-installer/):

install_type: installer_offline
source_kind: folder          # GUI wählt Setup-Ordner / .exe
source_label: "Ordner mit Offline-Installer (setup.exe / Set-up.exe)"
winetricks: [win10, vcrun2015]
install_steps:
  - prepare_source
  - prefix
  - winetricks
  - run_installer

Optional (selten): source_kind: fixed_path + installer_dir: "{repo}/installer" für fest verdrahtete Repo-Pfade — die mitgelieferte Vorlage nutzt das nicht.

Steam-Titel mit externem Fix (BYOS, Launch aus Rezeptor):

Für Spiele, die im Steam-Ordner bleiben und nur einen selbst eingelegten Fix brauchen. Kein Fix-Vertrieb im Repo — validate prüft Dateien read-only, Launch setzt Proton + WINEDLLOVERRIDES / SteamAppId. Vorlage: _template-steam-game/.

Wichtig: kein neuer Steam-Eintrag (Start nur Rezeptor); FakeAppId oft 480/Spacewar (muss in Steam installiert sein); Deinstall entfernt nur Rezeptor-Wrapper, nicht Spiel/Fix.

install_type: game_portable
deploy_mode: link          # kein Kopieren; Dialog ohne Zielordner
source_kind: folder
steam_appid: "1281590"     # echte Steam-AppID (compatdata)
steam_fake_appid: "480"    # oft Spacewar — muss in Steam installiert sein
steam_fix_win64_rel: "Binaries/Win64"   # relativ zum Spielordner
steam_fix_required:
  - OnlineFix64.dll
  - OnlineFix.ini
steam_api_rel: ""          # optional, relativ zum Spielordner
runtime: proton-ge
fix_kind: none
exe_glob: "Game.exe"
install_steps:
  - emit_log_paths         # Logik in install.sh / validate.sh / launch.sh

Feld	Rolle
`steam_appid`	Echte AppID → Steam-Spielordner / compatdata
`steam_fake_appid`	FakeAppId in Online-Fix-INI (häufig `480`)
`steam_fix_win64_rel`	Unterordner mit Fix-DLLs/INI
`steam_fix_required`	Pflicht-Dateinamen für validate
`steam_api_rel`	Optionaler `steam_api64.dll`-Pfad

Details: STEAM-WRAPPER.md.

	Trainer (Muster)	Steam+Fix (`_template-steam-game`)
Quelle	einzelne `.exe`	Spielordner
Deploy	copy in Zielunterordner	`link` (Pfad merken)
Prefix	Steam compatdata des Spiels	dasselbe
Validate	EXE + Wrapper	EXE + Fix-Dateien + INI-AppIDs
Uninstall	nur Rezeptor-Dateien	nur Rezeptor-State; Spiel/Fix bleiben

Tokens: {repo}, {data_root}, {recipe}, ~.

Qualität / CI¶

./scripts/recipe-lint.sh      # Hooks ERROR, install_steps, Schema
./scripts/recipe-manifest.sh
make recipe-lint              # CI
REZEPTOR_DEV=1 ./setup.sh

Runtime-Helfer (Pflicht in Custom-/Repair-Code)¶

Aufgabe	Nur so	Nie
Winetricks	`recipe_winetricks::run` (Retry nur Exit 139)	Direktes `winetricks`, Subshell-Hacks
Windows 10	`recipe_win10::ensure` (Registry)	`winetricks winecfg` / doppeltes `win10`+`settings win10`
Grafik/DXVK	`wine_runtime::deploy_proton_graphics_dlls`	`winetricks dxvk`
Prefix	`recipe_prefix::ensure`	System-Wine-Fallback

Verboten (Lint ERROR): winetricks dxvk, System-Wine-Fallback, doppeltes win10.
API-Details: CORE-API.md.

Grafik-Apps — GPU¶

DXVK nur über wine_runtime::deploy_proton_graphics_dlls — kein winetricks-dxvk.

Kernmodule¶

Vollständige API: CORE-API.md. Kurz:

Datei	Zweck
`recipe-hooks.sh`	Hook-Einstieg + `purge_recipe_data`
`recipe-install-steps.sh`	Deklarative Installation
`recipe-install.sh`	prepare_source / apply_fix
`recipe-prefix.sh` / `recipe-winetricks.sh` / `recipe-win10.sh`	Prefix, Winetricks (Retry 139), Win10
`recipe-validate.sh`	OK/FAIL/WARN-Helfer
`recipe-<id>.sh`	App-Logik
`wine-runtime.sh`	Proton-GE + Grafik-DLLs

Lifecycle: VALIDATE-REPAIR.md · UNINSTALL.md · LOG-PROTOCOL.md