Profile sesji

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.

Profil sesji to deklaratywny pakiet YAML, który autor zawartości dostarcza razem z mapą lub dodatkiem, aby użytkownicy końcowi mogli jednym poleceniem uruchomić powtarzalną sesję OmsiLaunch (OmsiLaunch.exe /predefined-profile:<id> /predefined-profile-index:<1..5> /new). Ta strona jest normatywną dokumentacją referencyjną formatu omsilaunch.session-profile/v1 w postaci zaimplementowanej przez SessionProfileCompiler w src/OmsiLaunch.Core/SessionProfiles.cs, reguł pierwszeństwa stosowanych przez CLI (CliInput.BuildSpecAsync i RejectProfileConflicts w tools/OmsiLaunch.Cli/Program.cs) oraz katalogu ustawień, które profil może zapisywać (ConfigurationCatalog). Wszystko, co potrafi profil, można też zrobić za pomocą flag CLI i rekordu LaunchSpec; profil jedynie pakuje te wybory.

Stabilność: STABLE_BETA dla parsowania, walidacji, wykrywania konfliktów oraz bloków settings / presentation / internet-textures / behavior (test offline session-profiles.strict-compiler; ścieżka nakładki (overlay) i przywracania jest zweryfikowana w runtime przez RV-005 i RV-006, zob. stan weryfikacji w runtime). Klucze new.date, new.time, new.year i new.weather są w tym buildzie UNAVAILABLE (zob. Blok new).

Lokalizacja i nazewnictwo pakietu#

Profil instaluje i usuwa użytkownik lub autor zawartości. OmsiLaunch nigdy nie zapisuje niczego w pakiecie, nigdy go nie kopiuje i nigdy go nie usuwa. Katalog pakietu nie jest częścią żadnej transakcji.

Reguły parsowania#

Ukośniki odwrotne w zwykłych (niecytowanych) skalarach są znakami dosłownymi. Ścieżki Windows należy zapisywać z pojedynczym ukośnikiem odwrotnym (maps\Grundorf\global.cfg). Podwojony ukośnik odwrotny w zwykłym skalarze pozostaje w wartości podwojony; zob. Przykład dołączony do pakietu.

Dokumentacja kluczy#

Konteksty są nazwane dokładnie tak, jak nazywa je kompilator. Każdy wymieniony tu klucz jest akceptowany; żaden inny nie jest.

profile (mapowanie główne)#

compatibility#

new#

Blok jest odczytywany i walidowany zawsze, gdy jest obecny, ale do specyfikacji jest stosowany tylko wtedy, gdy wybranym trybem świata jest NEW_MAP (/new, domyślny tryb CLI). Przy /saved:<file.osn> blok jest ignorowany.

date, time, year i weather są kompilowane do DateSpec, TimeSpec, YearSpec i WeatherSpec z DateTimeMode.Explicit / wybranym WeatherMode. Planista sesji (src/OmsiLaunch.Core/SessionPlanner.cs) zgłasza wtedy możliwości world.explicit-date, world.explicit-time, world.explicit-year i weather jako STATICALLY_PARTIAL, dodaje OL_E_CAPABILITY_UNAVAILABLE do komunikatów diagnostycznych planu i oznacza plan jako niemożliwy do uruchomienia. Wtyczka dodatkowo odrzuca przekazanie, którego tryb daty lub czasu nie ma wartości Unset (plugin.request.unsupported). Skutek dla tego buildu: profil ustawiający którykolwiek z tych czterech kluczy można zwalidować za pomocą /plan, ale nie można nim uruchomić sesji (kod wyjścia 1, OL_E_PLAN_NOT_RUNNABLE). W profilach przeznaczonych do uruchamiania należy je pominąć.

new.date#

new.time#

new.weather#

preset (każdy wpis w presets)#

Stosowane jest tylko wybrane ustawienie wstępne. Każde ustawienie wstępne jest jednak parsowane i walidowane, więc błąd w ustawieniu wstępnym 3 powoduje niepowodzenie żądania ustawienia wstępnego 1.

presentation#

presentation.splash#

Profil nie może ustawić SessionPresentationSpec.SuppressTrayIcon; pozostaje ono false, chyba że ustawi je /spec.

internet-textures#

behavior#

Gdy obecny jest blok behavior, ustawiane są oba limity czasu (podana wartość lub domyślna) i całkowicie zastępują bazowy LaunchBehaviorSpec, w tym RestoreConfiguration i SuppressStaleClosecheckWarning, które wracają do wartości domyślnych (true, true).

Ustawienia#

Klucze settings to semantyczne nazwy z ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs). Kompilator akceptuje klucz tylko wtedy, gdy istnieje (OL_E_SESSION_PROFILE_SETTING_UNKNOWN) i jest zapisywalny (OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE). Wartości są przechowywane jako ciągi znaków i przekształcane w poprawkę options.cfg, gdy sesja buduje swoje nakładki; nieprawidłowa wartość jest więc wykrywana w StartSessionAsync, a nie przy wczytywaniu profilu, i powoduje niepowodzenie sesji z OL_E_START_SESSION, którego komunikat zawiera OL_E_INVALID_SETTING_VALUE: <key>. Każde z poniższych ustawień zapisuje options.cfg; wszystkie mają zasięg sesji i po jej zakończeniu są dokładnie przywracane.

Postacie wartości:

• bool to true lub false (bez rozróżniania wielkości liter). W przypadku tokenów obecności token jest dodawany lub usuwany; w przypadku tokenów odwróconych (no_*) wartość true usuwa token negatywny.
• int / decimal są walidowane względem zakresu; wartości z dzielnikiem są zapisywane po podzieleniu (na przykład graphics.minObjectScreenPercent: 5 zapisuje 0.05).
• string jest zapisywany dosłownie.

Wpisy katalogu, które istnieją, ale nie są zapisywalne (odrzucane z OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE): advanced.multithreadingCalculate, advanced.multithreadingTextureLoad (zastąpione przez advanced.reducedMultithreading), graphics.texture, graphics.textureFilter.

Ograniczenie ścieżek#

presentation.splash.assets i internet-textures.profile są rozwiązywane przez Confined(package root, value):

1. Ścieżki zakorzenione (C:\...), ścieżki zaczynające się od \ oraz każda ścieżka ze składową równą .. są odrzucane.
2. Obliczana jest pełna ścieżka, która musi zaczynać się od katalogu pakietu.
3. Każda istniejąca składowa poniżej katalogu głównego pakietu, aż do ścieżki końcowej włącznie, jest sprawdzana pod kątem atrybutu ReparsePoint. Połączenie (junction), dowiązanie symboliczne katalogu lub dowiązanie symboliczne pliku w dowolnym miejscu tej ścieżki jest odrzucane, podobnie jak składowa, której nie da się sprawdzić (IOException / UnauthorizedAccessException).

Wszystkie trzy błędy to OL_E_SESSION_PROFILE_PATH_ESCAPE. Ta sama reguła punktów ponownej analizy jest stosowana przy budowaniu sesji do celów .itx w Texture\.

Pierwszeństwo i konflikty nadpisań#

CliInput.BuildSpecAsync składa specyfikację w następującej kolejności:

1. Wartości domyślne (NEW_MAP, wszystko nieustawione, limity czasu 180 s / 30 s).
2. /spec:<file.json>, jeśli podano, całkowicie zastępuje wartości domyślne.
3. Katalog główny instalacji: jawny argument instalacji wygrywa z RootPath ze specyfikacji; . oznacza katalog zawierający plik wykonywalny.
4. Profil (/predefined-profile + /predefined-profile-index): pakiet jest wczytywany, a RejectProfileConflicts działa na surowych argumentach CLI zanim cokolwiek zostanie scalone. Blok świata z punktu wyjścia jest następnie resetowany do pustego WorldSpec wybranego trybu (świat z /spec jest odrzucany, gdy używany jest profil), a SessionProfileCompiler.Apply nakłada profil na punkt wyjścia: new (tylko NEW_MAP), settings (scalane na Environment.General z punktu wyjścia, profil wygrywa dla każdego klucza) oraz presentation, internet-textures, behavior (każdy zastępuje blok z punktu wyjścia tylko wtedy, gdy ustawienie wstępne go definiuje).
5. Pozostałe argumenty CLI są nakładane na wierzch: /map, /entrypoint, /entrypoint-index, /date, /time, /year, flagi pogody, flagi pojazdu, /set, flagi ekranu startowego, flagi tekstur internetowych, /startup-timeout, /shutdown-timeout. Limity czasu z CLI są stosowane tylko wtedy, gdy zostały podane; w przeciwnym razie obowiązuje wartość ze specyfikacji/profilu/domyślna.
6. Sprawdzenie zgodności dla trybów innych niż NEW_MAP (ValidateCompatibility).

Argument CLI, który dotyczy pola należącego do wybranego profilu, jest konfliktem odrzucanym z OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (kod wyjścia 2, kategoria invalid_argument). Sprawdzenie odbywa się na poziomie pola, a nie wartości: powtórzenie wartości zdefiniowanej w profilu też jest konfliktem.

Nie są konfliktami: klucze /set, których ustawienie wstępne nie definiuje (są dodawane), flagi pojazdu (/vehicle, /repaint, /hof, /fleet, /registration, /no-vehicle; profil nie może definiować pojazdu gracza) oraz dowolny argument świata przy /saved (blok new nie jest tam stosowany). /map, /entrypoint i /entrypoint-index są nieprawidłowe razem z /saved niezależnie od profili (OL_E_INVALID_ARGUMENT).

Kody błędów#

Wszystkie te błędy są zgłaszane podczas kompilowania wiersza polecenia, przed planowaniem. Są to wyjątki SessionProfileException (lub ArgumentException w przypadku konfliktu) i nigdy nie uruchamiają sesji. Pełny katalog znajduje się w dokumentacji błędów; kody wyjścia – w dokumentacji kodów wyjścia.

Jak profil jest widoczny w API#

Po pomyślnym wczytaniu specyfikacja zawiera rekord SessionProfileMetadata w LaunchSpec.SessionProfile:

Planista dodaje informacyjny komunikat diagnostyczny session_profile.selected do każdego SessionPlan zbudowanego z takiej specyfikacji, z kluczami danych session_profile.id, session_profile.name, session_profile.version, session_profile.author, session_profile.preset_id, session_profile.preset_index, session_profile.preset_name i session_profile.path. Nie wpływa on na możliwość uruchomienia. Integratorzy korzystający bezpośrednio z publicznego API mogą wywoływać SessionProfileCompiler.Load i SessionProfileCompiler.Apply z OmsiLaunch.Core; reprezentacja YAML nigdy nie przechodzi do OmsiLaunch.Api.

Przykłady#

Przykład 1: profil zawierający tylko ustawienia, jedno ustawienie wstępne#

<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

Uruchomienie: OmsiLaunch.exe /predefined-profile:quiet-evening /predefined-profile-index:1 /new /map:maps\Grundorf\global.cfg /entrypoint-index:0. Mapa i punkt wejścia pochodzą z wiersza polecenia, ponieważ profil nie definiuje bloku new; dodanie /set:graphics.maxFPS=60 jest dozwolone, a dodanie /set:traffic.humans=10 jest konfliktem.

Przykład 2: profil powiązany z mapą, z trzema ustawieniami wstępnymi i zasobami w pakiecie#

<root>\.omsilaunch\session-profiles\grundorf-tour\profile.yaml, z plikami assets\splash\ENG.bmp, assets\splash\DEU.bmp i textures\offline.itx wewnątrz pakietu:

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

Uruchomienie: OmsiLaunch.exe /predefined-profile:grundorf-tour /predefined-profile-index:2 /new. Przy /saved:situations\mytrip.osn blok new jest pomijany, a plik .osn musi wskazywać na maps\Grundorf\global.cfg.

Przykład dołączony do pakietu#

Wydanie zawiera docs/examples/session-profiles/rmg-leste/profile.yaml (podgląd). Jest on poprawny składniowo, zgodny ze schematem i wczytałby się bez błędów. Dwie jego właściwości sprawiają, że w tym buildzie w niezmienionej postaci nie uruchamia sesji:

1. Ustawia new.date, new.time i new.weather, co czyni plan niemożliwym do uruchomienia (zob. Blok new).
2. Jego wartości ścieżek to zwykłe skalary z podwojonymi ukośnikami odwrotnymi (maps\\RMG Leste\\global.cfg). YAML zachowuje je podwojone, a identyfikatory map są porównywane tekstowo (wyłącznie po normalizacji / do \), więc new.map i compatibility.maps nie pasowałyby do identyfikatora z katalogu maps\RMG Leste\global.cfg (OL_E_MAP_NOT_FOUND podczas planowania). Wartość assets nadal się rozwiązuje, ponieważ normalizacja ścieżek Windows scala podwojone separatory.

Postać możliwa do uruchomienia w tym buildzie:

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

Powiązane strony#

• Dokumentacja CLI – /predefined-profile, /predefined-profile-index, /set i flagi świata
• LaunchSpec – rekord, do którego kompilowany jest profil
• Transakcje i odzyskiwanie – sposób stosowania i przywracania nakładek settings, ekranu startowego i .itx
• Możliwości i stan weryfikacji w runtime