Sitzungsprofile

Dokumentation für Version v0.1.0-beta.3Quelle auf GitHub ansehen

Übersetzung der englischen Originalseite für OmsiLaunch 0.1.0-beta3. Maßgeblich ist die englische Seite: Bei Abweichungen gelten die englische Seite und der Code.

Ein Sitzungsprofil ist ein deklaratives YAML-Paket, das ein Inhaltsautor mit einer Karte oder einem Add-on ausliefert, damit Endanwender mit einem einzigen Befehl eine reproduzierbare OmsiLaunch-Sitzung starten können (OmsiLaunch.exe /predefined-profile:<id> /predefined-profile-index:<1..5> /new). Diese Seite ist die normative Referenz für das Format omsilaunch.session-profile/v1, wie es von SessionProfileCompiler in src/OmsiLaunch.Core/SessionProfiles.cs implementiert wird, für die von der CLI angewendeten Rangfolgeregeln (CliInput.BuildSpecAsync und RejectProfileConflicts in tools/OmsiLaunch.Cli/Program.cs) sowie für den Einstellungskatalog, den ein Profil schreiben darf (ConfigurationCatalog). Alles, was ein Profil kann, können auch die CLI-Flags und die LaunchSpec; ein Profil bündelt diese Entscheidungen lediglich.

Stabilität: STABLE_BETA für Parsing, Validierung, Konflikterkennung und die Blöcke settings / presentation / internet-textures / behavior (Offline-Test session-profiles.strict-compiler; der Overlay- und Wiederherstellungspfad ist durch RV-005 und RV-006 zur Laufzeit validiert, siehe Status der Runtime-Validierung). Die Schlüssel new.date, new.time, new.year und new.weather sind in diesem Build UNAVAILABLE (siehe Der new-Block).

Ablageort und Benennung des Pakets#

Ein Profil wird vom Anwender oder vom Inhaltsautor installiert und entfernt. OmsiLaunch schreibt nie in ein Paket, kopiert es nie und löscht es nie. Das Paketverzeichnis ist nicht Teil einer Transaktion.

Parsing-Regeln#

Backslashes in einfachen (nicht in Anführungszeichen gesetzten) Skalaren sind literale Zeichen. Schreiben Sie Windows-Pfade mit einem einzelnen Backslash (maps\Grundorf\global.cfg). Ein doppelter Backslash in einem einfachen Skalar bleibt im Wert doppelt; siehe Das mitgelieferte Beispiel.

Schlüsselreferenz#

Kontexte werden genau so benannt, wie der Compiler sie benennt. Jeder hier aufgeführte Schlüssel wird akzeptiert, sonst keiner.

profile (Wurzel-Mapping)#

compatibility#

new#

Der Block wird gelesen und validiert, sobald er vorhanden ist, aber nur dann auf die Spec angewendet, wenn der ausgewählte Weltmodus NEW_MAP ist (/new, der CLI-Standard). Unter /saved:<file.osn> wird der Block ignoriert.

date, time, year und weather werden in DateSpec, TimeSpec, YearSpec und WeatherSpec mit DateTimeMode.Explicit / dem ausgewählten WeatherMode kompiliert. Der Sitzungsplaner (src/OmsiLaunch.Core/SessionPlanner.cs) meldet daraufhin die Capabilities world.explicit-date, world.explicit-time, world.explicit-year und weather als STATICALLY_PARTIAL, fügt den Plandiagnosen OL_E_CAPABILITY_UNAVAILABLE hinzu und kennzeichnet den Plan als nicht ausführbar. Das Plugin lehnt zusätzlich eine Übergabe ab, deren Datums- oder Zeitmodus nicht Unset ist (plugin.request.unsupported). Folge für diesen Build: Ein Profil, das einen dieser vier Schlüssel setzt, kann mit /plan validiert werden, aber keine Sitzung starten (Exitcode 1, OL_E_PLAN_NOT_RUNNABLE). Lassen Sie sie in Profilen weg, die ausgeführt werden sollen.

new.date#

new.time#

new.weather#

preset (jeder Eintrag von presets)#

Nur die ausgewählte Voreinstellung wird angewendet. Dennoch wird jede Voreinstellung geparst und validiert, sodass ein Fehler in Voreinstellung 3 eine Anforderung für Voreinstellung 1 scheitern lässt.

presentation#

presentation.splash#

Ein Profil kann SessionPresentationSpec.SuppressTrayIcon nicht setzen; der Wert bleibt false, sofern ihn nicht eine /spec setzt.

internet-textures#

behavior#

Ist der behavior-Block vorhanden, werden beide Timeouts gesetzt (angegebener Wert oder Standardwert) und ersetzen die LaunchBehaviorSpec der Ausgangsbasis vollständig, einschließlich RestoreConfiguration und SuppressStaleClosecheckWarning, die auf ihre Standardwerte (true, true) zurückfallen.

Einstellungen#

settings-Schlüssel sind die semantischen Namen aus ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs). Der Compiler akzeptiert einen Schlüssel nur, wenn er existiert (OL_E_SESSION_PROFILE_SETTING_UNKNOWN) und beschreibbar ist (OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE). Werte werden als Strings gespeichert und in einen options.cfg-Patch umgewandelt, wenn die Sitzung ihre Overlays aufbaut; ein ungültiger Wert wird daher erst bei StartSessionAsync erkannt, nicht beim Laden des Profils, und lässt die Sitzung mit OL_E_START_SESSION scheitern, dessen Meldung OL_E_INVALID_SETTING_VALUE: <key> enthält. Jede der folgenden Einstellungen schreibt in options.cfg; alle sind sitzungsbezogen und werden nach der Sitzung exakt wiederhergestellt.

Wertformen:

• bool ist true oder false (ohne Beachtung der Groß-/Kleinschreibung). Bei Präsenz-Tokens wird das Token hinzugefügt oder entfernt; bei invertierten Tokens (no_*) entfernt true das negative Token.
• int / decimal werden gegen den Bereich validiert; Werte mit einem Divisor werden geteilt gespeichert (z. B. schreibt graphics.minObjectScreenPercent: 5 den Wert 0.05).
• string wird unverändert geschrieben.

Katalogeinträge, die existieren, aber nicht beschreibbar sind (abgelehnt mit OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE): advanced.multithreadingCalculate, advanced.multithreadingTextureLoad (abgelöst durch advanced.reducedMultithreading), graphics.texture, graphics.textureFilter.

Pfadbeschränkung#

presentation.splash.assets und internet-textures.profile werden durch Confined(package root, value) aufgelöst:

1. Absolute Pfade (C:\...), Pfade, die mit \ beginnen, und jede Pfadkomponente, die .. entspricht, werden abgelehnt.
2. Der vollständige Pfad wird berechnet und muss mit dem Paketverzeichnis beginnen.
3. Jede existierende Komponente unterhalb des Paketstamms bis einschließlich des endgültigen Pfads wird auf das Attribut ReparsePoint geprüft. Eine Junction, ein symbolischer Verzeichnislink oder ein symbolischer Dateilink irgendwo auf diesem Pfad wird abgelehnt, ebenso eine Komponente, die sich nicht prüfen lässt (IOException / UnauthorizedAccessException).

Alle drei Fehler ergeben OL_E_SESSION_PROFILE_PATH_ESCAPE. Dieselbe Regel für Analysepunkte wird beim Aufbau der Sitzung auf .itx-Ziele unter Texture\ angewendet.

Rangfolge und Überschreibungskonflikte#

CliInput.BuildSpecAsync setzt die Spec in dieser Reihenfolge zusammen:

1. Standardwerte (NEW_MAP, alles nicht gesetzt, Timeouts 180 s / 30 s).
2. /spec:<file.json> ersetzt, falls angegeben, die Standardwerte vollständig.
3. Installationsstammverzeichnis: Ein explizites Installationsargument hat Vorrang vor dem RootPath der Spec; . bedeutet das Verzeichnis, das die ausführbare Datei enthält.
4. Profil (/predefined-profile + /predefined-profile-index): Das Paket wird geladen, und RejectProfileConflicts läuft gegen die rohen CLI-Argumente, bevor irgendetwas zusammengeführt wird. Anschließend wird der Weltblock der Ausgangsbasis auf eine leere WorldSpec des ausgewählten Modus zurückgesetzt (eine /spec-Welt wird verworfen, wenn ein Profil verwendet wird), und SessionProfileCompiler.Apply legt das Profil über die Ausgangsbasis: new (nur NEW_MAP), settings (über Environment.General der Ausgangsbasis zusammengeführt, das Profil gewinnt je Schlüssel) sowie presentation, internet-textures, behavior (jeweils ersetzen sie den Block der Ausgangsbasis nur, wenn die Voreinstellung ihn definiert).
5. Übrige CLI-Argumente werden darübergelegt: /map, /entrypoint, /entrypoint-index, /date, /time, /year, Wetter-Flags, Fahrzeug-Flags, /set, Startbild-Flags, Internettextur-Flags, /startup-timeout, /shutdown-timeout. Timeouts aus der CLI gelten nur, wenn sie angegeben sind; andernfalls bleibt der Wert aus Spec/Profil/Standard bestehen.
6. Kompatibilitätsprüfung für Modi außer NEW_MAP (ValidateCompatibility).

Ein CLI-Argument, das auf ein Feld zielt, das dem ausgewählten Profil gehört, ist ein Konflikt und wird mit OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT abgelehnt (Exitcode 2, Kategorie invalid_argument). Die Prüfung erfolgt pro Feld, nicht pro Wert: Auch die Wiederholung des profileigenen Werts ist ein Konflikt.

Keine Konflikte sind: /set-Schlüssel, die die Voreinstellung nicht definiert (sie werden hinzugefügt), Fahrzeug-Flags (/vehicle, /repaint, /hof, /fleet, /registration, /no-vehicle; ein Profil kann kein Spielerfahrzeug definieren) und jedes Weltargument unter /saved (der new-Block wird dort nicht angewendet). /map, /entrypoint und /entrypoint-index sind zusammen mit /saved unabhängig von Profilen ungültig (OL_E_INVALID_ARGUMENT).

Fehlercodes#

Alle diese Fehler werden ausgelöst, während die Befehlszeile kompiliert wird, also vor der Planung. Es handelt sich um SessionProfileException (bzw. ArgumentException für den Konflikt), und sie starten nie eine Sitzung. Der vollständige Katalog steht unter Fehler, die Exitcodes unter Exitcodes.

Wie ein Profil in der API erscheint#

Nach einem erfolgreichen Laden trägt die Spec einen SessionProfileMetadata-Datensatz in LaunchSpec.SessionProfile:

Der Planer fügt jedem SessionPlan, der aus einer solchen Spec erstellt wird, die informative Diagnose session_profile.selected hinzu, mit den Datenschlüsseln session_profile.id, session_profile.name, session_profile.version, session_profile.author, session_profile.preset_id, session_profile.preset_index, session_profile.preset_name und session_profile.path. Sie beeinflusst die Ausführbarkeit nicht. Integratoren, die die öffentliche API direkt verwenden, können SessionProfileCompiler.Load und SessionProfileCompiler.Apply aus OmsiLaunch.Core aufrufen; die YAML-Repräsentation gelangt nie in OmsiLaunch.Api.

Beispiele#

Beispiel 1: Profil nur mit Einstellungen, eine Voreinstellung#

<root>\.omsilaunch\session-profiles\quiet-evening\profile.yaml

schema: omsilaunch.session-profile/v1
id: quiet-evening
name: Quiet evening
author: Example author
version: "1.0"
presets:
  - index: 1
    id: default
    name: Low traffic, no autosave
    settings:
      traffic.randomVehicles: 40
      traffic.humans: 60
      general.autoSave: false
      sound.masterVolume: 0.6

Ausführen: OmsiLaunch.exe /predefined-profile:quiet-evening /predefined-profile-index:1 /new /map:maps\Grundorf\global.cfg /entrypoint-index:0. Karte und Einstiegspunkt stammen aus der Befehlszeile, weil das Profil keinen new-Block definiert; das Hinzufügen von /set:graphics.maxFPS=60 ist erlaubt, das Hinzufügen von /set:traffic.humans=10 ist ein Konflikt.

Beispiel 2: kartengebundenes Profil mit drei Voreinstellungen und mitgelieferten Assets#

<root>\.omsilaunch\session-profiles\grundorf-tour\profile.yaml, mit assets\splash\ENG.bmp, assets\splash\DEU.bmp und textures\offline.itx innerhalb des Pakets:

schema: omsilaunch.session-profile/v1
id: grundorf-tour
name: Grundorf guided tour
author: Example team
version: "2.1"
compatibility:
  maps:
    - maps\Grundorf\global.cfg
new:
  map: maps\Grundorf\global.cfg
  entrypoint-index: 0
presets:
  - index: 1
    id: low
    name: Low-end PC
    settings:
      graphics.maxFPS: 30
      graphics.tileDistance: 3
      graphics.rainReflections: false
    presentation:
      splash:
        mode: managed
        language: DEU
        assets: assets\splash
    internet-textures:
      mode: disabled
    behavior:
      startup-timeout: 300
  - index: 2
    id: mid
    name: Mid-range PC
    settings:
      graphics.maxFPS: 60
      graphics.tileDistance: 6
    internet-textures:
      mode: override
      profile: textures\offline.itx
  - index: 3
    id: high
    name: High-end PC
    settings:
      graphics.maxFPS: 120
      graphics.tileDistance: 10
      advanced.reducedMultithreading: false
    presentation:
      splash:
        mode: native

Ausführen: OmsiLaunch.exe /predefined-profile:grundorf-tour /predefined-profile-index:2 /new. Mit /saved:situations\mytrip.osn wird der new-Block übersprungen, und die .osn muss auf maps\Grundorf\global.cfg verweisen.

Das mitgelieferte Beispiel#

Das Release liefert docs/examples/session-profiles/rmg-leste/profile.yaml aus (ansehen). Es ist syntaktisch gültig, entspricht dem Schema und würde ohne Fehler geladen. Zwei Eigenschaften verhindern, dass es in diesem Build unverändert eine Sitzung startet:

1. Es setzt new.date, new.time und new.weather, wodurch der Plan nicht ausführbar wird (siehe Der new-Block).
2. Seine Pfadwerte sind einfache Skalare mit doppelten Backslashes (maps\\RMG Leste\\global.cfg). YAML behält sie doppelt bei, und Kartenidentitäten werden textuell verglichen (nur nach der Normalisierung von / zu \), sodass new.map und compatibility.maps nicht mit der Katalogidentität maps\RMG Leste\global.cfg übereinstimmen würden (OL_E_MAP_NOT_FOUND bei der Planung). Der assets-Wert wird dennoch aufgelöst, weil die Windows-Pfadnormalisierung doppelte Trennzeichen zusammenfasst.

Die in diesem Build ausführbare Form lautet:

schema: omsilaunch.session-profile/v1
id: rmg-leste
name: RMG Leste
author: Equipe RMG
version: "1.0"
compatibility:
  maps:
    - maps\RMG Leste\global.cfg
new:
  map: maps\RMG Leste\global.cfg
  entrypoint-index: 3
presets:
  - index: 1
    id: weak
    name: PC fraco
    settings:
      graphics.maxFPS: 30
      graphics.tileDistance: 3
    presentation:
      splash:
        mode: managed
        language: PTB
        assets: assets\splash
    internet-textures:
      mode: disabled
  - index: 2
    id: medium
    name: PC medio
    settings:
      graphics.maxFPS: 40
      graphics.tileDistance: 5
  - index: 3
    id: strong
    name: PC forte
    settings:
      graphics.maxFPS: 60
      graphics.tileDistance: 8

Verwandte Seiten#

• CLI-Referenz zu /predefined-profile, /predefined-profile-index, /set und den Welt-Flags
• LaunchSpec zu dem Datensatz, in den ein Profil kompiliert wird
• Transaktionen und Recovery dazu, wie settings-, Startbild- und .itx-Overlays angewendet und wiederhergestellt werden
• Capabilities und Status der Runtime-Validierung