Gestion des HOF

Documentation de la version main@63ccaf8Voir la source sur GitHub

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

OMSI lit les fichiers HOF (*.hof : destinations, numéros de ligne et listes d'arrêts affichés par l'IBIS/la girouette du véhicule) dans le dossier de chaque véhicule. La gestion des HOF copie des fichiers HOF dans les dossiers de véhicules pour la durée d'une session : une carte ou un add-on peut livrer les HOF dont ses lignes ont besoin, et un utilisateur peut réutiliser les HOF d'un véhicule sur d'autres, sans modifier durablement aucun véhicule. Cette page est la référence normative, telle qu'implémentée par HofPlanner dans src/OmsiLaunch.Core/HofPlanner.cs, le champ HofManagement du LaunchSpec, les options de la CLI /hof-source, /hof-target, /hof-file et /hof-mode et le bloc hofs des profils de session.

Stabilité : STABLE_BETA pour la planification, les règles de conflit, le confinement et la restauration transactionnelle (contrôles bloquants hors ligne hof.plan-sources-and-modes, hof.plan-rejects-unsafe-input, hof.transaction-exact-restore, hof.recovery-after-crash, session-profiles.hofs). Validé à l'exécution : une session miroir avec restauration exacte et récupération après plantage via /recover (voir l'état de la validation à l'exécution).

La gestion des HOF n'est pas la même chose que PlayerVehicle.Hof / /hof:<id>, qui sélectionne le HOF du véhicule du joueur au démarrage et est UNAVAILABLE dans ce build.

Modèle#

Une demande est une liste d'opérations (HofManagementSpec.Operations). Chaque HofOperationSpec comporte :

Seuls les fichiers situés directement dans le répertoire source sont utilisés (pas de récursion). Les liens symboliques et les jonctions ne sont jamais suivis (voir confinement).

Ce que fait une session#

1. Planification (PlanSessionAsync, /plan). Chaque opération est résolue : les sources sont lues, les cibles sont vérifiées, les conflits sont détectés. Chaque fichier qui sera modifié apparaît dans SessionPlan.PlannedMutations avec la SemanticKey hof.add ou hof.mirror, RequestedValue = l'identité de la source, et l'Operation exact-file-overlay (écrit) ou session-deletion (retiré par un miroir) ; les chemins font partie de TouchedFiles. Un problème rend le plan non exécutable avec les codes ci-dessous.
2. Démarrage. Après la récupération d'un journal obsolète, les opérations sont de nouveau résolues à partir des fichiers réels et transmises à la transaction de session : les fichiers écrits sont des overlays, les fichiers retirés par le miroir sont des suppressions de session. Un fichier cible dont les octets sont déjà identiques à la source est laissé tel quel et ne constitue pas une entrée de la transaction.
3. Fin de session, échec, plantage. La transaction restaure exactement chaque dossier cible : les fichiers qui existaient retrouvent leurs octets, horodatages et attributs d'origine ; les fichiers créés par la session sont supprimés ; les fichiers retirés par le miroir reviennent. Après un plantage du propriétaire, la même restauration s'exécute au démarrage suivant ou via /recover (voir transactions et récupération).

Rien n'est écrit en dehors des dossiers cibles. Les fichiers sources sont uniquement lus. .omsilaunch\hof\ n'est jamais modifié par une session.

Règles de conflit#

Les opérations sont appliquées dans l'ordre et doivent être concordantes :

• Deux opérations qui écrivent le même fichier cible avec les mêmes octets sont fusionnées ; avec des octets différents : OL_E_HOF_CONFLICT.
• Un miroir qui retirerait un fichier qu'une opération antérieure écrit, ou une opération qui écrit un fichier qu'un miroir antérieur retire : OL_E_HOF_CONFLICT.
• Un miroir couvre l'ensemble des HOF de session du dossier : les fichiers existants plus les fichiers que des opérations antérieures y écrivent.
• Une cible HOF également écrite par la présentation de la session (écran de démarrage ou textures Internet) : OL_E_HOF_CONFLICT (ne peut pas se produire avec les chemins de présentation actuels, qui sont en dehors de Vehicles\).
• Lorsqu'une cible contient déjà un fichier du même nom avec une casse différente, l'orthographe existante est conservée.

Confinement#

Chaque source et chaque cible doivent rester à l'intérieur de l'installation : les chemins enracinés, les segments .. et les chemins qui sortent de la racine donnent OL_E_HOF_PATH_ESCAPE ; il en va de même pour les cibles (et les sources Vehicle) situées en dehors de Vehicles\, les noms de collection qui ne sont pas un simple nom de répertoire, et tout dossier source ou cible atteint par une jonction ou un lien symbolique. Les fichiers .hof qui sont eux-mêmes des points d'analyse (reparse points) sont ignorés.

Limites#

Codes d'erreur#

Utilisation#

Ligne de commande (une seule opération ; plusieurs opérations nécessitent /spec ou un profil de session) :

OmsiLaunch.exe /new /map:maps\Grundorf\global.cfg /entrypoint-index:1 /hof-source:collection:berlin /hof-target:Vehicles\MAN_SD200\MAN_SD77.bus /plan
OmsiLaunch.exe /new /map:maps\Grundorf\global.cfg /entrypoint-index:1 /hof-source:vehicle:Vehicles\MAN_SD200\MAN_SD77.bus /hof-target:Vehicles\MAN_SD202 /hof-mode:mirror

LaunchSpec (JSON /spec, énumérations sous forme d'entiers) :

{
  "HofManagement": {
    "Operations": [
      { "SourceKind": 1, "Source": "maps\\Grundorf\\hof", "TargetVehicles": [ "Vehicles\\MAN_SD200\\MAN_SD77.bus" ], "Mode": 0 },
      { "SourceKind": 0, "Source": "berlin", "TargetVehicles": [ "Vehicles\\MAN_SD202" ], "Mode": 1, "Files": [ "Linie5.hof" ] }
    ]
  }
}

Préréglage de profil de session (une source package est un répertoire situé dans le paquet du profil) :

hofs:
  - package: hof
    targets:
      - Vehicles\MAN_SD200\MAN_SD77.bus
    mode: mirror

API : définissez LaunchSpec.HofManagement et appelez PlanSessionAsync / StartSessionAsync comme d'habitude ; /list:Hofs (ContentQueryKind.Hofs) liste les fichiers HOF installés.

Voir aussi : LaunchSpec, profils de session, CLI, erreurs, transactions et récupération.