Programação e scripts do OMSI 2 – conceitos básicos vol. 1

Olá, por meio deste tutorial vou explicar alguns princípios básicos de programação e como eles se aplicam aos scripts do OMSI 2. A partir dos princípios explicados aqui é possível compreender e ter um domínio maior sobre como modificar/criar scripts para seus modelos no jogo.

Estrutura
Para começar a entender os scripts do OMSI 2, é necessário antes entender um conjunto de conceitos chamado de lógica de programação. No entanto, a melhor forma de explicar isso é com exemplos práticos com o próprio script.

Os scripts do jogo são feitos em uma linguagem de programação própria do jogo, baseada em Pascal mas com algumas diferenças. A estrutura básica de organização dos arquivos da base de scripts segue a seguinte lógica:

Arquivos _varlist no formato .txt
Arquivos _constfile no formato .txt
Arquivos _stringvarlist no formato .txt
Arquivos script no formato .osc
Arquivos varlist
Os arquivos varlist armazenam os nomes de todas as variáveis usadas em um script .osc. Estas variáveis assumem valores numéricos na programação de um script. Os nomes das variáveis devem ser colocados um a um por linha, sem espaços ou caracteres especiais. Podem ser usadas linhas em branco para separar grupos de variáveis.

Exemplo: door_varlist.txt

door_0
door_1
door_2
door_3

door_anjodaguarda_off
doorTarget_01
Arquivos constfile
São os arquivos que armazenam valores constantes, ou seja, valores numéricos que não mudam conforme a execução do script. Também são usados para armazenar as curvas de torque e consumo e limites de RPM dos motores, por exemplo.

Exemplo: engine_constfile_OM926LA.txt

 
[const]
engine_speedcontrol
1 

------------------------
Speed Governor thershold 
------------------------

[newcurve]
governor

[pnt]
0
1

[pnt]
1
0

[pnt]
1.01
0

Os trechos começados em [newcurve] são declarações de funções matemáticas lineares ponto a ponto. Por exemplo, a curva de torque do motor é uma função: dado um determinado valor X de RPM (valor de entrada), o valor de torque (valor de saída) é um determinado valor Y:

[newcurve]
engine_M_maxThrottle

[pnt]
300
350

[pnt]
550
600

[pnt]
600
695

[pnt]
800
755

[pnt]
1000   <- para 1000 RPM saem 830 NM de torque
830

[pnt]
1200
850

[pnt]
1400
850

[pnt]
1600
850 

Arquivos stringvarlist
São arquivos que armazenam variáveis de texto ou strings, que serão utilizadas em determinado script .osc. Geralmente este tipo de arquivo é usado nos scripts de letreiro e painel (cockpit), para tratar os textos dinâmicos exibidos no veículo como números de linhas, destinos, informações do painel, letreiros, etc. A organização dos nomes das variáveis é a mesma dos arquivos varlist, com cada nome em cada linha, sem caracteres especiais e espaços.

Exemplo: matrix_stringvarlist.txt

Matrix_InnerDispStatus

Matrix_MEPStatus1
Matrix_MEPStatus2
Matrix_MEPStatus3
Matrix_MEPStatus4
Matrix_MEPStatusCut2
Matrix_MEPStatusCut3
Matrix_MEPStatusCutBegin2
Matrix_MEPStatusCutBegin3
Arquivos script .osc
Os arquivos script são os que contém toda a lógica e o código para execução das funções de um veículo no jogo. Ele consome todos os outros arquivos que armazenam variáveis, constantes e variáveis de texto a depender do que foi programado no código.
Um mesmo script pode acessar variáveis de quaisquer arquivos varlist presentes na pasta Scripts do veículo. Por convenção e boas práticas, procura-se, quando possível, apenas acessar variáveis presentes nos arquivos .txt de mesmo nome do script, especialmente se são variáveis apenas para o funcionamento daquele script em especial (ex.: variável door_0 da porta 1, é declarada e usada no script door.osc apesar de ser usada em outros scripts para saber seu estado).
Um script é subdividido em três principais blocos de código:

Triggers
Macros principais _init e _frame
Macros auxiliares
É importante notar que a ordem destes blocos é essencial para o correto funcionamento do script. Triggers não podem ficar abaixo de quaisquer outros blocos de código, sendo presentes sempre no início do script. Além disso, todos os comandos de código devem estar dentro de alguma destas estruturas, senão podem gerar erros de execução do script.

As macros principais com sufixos_init e _frame precisam sempre estar logo após os triggers, para o correto funcionamento das macros auxiliares que seguem após elas.

Além disso, entre si, os arquivos de script seguem a seguinte hierarquia: o script main.osc é o script responsável por chamar à execução todas as macros _init e _frame principais de cada um dos outros scripts. O OMSI 2 reconhece as macros {init} e {frame} do main.osc como as macros principais para execução de todos os sistemas do veículo, portanto são indispensáveis para o funcionamento correto.

Clique para ver imagem

exemplo
Todos os blocos de código são terminados com uma tag de fim de bloco, a tag {end}:

Clique para ver imagem

Se um bloco de código, seja ele trigger ou macro, estiver sem a tag {end} ao final dele, o script terá erro de sintaxe e isso irá gerar erros na execução no jogo.

Variáveis
Aqui, detalhamos como são utilizadas as variáveis vistas anteriormente nos arquivos varlist. As variáveis podem ter seus valores lidos ou sobrescritos conforme os comandos de leitura e escrita no código do script, os comandos load local (L.L.) e save local (S.L.). Exemplo:

' Carrega o valor de uma variável para a memória
(L.L.door_0)
' Salva o valor 1 na variável anjo_da_guarda
1 (S.L.anjo_da_guarda)
Constantes
As constantes, por serem valores já fixados, podem apenas serem lidos no código com constant load (C.L.):

' Carregando a constante do valor máximo de RPM na memória
  (C.L.rpmgov)

Funções
As funções, declaradas no arquivo constfile, são utilizadas somente conforme a associação com algum valor de entrada, seja ele uma variável, número explícito no código ou uma constante, através do comando function load (F.L.). Por exemplo, para obter o valor de torque do motor a uma determinada rotação:

'  Puxa qual o torque a 1500 rpm para a memória:
   1500 (F.L.engine_M_maxThrottle)
Variáveis de texto (strings)
As strings podem ser lidas e escritas no código da mesma forma que as variáveis numéricas, mas trocando o L de local para o caractere $ nos comandos save string (S.$.) e load string (L.$). Exemplo:

' Carrega o texto da primeira fase do letreiro (string) para a memoria:
   (L.$.matrix_MEPStatus1)

' Salva o texto METRO TATUAPE na variável string da segunda fase do letreiro:
   "METRO TATUAPE" (S.$.matrix_MEPStatus2)
Triggers
São blocos de código que são chamados através de comandos clicáveis ou por comandos do teclado nos modelos. Um comando abaixo de uma tag [mouseevent] lá no arquivomodel.cfg de um modelo para acionar as luzes do interior, por exemplo, é um trigger:

Clique para ver imagem

mouseevent para o botão multiplex da luz do salão

Clique para ver imagem

trigger do botão multiplex da luz do salão dentro do arquivo de script cockpit.osc
Triggers são executados somente quando é acionado o botão/tecla do teclado ao qual foram atribuídos.

Macros
Macros são blocos de código que executam quando são chamadas dentro do script, através do comando (M.L.) – macro load. As macros subdividem-se em macros principais com os sufixos _init e _frame e macros auxiliares.

Clique para ver imagem

Exemplo: as chamadas às macros destacadas cuidam da execução da animação em tempo real dos ponteiros do painel, de acordo com os parâmetros dos sistemas do veículo
As macros principais são mandatórias em um arquivo script pois são elas que cuidarão da execução de todo o funcionamento daquele script em tempo de execução, ao rodar o jogo. Também são as macros que serão chamadas através do macro load no script principal main.osc.

A macro principal com sufixo _init é chamada sempre na inicialização do modelo (quando você coloca o modelo no mapa pela primeira vez). Ela serve para inicializar variáveis com valores padrão, como o estado de alguns itens do painel (por exemplo, sistema elétrico desligado e portas abertas, janelas abertas, etc.).

Já a macro principal com o sufixo _frame é a macro que é executada em loop infinito enquanto o veículo estiver no jogo, que trata de executar e controlar as funcionalidades em tempo real.

Exemplo: script cockpit.osc
Cada script irá conter uma macro principal _init e outra _frame com o mesmo nome do arquivo de script, por convenção. Logo, neste exemplo teremos as macros cockpit_init e cockpit_frame:

Clique para ver imagem

As macros cockpit_init e cockpit_frame são as primeiras no script, logo depois de todos os triggers de funções clicáveis/teclas.
No próximo post, veremos com mais detalhe sobre como são feitas as operações entre variáveis como as matemáticas (adição, subtração, etc.) e lógicas if, else (se, senão) para o controle de ações. Para adiantar, vale a leitura sobre a notação polonesa reversa, que é a forma na qual as operações lógico-matemáticas são feitas nos scripts do OMSI 2.

Referências e leitura adicional
Scripting system – OMSIWiki – página em inglês, contém detalhes sobre as operações lógico-matemáticas, strings e comandos de sistema.