Profils de session

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.

Un profil de session est un paquet YAML déclaratif qu'un auteur de contenu livre avec une carte ou un add-on afin que les utilisateurs finaux puissent démarrer une session OmsiLaunch reproductible avec une seule commande (OmsiLaunch.exe /predefined-profile:<id> /predefined-profile-index:<1..5> /new). Cette page est la référence normative du format omsilaunch.session-profile/v1 tel qu'implémenté par SessionProfileCompiler dans src/OmsiLaunch.Core/SessionProfiles.cs, des règles de priorité appliquées par la CLI (CliInput.BuildSpecAsync et RejectProfileConflicts dans tools/OmsiLaunch.Cli/Program.cs) et du catalogue de paramètres qu'un profil peut écrire (ConfigurationCatalog). Tout ce qu'un profil peut faire, les options de la CLI et le LaunchSpec peuvent aussi le faire ; un profil ne fait qu'empaqueter ces choix.

Stabilité : STABLE_BETA pour l'analyse, la validation, la détection des conflits et les blocs settings / presentation / internet-textures / behavior (test hors ligne session-profiles.strict-compiler ; le chemin d'overlay et de restauration est validé à l'exécution par RV-005 et RV-006, voir l'état de la validation à l'exécution). Les clés new.date, new.time, new.year et new.weather sont UNAVAILABLE dans ce build (voir Le bloc new).

Emplacement et nommage du paquet#

Un profil est installé et supprimé par l'utilisateur ou l'auteur du contenu. OmsiLaunch n'écrit jamais dans un paquet, ne le copie jamais et ne le supprime jamais. Le répertoire du paquet ne fait partie d'aucune transaction.

Règles d'analyse#

Les barres obliques inverses dans les scalaires simples (non entre guillemets) sont des caractères littéraux. Écrivez les chemins Windows avec une seule barre oblique inverse (maps\Grundorf\global.cfg). Une barre oblique inverse doublée dans un scalaire simple reste doublée dans la valeur ; voir L'exemple livré.

Référence des clés#

Les contextes sont nommés exactement comme le compilateur les nomme. Chaque clé listée ici est acceptée ; aucune autre ne l'est.

profile (mapping racine)#

compatibility#

new#

Le bloc est lu et validé dès qu'il est présent, mais il n'est appliqué à la spécification que lorsque le mode de monde sélectionné est NEW_MAP (/new, la valeur par défaut de la CLI). Sous /saved:<file.osn>, le bloc est ignoré.

date, time, year et weather sont compilés en DateSpec, TimeSpec, YearSpec et WeatherSpec avec DateTimeMode.Explicit / le WeatherMode sélectionné. Le planificateur de session (src/OmsiLaunch.Core/SessionPlanner.cs) signale alors les capacités world.explicit-date, world.explicit-time, world.explicit-year et weather comme STATICALLY_PARTIAL, ajoute OL_E_CAPABILITY_UNAVAILABLE aux diagnostics du plan et marque le plan comme non exécutable. Le plugin rejette en outre un handoff dont le mode de date ou d'heure ne vaut pas Unset (plugin.request.unsupported). Conséquence pour ce build : un profil qui définit l'une de ces quatre clés peut être validé avec /plan mais ne peut pas démarrer de session (code de sortie 1, OL_E_PLAN_NOT_RUNNABLE). Omettez-les dans les profils destinés à être exécutés.

new.date#

new.time#

new.weather#

preset (chaque entrée de presets)#

Seul le préréglage sélectionné est appliqué. Chaque préréglage est néanmoins analysé et validé, si bien qu'une erreur dans le préréglage 3 fait échouer une demande portant sur le préréglage 1.

presentation#

presentation.splash#

Un profil ne peut pas définir SessionPresentationSpec.SuppressTrayIcon ; la valeur reste false sauf si un /spec la définit.

internet-textures#

behavior#

Lorsque le bloc behavior est présent, les deux timeouts sont définis (valeur fournie ou valeur par défaut) et remplacent entièrement le LaunchBehaviorSpec de base, y compris RestoreConfiguration et SuppressStaleClosecheckWarning, qui reviennent à leurs valeurs par défaut (true, true).

Paramètres#

Les clés de settings sont les noms sémantiques de ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs). Le compilateur n'accepte une clé que si elle existe (OL_E_SESSION_PROFILE_SETTING_UNKNOWN) et qu'elle est accessible en écriture (OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE). Les valeurs sont stockées sous forme de chaînes et converties en correctif de options.cfg lorsque la session construit ses overlays ; une valeur invalide est donc détectée lors de StartSessionAsync, et non au chargement du profil, et fait échouer la session avec OL_E_START_SESSION, dont le message porte OL_E_INVALID_SETTING_VALUE: <key>. Chaque paramètre ci-dessous écrit dans options.cfg ; tous sont limités à la session et restaurés à l'identique après la session.

Formes de valeurs :

• bool vaut true ou false (insensible à la casse). Pour les jetons de présence, le jeton est ajouté ou retiré ; pour les jetons inversés (no_*), true retire le jeton négatif.
• int / decimal sont validés par rapport à la plage ; les valeurs avec un diviseur sont stockées divisées (par exemple, graphics.minObjectScreenPercent: 5 écrit 0.05).
• string est écrite telle quelle.

Entrées du catalogue qui existent mais ne sont pas accessibles en écriture (rejetées avec OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE) : advanced.multithreadingCalculate, advanced.multithreadingTextureLoad (remplacées par advanced.reducedMultithreading), graphics.texture, graphics.textureFilter.

Confinement des chemins#

presentation.splash.assets et internet-textures.profile sont résolus par Confined(package root, value) :

1. Les chemins enracinés (C:\...), les chemins commençant par \ et tout composant de chemin égal à .. sont rejetés.
2. Le chemin complet est calculé et doit commencer par le répertoire du paquet.
3. Chaque composant existant sous la racine du paquet, jusqu'au chemin final inclus, est inspecté à la recherche de l'attribut ReparsePoint. Une jonction, un lien symbolique de répertoire ou un lien symbolique de fichier situé n'importe où sur ce chemin est rejeté, de même qu'un composant qui ne peut pas être inspecté (IOException / UnauthorizedAccessException).

Ces trois échecs donnent tous OL_E_SESSION_PROFILE_PATH_ESCAPE. La même règle relative aux points d'analyse est appliquée aux cibles .itx sous Texture\ lors de la construction de la session.

Priorité et conflits de remplacement#

CliInput.BuildSpecAsync compose la spécification dans cet ordre :

1. Valeurs par défaut (NEW_MAP, tout non défini, timeouts 180 s / 30 s).
2. /spec:<file.json>, s'il est fourni, remplace entièrement les valeurs par défaut.
3. Racine de l'installation : un argument d'installation explicite l'emporte sur le RootPath de la spécification ; . désigne le répertoire contenant l'exécutable.
4. Profil (/predefined-profile + /predefined-profile-index) : le paquet est chargé et RejectProfileConflicts s'exécute sur les arguments bruts de la CLI avant toute fusion. Le bloc de monde de la base est ensuite réinitialisé en un WorldSpec vide du mode sélectionné (un monde issu de /spec est abandonné lorsqu'un profil est utilisé) et SessionProfileCompiler.Apply superpose le profil à la base : new (NEW_MAP uniquement), settings (fusionnés par-dessus le Environment.General de la base, le profil l'emportant clé par clé), ainsi que presentation, internet-textures, behavior (chacun ne remplaçant le bloc de la base que lorsque le préréglage le définit).
5. Arguments restants de la CLI, superposés par-dessus : /map, /entrypoint, /entrypoint-index, /date, /time, /year, options météo, options de véhicule, /set, options d'écran de démarrage, options de textures Internet, /startup-timeout, /shutdown-timeout. Les timeouts de la CLI ne s'appliquent que lorsqu'ils sont fournis ; sinon, la valeur de la spécification, du profil ou par défaut est conservée.
6. Vérification de compatibilité pour les modes autres que NEW_MAP (ValidateCompatibility).

Un argument de la CLI qui cible un champ détenu par le profil sélectionné constitue un conflit, rejeté avec OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (code de sortie 2, catégorie invalid_argument). La vérification porte sur le champ, pas sur la valeur : répéter la valeur du profil lui-même reste un conflit.

Ne constituent pas des conflits : les clés /set que le préréglage ne définit pas (elles sont ajoutées), les options de véhicule (/vehicle, /repaint, /hof, /fleet, /registration, /no-vehicle ; un profil ne peut pas définir de véhicule du joueur), et tout argument de monde sous /saved (le bloc new n'y est pas appliqué). /map, /entrypoint et /entrypoint-index sont invalides avec /saved, indépendamment des profils (OL_E_INVALID_ARGUMENT).

Codes d'erreur#

Toutes ces erreurs sont levées pendant la compilation de la ligne de commande, avant la planification. Ce sont des SessionProfileException (ou ArgumentException pour le conflit) et elles ne démarrent jamais de session. Le catalogue complet se trouve dans erreurs ; les codes de sortie dans codes de sortie.

Apparence d'un profil dans l'API#

Après un chargement réussi, la spécification transporte un enregistrement SessionProfileMetadata dans LaunchSpec.SessionProfile :

Le planificateur ajoute un diagnostic informatif session_profile.selected à chaque SessionPlan construit à partir d'une telle spécification, avec les clés de données session_profile.id, session_profile.name, session_profile.version, session_profile.author, session_profile.preset_id, session_profile.preset_index, session_profile.preset_name et session_profile.path. Il n'affecte pas l'exécutabilité. Les intégrateurs qui utilisent directement l'API publique peuvent appeler SessionProfileCompiler.Load et SessionProfileCompiler.Apply depuis OmsiLaunch.Core ; la représentation YAML ne franchit jamais la frontière de OmsiLaunch.Api.

Exemples#

Exemple 1 : profil limité aux paramètres, un préréglage#

<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

Exécution : OmsiLaunch.exe /predefined-profile:quiet-evening /predefined-profile-index:1 /new /map:maps\Grundorf\global.cfg /entrypoint-index:0. La carte et le point d'entrée proviennent de la ligne de commande, car le profil ne définit pas de bloc new ; ajouter /set:graphics.maxFPS=60 est autorisé, ajouter /set:traffic.humans=10 est un conflit.

Exemple 2 : profil lié à une carte avec trois préréglages et des ressources empaquetées#

<root>\.omsilaunch\session-profiles\grundorf-tour\profile.yaml, avec assets\splash\ENG.bmp, assets\splash\DEU.bmp et textures\offline.itx dans le paquet :

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

Exécution : OmsiLaunch.exe /predefined-profile:grundorf-tour /predefined-profile-index:2 /new. Avec /saved:situations\mytrip.osn, le bloc new est ignoré et le .osn doit référencer maps\Grundorf\global.cfg.

L'exemple livré#

La version livre docs/examples/session-profiles/rmg-leste/profile.yaml (afficher). Il est syntaxiquement valide, conforme au schéma et se chargerait sans erreur. Deux propriétés l'empêchent de démarrer une session sans modification dans ce build :

1. Il définit new.date, new.time et new.weather, qui rendent le plan non exécutable (voir Le bloc new).
2. Ses valeurs de chemin sont des scalaires simples avec des barres obliques inverses doublées (maps\\RMG Leste\\global.cfg). YAML les conserve doublées, et les identités de carte sont comparées textuellement (après la seule normalisation de / en \), si bien que new.map et compatibility.maps ne correspondraient pas à l'identité du catalogue maps\RMG Leste\global.cfg (OL_E_MAP_NOT_FOUND lors de la planification). La valeur assets se résout néanmoins, car la normalisation des chemins Windows fusionne les séparateurs doublés.

La forme exécutable pour ce build est :

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

Pages associées#

• Référence de la CLI pour /predefined-profile, /predefined-profile-index, /set et les options de monde
• LaunchSpec pour l'enregistrement dans lequel un profil est compilé
• Transactions et récupération pour la façon dont les overlays de settings, d'écran de démarrage et .itx sont appliqués et restaurés
• Capacités et état de la validation à l'exécution