Dokumentacja LaunchSpec

Dokumentacja wersji v0.1.0-beta.3Zobacz źródło na GitHubie

Tłumaczenie oryginalnej strony w języku angielskim dla OmsiLaunch 0.1.0-beta3. Wiążąca jest strona angielska: w razie rozbieżności obowiązują strona angielska i kod.

Ta strona jest normatywną dokumentacją referencyjną rekordu LaunchSpec – rekordu żądania opisującego jedną sesję OmsiLaunch. Opisuje jego kształt w C# (OmsiLaunch.Api), postać pliku JSON wczytywanego przez CLI (/spec:<path>, tools/OmsiLaunch.Cli/LaunchSpecJson.cs), każdą właściwość wraz z typem, wartością domyślną, regułą walidacji i bieżącym działaniem, reguły walidacji, które czynią plan niemożliwym do uruchomienia, oraz pierwszeństwo między flagami CLI, plikami specyfikacji i profilami sesji. Udokumentowano wyłącznie to, co robi bieżący kod.

Powiązane strony: publiczne API, dokumentacja CLI, profile sesji, kody błędów, cykl życia sesji, możliwości.

Skąd pochodzi LaunchSpec#

Poniższy kompletny przykład jest zweryfikowany względem kształtu rekordu. Kopia minimalnego przykładu jest dostarczana jako examples/release-session.example.json (oraz .omsilaunch\examples\release-session.example.json w pakiecie wydania).

Postać JSON#

Kompletny przykład#

{
  // 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
}

Jawną datę, gdy kompilacja (build) ją obsługuje, zapisuje się jako "Date": { "Mode": 1, "Value": { "Presence": 1, "Value": { "Year": 2024, "Month": 5, "Day": 1 } } }, a czas jako { "Mode": 1, "Value": { "Presence": 1, "Value": { "Hour": 7, "Minute": 30, "Second": 0 } } }. W tym buildzie obie czynią plan niemożliwym do uruchomienia (zob. niżej).

Dokumentacja właściwości#

Kolumna „Wykorzystanie” określa, co bieżący kod robi z wartością. Stabilność jest opisana słownictwem ze strony publicznego API.

LaunchSpec (element główny)#

Akcesory tylko do odczytu (obecne w danych wyjściowych JSON CLI, ignorowane przy wczytywaniu): EffectiveYear, EffectiveWeather, EffectiveInput, EffectiveDiagnostics, EffectivePresentation, EffectiveInternetTextures.

InstallationSpec#

WorldSpec#

DateSpec, TimeSpec, YearSpec#

WeatherSpec#

PlayerVehicleSpec (wewnątrz PlayerVehicle)#

PlayerVehicle z Presence 1 i wszystkimi polami nieustawionymi jest akceptowany i nie ma żadnego efektu. Każde ustawione pole czyni plan w tym buildzie niemożliwym do uruchomienia (STATICALLY_PARTIAL).

EnvironmentSpec#

Osiem grup jest łączonych; to, w której grupie umieszczono klucz, nie ma znaczenia. Każdy wpis z Presence 1 jest ustawieniem semantycznym z ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs); klucz wybiera plik docelowy (options.cfg dla każdego obecnego klucza) i token. Planowanie sprawdza, czy klucz istnieje (OL_E_UNKNOWN_SETTING) i czy jest zapisywalny (OL_E_SETTING_NOT_WRITABLE); wartość jest walidowana dopiero przy uruchomieniu (OL_E_INVALID_SETTING_VALUE, zgłaszane jako sesja Failed z OL_E_START_SESSION). Klucze nie rozróżniają wielkości liter. Nieustawione wpisy są ignorowane. Flaga CLI /set:<key>=<value> zapisuje do General; ustawienia settings z profilu sesji również są scalane z General.

Modyfikowane pliki zachowują swoje kodowanie (bajty Windows-1252 zachowane; UTF-8/UTF-16 oznaczone BOM respektowane) i znaki końca wiersza.

LaunchBehaviorSpec#

InputSpec#

DiagnosticsSpec#

Flagi CLI /log, /logall, /omsi-logall, /verbose, /trace, /trace-process, /trace-plugin, /trace-native ustawiają te wartości logiczne (/logall ustawia Verbose, ProcessTrace, PluginTrace, NativeTrace); są one łączone operacją OR z wartościami ze specyfikacji.

SessionPresentationSpec#

InternetTexturesSpec#

SessionProfileMetadata#

Wyliczenia#

Liczby całkowite spoza zadeklarowanego zakresu są zapisywane przez serializator bez zmian i zachowują się jak nieznane wartości (na przykład nieznany WorldMode nie jest ani NEW_MAP, ani SAVED_SITUATION i daje plan bez możliwości świata; wtyczka by go odrzuciła, ale CLI i tak zastępuje tryb – zob. pierwszeństwo).

Reguły walidacji i komunikaty diagnostyczne braku możliwości uruchomienia#

PlanSessionAsync wykonuje LaunchValidation.Validate, a następnie SessionPlanner.PlanAsync. Plan jest możliwy do uruchomienia dokładnie wtedy, gdy żaden kod komunikatu diagnostycznego nie zaczyna się od OL_E_. Pełny zestaw:

Niewalidowane na etapie planowania (błąd występuje przy uruchomieniu jako sesja Failed z OL_E_START_SESSION): wartości ustawień (OL_E_INVALID_SETTING_VALUE), integralność stałej wtyczki (OL_E_PERMANENT_PLUGIN_*), dostępność dzierżawy instalacji (OL_E_INSTALLATION_BUSY), zakres StartupTimeoutSeconds (wyjątek zgłaszany przez StartSessionAsync).

Informacyjne komunikaty diagnostyczne planu: plugin.integrity.reference (komunikat manifest lub self), session_profile.selected.

Pierwszeństwo: flagi CLI, plik specyfikacji i profil sesji#

CliInput.BuildSpecAsync (tools/OmsiLaunch.Cli/Program.cs) buduje efektywną specyfikację w następującej kolejności:

1. Punkt wyjścia = wbudowane wartości domyślne lub plik /spec, jeśli go podano.
2. Katalog główny instalacji = jawny argument instalacji, jeśli podano, w przeciwnym razie RootPath z punktu wyjścia; następnie ./pusta wartość → katalog pliku wykonywalnego, Path.GetFullPath. Jawny argument instalacji zawsze ma pierwszeństwo przed RootPath ze specyfikacji.
3. Profil sesji (/predefined-profile + /predefined-profile-index): jawne argumenty CLI dotykające pola należącego do profilu są odrzucane z OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (pola świata tylko w trybie NEW_MAP; klucze /set obecne w ustawieniu wstępnym; flagi ekranu startowego, gdy ustawienie wstępne ma presentation; flagi tekstur internetowych, gdy ma internet-textures; limity czasu, gdy ma behavior). World z punktu wyjścia jest zastępowany nowym (zachowuje się tylko tryb świata z CLI), po czym stosowane są blok new: profilu (tylko NEW_MAP), settings (do General), presentation, internet-textures, behavior oraz metadane SessionProfile. compatibility.maps jest egzekwowane dla NEW_MAP i SAVED_SITUATION.
4. Świat: tryb świata z CLI zawsze wygrywa (/new domyślnie, /saved:<osn>, /last); World.Mode z pliku specyfikacji jest zastępowany. Aby uruchomić zapisaną sytuację ze specyfikacji, należy przekazać /saved:. /map oraz /entrypoint//entrypoint-index nadpisują punkt wyjścia; identyfikator /entrypoint z CLI czyści indeks; /saved razem z /map lub flagami punktu wejścia daje OL_E_INVALID_ARGUMENT.
5. /date, /time, /year, /weather* nadpisują punkt wyjścia, gdy zostały podane (system wybiera DateTimeMode.System).
6. /no-vehicle czyści PlayerVehicle; poszczególne flagi /vehicle, /repaint, /hof, /fleet, /registration nadpisują poszczególne pola pojazdu gracza z punktu wyjścia.
7. Wpisy /set:<key>=<value> są dodawane do Environment.General (klucz jest sprawdzany, wartość nie); pozostałe siedem grup pochodzi bez zmian z punktu wyjścia.
8. /startup-timeout i /shutdown-timeout nadpisują punkt wyjścia tylko wtedy, gdy zostały podane; w przeciwnym razie obowiązuje specyfikacja, potem profil, a potem wartości domyślne 180 s / 30 s. ShutdownTimeoutSeconds ma w nadzorcy status ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT.
9. /splash, /splash-language, /splash-assets, /internet-textures, /internet-textures-profile nadpisują punkt wyjścia, gdy zostały podane; SuppressTrayIcon pochodzi wyłącznie z punktu wyjścia.
10. Flagi diagnostyczne są łączone operacją OR z punktem wyjścia.

Wynik: jawna flaga CLI > profil sesji > plik specyfikacji > wbudowana wartość domyślna, z tym że flaga CLI kolidująca z polem należącym do profilu jest błędem, a nie nadpisaniem.

Reguły ścieżek#

Przenoszone, ale niestosowane#