LaunchSpec-Referenz

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.

Diese Seite ist die normative Referenz für LaunchSpec, den Anforderungsdatensatz, der eine OmsiLaunch-Sitzung beschreibt: seine C#-Form (OmsiLaunch.Api), seine JSON-Dateiform, wie sie von der CLI geladen wird (/spec:<path>, tools/OmsiLaunch.Cli/LaunchSpecJson.cs), jede Eigenschaft mit Typ, Standardwert, Validierungsregel und aktueller Wirkung, die Validierungsregeln, die einen Plan nicht ausführbar machen, sowie die Rangfolge zwischen CLI-Flags, Spec-Dateien und Sitzungsprofilen. Dokumentiert wird nur, was der aktuelle Code tut.

Verwandte Seiten: öffentliche API, CLI-Referenz, Sitzungsprofile, Fehlercodes, Sitzungslebenszyklus, Capabilities.

Woher eine LaunchSpec stammt#

Das vollständige Beispiel unten ist gegen die Form des Datensatzes geprüft. Eine Kopie des minimalen Beispiels wird als examples/release-session.example.json ausgeliefert (und im Release-Paket als .omsilaunch\examples\release-session.example.json).

JSON-Form#

Vollständiges Beispiel#

{
  // Comments and trailing commas are accepted. Enums are integers.
  "Installation": {
    "RootPath": ".",                          // "." = directory that contains OmsiLaunch.exe (CLI only)
    "ExpectedExecutableSha256": null          // carried, not consumed
  },
  "World": {
    "Mode": 0,                                // 0 NewMap, 1 SavedSituation, 2 LastMapState (unavailable)
    "MapIdentity": { "Presence": 1, "Value": "maps\\Grundorf\\global.cfg" },
    "SituationIdentity": { "Presence": 0, "Value": null },
    "PresentedEntrypointIndex": { "Presence": 1, "Value": 1 },
    "EntrypointIdentity": { "Presence": 0, "Value": null }
  },
  "Date": { "Mode": 0, "Value": { "Presence": 0, "Value": null } },
  "Time": { "Mode": 0, "Value": { "Presence": 0, "Value": null } },
  "Year": null,
  "Weather": null,
  "PlayerVehicle": { "Presence": 0, "Value": null },
  "Environment": {
    "General": {
      "traffic.randomVehicles": { "Presence": 1, "Value": "150" },
      "graphics.maxFPS": { "Presence": 1, "Value": "60" }
    },
    "Advanced": {}, "Graphics": {}, "AdvancedGraphics": {},
    "Sound": {}, "AiPassengers": {}, "Keyboard": {}, "Controllers": {}
  },
  "Behavior": {
    "RestoreConfiguration": true,             // carried, restore always happens
    "SuppressStaleClosecheckWarning": true,
    "StartupTimeoutSeconds": 180,             // 1..600
    "ShutdownTimeoutSeconds": 30              // carried, not consumed
  },
  "Input": null,
  "Diagnostics": null,
  "Presentation": {
    "Splash": 1,                              // 0 Unset/Native (keep OMSI files), 1 Managed
    "Language": { "Presence": 0, "Value": null },
    "CustomAssetDirectory": { "Presence": 0, "Value": null },
    "SuppressTrayIcon": false
  },
  "InternetTextures": {
    "Mode": 0,                                // 0 Native, 1 Disabled, 2 Override
    "OverrideProfilePath": { "Presence": 0, "Value": null }
  },
  "SessionProfile": null
}

Ein explizites Datum wird, sofern der Build es unterstützt, als "Date": { "Mode": 1, "Value": { "Presence": 1, "Value": { "Year": 2024, "Month": 5, "Day": 1 } } } geschrieben und eine Uhrzeit als { "Mode": 1, "Value": { "Presence": 1, "Value": { "Hour": 7, "Minute": 30, "Second": 0 } } }. In diesem Build machen beide den Plan nicht ausführbar (siehe unten).

Eigenschaftsreferenz#

Die Spalte „Verwendet“ gibt an, was der aktuelle Code mit dem Wert tut. Die Stabilitätsangaben verwenden das Vokabular der Seite zur öffentlichen API.

LaunchSpec (Wurzel)#

Schreibgeschützte Accessoren (in der JSON-Ausgabe der CLI vorhanden, beim Laden ignoriert): EffectiveYear, EffectiveWeather, EffectiveInput, EffectiveDiagnostics, EffectivePresentation, EffectiveInternetTextures.

InstallationSpec#

WorldSpec#

DateSpec, TimeSpec, YearSpec#

WeatherSpec#

PlayerVehicleSpec (innerhalb von PlayerVehicle)#

Ein PlayerVehicle mit Presence 1 und lauter nicht gesetzten Feldern wird akzeptiert und hat keine Wirkung. Jedes gesetzte Feld macht den Plan in diesem Build nicht ausführbar (STATICALLY_PARTIAL).

EnvironmentSpec#

Die acht Gruppen werden zusammengefügt; in welcher Gruppe ein Schlüssel steht, hat keine Wirkung. Jeder Eintrag mit Presence 1 ist eine semantische Einstellung aus ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs); der Schlüssel bestimmt die Zieldatei (options.cfg für jeden aktuellen Schlüssel) und das Token. Die Planung prüft, dass der Schlüssel existiert (OL_E_UNKNOWN_SETTING) und beschreibbar ist (OL_E_SETTING_NOT_WRITABLE); der Wert wird erst beim Start validiert (OL_E_INVALID_SETTING_VALUE, gemeldet als Failed-Sitzung mit OL_E_START_SESSION). Bei Schlüsseln wird Groß-/Kleinschreibung nicht beachtet. Nicht gesetzte Einträge werden ignoriert. Das CLI-Flag /set:<key>=<value> schreibt in General; die settings von Sitzungsprofilen werden ebenfalls in General zusammengeführt.

Gepatchte Dateien behalten ihre Codierung (Windows-1252-Bytes bleiben erhalten; mit BOM gekennzeichnetes UTF-8/UTF-16 wird berücksichtigt) und ihre Zeilenenden.

LaunchBehaviorSpec#

InputSpec#

DiagnosticsSpec#

Die CLI-Flags /log, /logall, /omsi-logall, /verbose, /trace, /trace-process, /trace-plugin, /trace-native befüllen diese booleschen Werte (/logall setzt Verbose, ProcessTrace, PluginTrace, NativeTrace); sie werden mit den Spec-Werten ODER-verknüpft.

SessionPresentationSpec#

InternetTexturesSpec#

SessionProfileMetadata#

Aufzählungen#

Ganzzahlen außerhalb des deklarierten Bereichs werden vom Serializer unverändert gespeichert und verhalten sich wie unbekannte Werte (ein unbekannter WorldMode ist z. B. weder NEW_MAP noch SAVED_SITUATION und ergibt einen Plan ohne Welt-Capability; das Plugin würde ihn ablehnen, die CLI ersetzt den Modus jedoch ohnehin, siehe Rangfolge).

Validierungsregeln und Diagnosen für nicht ausführbare Pläne#

PlanSessionAsync führt LaunchValidation.Validate und anschließend SessionPlanner.PlanAsync aus. Ein Plan ist genau dann ausführbar, wenn kein Diagnosecode mit OL_E_ beginnt. Die vollständige Menge:

Nicht zur Planungszeit validiert (scheitert beim Start als Failed-Sitzung mit OL_E_START_SESSION): Einstellungswerte (OL_E_INVALID_SETTING_VALUE), Integrität des permanenten Plugins (OL_E_PERMANENT_PLUGIN_*), Verfügbarkeit der Lease (OL_E_INSTALLATION_BUSY), Bereich von StartupTimeoutSeconds (ausgelöst von StartSessionAsync).

Informative Plandiagnosen: plugin.integrity.reference (Meldung manifest oder self), session_profile.selected.

Rangfolge: CLI-Flags vs. Spec-Datei vs. Sitzungsprofil#

CliInput.BuildSpecAsync (tools/OmsiLaunch.Cli/Program.cs) erstellt die wirksame Spec in dieser Reihenfolge:

1. Ausgangsbasis = eingebaute Standardwerte oder, falls angegeben, die /spec-Datei.
2. Installationsstammverzeichnis = das explizite Installationsargument, falls angegeben, sonst der RootPath der Ausgangsbasis; danach ./leer → Verzeichnis der ausführbaren Datei, Path.GetFullPath. Ein explizites Installationsargument hat immer Vorrang vor dem RootPath der Spec.
3. Sitzungsprofil (/predefined-profile + /predefined-profile-index): Explizite CLI-Argumente, die ein profileigenes Feld betreffen, werden mit OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT abgelehnt (Weltfelder nur im NEW_MAP-Modus; /set-Schlüssel, die in der Voreinstellung vorhanden sind; Startbild-Flags, wenn die Voreinstellung presentation hat; Internettextur-Flags, wenn sie internet-textures hat; Timeouts, wenn sie behavior hat). Die World der Ausgangsbasis wird durch eine neue ersetzt (nur der Weltmodus der CLI bleibt erhalten), dann werden der new:-Block des Profils (nur NEW_MAP), settings (in General), presentation, internet-textures, behavior und die SessionProfile-Metadaten angewendet. compatibility.maps wird für NEW_MAP und SAVED_SITUATION erzwungen.
4. Welt: Der Weltmodus der CLI hat immer Vorrang (/new Standard, /saved:<osn>, /last); der World.Mode der Spec-Datei wird ersetzt. Um eine gespeicherte Situation aus einer Spec auszuführen, übergeben Sie /saved:. /map und /entrypoint//entrypoint-index überschreiben die Ausgangsbasis; eine CLI-Identität per /entrypoint löscht den Index; /saved zusammen mit /map oder Einstiegspunkt-Flags ergibt OL_E_INVALID_ARGUMENT.
5. /date, /time, /year, /weather* überschreiben die Ausgangsbasis, wenn angegeben (system wählt DateTimeMode.System).
6. /no-vehicle löscht PlayerVehicle; die einzelnen Flags /vehicle, /repaint, /hof, /fleet, /registration überschreiben einzelne Felder des Spielerfahrzeugs der Ausgangsbasis.
7. /set:<key>=<value>-Einträge werden zu Environment.General hinzugefügt (Schlüssel geprüft, Wert nicht); die anderen sieben Gruppen stammen unverändert aus der Ausgangsbasis.
8. /startup-timeout und /shutdown-timeout überschreiben die Ausgangsbasis nur, wenn angegeben; andernfalls gelten Spec, dann Profil, dann die Standardwerte 180 s / 30 s. ShutdownTimeoutSeconds ist für den Supervisor ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT.
9. /splash, /splash-language, /splash-assets, /internet-textures, /internet-textures-profile überschreiben die Ausgangsbasis, wenn angegeben; SuppressTrayIcon stammt ausschließlich aus der Ausgangsbasis.
10. Diagnose-Flags werden mit der Ausgangsbasis ODER-verknüpft.

Ergebnis: explizites CLI-Flag > Sitzungsprofil > Spec-Datei > eingebauter Standardwert, mit der Ausnahme, dass ein CLI-Flag, das mit einem profileigenen Feld kollidiert, ein Fehler ist und kein Überschreiben.

Pfadregeln#

Mitgeführt, aber nicht angewendet#