Perfis de sessão

Documentação da versão v0.1.0-beta.3Ver código-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: em caso de divergência, prevalecem a página em inglês e o código.

Um perfil de sessão é um pacote YAML declarativo que um autor de conteúdos distribui com um mapa ou um add-on para que os utilizadores finais possam iniciar uma sessão reprodutí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 tal como 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 definições que um perfil pode escrever (ConfigurationCatalog). Tudo o que um perfil pode fazer também o podem fazer as flags da CLI e o LaunchSpec; um perfil limita-se a empacotar essas escolhas.

Estabilidade: STABLE_BETA para a análise, a validação, a deteção de conflitos e os blocos settings / presentation / internet-textures / behavior (teste offline session-profiles.strict-compiler; o caminho de overlay e restauro está validado em runtime por RV-005 e RV-006, ver o estado 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).

Localização e nomenclatura do pacote#

Um perfil é instalado e removido pelo utilizador ou pelo autor de conteúdos. O OmsiLaunch nunca escreve num pacote, nunca o copia e nunca o elimina. O diretório do pacote não faz parte de nenhuma transação.

Regras de análise#

As barras invertidas em escalares simples (sem aspas) são caracteres literais. Os caminhos do Windows escrevem-se com uma única barra invertida (maps\Grundorf\global.cfg). Uma barra invertida duplicada num escalar simples fica duplicada no valor; ver O exemplo incluído no pacote.

Referência das chaves#

Os contextos têm exatamente os nomes que o compilador lhes dá. Todas as chaves aqui listadas são aceites; nenhuma outra o é.

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, a predefiniçã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 planeador de sessões (src/OmsiLaunch.Core/SessionPlanner.cs) reporta então as capacidades world.explicit-date, world.explicit-time, world.explicit-year e weather como STATICALLY_PARTIAL, acrescenta OL_E_CAPABILITY_UNAVAILABLE aos diagnósticos do plano e marca o plano como não executável. Além disso, o plugin rejeita um handoff cujo modo de data ou de hora não seja Unset (plugin.request.unsupported). Consequência para este build: um perfil que defina qualquer uma destas quatro chaves pode ser validado com /plan, mas não consegue iniciar uma sessão (código de saída 1, OL_E_PLAN_NOT_RUNNABLE). Estas chaves devem ficar de fora dos perfis destinados a ser executados.

new.date#

new.time#

new.weather#

preset (cada entrada de presets)#

Só a predefinição selecionada é aplicada. Todas as predefinições são, ainda assim, analisadas e validadas, pelo que um erro na predefinição 3 faz falhar um pedido da predefinição 1.

presentation#

presentation.splash#

Um perfil não pode definir SessionPresentationSpec.SuppressTrayIcon; mantém-se false, a menos que um /spec o defina.

internet-textures#

behavior#

Quando o bloco behavior está presente, ambos os timeouts são definidos (valor indicado ou predefinição) e substituem por completo o LaunchBehaviorSpec de base, incluindo RestoreConfiguration e SuppressStaleClosecheckWarning, que voltam às respetivas predefinições (true, true).

Definições#

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

Formas dos valores:

• bool é true ou false (sem distinção de maiúsculas/minúsculas). Nos tokens de presença, o token é acrescentado ou removido; nos tokens invertidos (no_*), true remove o token negativo.
• int / decimal são validados contra o intervalo; os valores com divisor são guardados divididos (por exemplo, graphics.minObjectScreenPercent: 5 escreve 0.05).
• string é escrita tal como está.

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 caminhos#

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

1. São rejeitados os caminhos com raiz (C:\...), os caminhos que começam por \ e qualquer componente de caminho igual a ...
2. O caminho completo é calculado e tem de começar pelo diretório do pacote.
3. Cada componente existente abaixo da raiz do pacote, até ao caminho final inclusive, é inspecionado quanto ao atributo ReparsePoint. Uma junção, uma ligação simbólica de diretório ou uma ligação simbólica de ficheiro em qualquer ponto desse caminho é rejeitada, tal como um componente que não possa ser inspecionado (IOException / UnauthorizedAccessException).

As três falhas dão OL_E_SESSION_PROFILE_PATH_ESCAPE. A mesma regra de pontos de reanálise é aplicada aos destinos .itx sob Texture\ na construção da sessão.

Precedência e conflitos de substituição#

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

1. Predefinições (NEW_MAP, tudo por definir, timeouts 180 s / 30 s).
2. /spec:<file.json>, se indicado, substitui por completo as predefiniçõ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 fusão. O bloco de mundo da semente é então reposto num WorldSpec vazio do modo selecionado (um mundo de /spec é descartado quando se usa um perfil) e SessionProfileCompiler.Apply sobrepõe o perfil à semente: new (apenas NEW_MAP), settings (fundidas sobre o Environment.General da semente, prevalecendo o perfil chave a chave) e presentation, internet-textures, behavior (cada um substitui o bloco da semente apenas quando a predefinição o define).
5. Restantes argumentos da CLI são sobrepostos: /map, /entrypoint, /entrypoint-index, /date, /time, /year, flags de meteorologia, flags de veículo, /set, flags de splash, flags de internet-textures, /startup-timeout, /shutdown-timeout. Os timeouts da CLI só se aplicam quando indicados; caso contrário mantém-se o valor da especificação/perfil/predefinição.
6. Verificação de compatibilidade para modos que não sejam NEW_MAP (ValidateCompatibility).

Um argumento da CLI que vise 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 é feita por campo, não por valor: repetir o próprio valor do perfil continua a ser um conflito.

Não são conflitos: chaves /set que a predefinição não define (são acrescentadas), 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 em conjunto com /saved, independentemente dos perfis (OL_E_INVALID_ARGUMENT).

Códigos de erro#

Todos estes erros são gerados durante a compilação da linha de comandos, antes do planeamento. São SessionProfileException (ou ArgumentException no caso do conflito) e nunca iniciam uma sessão. O catálogo completo está em erros; os códigos de saída estão em códigos de saída.

Como um perfil aparece na API#

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

O planeador acrescenta um diagnóstico informativo session_profile.selected a cada SessionPlan construído a partir de uma 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. Não afeta a executabilidade. Os integradores que usam diretamente a API pública podem chamar SessionProfileCompiler.Load e SessionProfileCompiler.Apply a partir de OmsiLaunch.Core; a representação YAML nunca atravessa para OmsiLaunch.Api.

Exemplos#

Exemplo 1: perfil só com definiçõ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

Executar: 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 comandos porque o perfil não define nenhum bloco new; acrescentar /set:graphics.maxFPS=60 é permitido, acrescentar /set:traffic.humans=10 é um conflito.

Exemplo 2: perfil associado a um mapa, com três predefinições e recursos incluídos no pacote#

<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

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

O exemplo incluído no pacote#

O lançamento inclui docs/examples/session-profiles/rmg-leste/profile.yaml (ver). É sintaticamente válido, corresponde ao esquema e seria carregado sem erros. Duas propriedades impedem-no de iniciar uma sessão sem alterações neste build:

1. Define new.date, new.time e new.weather, que tornam o plano não executável (ver O bloco new).
2. Os seus valores de caminho são escalares simples com barras invertidas duplicadas (maps\\RMG Leste\\global.cfg). O YAML mantém-nas duplicadas e as identidades de mapa são comparadas textualmente (apenas após a normalização de / para \), pelo que new.map e compatibility.maps não corresponderiam à identidade do catálogo maps\RMG Leste\global.cfg (OL_E_MAP_NOT_FOUND no planeamento). O valor assets continua a ser resolvido porque a normalização de caminhos do Windows reduz os separadores duplicados.

A forma executável para este 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 registo em que um perfil é compilado
• Transações e recuperação para a forma como os overlays de settings, de splash e de .itx são aplicados e restaurados
• Capacidades e estado da validação em runtime