ZScript

ZScript (antigamente conhecido como DoomScript) é um lump baseado em texto usado para criar classes, structs, menus e funcionalidades personalizadas para uso no ZDoom. Ele serve como substituto completo do DECORATE e como substituto parcial do SBARINFO, ao mesmo tempo em que suporta todos os métodos e recursos deles. ZScript é parecido com Java e C# em vários aspectos e permite um controle muito mais avançado de praticamente tudo no gameplay (Atores, mapas, modos de jogo, etc.) do que o DECORATE permite, além de possibilitar a criação de UI (como HUDs customizadas e menus).

Assim como no DECORATE, você pode incluir múltiplos lumps/arquivos de ZScript para processamento, usando um caminho completo ou relativo. Um caminho relativo começa com ./ ou ../:

 // Caminho completo

# include "ZScript/Const.txt"

// Caminhos relativos

# include "./Items/Health.txt" // Começa a partir do diretório onde este arquivo está
# include "../Items/Armor.txt" // Começa a partir do diretório pai

Devido a como o ZScript é processado, é possível dar a um arquivo um nome que conflite com outros mods ou com arquivos internos do próprio engine. Por exemplo, se você tiver um arquivo no seu mod com o caminho ZScript/Const.txt, isso impedirá o jogo de carregar corretamente esse arquivo, já que o próprio ZDoom já define esse arquivo dentro da subpasta ZScript dele. Para evitar esse tipo de conflito, é recomendado ter uma subpasta com o nome do seu mod, por exemplo:

# include "MyMod/Const.txt"

Antes de GZDoom 2.3.0, o ZScript precisava ser habilitado manualmente via parâmetro de linha de comando, mas hoje ele é usado por padrão. As últimas versões de desenvolvimento do ZDoom após a 2.8.1 exigiam o parâmetro -zscript para habilitar o carregamento de lumps ZScript.

Um arquivo completo de ZScript é chamado de unidade de tradução (translation unit), semelhante ao uso do termo na linguagem C.

Note: Todas as palavras-chave e identificadores no ZScript não diferenciam maiúsculas/minúsculas (case insensitive).

Recursos do ZScript

Os seguintes recursos existem desde o GZDoom 3.0:

Compatibilidade com DECORATE (classes em DECORATE podem herdar de classes em ZScript)
Constantes
Variáveis locais e no escopo da classe
Capacidade de definir e manipular ponteiros de ator customizados
Funções customizadas
Arrays
Dynamic arrays
Acesso (e controle parcial) a dados do mapa (por exemplo, veja LevelLocals)
Definição de menus customizados
Substituto do SBARINFO

Ordem de carregamento

Para um arquivo carregado no GZDoom, ele carrega o arquivo ./zscript.txt em um arquivo ZIP (PK3) ou o lump ZSCRIPT em um WAD. Para mais informações, veja a página sobre versionamento de arquivos.

O ZScript é bem mais flexível e os includes podem ser feitos em qualquer ordem, exceto no caso de extender classes.

Combinando ZScript e DECORATE

É possível usar DECORATE e ZScript ao mesmo tempo. Por exemplo, o ZScript pode ser usado para criar uma função customizada que então fica disponível para atores em DECORATE. O código em ZScript é processado e compilado antes do código em DECORATE; isso significa que atores DECORATE podem herdar de atores ZScript, mas não o contrário. Para referências necessárias apenas em tempo de execução, e não em tempo de compilação (como chamar uma função para spawnar um ator), não há restrição: um ator em ZScript pode spawnar um ator em DECORATE, e vice-versa.

Isso geralmente só é recomendado quando um projeto originalmente feito em DECORATE está sendo atualizado para ZScript. Para projetos novos, o DECORATE deve ser considerado obsoleto, e o ZScript deve ser usado para definir todas as classes (todos os métodos, recursos e funções do DECORATE ainda podem ser usados no ZScript de maneira muito parecida). O próprio GZDoom não usa mais DECORATE para suas classes internas.

ZScript tem, e continuará tendo, uma enorme expansão de recursos.

Tópicos de ZScript

Tópicos avançados

Estas seções são para usuários avançados e programadores que querem mais controle sobre seus mods. O melhor caminho para modders é dar uma revisada em uma linguagem como Java ou C#. Esses tópicos assumem que quem lê já sabe trabalhar com ZScript, de preferência com boa parte do que foi listado acima.

Também vale a pena abrir o gzdoom.pk3 com qualquer programa que consiga navegar arquivos ZIP. O arquivo base contém bastante código ZScript que pode servir como exemplo para modders.

Guias de ZScript

Documentação adicional

Se nenhuma das páginas acima responder suas dúvidas, o Marrub vem trabalhando em uma documentação mais detalhada e abrangente do núcleo da linguagem e da API do ZScript, disponível em este tópico no fórum. Esse material ainda é um trabalho em andamento, mas deve ser incorporado ao wiki quando estiver completo. Até lá, essa documentação extra pode ser encontrada aqui: https://github.com/marrub--/zscript-doc/blob/master/README.md