LaunchSpec-referentie

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.

Deze pagina is de normatieve referentie voor LaunchSpec, het aanvraagrecord dat één OmsiLaunch-sessie beschrijft: de C#-vorm (OmsiLaunch.Api), de JSON-bestandsvorm zoals de CLI die laadt (/spec:<path>, tools/OmsiLaunch.Cli/LaunchSpecJson.cs), elke eigenschap met type, standaardwaarde, validatieregel en huidig effect, de validatieregels die een plan niet uitvoerbaar maken, en de voorrang tussen CLI-vlaggen, spec-bestanden en sessieprofielen. Alleen wat de huidige code doet, is gedocumenteerd.

Gerelateerde pagina's: openbare API, CLI-referentie, sessieprofielen, foutcodes, sessielevenscyclus, capabilities.

Waar een LaunchSpec vandaan komt#

Het volledige voorbeeld hieronder is gecontroleerd tegen de vorm van het record. Een kopie van het minimale voorbeeld wordt meegeleverd als examples/release-session.example.json (en .omsilaunch\examples\release-session.example.json in het releasepakket).

JSON-vorm#

Volledig voorbeeld#

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

Een expliciete datum wordt, als de build dat ondersteunt, geschreven als "Date": { "Mode": 1, "Value": { "Presence": 1, "Value": { "Year": 2024, "Month": 5, "Day": 1 } } } en een tijd als { "Mode": 1, "Value": { "Presence": 1, "Value": { "Hour": 7, "Minute": 30, "Second": 0 } } }. In deze build maken beide het plan niet uitvoerbaar (zie hieronder).

Eigenschappenreferentie#

De kolom "Verwerkt" vermeldt wat de huidige code met de waarde doet. Stabiliteit gebruikt de terminologie van de pagina over de openbare API.

LaunchSpec (hoofdniveau)#

Alleen-lezen accessors (aanwezig in JSON-uitvoer van de CLI, genegeerd bij het laden): EffectiveYear, EffectiveWeather, EffectiveInput, EffectiveDiagnostics, EffectivePresentation, EffectiveInternetTextures.

InstallationSpec#

WorldSpec#

DateSpec, TimeSpec, YearSpec#

WeatherSpec#

PlayerVehicleSpec (binnen PlayerVehicle)#

Een PlayerVehicle met Presence 1 en alle velden niet ingesteld wordt geaccepteerd en heeft geen effect. Elk ingesteld veld maakt het plan in deze build niet uitvoerbaar (STATICALLY_PARTIAL).

EnvironmentSpec#

De acht groepen worden samengevoegd; de groep waarin een sleutel staat, heeft geen effect. Elke vermelding met Presence 1 is een semantische instelling uit ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs); de sleutel bepaalt het doelbestand (options.cfg voor elke huidige sleutel) en het token. Bij het plannen wordt gecontroleerd of de sleutel bestaat (OL_E_UNKNOWN_SETTING) en schrijfbaar is (OL_E_SETTING_NOT_WRITABLE); de waarde wordt pas bij de start gevalideerd (OL_E_INVALID_SETTING_VALUE, gemeld als een Failed-sessie met OL_E_START_SESSION). Sleutels zijn niet hoofdlettergevoelig. Niet-ingestelde vermeldingen worden genegeerd. De CLI-vlag /set:<key>=<value> schrijft naar General; settings uit sessieprofielen worden eveneens samengevoegd in General.

Gepatchte bestanden behouden hun codering (Windows-1252-bytes blijven behouden; UTF-8/UTF-16 met BOM wordt gerespecteerd) en regeleinden.

LaunchBehaviorSpec#

InputSpec#

DiagnosticsSpec#

De CLI-vlaggen /log, /logall, /omsi-logall, /verbose, /trace, /trace-process, /trace-plugin, /trace-native vullen deze booleans (/logall stelt Verbose, ProcessTrace, PluginTrace, NativeTrace in); ze worden met een OF-bewerking gecombineerd met de waarden uit de spec.

SessionPresentationSpec#

InternetTexturesSpec#

SessionProfileMetadata#

Enumeraties#

Gehele getallen buiten het gedeclareerde bereik worden door de serializer ongewijzigd opgeslagen en gedragen zich als onbekende waarden (een onbekende WorldMode is bijvoorbeeld noch NEW_MAP noch SAVED_SITUATION en levert een plan op zonder wereld-capability; de plugin zou het weigeren, maar de CLI vervangt de modus hoe dan ook, zie voorrang).

Validatieregels en diagnoses voor niet-uitvoerbare plannen#

PlanSessionAsync voert LaunchValidation.Validate uit en daarna SessionPlanner.PlanAsync. Een plan is uitvoerbaar precies wanneer geen enkele diagnosecode met OL_E_ begint. De volledige set:

Niet gevalideerd tijdens het plannen (mislukt bij de start als Failed-sessie met OL_E_START_SESSION): instellingswaarden (OL_E_INVALID_SETTING_VALUE), integriteit van de permanente plugin (OL_E_PERMANENT_PLUGIN_*), beschikbaarheid van de lease (OL_E_INSTALLATION_BUSY), bereik van StartupTimeoutSeconds (exceptie van StartSessionAsync).

Informatieve plandiagnoses: plugin.integrity.reference (bericht manifest of self), session_profile.selected.

Voorrang: CLI-vlaggen, spec-bestand en sessieprofiel#

CliInput.BuildSpecAsync (tools/OmsiLaunch.Cli/Program.cs) bouwt de effectieve spec in deze volgorde op:

1. Basis = ingebouwde standaardwaarden, of het /spec-bestand wanneer opgegeven.
2. Installatiemap = het expliciete installatieargument indien opgegeven, anders de RootPath van de basis; daarna ./leeg → map van het uitvoerbare bestand, Path.GetFullPath. Een expliciet installatieargument heeft altijd voorrang op de RootPath van de spec.
3. Sessieprofiel (/predefined-profile + /predefined-profile-index): expliciete CLI-argumenten die een veld raken dat het profiel beheert, worden geweigerd met OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (wereldvelden alleen in NEW_MAP-modus; /set-sleutels die in de preset voorkomen; splash-vlaggen wanneer de preset presentation heeft; internettexture-vlaggen wanneer de preset internet-textures heeft; timeouts wanneer de preset behavior heeft). De World van de basis wordt vervangen door een nieuwe (alleen de wereldmodus van de CLI blijft behouden), waarna het new:-blok van het profiel (alleen NEW_MAP), settings (in General), presentation, internet-textures, behavior en de metagegevens van SessionProfile worden toegepast. compatibility.maps wordt afgedwongen voor NEW_MAP en SAVED_SITUATION.
4. Wereld: de wereldmodus van de CLI heeft altijd voorrang (/new standaard, /saved:<osn>, /last); de World.Mode van het spec-bestand wordt vervangen. Geef /saved: mee om een opgeslagen situatie vanuit een spec te starten. /map en /entrypoint//entrypoint-index overschrijven de basis; een CLI-identiteit via /entrypoint wist de index; /saved met /map of instappuntvlaggen levert OL_E_INVALID_ARGUMENT op.
5. /date, /time, /year, /weather* overschrijven de basis wanneer opgegeven (system selecteert DateTimeMode.System).
6. /no-vehicle wist PlayerVehicle; afzonderlijke /vehicle, /repaint, /hof, /fleet, /registration overschrijven afzonderlijke velden van het spelersvoertuig van de basis.
7. Vermeldingen /set:<key>=<value> worden toegevoegd aan Environment.General (sleutel gecontroleerd, waarde niet); de andere zeven groepen komen ongewijzigd uit de basis.
8. /startup-timeout en /shutdown-timeout overschrijven de basis alleen wanneer opgegeven; anders gelden achtereenvolgens de spec, het profiel en de standaardwaarden 180 s / 30 s. ShutdownTimeoutSeconds is ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT voor de supervisor.
9. /splash, /splash-language, /splash-assets, /internet-textures, /internet-textures-profile overschrijven de basis wanneer opgegeven; SuppressTrayIcon komt alleen uit de basis.
10. Diagnosevlaggen worden met een OF-bewerking gecombineerd met de basis.

Resultaat: expliciete CLI-vlag > sessieprofiel > spec-bestand > ingebouwde standaardwaarde, met de uitzondering dat een CLI-vlag die conflicteert met een veld dat het profiel beheert, een fout is in plaats van een overschrijving.

Padregels#

Meegenomen maar niet toegepast#