Profili di sessione

Documentazione della versione v0.1.0-beta.3Vedi il sorgente su GitHub

Traduzione della pagina originale in inglese di OmsiLaunch 0.1.0-beta3. La pagina inglese è normativa: in caso di differenze prevalgono la pagina inglese e il codice.

Un profilo di sessione è un pacchetto YAML dichiarativo che un autore di contenuti distribuisce con una mappa o un add-on affinché gli utenti finali possano avviare una sessione OmsiLaunch riproducibile con un solo comando (OmsiLaunch.exe /predefined-profile:<id> /predefined-profile-index:<1..5> /new). Questa pagina è il riferimento normativo per il formato omsilaunch.session-profile/v1 così come è implementato da SessionProfileCompiler in src/OmsiLaunch.Core/SessionProfiles.cs, per le regole di precedenza applicate dalla CLI (CliInput.BuildSpecAsync e RejectProfileConflicts in tools/OmsiLaunch.Cli/Program.cs) e per il catalogo delle impostazioni che un profilo può scrivere (ConfigurationCatalog). Tutto ciò che un profilo può fare è possibile anche con i flag della CLI e con LaunchSpec; un profilo si limita a impacchettare quelle scelte.

Stabilità: STABLE_BETA per l'analisi, la validazione, il rilevamento dei conflitti e i blocchi settings / presentation / internet-textures / behavior (test offline session-profiles.strict-compiler; il percorso di overlay e ripristino è validato a runtime da RV-005 e RV-006, vedere stato della validazione a runtime). Le chiavi new.date, new.time, new.year e new.weather sono UNAVAILABLE in questo build (vedere Il blocco new).

Posizione e denominazione del pacchetto#

Un profilo viene installato e rimosso dall'utente o dall'autore dei contenuti. OmsiLaunch non scrive mai in un pacchetto, non lo copia mai e non lo elimina mai. La directory del pacchetto non fa parte di alcuna transazione.

Regole di analisi#

Le barre rovesciate negli scalari plain (senza virgolette) sono caratteri letterali. Scrivere i percorsi Windows con una sola barra rovesciata (maps\Grundorf\global.cfg). Una barra rovesciata doppia in uno scalare plain resta doppia nel valore; vedere L'esempio incluso nel pacchetto.

Riferimento delle chiavi#

I contesti sono denominati esattamente come li denomina il compilatore. Ogni chiave elencata qui è accettata; nient'altro lo è.

profile (mapping radice)#

compatibility#

new#

Il blocco viene letto e validato ogni volta che è presente, ma viene applicato alla specifica solo quando la modalità del mondo selezionata è NEW_MAP (/new, il valore predefinito della CLI). Con /saved:<file.osn> il blocco viene ignorato.

date, time, year e weather vengono compilati in DateSpec, TimeSpec, YearSpec e WeatherSpec con DateTimeMode.Explicit / il WeatherMode selezionato. Il planner di sessione (src/OmsiLaunch.Core/SessionPlanner.cs) segnala quindi le capability world.explicit-date, world.explicit-time, world.explicit-year e weather come STATICALLY_PARTIAL, aggiunge OL_E_CAPABILITY_UNAVAILABLE alla diagnostica del piano e contrassegna il piano come non eseguibile. Il plugin rifiuta inoltre un handoff la cui modalità di data o di orario non sia Unset (plugin.request.unsupported). Conseguenza per questo build: un profilo che imposta una qualsiasi di queste quattro chiavi può essere validato con /plan ma non può avviare una sessione (codice di uscita 1, OL_E_PLAN_NOT_RUNNABLE). Ometterle nei profili destinati a essere eseguiti.

new.date#

new.time#

new.weather#

preset (ogni voce di presets)#

Viene applicato solo il preset selezionato. Ogni preset viene comunque analizzato e validato, quindi un errore nel preset 3 fa fallire una richiesta per il preset 1.

presentation#

presentation.splash#

Un profilo non può impostare SessionPresentationSpec.SuppressTrayIcon; resta false a meno che non lo imposti un /spec.

internet-textures#

behavior#

Quando il blocco behavior è presente, entrambi i timeout vengono impostati (valore indicato o predefinito) e sostituiscono interamente il LaunchBehaviorSpec di base, inclusi RestoreConfiguration e SuppressStaleClosecheckWarning, che tornano ai loro valori predefiniti (true, true).

Impostazioni#

Le chiavi di settings sono i nomi semantici di ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs). Il compilatore accetta una chiave solo se esiste (OL_E_SESSION_PROFILE_SETTING_UNKNOWN) ed è scrivibile (OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE). I valori vengono memorizzati come stringhe e convertiti in una modifica di options.cfg quando la sessione costruisce i propri overlay; un valore non valido viene quindi rilevato in StartSessionAsync, non al caricamento del profilo, e fa fallire la sessione con OL_E_START_SESSION, il cui messaggio contiene OL_E_INVALID_SETTING_VALUE: <key>. Ogni impostazione seguente scrive options.cfg; tutte sono limitate alla sessione e vengono ripristinate in modo esatto dopo la sessione.

Forme dei valori:

• bool è true o false (senza distinzione tra maiuscole e minuscole). Per i token di presenza il token viene aggiunto o rimosso; per i token invertiti (no_*) true rimuove il token negativo.
• int / decimal vengono validati rispetto all'intervallo; i valori con un divisore vengono memorizzati divisi (ad esempio graphics.minObjectScreenPercent: 5 scrive 0.05).
• string viene scritto testualmente.

Voci del catalogo che esistono ma non sono scrivibili (rifiutate con OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE): advanced.multithreadingCalculate, advanced.multithreadingTextureLoad (sostituite da advanced.reducedMultithreading), graphics.texture, graphics.textureFilter.

Confinamento dei percorsi#

presentation.splash.assets e internet-textures.profile vengono risolti da Confined(package root, value):

1. I percorsi radicati (C:\...), i percorsi che iniziano con \ e qualsiasi componente del percorso uguale a .. vengono rifiutati.
2. Viene calcolato il percorso completo, che deve iniziare con la directory del pacchetto.
3. Ogni componente esistente al di sotto della radice del pacchetto, fino al percorso finale incluso, viene ispezionato per verificare l'attributo ReparsePoint. Una junction, un collegamento simbolico a directory o un collegamento simbolico a file in qualunque punto di quel percorso viene rifiutato, così come un componente che non può essere ispezionato (IOException / UnauthorizedAccessException).

Tutti e tre gli errori producono OL_E_SESSION_PROFILE_PATH_ESCAPE. La stessa regola sui reparse point viene applicata alle destinazioni .itx sotto Texture\ alla costruzione della sessione.

Precedenza e conflitti di sovrascrittura#

CliInput.BuildSpecAsync compone la specifica in questo ordine:

1. Valori predefiniti (NEW_MAP, tutto non impostato, timeout 180 s / 30 s).
2. /spec:<file.json>, se indicato, sostituisce interamente i valori predefiniti.
3. Radice dell'installazione: un argomento di installazione esplicito prevale sul RootPath della specifica; . indica la directory che contiene l'eseguibile.
4. Profilo (/predefined-profile + /predefined-profile-index): il pacchetto viene caricato e RejectProfileConflicts viene eseguito sugli argomenti grezzi della CLI prima che venga unito qualsiasi elemento. Il blocco del mondo della base viene quindi reimpostato a un WorldSpec vuoto della modalità selezionata (un mondo di /spec viene scartato quando si usa un profilo) e SessionProfileCompiler.Apply sovrappone il profilo alla base: new (solo NEW_MAP), settings (unite sopra l'Environment.General della base, il profilo prevale per ogni chiave) e presentation, internet-textures, behavior (ciascuno sostituisce il blocco della base solo quando il preset lo definisce).
5. Argomenti della CLI rimanenti vengono sovrapposti: /map, /entrypoint, /entrypoint-index, /date, /time, /year, flag meteo, flag del veicolo, /set, flag della splash, flag delle internet-textures, /startup-timeout, /shutdown-timeout. I timeout della CLI si applicano solo quando indicati; altrimenti resta valido il valore della specifica/del profilo/predefinito.
6. Controllo di compatibilità per le modalità diverse da NEW_MAP (ValidateCompatibility).

Un argomento della CLI che punta a un campo di proprietà del profilo selezionato è un conflitto, rifiutato con OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (codice di uscita 2, categoria invalid_argument). Il controllo è per campo, non per valore: ripetere lo stesso valore del profilo è comunque un conflitto.

Non sono conflitti: le chiavi /set che il preset non definisce (vengono aggiunte), i flag del veicolo (/vehicle, /repaint, /hof, /fleet, /registration, /no-vehicle; un profilo non può definire un veicolo del giocatore) e qualsiasi argomento del mondo con /saved (lì il blocco new non viene applicato). /map, /entrypoint e /entrypoint-index non sono validi insieme a /saved indipendentemente dai profili (OL_E_INVALID_ARGUMENT).

Codici di errore#

Tutti questi errori vengono generati durante la compilazione della riga di comando, prima della pianificazione. Sono SessionProfileException (o ArgumentException per il conflitto) e non avviano mai una sessione. Il catalogo completo si trova in errori; i codici di uscita in codici di uscita.

Come appare un profilo nell'API#

Dopo un caricamento riuscito la specifica contiene un record SessionProfileMetadata in LaunchSpec.SessionProfile:

Il planner aggiunge una voce di diagnostica informativa session_profile.selected a ogni SessionPlan costruito da una tale specifica, con le chiavi di dati session_profile.id, session_profile.name, session_profile.version, session_profile.author, session_profile.preset_id, session_profile.preset_index, session_profile.preset_name e session_profile.path. Non influisce sull'eseguibilità. Gli integratori che usano direttamente l'API pubblica possono chiamare SessionProfileCompiler.Load e SessionProfileCompiler.Apply da OmsiLaunch.Core; la rappresentazione YAML non attraversa mai il confine verso OmsiLaunch.Api.

Esempi#

Esempio 1: profilo con sole impostazioni, un preset#

<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

Esecuzione: OmsiLaunch.exe /predefined-profile:quiet-evening /predefined-profile-index:1 /new /map:maps\Grundorf\global.cfg /entrypoint-index:0. La mappa e il punto di ingresso provengono dalla riga di comando perché il profilo non definisce alcun blocco new; aggiungere /set:graphics.maxFPS=60 è consentito, aggiungere /set:traffic.humans=10 è un conflitto.

Esempio 2: profilo legato a una mappa con tre preset e asset nel pacchetto#

<root>\.omsilaunch\session-profiles\grundorf-tour\profile.yaml, con assets\splash\ENG.bmp, assets\splash\DEU.bmp e textures\offline.itx all'interno del pacchetto:

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

Esecuzione: OmsiLaunch.exe /predefined-profile:grundorf-tour /predefined-profile-index:2 /new. Con /saved:situations\mytrip.osn il blocco new viene saltato e il file .osn deve referenziare maps\Grundorf\global.cfg.

L'esempio incluso nel pacchetto#

Il rilascio include docs/examples/session-profiles/rmg-leste/profile.yaml (visualizza). È sintatticamente valido, rispetta lo schema e verrebbe caricato senza errori. Due caratteristiche gli impediscono di avviare una sessione senza modifiche in questo build:

1. Imposta new.date, new.time e new.weather, che rendono il piano non eseguibile (vedere Il blocco new).
2. I suoi valori di percorso sono scalari plain con barre rovesciate doppie (maps\\RMG Leste\\global.cfg). YAML le mantiene doppie e le identità delle mappe vengono confrontate testualmente (solo dopo la normalizzazione da / a \), quindi new.map e compatibility.maps non corrisponderebbero all'identità di catalogo maps\RMG Leste\global.cfg (OL_E_MAP_NOT_FOUND in fase di pianificazione). Il valore assets viene comunque risolto perché la normalizzazione dei percorsi di Windows comprime i separatori doppi.

La forma eseguibile per questo build è:

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

Pagine correlate#

• Riferimento CLI per /predefined-profile, /predefined-profile-index, /set e i flag del mondo
• LaunchSpec per il record in cui viene compilato un profilo
• Transazioni e recupero per il modo in cui gli overlay di settings, della splash screen e .itx vengono applicati e ripristinati
• Capability e stato della validazione a runtime