Runtimemodules

Documentatie voor versie main@63ccaf8Bron bekijken op GitHub

Vertaling van de oorspronkelijke Engelse pagina voor OmsiLaunch 0.1.0-beta4. De Engelse pagina is normatief: bij verschillen gelden de Engelse pagina en de code.

Een runtimemodule voegt gedrag toe aan een beheerde OMSI-sessie: een functie die met de sessie meedraait (bijvoorbeeld de HUD van een kaart of laadoptimalisaties), zonder deel van OmsiLaunch zelf te worden. De brug laadt de module, geeft hem alleen wat hij declareert en verwijdert alles wat hij vasthoudt wanneer de sessie eindigt of de module faalt. Deze pagina is de normatieve referentie voor runtimemodules zoals geïmplementeerd door src/OmsiLaunch.Runtime.Modules (manifest, instellingen, geschiktheid, levenscyclushost), de planner, de sessieprogramma's van de controller (ModuleSessionPrograms, ModuleSessionProcess), de moduleomgeving van de plugin en de modulevlaggen van de CLI.

Stabiliteit: EXPERIMENTAL. Brugprotocol 1 is in ronde B runtime-gevalideerd (beheerde modules, contentactivering, operaties, disable-module en fail-session; native componenten met IAT-hooks; zie de status van de runtimevalidatie). Brugprotocol 2 (instellingen, standaardactivering, het instellingenbestand, sessieprogramma's, pluginconflicten, meldingen, get_value) is alleen offline gevalideerd. Offline gates: de module.*-gates van tests/OmsiLaunch.ModuleTests (manifest, integriteit, selectie en activering, instellingen, het instellingenbestand, pluginconflicten, sessieprogramma's gestart via hun job, een in elke fase geïnjecteerde fout onder elk faalbeleid, levenscyclus van native componenten, opruimen, handoff), plugin-runtime.modules-lifecycle (een echte beheerde module geladen door de omgeving van de plugin), runtime-modules.native-component (een echte native component die een import hookt en waarden leest via de brug), runtime-modules.plugin-conflict en native-hooks.self-check (de hook-engine).

Laden is open: elke module die onder plugins\OmsiLaunch.Modules is geïnstalleerd kan worden geladen, door wie hij ook is gemaakt. OmsiLaunch staat niet in voor wat een module binnen OMSI doet. Wat het wel garandeert is de grens: modules draaien nooit binnen het OmsiLaunch-proces, en niets wat OmsiLaunch biedt laat een module verder reiken dan de eigen rechten van OMSI.

Waar modules staan#

Elke module is een map onder de permanente pluginmap:

<OMSI root>\plugins\OmsiLaunch.Modules\<id>\module.json
<OMSI root>\plugins\OmsiLaunch.Modules\<id>\<managed component>.dll
<OMSI root>\plugins\OmsiLaunch.Modules\<id>\<assets and other components>

De mapnaam moet gelijk zijn aan de id van de module. Modules worden geïnstalleerd door wie ze distribueert; een sessie schrijft, maakt geen snapshot van en herstelt daar nooit bestanden, en modules wijzigen via OmsiLaunch nooit installatiebestanden (een manifest kent geen manier om een installatie-overlay te declareren). De schrijfbare gegevens van een module staan in zijn gegevensmap.

Manifest (module.json)#

Schema omsilaunch.runtime-module/v1. Onbekende sleutels worden geweigerd, zodat een manifest dat voor een later schema is geschreven wordt geweigerd in plaats van half begrepen. Alle paden zijn relatief ten opzichte van de modulemap (gebonden contentpaden zijn relatief ten opzichte van de OMSI-hoofdmap), gebruiken \ of / en mogen geen .. of stationsaanduiding bevatten.

Een manifest dat een functie van protocol 2 gebruikt (settings, conflicts, activering default, een host-component, prepare_ms of host_stop_ms) moet bridge_protocol.min 2 declareren.

Elk bestand dat door components en assets wordt genoemd, is vastgezet met zijn SHA-256. module.json kan zichzelf niet vastzetten.

{
  "schema": "omsilaunch.runtime-module/v1",
  "id": "example-preload",
  "version": "1.0.0",
  "bridge_protocol": { "min": 2, "max": 2 },
  "activation": "default",
  "required_capabilities": ["bridge.events", "bridge.hooks.iat"],
  "components": [
    { "kind": "managed", "path": "Example.Preload.dll", "sha256": "<64 hex digits>", "entry": "Example.Preload.PreloadModule" },
    { "kind": "native", "path": "example-preload.dll", "sha256": "<64 hex digits>" },
    { "kind": "host", "path": "ExamplePreloader.exe", "sha256": "<64 hex digits>" }
  ],
  "settings": [
    { "key": "ram_budget_mb", "type": "integer", "default": "auto", "auto": true, "min": 256, "max": 12288, "flag": "example-ram" },
    { "key": "monitor", "type": "boolean", "default": false, "flag": "example-monitor" }
  ],
  "conflicts": { "plugins": ["OldExamplePlugin.dll"] },
  "failure_policy": "degrade",
  "timeouts": { "prepare_ms": 300000 }
}

Integriteit#

Elk vastgezet bestand moet bestaan, mag niet via een junction of symbolische koppeling worden bereikt en moet zijn vastgezette SHA-256 hebben; anders wordt de module geweigerd met OL_E_MODULE_INTEGRITY. Dit vangt een module op die beschadigd of half bijgewerkt is. Het is geen vertrouwensbeslissing: een module wordt niet getoetst aan een lijst, handtekening of uitgever.

De controle wordt herhaald op de plek waar de code van de module start: de plugin laadt een module alleen als zijn module.json nog steeds de SHA-256 heeft die het plan heeft geëvalueerd en elke vastgezette waarde nog klopt, en de controller start een sessieprogramma pas nadat de vastzetting van dat programma is geverifieerd.

Beveiligingsgrens#

OmsiLaunch heeft geen controle over wat een module binnen OMSI doet: zijn beheerde en native componenten draaien in het OMSI-proces met dezelfde rechten als elke OMSI-plugin. OmsiLaunch garandeert het volgende:

1. Het OmsiLaunch-proces laadt nooit modulecode. Modulecode draait binnen OMSI, in een hulpprogramma dat vanuit OMSI wordt gestart, of in het sessieprogramma van de module.
2. De programma's die OmsiLaunch voor modules start, zijn bestanden uit de eigen map van de module, geverifieerd tegen hun vastzetting en gestart met een opdrachtregel die OmsiLaunch vastlegt. Een sessieprogramma draait in een jobobject dat het met de sessie beëindigt, staat geen tweede proces toe (het kan geen andere programma's starten) en weigert wijzigingen aan systeemparameters, weergave-instellingen, het bureaublad en afmelden of afsluiten. Het erft alleen zijn twee pipe-handles.
3. Alles wat een module declareert blijft binnen zijn map, en zijn schrijfbare gegevens binnen .omsilaunch\module-data\<id>.
4. De OmsiLaunch-kanalen (local control, opstart-handoff, telemetrie, runtimeopdrachten) blijven beperkt tot de huidige gebruiker en gebonden aan de sessie; geen ervan laat een aanroeper een programma starten, bestanden buiten de installatie lezen of schrijven, of systeeminstellingen wijzigen.
5. OmsiLaunch verhoogt nooit rechten. Een module draait met de rechten van de gebruiker die de sessie heeft gestart.
6. Tekst die van een module komt (meldingen, events, waarden) wordt als gegevens behandeld: begrensd, zonder besturingstekens, nooit uitgevoerd, geopend of als koppeling gevolgd.

Capabilities#

required_capabilities en optional_capabilities noemen ofwel een native capability van de draaiende build (de kolom native capability van de capabilitycatalogus, bijvoorbeeld time.read of d3d.texture) ofwel een brugfunctie:

Een naam die geen van beide is, wordt bij het plannen geweigerd (OL_E_MODULE_CAPABILITY_UNRESOLVED). Op een OMSI 2-build zonder bekende layout wordt een native capability die het uitvoerbare bestand niet oplost, in het proces beslist; als ze daar niet wordt opgelost, wordt de module niet geladen.

Modules kiezen voor een sessie#

Een module neemt op een van vier manieren deel aan een sessie; PlannedModule.Activation geeft aan welke:

Een module wordt buiten de sessie gehouden door LaunchSpec.Modules.Disable, /no-module:<id>, enabled: false in de preset of enabled=false in het instellingenbestand (plandiagnose module.disabled). Een expliciete aanvraag gaat voor het instellingenbestand. Dezelfde module in één aanvraag zowel inschakelen als uitschakelen is OL_E_MODULE_SETTING_INVALID.

Planregels: een aangevraagde module die niet kan worden geladen, maakt het plan niet uitvoerbaar met zijn OL_E_MODULE_*-code. Een module die uit zichzelf deelnam (instellingenbestand, content, standaard) en niet kan worden geladen, stopt de sessie niet: het plan meldt OL_W_MODULE_NOT_LOADED.

OmsiLaunch.exe /new /map:maps\Grundorf\global.cfg /entrypoint-index:1 /no-module:example-preload

Instellingen#

Een module declareert zijn instellingen in settings; elke invoer:

Waarden worden genormaliseerd: booleans accepteren true/false, yes/no, on/off, 1/0; keuzes worden zonder hoofdlettergevoeligheid vergeleken; gehele getallen worden aan hun grenzen getoetst.

De effectieve waarde van elke instelling is, in volgorde:

1. de aanvraag: LaunchSpec.Modules.Settings ("<module-id>.<key>": "<value>"), /module-setting:<module-id>.<key>=<value>, een eigen vlag van de module, of modules.<id>.settings in de geselecteerde preset van het sessieprofiel. Zoals bij elk ander presetveld kan de opdrachtregel niet ook een sleutel instellen die de preset instelt (OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT);
2. het instellingenbestand;
3. de standaardwaarde uit het manifest.

Een ongeldige aangevraagde waarde, of een aangevraagde sleutel die de module niet declareert, maakt het plan niet uitvoerbaar (OL_E_MODULE_SETTING_INVALID). Een invoer in het instellingenbestand die niet kan worden gebruikt, wordt genegeerd met OL_W_MODULE_SETTING_IGNORED, evenals aangevraagde instellingen voor een module die de sessie niet laadt. Het plan toont elke effectieve waarde met haar bron (request, settings-file of default) in PlannedModule.Settings.

De module ontvangt elke gedeclareerde sleutel met haar effectieve waarde: IRuntimeModuleContext.Settings, get_value("setting.<key>") in een native component, en het settings-object van de context van een sessieprogramma.

Het instellingenbestand#

<OMSI root>\.omsilaunch\modules.ini, naast de sessieprofielen. OmsiLaunch leest het alleen.

; one section per module id
[example-preload]
enabled=true
ram_budget_mb=8192
monitor=false

Secties zijn module-id's; regels key=value stellen instellingen in, enabled schakelt de module voor elke sessie in of uit; regels die met ; of # beginnen zijn commentaar. Het bestand mag maximaal 256 KiB groot zijn. Alles wat niet bruikbaar is (een sectie die geen module-id is, een regel buiten een sectie, een onbekende sleutel, een ongeldige waarde) wordt gemeld met OL_W_MODULE_SETTING_IGNORED en genegeerd.

Sessieprogramma's#

Een module mag één host-component declareren: zijn sessieprogramma, een uitvoerbaar bestand uit zijn eigen map. Wanneer de module in het plan staat, doet de controller het volgende:

1. verifieert de vastzetting van het programma en maakt de gegevensmap van de module aan;
2. start het vóór OMSI, vanuit de modulemap, met de opdrachtregel "<program>" --omsilaunch-session <session id>, opgeschort totdat het in zijn job zit (zie de beveiligingsgrens);
3. schrijft de context als eerste regel op de standaardinvoer ervan;
4. wacht tot het programma {"type":"ready"} schrijft, hoogstens prepare_ms; pas daarna start het OMSI;
5. schrijft nadat OMSI is aangemaakt {"type":"omsi-started","pid":<process id>};
6. schrijft aan het einde van de sessie, nadat OMSI is afgesloten en voordat een bestand wordt hersteld, {"type":"stop"}, wacht hoogstens host_stop_ms en beëindigt dan het programma.

Beide richtingen gebruiken UTF-8-JSON, één object per regel. De context:

Wat het programma behalve ready mag schrijven:

Andere regels, regels langer dan 64 KiB en alles na 10.000 regels worden genegeerd. De controller registreert module.<id>.host.started, host.ready (met prepare_ms), host.failed, host.exited en host.killed.

Een programma dat niet binnen prepare_ms gereed is, afsluit voordat het gereed is, of waarvan de vastzetting niet klopt, laat de voorbereiding van zijn module mislukken: onder fail-session start de sessie niet (OL_E_MODULE_SESSION_FAILED); onder disable-module wordt het programma beëindigd en blijft de module buiten OMSI; onder degrade blijft de module (en blijft het programma doordraaien als dat nog kan). De StartupTimeoutSeconds van de sessie telt vanaf het moment dat OMSI wordt gestart, dus de voorbereiding verbruikt hem niet.

Conflicten met OMSI-plugins#

conflicts.plugins noemt OMSI-plugin-DLL's die niet naast de module mogen draaien, bijvoorbeeld een oudere plugin die dezelfde hooks installeert. Bij het plannen leest OmsiLaunch de sectie [dll] van elke plugins\*.opl; als er een een conflicterende DLL laadt, wordt de module geweigerd met OL_E_MODULE_CONFLICT en noemt de reden de .opl. Binnen OMSI wordt een module waarvan de conflicterende DLL toch is geladen, niet geladen. OmsiLaunch wijzigt nooit de bestanden van een andere plugin; die uitschakelen is de beslissing van de gebruiker.

Meldingen#

Een module-event met de naam notice (van Emit("notice", ...), de emit van een native component of de meldingsregel van een sessieprogramma) wordt door het OmsiLaunch-systeemvakpictogram getoond als een ballonmelding waarvan de titel de module noemt. Alleen title (maximaal 63 tekens) en text (maximaal 255 tekens) blijven behouden, besturingstekens worden verwijderd en niets erin wordt geopend of uitgevoerd. Een sessieprogramma dat de gebruiker moet informeren voordat OMSI start (wanneer het systeemvakpictogram nog niet getoond wordt), gebruikt zijn eigen venster.

Gegevensmap#

<OMSI root>\.omsilaunch\module-data\<id>\ is de schrijfbare map van de module voor deze installatie: IRuntimeModuleContext.DataDirectory, get_value("data_directory") en de data_directory van het sessieprogramma. Ze wordt bij het eerste gebruik aangemaakt. Ze maakt geen deel uit van de sessietransactie: wat een module daar schrijft blijft na de sessie bestaan. /clear-module-data:<id> verwijdert haar (en niets anders); het wordt geweigerd zolang een sessie de installatie in bezit heeft, en een map die via een koppeling wordt bereikt, wordt als koppeling verwijderd en nooit gevolgd.

Levenscyclus#

Elke callback in het proces draait op de UI-thread van OMSI, zoals de eigen runtime-operaties van het product. De brug meet elke callback aan zijn budget: een callback die te laat terugkeert, laat zijn fase mislukken (OL_E_MODULE_PHASE_TIMEOUT). De brug kan een callback die nooit terugkeert niet onderbreken; zo'n module laat OMSI vastlopen, en de sessie eindigt bij zijn opstart-timeout of door session stop, zoals elke andere sessie.

Fouten#

Een fout is een uitzondering of een overschrijding in een fase of operatie, een in het proces niet opgeloste capability, een contentbinding die in het proces niet klopt, een conflicterende plugin die in OMSI is geladen, of een sessieprogramma dat niet gereed raakt. Het failure_policy van de module bepaalt wat volgt. In elk geval worden de resources van de module vrijgegeven.

Een uitgeschakelde of gefaalde module beantwoordt zijn operaties met OL_E_MODULE_DISABLED. Modulefouten verschijnen als sessiediagnoses (SessionStatus.Diagnostics) met hun OL_E_MODULE_*-code en als runtime-events.

Opruimen#

Wat een module via zijn context verkrijgt, wordt bijgehouden: resources geregistreerd met Track, threads gestart met RunBackground, processen gestart met StartAuxiliaryProcess. Bij stoppen of falen annuleert de brug Stopping en geeft ze deze daarna in omgekeerde volgorde vrij. Hulpprocessen worden ook in een jobobject met kill-on-close geplaatst, zodat ze met OMSI eindigen, zelfs als OMSI wordt beëindigd; de job van een sessieprogramma beëindigt het met de OmsiLaunch-sessie, zelfs als OmsiLaunch zelf wordt beëindigd. Een resource die na het vrijgeven nog leeft (een proces dat niet is afgesloten, een thread die niet is geëindigd) wordt gemeld als OL_E_MODULE_CLEANUP_INCOMPLETE. Threads of processen die een module zonder zijn context aanmaakt, worden niet bijgehouden.

Na een crash valt er voor modules niets te herstellen: ze houden geen installatiebestanden vast, en hun geheugen, threads en aan een job gebonden processen eindigen met het OMSI-proces of het OmsiLaunch-proces.

Native componenten en hooks#

Een native component is een 32-bits DLL die de C-interface in src/OmsiLaunch.Native.x86/include/omsilaunch_module_native_v1.h implementeert:

De brugtabel geeft de component request_hook, emit (runtime-events module.<id>.<name> met een JSON-object van tekenreeksen) en, vanaf protocol 2, get_value. Een component leest de size van de tabel voordat ze get_value gebruikt (OMSILAUNCH_BRIDGE_V1_SIZE_WITH_GET_VALUE). get_value(context, name, buffer, capacity, length) kopieert een waarde als UTF-8 met een afsluitende nul en zet *length op de benodigde bytes zonder die nul; het geeft 0, 1 (argument), 2 (onbekende naam), 11 (na stoppen) of 12 (buffer te klein) terug. Namen:

Hooks worden alleen via een symbolisch doel aangevraagd, tijdens start of gameplay_ready, voor een doel waarvan het manifest de capability declareert:

request_hook geeft de functie om de keten voort te zetten terug in *original (een detour moet haar aanroepen). Het resultaat: 0 succes, 1 argument, 2 onbekend doel, 3 de locatie bevat niet wat ze zou moeten bevatten, 4 de locatie is gehookt door iemand buiten de brug, 5 geheugenbeveiliging, 6 register vol, 7 volgorde, 8 geheugen, 9 een thread voerde de te patchen bytes uit, 10 nog geen Direct3D-apparaat, 11 nu niet toegestaan of capability niet gedeclareerd.

Elke hook die de brug installeert, voor het product of een module, wordt in één register vastgelegd met zijn eigenaar (module:<id> voor een module):

• Een hook wordt alleen geïnstalleerd over de waarde die de locatie zou moeten bevatten (de geïmporteerde functie; een functie van een module met de naam d3d9.dll, de systeemruntime of een wrapper), of gestapeld over de bovenste hook van het register zelf op die locatie. Een locatie die al door iemand anders is gewijzigd, wordt geweigerd (4), nooit overschreven.
• Hooks op één locatie worden in last-in-first-out-volgorde verwijderd; een hook met een andere erbovenop blijft staan tot die andere is verwijderd.
• De eigen Direct3D-Reset-hook van het product staat in het register, zodat apparaathooks van modules erop stapelen.
• Bij het opruimen verwijdert de brug elke hook van de module nadat stop is teruggekeerd. Als er een niet kan worden verwijderd (iemand anders heeft de locatie gewijzigd), meldt het opruimen OL_E_MODULE_CLEANUP_INCOMPLETE. De DLL van een native component wordt nooit ontladen zolang OMSI draait, zodat een detour waar nog doorheen wordt teruggekeerd geldig blijft.

De engine ondersteunt ook hooks op functieprologen met een trampoline (andere threads worden opgeschort terwijl de bytes veranderen, en de exacte verwachte bytes worden eerst gecontroleerd), maar er wordt nog geen prologendoel aan modules aangeboden: zulke doelen komen uit de doelcatalogus van de build met geverifieerde bytes.

Operaties#

Een moduleoperatie is module.<id>.<operation>. Ze bestaat alleen voor een sessie waarvan het plan de module heeft geladen (PlannedModule.Operations); anders antwoordt ExecuteRuntimeAsync met OL_E_MODULE_NOT_LOADED of OL_E_MODULE_OPERATION_UNKNOWN. Vereiste argumenten worden gecontroleerd en niet-gedeclareerde argumenten worden geweigerd (OL_E_RUNTIME_ARGUMENT_REQUIRED). Een getypeerde fout van een module behoudt zijn code wanneer dat een gecatalogiseerde openbare code is; elke andere code wordt OL_E_MODULE_OPERATION_FAILED met de code van de module in Values["module_code"]. Resultaatsleutels die de interne naamconventie volgen worden verwijderd, zoals bij elke runtime-operatie.

OmsiLaunch.exe /new /map:maps\Grundorf\global.cfg /entrypoint-index:1 /module:null-test
OmsiLaunch.exe /runtime:module.null-test.ping /runtime-arg:text=hello

Een module schrijven (contracten)#

De beheerde component verwijst naar OmsiLaunch.Runtime.Modules en OmsiLaunch.Api en implementeert IRuntimeModule. De brug bindt deze twee verwijzingen aan haar eigen geladen assemblies (in welke laadcontext de plugin ook draait), dus een met de module meegeleverde kopie wordt genegeerd:

IRuntimeModuleContext biedt SessionId, ModuleId, ModuleDirectory, Settings, DataDirectory, ProductVersion, SessionChannelName, Stopping (een annuleringstoken), IsCapabilityAvailable, Emit, Track, RunBackground en StartAuxiliaryProcess. Niets daarin legt adressen, het uitvoerbare bestand of zijn identiteit bloot. De component moet door de 32-bits plugin laadbaar zijn (AnyCPU of x86, .NET 6). Zet elk bestand vast dat de programma's van de module laden (voor een .NET-programma: zijn .dll naast de .exe), zodat de integriteitscontrole ze dekt.

Bekende beperkingen#

• Native componenten kunnen imports van Omsi.exe en methoden van het Direct3D-apparaat hooken; hooks op prologen en aanroeplocaties van OMSI-functies worden nog niet aan modules aangeboden.
• De contentbindingscontrole in het proces gebruikt de kaart die de start heeft aangevraagd (NEW_MAP); voor een opgeslagen situatie wordt de binding bij het plannen gecontroleerd tegen de kaart van de situatie.
• Apparaathooks zijn vtable-hooks. Waar een andere component de oorspronkelijke methoden van het apparaat terugschrijft (waargenomen op de regressie-installatie kort nadat de gameplay start), wordt een apparaathook niet meer aangeroepen en kan hij niet worden verwijderd; het opruimen meldt dan OL_E_MODULE_CLEANUP_INCOMPLETE en de component blijft geladen. Een apparaatmethode die al door iets buiten het register is gehookt, wordt geweigerd (4); het weigeringsevent noemt de module die de methode bezit.
• Modules stoppen bij een normale OMSI-afsluiting; een sessiestop beëindigt OMSI, dus het opruimen van modules binnen een sessie gebeurt alleen via een faalbeleid.
• Meldingen worden getoond zodra het systeemvakpictogram bestaat, nadat OMSI is gestart; een sessieprogramma toont zijn eigen venster voor alles wat het daarvóór moet zeggen.