Référence de LaunchSpec

Documentation de la version v0.1.0-beta.3Voir la source sur GitHub

Traduction de la page originale en anglais d’OmsiLaunch 0.1.0-beta3. La page anglaise fait foi : en cas de divergence, la page anglaise et le code prévalent.

Cette page est la référence normative de LaunchSpec, l'enregistrement de requête qui décrit une session OmsiLaunch : sa forme C# (OmsiLaunch.Api), sa forme de fichier JSON telle que chargée par la CLI (/spec:<path>, tools/OmsiLaunch.Cli/LaunchSpecJson.cs), chaque propriété avec son type, sa valeur par défaut, sa règle de validation et son effet actuel, les règles de validation qui rendent un plan non exécutable, et la priorité entre les options de la CLI, les fichiers de spécification et les profils de session. Seul ce que fait le code actuel est documenté.

Pages associées : API publique, référence de la CLI, profils de session, codes d'erreur, cycle de vie de la session, capacités.

Origine d'un LaunchSpec#

L'exemple complet ci-dessous est vérifié par rapport à la forme de l'enregistrement. Une copie de l'exemple minimal est livrée sous examples/release-session.example.json (et .omsilaunch\examples\release-session.example.json dans le paquet de version).

Forme JSON#

Exemple complet#

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

Une date explicite, lorsque le build la prend en charge, s'écrit "Date": { "Mode": 1, "Value": { "Presence": 1, "Value": { "Year": 2024, "Month": 5, "Day": 1 } } } et une heure { "Mode": 1, "Value": { "Presence": 1, "Value": { "Hour": 7, "Minute": 30, "Second": 0 } } }. Sur ce build, les deux rendent le plan non exécutable (voir ci-dessous).

Référence des propriétés#

La colonne « Consommée » indique ce que le code actuel fait de la valeur. La stabilité utilise le vocabulaire de la page de l'API publique.

LaunchSpec (racine)#

Accesseurs en lecture seule (présents dans la sortie JSON de la CLI, ignorés au chargement) : EffectiveYear, EffectiveWeather, EffectiveInput, EffectiveDiagnostics, EffectivePresentation, EffectiveInternetTextures.

InstallationSpec#

WorldSpec#

DateSpec, TimeSpec, YearSpec#

WeatherSpec#

PlayerVehicleSpec (dans PlayerVehicle)#

Un PlayerVehicle avec Presence 1 et tous les champs non définis est accepté et n'a aucun effet. Tout champ défini rend le plan non exécutable sur ce build (STATICALLY_PARTIAL).

EnvironmentSpec#

Les huit groupes sont concaténés ; le groupe dans lequel une clé est placée n'a aucun effet. Chaque entrée avec Presence 1 est un paramètre sémantique de ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs) ; la clé sélectionne le fichier cible (options.cfg pour toutes les clés actuelles) et le jeton. La planification vérifie que la clé existe (OL_E_UNKNOWN_SETTING) et qu'elle est accessible en écriture (OL_E_SETTING_NOT_WRITABLE) ; la valeur n'est validée qu'au démarrage (OL_E_INVALID_SETTING_VALUE, signalé comme une session Failed avec OL_E_START_SESSION). Les clés sont insensibles à la casse. Les entrées non définies sont ignorées. L'option de la CLI /set:<key>=<value> écrit dans General ; les settings des profils de session sont également fusionnés dans General.

Les fichiers modifiés conservent leur encodage (octets Windows-1252 préservés ; UTF-8/UTF-16 marqués par une BOM respectés) et leurs fins de ligne.

LaunchBehaviorSpec#

InputSpec#

DiagnosticsSpec#

Les options de la CLI /log, /logall, /omsi-logall, /verbose, /trace, /trace-process, /trace-plugin, /trace-native renseignent ces booléens (/logall définit Verbose, ProcessTrace, PluginTrace, NativeTrace) ; elles sont combinées par OU avec les valeurs de la spécification.

SessionPresentationSpec#

InternetTexturesSpec#

SessionProfileMetadata#

Énumérations#

Les entiers hors de la plage déclarée sont stockés tels quels par le sérialiseur et se comportent comme des valeurs inconnues (par exemple, un WorldMode inconnu n'est ni NEW_MAP ni SAVED_SITUATION et produit un plan sans capacité de monde ; le plugin le rejetterait, mais la CLI remplace de toute façon le mode, voir la priorité).

Règles de validation et diagnostics de non-exécutabilité#

PlanSessionAsync exécute LaunchValidation.Validate puis SessionPlanner.PlanAsync. Un plan est exécutable exactement lorsqu'aucun code de diagnostic ne commence par OL_E_. L'ensemble complet :

Non validé au moment de la planification (échoue au démarrage sous la forme d'une session Failed avec OL_E_START_SESSION) : valeurs des paramètres (OL_E_INVALID_SETTING_VALUE), intégrité du plugin permanent (OL_E_PERMANENT_PLUGIN_*), disponibilité du bail (OL_E_INSTALLATION_BUSY), plage de StartupTimeoutSeconds (levée par StartSessionAsync).

Diagnostics de plan informatifs : plugin.integrity.reference (message manifest ou self), session_profile.selected.

Priorité : options de la CLI, fichier de spécification et profil de session#

CliInput.BuildSpecAsync (tools/OmsiLaunch.Cli/Program.cs) construit la spécification effective dans cet ordre :

1. Base = valeurs par défaut intégrées, ou le fichier /spec lorsqu'il est fourni.
2. Racine de l'installation = l'argument d'installation explicite s'il est fourni, sinon le RootPath de la base ; ensuite ./vide → répertoire de l'exécutable, Path.GetFullPath. Un argument d'installation explicite l'emporte toujours sur le RootPath de la spécification.
3. Profil de session (/predefined-profile + /predefined-profile-index) : les arguments explicites de la CLI qui touchent un champ détenu par le profil sont rejetés avec OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (champs de monde uniquement en mode NEW_MAP ; clés /set présentes dans le préréglage ; options d'écran de démarrage lorsque le préréglage a presentation ; options de textures Internet lorsqu'il a internet-textures ; timeouts lorsqu'il a behavior). Le World de la base est remplacé par un nouveau (seul le mode de monde de la CLI subsiste), puis le bloc new: du profil (NEW_MAP uniquement), settings (dans General), presentation, internet-textures, behavior et les métadonnées SessionProfile sont appliqués. compatibility.maps est appliqué pour NEW_MAP et SAVED_SITUATION.
4. Monde : le mode de monde de la CLI l'emporte toujours (/new par défaut, /saved:<osn>, /last) ; le World.Mode du fichier de spécification est remplacé. Pour exécuter une situation enregistrée à partir d'une spécification, passez /saved:. /map et /entrypoint//entrypoint-index remplacent la base ; une identité /entrypoint de la CLI efface l'index ; /saved avec /map ou des options de point d'entrée donne OL_E_INVALID_ARGUMENT.
5. /date, /time, /year, /weather* remplacent la base lorsqu'ils sont fournis (system sélectionne DateTimeMode.System).
6. /no-vehicle efface PlayerVehicle ; les options individuelles /vehicle, /repaint, /hof, /fleet, /registration remplacent les champs individuels du véhicule du joueur de la base.
7. Les entrées /set:<key>=<value> sont ajoutées à Environment.General (clé vérifiée, valeur non) ; les sept autres groupes proviennent de la base sans modification.
8. /startup-timeout et /shutdown-timeout ne remplacent la base que lorsqu'ils sont fournis ; sinon s'appliquent la spécification, puis le profil, puis les valeurs par défaut 180 s / 30 s. ShutdownTimeoutSeconds est ACCEPTED_FOR_COMPATIBILITY / CURRENTLY_NO_EFFECT pour le superviseur.
9. /splash, /splash-language, /splash-assets, /internet-textures, /internet-textures-profile remplacent la base lorsqu'ils sont fournis ; SuppressTrayIcon provient uniquement de la base.
10. Les options de diagnostic sont combinées par OU avec la base.

Résultat : option explicite de la CLI > profil de session > fichier de spécification > valeur par défaut intégrée, à ceci près qu'une option de la CLI en conflit avec un champ détenu par le profil est une erreur et non un remplacement.

Règles de chemin#

Transporté mais non appliqué#