Gestione HOF

Documentazione della versione main@63ccaf8Vedi il sorgente su GitHub

Traduzione della pagina originale in inglese di OmsiLaunch 0.1.0-beta4. La pagina inglese è normativa: in caso di differenze prevalgono la pagina inglese e il codice.

OMSI legge i file HOF (*.hof: destinazioni, numeri di linea ed elenchi di fermate mostrati dal display IBIS/delle destinazioni del veicolo) dalla cartella di ciascun veicolo. La gestione HOF copia i file HOF nelle cartelle dei veicoli per la durata di una sessione: una mappa o un add-on può distribuire i file HOF di cui le sue linee hanno bisogno, e un utente può riutilizzare i file HOF di un veicolo su altri, senza modificare permanentemente alcun veicolo. Questa pagina è il riferimento normativo, secondo l'implementazione di HofPlanner in src/OmsiLaunch.Core/HofPlanner.cs, del campo HofManagement del LaunchSpec, dei flag /hof-source, /hof-target, /hof-file e /hof-mode della CLI e del blocco hofs dei profili di sessione.

Stabilità: STABLE_BETA per la pianificazione, le regole sui conflitti, il confinamento e il ripristino transazionale (gate offline hof.plan-sources-and-modes, hof.plan-rejects-unsafe-input, hof.transaction-exact-restore, hof.recovery-after-crash, session-profiles.hofs). Validata a runtime: una sessione con mirror con ripristino esatto e recupero dopo un crash tramite /recover (vedere stato della validazione a runtime).

La gestione HOF non coincide con PlayerVehicle.Hof / /hof:<id>, che seleziona il file HOF del veicolo del giocatore all'avvio ed è UNAVAILABLE in questo build.

Modello#

Una richiesta è un elenco di operazioni (HofManagementSpec.Operations). Ogni HofOperationSpec ha:

Vengono usati solo i file presenti direttamente nella directory sorgente (nessuna ricorsione). I collegamenti simbolici e le junction non vengono mai seguiti (vedere confinamento).

Che cosa fa una sessione#

1. Pianificazione (PlanSessionAsync, /plan). Ogni operazione viene risolta: le sorgenti vengono lette, le destinazioni controllate, i conflitti rilevati. Ogni file che cambierà compare in SessionPlan.PlannedMutations con SemanticKey hof.add o hof.mirror, RequestedValue = l'identità della sorgente e Operation exact-file-overlay (scritto) o session-deletion (rimosso da un mirror); i percorsi fanno parte di TouchedFiles. Un problema rende il piano non eseguibile con i codici riportati sotto.
2. Avvio. Dopo il recupero di un journal obsoleto, le operazioni vengono risolte di nuovo a partire dai file attivi e consegnate alla transazione della sessione: i file scritti sono overlay, i file eliminati da un mirror sono eliminazioni di sessione. Un file di destinazione i cui byte sono già uguali alla sorgente viene lasciato com'è e non è una voce della transazione.
3. Fine della sessione, errore, crash. La transazione ripristina esattamente ogni cartella di destinazione: i file esistenti riottengono i byte, i timestamp e gli attributi originali; i file creati dalla sessione vengono rimossi; i file eliminati da un mirror tornano al loro posto. Dopo un crash dell'owner lo stesso ripristino viene eseguito al successivo avvio o tramite /recover (vedere transazioni e recupero).

Non viene scritto nulla al di fuori delle cartelle di destinazione. I file sorgente vengono solo letti. .omsilaunch\hof\ non viene mai modificato da una sessione.

Regole sui conflitti#

Le operazioni vengono applicate in ordine e devono essere concordi:

• Due operazioni che scrivono lo stesso file di destinazione con gli stessi byte vengono unite; con byte diversi: OL_E_HOF_CONFLICT.
• Un mirror che rimuoverebbe un file scritto da un'operazione precedente, oppure un'operazione che scrive un file rimosso da un mirror precedente: OL_E_HOF_CONFLICT.
• Un mirror copre l'insieme dei file HOF di sessione della cartella: i file esistenti più i file che le operazioni precedenti vi scrivono.
• Una destinazione HOF che è scritta anche dalla presentazione della sessione (splash o Internet Textures): OL_E_HOF_CONFLICT (non può accadere con i percorsi di presentazione attuali, che sono al di fuori di Vehicles\).
• Quando una destinazione ha già un file con lo stesso nome in maiuscole e minuscole diverse, viene mantenuta la grafia esistente.

Confinamento#

Ogni sorgente e ogni destinazione devono restare all'interno dell'installazione: percorsi radicati, segmenti .. e percorsi che escono dalla radice sono OL_E_HOF_PATH_ESCAPE; lo sono anche le destinazioni (e le sorgenti Vehicle) al di fuori di Vehicles\, i nomi di collezione che non sono un semplice nome di directory e qualsiasi cartella sorgente o di destinazione raggiunta attraverso una junction o un collegamento simbolico. I file .hof che sono essi stessi reparse point vengono ignorati.

Limiti#

Codici di errore#

Utilizzo#

Riga di comando (una sola operazione; più operazioni richiedono /spec o un profilo di sessione):

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 di /spec, enum come interi):

{
  "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" ] }
    ]
  }
}

Preset di un profilo di sessione (una sorgente package è una directory all'interno del pacchetto del profilo):

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

API: impostare LaunchSpec.HofManagement e chiamare PlanSessionAsync / StartSessionAsync come di consueto; /list:Hofs (ContentQueryKind.Hofs) elenca i file HOF installati.

Correlati: LaunchSpec, profili di sessione, CLI, errori, transazioni e recupero.