Perfis de sessão

Documentação da versão v0.1.0-beta.3Ver fonte no GitHub

Tradução da página original em inglês do OmsiLaunch 0.1.0-beta3. A página em inglês é a referência normativa: se as duas divergirem, valem a página em inglês e o código.

Um perfil de sessão é um pacote YAML declarativo que um autor de conteúdo distribui com um mapa ou um add-on para que os usuários finais possam iniciar uma sessão reproduzível do OmsiLaunch com um único comando (OmsiLaunch.exe /predefined-profile:<id> /predefined-profile-index:<1..5> /new). Esta página é a referência normativa do formato omsilaunch.session-profile/v1 conforme implementado por SessionProfileCompiler em src/OmsiLaunch.Core/SessionProfiles.cs, das regras de precedência aplicadas pela CLI (CliInput.BuildSpecAsync e RejectProfileConflicts em tools/OmsiLaunch.Cli/Program.cs) e do catálogo de configurações que um perfil pode gravar (ConfigurationCatalog). Tudo o que um perfil pode fazer também pode ser feito pelas flags da CLI e pelo LaunchSpec; um perfil apenas empacota essas escolhas.

Estabilidade: STABLE_BETA para análise, validação, detecção de conflitos e os blocos settings / presentation / internet-textures / behavior (teste offline session-profiles.strict-compiler; o caminho de overlay e restauração é validado em runtime por RV-005 e RV-006, ver status da validação em runtime). As chaves new.date, new.time, new.year e new.weather são UNAVAILABLE neste build (ver O bloco new).

Local e nomenclatura do pacote#

Um perfil é instalado e removido pelo usuário ou pelo autor do conteúdo. O OmsiLaunch nunca grava dentro de um pacote, nunca o copia e nunca o exclui. O diretório do pacote não faz parte de nenhuma transação.

Regras de análise#

Barras invertidas em escalares simples (sem aspas) são caracteres literais. Escreva caminhos do Windows com uma única barra invertida (maps\Grundorf\global.cfg). Uma barra invertida dupla em um escalar simples permanece dupla no valor; ver O exemplo empacotado.

Referência de chaves#

Os contextos têm exatamente os nomes que o compilador usa. Toda chave listada aqui é aceita; nenhuma outra é.

profile (mapeamento raiz)#

compatibility#

new#

O bloco é lido e validado sempre que está presente, mas só é aplicado à especificação quando o modo de mundo selecionado é NEW_MAP (/new, o padrão da CLI). Com /saved:<file.osn> o bloco é ignorado.

date, time, year e weather são compilados em DateSpec, TimeSpec, YearSpec e WeatherSpec com DateTimeMode.Explicit / o WeatherMode selecionado. O planejador de sessão (src/OmsiLaunch.Core/SessionPlanner.cs) então reporta as capacidades world.explicit-date, world.explicit-time, world.explicit-year e weather como STATICALLY_PARTIAL, adiciona OL_E_CAPABILITY_UNAVAILABLE aos diagnósticos do plano e marca o plano como não apto para execução. O plugin, além disso, rejeita um handoff cujo modo de data ou hora não seja Unset (plugin.request.unsupported). Consequência para este build: um perfil que define qualquer uma dessas quatro chaves pode ser validado com /plan, mas não pode iniciar uma sessão (código de saída 1, OL_E_PLAN_NOT_RUNNABLE). Deixe-as fora dos perfis destinados a serem executados.

new.date#

new.time#

new.weather#

preset (cada entrada de presets)#

Apenas a predefinição selecionada é aplicada. Todas as predefinições ainda são analisadas e validadas, então um erro na predefinição 3 faz falhar uma requisição da predefinição 1.

presentation#

presentation.splash#

Um perfil não pode definir SessionPresentationSpec.SuppressTrayIcon; ele permanece false, a menos que um /spec o defina.

internet-textures#

behavior#

Quando o bloco behavior está presente, ambos os timeouts são definidos (valor informado ou padrão) e substituem inteiramente o LaunchBehaviorSpec da linha de base, incluindo RestoreConfiguration e SuppressStaleClosecheckWarning, que voltam aos seus padrões (true, true).

Configurações#

As chaves de settings são os nomes semânticos de ConfigurationCatalog (src/OmsiLaunch.Configuration/ConfigurationCatalog.cs). O compilador aceita uma chave somente se ela existir (OL_E_SESSION_PROFILE_SETTING_UNKNOWN) e for gravável (OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE). Os valores são armazenados como strings e convertidos em um patch de options.cfg quando a sessão constrói seus overlays; um valor inválido, portanto, é detectado em StartSessionAsync, não no carregamento do perfil, e faz a sessão falhar com OL_E_START_SESSION, cuja mensagem traz OL_E_INVALID_SETTING_VALUE: <key>. Todas as configurações abaixo gravam options.cfg; todas têm escopo de sessão e são restauradas exatamente após a sessão.

Formas de valor:

• bool é true ou false (sem diferenciar maiúsculas de minúsculas). Para tokens de presença, o token é adicionado ou removido; para tokens invertidos (no_*), true remove o token negativo.
• int / decimal são validados contra o intervalo; valores com divisor são armazenados divididos (por exemplo, graphics.minObjectScreenPercent: 5 grava 0.05).
• string é gravada literalmente.

Entradas do catálogo que existem, mas não são graváveis (rejeitadas com OL_E_SESSION_PROFILE_SETTING_NOT_WRITABLE): advanced.multithreadingCalculate, advanced.multithreadingTextureLoad (substituídas por advanced.reducedMultithreading), graphics.texture, graphics.textureFilter.

Confinamento de caminho#

presentation.splash.assets e internet-textures.profile são resolvidos por Confined(package root, value):

1. Caminhos enraizados (C:\...), caminhos que começam com \ e qualquer componente de caminho igual a .. são rejeitados.
2. O caminho completo é calculado e deve começar com o diretório do pacote.
3. Todo componente existente abaixo da raiz do pacote, até o caminho final inclusive, é inspecionado quanto ao atributo ReparsePoint. Uma junction, um link simbólico de diretório ou um link simbólico de arquivo em qualquer ponto desse caminho é rejeitado, assim como um componente que não pode ser inspecionado (IOException / UnauthorizedAccessException).

As três falhas geram OL_E_SESSION_PROFILE_PATH_ESCAPE. A mesma regra de reparse point é aplicada aos destinos .itx sob Texture\ na construção da sessão.

Precedência e conflitos de sobrescrita#

CliInput.BuildSpecAsync compõe a especificação nesta ordem:

1. Padrões (NEW_MAP, tudo não definido, timeouts 180 s / 30 s).
2. /spec:<file.json>, se informado, substitui inteiramente os padrões.
3. Raiz da instalação: um argumento de instalação explícito prevalece sobre o RootPath da especificação; . significa o diretório que contém o executável.
4. Perfil (/predefined-profile + /predefined-profile-index): o pacote é carregado e RejectProfileConflicts é executado contra os argumentos brutos da CLI antes de qualquer mesclagem. O bloco de mundo da base é então redefinido para um WorldSpec vazio do modo selecionado (um mundo de /spec é descartado quando um perfil é usado) e SessionProfileCompiler.Apply sobrepõe o perfil à base: new (apenas NEW_MAP), settings (mesclado sobre o Environment.General da base, o perfil prevalece por chave) e presentation, internet-textures, behavior (cada um substitui o bloco da base somente quando a predefinição o define).
5. Argumentos restantes da CLI são sobrepostos por cima: /map, /entrypoint, /entrypoint-index, /date, /time, /year, flags de clima, flags de veículo, /set, flags de splash, flags de texturas da internet, /startup-timeout, /shutdown-timeout. Os timeouts da CLI se aplicam apenas quando informados; caso contrário, vale o valor da especificação/perfil/padrão.
6. Verificação de compatibilidade para modos diferentes de NEW_MAP (ValidateCompatibility).

Um argumento da CLI que visa um campo pertencente ao perfil selecionado é um conflito, rejeitado com OL_E_SESSION_PROFILE_OVERRIDE_CONFLICT (código de saída 2, categoria invalid_argument). A verificação é por campo, não por valor: repetir o próprio valor do perfil ainda é um conflito.

Não são conflitos: chaves de /set que a predefinição não define (elas são adicionadas), flags de veículo (/vehicle, /repaint, /hof, /fleet, /registration, /no-vehicle; um perfil não pode definir um veículo do jogador) e qualquer argumento de mundo com /saved (o bloco new não é aplicado nesse caso). /map, /entrypoint e /entrypoint-index são inválidos junto com /saved, independentemente de perfis (OL_E_INVALID_ARGUMENT).

Códigos de erro#

Todos esses erros são gerados enquanto a linha de comando está sendo compilada, antes do planejamento. Eles são SessionProfileException (ou ArgumentException para o conflito) e nunca iniciam uma sessão. O catálogo completo está em erros; os códigos de saída em códigos de saída.

Como um perfil aparece na API#

Após um carregamento bem-sucedido, a especificação traz um registro SessionProfileMetadata em LaunchSpec.SessionProfile:

O planejador adiciona um diagnóstico informativo session_profile.selected a todo SessionPlan construído a partir de tal especificação, com as chaves de dados session_profile.id, session_profile.name, session_profile.version, session_profile.author, session_profile.preset_id, session_profile.preset_index, session_profile.preset_name e session_profile.path. Ele não afeta a aptidão para execução. Integradores que usam a API pública diretamente podem chamar SessionProfileCompiler.Load e SessionProfileCompiler.Apply a partir de OmsiLaunch.Core; a representação YAML nunca passa para OmsiLaunch.Api.

Exemplos#

Exemplo 1: perfil apenas com configurações, uma predefinição#

<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

Execução: OmsiLaunch.exe /predefined-profile:quiet-evening /predefined-profile-index:1 /new /map:maps\Grundorf\global.cfg /entrypoint-index:0. O mapa e o ponto de entrada vêm da linha de comando porque o perfil não define nenhum bloco new; adicionar /set:graphics.maxFPS=60 é permitido, adicionar /set:traffic.humans=10 é um conflito.

Exemplo 2: perfil vinculado a um mapa com três predefinições e assets empacotados#

<root>\.omsilaunch\session-profiles\grundorf-tour\profile.yaml, com assets\splash\ENG.bmp, assets\splash\DEU.bmp e textures\offline.itx dentro do pacote:

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

Execução: OmsiLaunch.exe /predefined-profile:grundorf-tour /predefined-profile-index:2 /new. Com /saved:situations\mytrip.osn, o bloco new é ignorado e o .osn deve referenciar maps\Grundorf\global.cfg.

O exemplo empacotado#

O release distribui docs/examples/session-profiles/rmg-leste/profile.yaml (ver). Ele é sintaticamente válido, corresponde ao schema e seria carregado sem erro. Duas características o impedem de iniciar uma sessão sem alterações neste build:

1. Ele define new.date, new.time e new.weather, que tornam o plano não apto para execução (ver O bloco new).
2. Seus valores de caminho são escalares simples com barras invertidas duplas (maps\\RMG Leste\\global.cfg). O YAML as mantém duplas, e as identidades de mapa são comparadas textualmente (após apenas a normalização de / para \), então new.map e compatibility.maps não corresponderiam à identidade de catálogo maps\RMG Leste\global.cfg (OL_E_MAP_NOT_FOUND no planejamento). O valor de assets ainda é resolvido porque a normalização de caminhos do Windows reduz separadores duplicados.

A forma apta para execução neste build é:

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

Páginas relacionadas#

• Referência da CLI para /predefined-profile, /predefined-profile-index, /set e as flags de mundo
• LaunchSpec para o registro no qual um perfil é compilado
• Transações e recuperação para como os overlays de settings, de splash e de .itx são aplicados e restaurados
• Capacidades e status da validação em runtime