Sessieprofielen

Documentatie voor versie v0.1.0-beta.3Bron bekijken op GitHub

Vertaling van de oorspronkelijke Engelse pagina voor OmsiLaunch 0.1.0-beta3. De Engelse pagina is normatief: bij verschillen gelden de Engelse pagina en de code.

Een sessieprofiel is een declaratief YAML-pakket dat een contentauteur met een kaart of add-on meelevert, zodat eindgebruikers met één opdracht een reproduceerbare OmsiLaunch-sessie kunnen starten (OmsiLaunch.exe /predefined-profile:<id> /predefined-profile-index:<1..5> /new). Deze pagina is de normatieve referentie voor het formaat omsilaunch.session-profile/v1 zoals geïmplementeerd door SessionProfileCompiler in src/OmsiLaunch.Core/SessionProfiles.cs, voor de voorrangsregels die de CLI toepast (CliInput.BuildSpecAsync en RejectProfileConflicts in tools/OmsiLaunch.Cli/Program.cs) en voor de catalogus van instellingen die een profiel mag schrijven (ConfigurationCatalog). Alles wat een profiel kan, kunnen de CLI-vlaggen en de LaunchSpec ook; een profiel verpakt alleen die keuzes.

Stabiliteit: STABLE_BETA voor parsing, validatie, conflictdetectie en de blokken settings / presentation / internet-textures / behavior (offline test session-profiles.strict-compiler; het overlay- en herstelpad is runtime-gevalideerd door RV-005 en RV-006, zie status van de runtimevalidatie). De sleutels new.date, new.time, new.year en new.weather zijn in deze build UNAVAILABLE (zie Het new-blok).

Locatie en naamgeving van het pakket#

Een profiel wordt geïnstalleerd en verwijderd door de gebruiker of de contentauteur. OmsiLaunch schrijft nooit in een pakket, kopieert het nooit en verwijdert het nooit. De pakketmap maakt geen deel uit van een transactie.

Parseerregels#

Backslashes in plain (niet-geciteerde) scalars zijn letterlijke tekens. Schrijf Windows-paden met één backslash (maps\Grundorf\global.cfg). Een dubbele backslash in een plain scalar blijft dubbel in de waarde; zie Het meegeleverde voorbeeld.

Sleutelreferentie#

Contexten worden precies zo genoemd als de compiler ze noemt. Elke hier vermelde sleutel wordt geaccepteerd; niets anders.

profile (hoofdmapping)#

compatibility#

new#

Het blok wordt gelezen en gevalideerd zodra het aanwezig is, maar wordt alleen op de spec toegepast wanneer de geselecteerde wereldmodus NEW_MAP is (/new, de standaard van de CLI). Onder /saved:<file.osn> wordt het blok genegeerd.

date, time, year en weather worden gecompileerd naar DateSpec, TimeSpec, YearSpec en WeatherSpec met DateTimeMode.Explicit / de geselecteerde WeatherMode. De sessieplanner (src/OmsiLaunch.Core/SessionPlanner.cs) rapporteert vervolgens de capabilities world.explicit-date, world.explicit-time, world.explicit-year en weather als STATICALLY_PARTIAL, voegt OL_E_CAPABILITY_UNAVAILABLE toe aan de plandiagnoses en markeert het plan als niet uitvoerbaar. De plugin weigert bovendien een handoff waarvan de datum- of tijdmodus niet Unset is (plugin.request.unsupported). Gevolg voor deze build: een profiel dat een van deze vier sleutels instelt, kan met /plan worden gevalideerd maar kan geen sessie starten (exitcode 1, OL_E_PLAN_NOT_RUNNABLE). Laat ze weg uit profielen die bedoeld zijn om te starten.

new.date#

new.time#

new.weather#

preset (elke vermelding van presets)#

Alleen de geselecteerde preset wordt toegepast. Elke preset wordt wel geparseerd en gevalideerd, dus een fout in preset 3 laat een aanvraag voor preset 1 mislukken.

presentation#

presentation.splash#

Een profiel kan SessionPresentationSpec.SuppressTrayIcon niet instellen; de waarde blijft false, tenzij een /spec deze instelt.

internet-textures#

behavior#

Wanneer het behavior-blok aanwezig is, worden beide timeouts ingesteld (opgegeven waarde of standaard) en vervangen ze de LaunchBehaviorSpec van de basislijn volledig, inclusief RestoreConfiguration en SuppressStaleClosecheckWarning, die terugvallen op hun standaardwaarden (true, true).

Instellingen#

De sleutels van settings zijn de semantische namen uit ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs). De compiler accepteert een sleutel alleen als die bestaat (OL_E_SESSION_PROFILE_SETTING_UNKNOWN) en schrijfbaar is (OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE). Waarden worden als strings opgeslagen en omgezet in een patch van options.cfg wanneer de sessie haar overlays opbouwt; een ongeldige waarde wordt daarom pas bij StartSessionAsync gedetecteerd, niet bij het laden van het profiel, en laat de sessie mislukken met OL_E_START_SESSION, waarvan het bericht OL_E_INVALID_SETTING_VALUE: <key> bevat. Elke onderstaande instelling schrijft naar options.cfg; ze zijn allemaal sessiegebonden en worden na de sessie exact hersteld.

Waardevormen:

• bool is true of false (niet hoofdlettergevoelig). Bij aanwezigheidstokens wordt het token toegevoegd of verwijderd; bij omgekeerde tokens (no_*) verwijdert true het negatieve token.
• int / decimal worden gevalideerd tegen het bereik; waarden met een deler worden gedeeld opgeslagen (graphics.minObjectScreenPercent: 5 schrijft bijvoorbeeld 0.05).
• string wordt letterlijk geschreven.

Catalogusvermeldingen die bestaan maar niet schrijfbaar zijn (geweigerd met OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE): advanced.multithreadingCalculate, advanced.multithreadingTextureLoad (vervangen door advanced.reducedMultithreading), graphics.texture, graphics.textureFilter.

Padbeperking#

presentation.splash.assets en internet-textures.profile worden opgelost door Confined(package root, value):

1. Geroote paden (C:\...), paden die met \ beginnen en elk padcomponent dat gelijk is aan .. worden geweigerd.
2. Het volledige pad wordt berekend en moet met de pakketmap beginnen.
3. Elk bestaand component onder de pakketroot, tot en met het uiteindelijke pad, wordt gecontroleerd op het kenmerk ReparsePoint. Een junction, symbolische koppeling naar een map of symbolische koppeling naar een bestand waar dan ook op dat pad wordt geweigerd, evenals een component dat niet kan worden gecontroleerd (IOException / UnauthorizedAccessException).

Alle drie de fouten geven OL_E_SESSION_PROFILE_PATH_ESCAPE. Dezelfde regel voor reparsepunten wordt bij het opbouwen van de sessie toegepast op .itx-doelen onder Texture\.

Voorrang en overschrijvingsconflicten#

CliInput.BuildSpecAsync stelt de spec in deze volgorde samen:

1. Standaardwaarden (NEW_MAP, alles niet ingesteld, timeouts 180 s / 30 s).
2. /spec:<file.json>, indien opgegeven, vervangt de standaardwaarden volledig.
3. Installatiemap: een expliciet installatieargument heeft voorrang op de RootPath van de spec; . betekent de map die het uitvoerbare bestand bevat.
4. Profiel (/predefined-profile + /predefined-profile-index): het pakket wordt geladen en RejectProfileConflicts wordt uitgevoerd tegen de onbewerkte CLI-argumenten, voordat er iets wordt samengevoegd. Het wereldblok van de basis wordt daarna teruggezet naar een lege WorldSpec van de geselecteerde modus (een /spec-wereld wordt verworpen wanneer een profiel wordt gebruikt) en SessionProfileCompiler.Apply legt het profiel over de basis: new (alleen NEW_MAP), settings (samengevoegd over Environment.General van de basis, het profiel wint per sleutel), en presentation, internet-textures, behavior (elk vervangt het blok van de basis alleen wanneer de preset het definieert).
5. Overige CLI-argumenten worden daarbovenop gelegd: /map, /entrypoint, /entrypoint-index, /date, /time, /year, weervlaggen, voertuigvlaggen, /set, splash-vlaggen, internettexture-vlaggen, /startup-timeout, /shutdown-timeout. Timeouts uit de CLI gelden alleen wanneer ze zijn opgegeven; anders blijft de waarde uit spec, profiel of standaard staan.
6. Compatibiliteitscontrole voor modi anders dan NEW_MAP (ValidateCompatibility).

Een CLI-argument dat een veld raakt dat het geselecteerde profiel beheert, is een conflict en wordt geweigerd met OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (exitcode 2, categorie invalid_argument). De controle is per veld, niet per waarde: het herhalen van de eigen waarde van het profiel is nog steeds een conflict.

Geen conflicten: /set-sleutels die de preset niet definieert (ze worden toegevoegd), voertuigvlaggen (/vehicle, /repaint, /hof, /fleet, /registration, /no-vehicle; een profiel kan geen spelersvoertuig definiëren) en elk wereldargument onder /saved (het new-blok wordt daar niet toegepast). /map, /entrypoint en /entrypoint-index zijn ongeldig in combinatie met /saved, ongeacht profielen (OL_E_INVALID_ARGUMENT).

Foutcodes#

Al deze fouten worden gegenereerd terwijl de opdrachtregel wordt gecompileerd, vóór het plannen. Het zijn SessionProfileException (of ArgumentException voor het conflict) en ze starten nooit een sessie. De volledige catalogus staat in foutcodes; exitcodes in exitcodes.

Hoe een profiel in de API verschijnt#

Na een geslaagde lading bevat de spec een SessionProfileMetadata-record in LaunchSpec.SessionProfile:

De planner voegt aan elk SessionPlan dat uit zo'n spec wordt opgebouwd een informatieve diagnose session_profile.selected toe, met de gegevenssleutels session_profile.id, session_profile.name, session_profile.version, session_profile.author, session_profile.preset_id, session_profile.preset_index, session_profile.preset_name en session_profile.path. Deze heeft geen invloed op de uitvoerbaarheid. Integrators die de openbare API rechtstreeks gebruiken, kunnen SessionProfileCompiler.Load en SessionProfileCompiler.Apply uit OmsiLaunch.Core aanroepen; de YAML-representatie komt nooit in OmsiLaunch.Api terecht.

Voorbeelden#

Voorbeeld 1: profiel met alleen instellingen, één 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

Uitvoeren: OmsiLaunch.exe /predefined-profile:quiet-evening /predefined-profile-index:1 /new /map:maps\Grundorf\global.cfg /entrypoint-index:0. De kaart en het instappunt komen van de opdrachtregel omdat het profiel geen new-blok definieert; /set:graphics.maxFPS=60 toevoegen is toegestaan, /set:traffic.humans=10 toevoegen is een conflict.

Voorbeeld 2: kaartgebonden profiel met drie presets en meegeleverde assets#

<root>\.omsilaunch\session-profiles\grundorf-tour\profile.yaml, met assets\splash\ENG.bmp, assets\splash\DEU.bmp en textures\offline.itx binnen het pakket:

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

Uitvoeren: OmsiLaunch.exe /predefined-profile:grundorf-tour /predefined-profile-index:2 /new. Met /saved:situations\mytrip.osn wordt het new-blok overgeslagen en moet de .osn verwijzen naar maps\Grundorf\global.cfg.

Het meegeleverde voorbeeld#

De release bevat docs/examples/session-profiles/rmg-leste/profile.yaml (bekijken). Het is syntactisch geldig, voldoet aan het schema en zou zonder fouten laden. Twee eigenschappen verhinderen dat het in deze build ongewijzigd een sessie start:

1. Het stelt new.date, new.time en new.weather in, waardoor het plan niet uitvoerbaar is (zie Het new-blok).
2. De padwaarden zijn plain scalars met dubbele backslashes (maps\\RMG Leste\\global.cfg). YAML laat ze dubbel en kaartidentiteiten worden tekstueel vergeleken (alleen na normalisatie van / naar \), zodat new.map en compatibility.maps niet overeenkomen met de catalogusidentiteit maps\RMG Leste\global.cfg (OL_E_MAP_NOT_FOUND bij het plannen). De waarde assets wordt wel opgelost, omdat de Windows-padnormalisatie dubbele scheidingstekens samenvoegt.

De uitvoerbare vorm voor deze build is:

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

Gerelateerde pagina's#

• CLI-referentie voor /predefined-profile, /predefined-profile-index, /set en de wereldvlaggen
• LaunchSpec voor het record waarnaar een profiel wordt gecompileerd
• Transacties en recovery voor hoe overlays van settings, het opstartscherm en .itx worden toegepast en hersteld
• Capabilities en status van de runtimevalidatie