MegaManx3: Criação da pagina do Zcript

2026-02-05T16:03:48Z

Criação da pagina do Zcript

Página nova

'''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 {{class|BaseStatusBar|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 {{c|./}} ou {{c|../}}:

<syntaxhighlight lang="csharp"> // 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

</syntaxhighlight>

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 {{c|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 {{c|ZScript}} dele. Para evitar esse tipo de conflito, é recomendado ter uma subpasta com o nome do seu mod, por exemplo:

<syntaxhighlight lang="csharp">

# include "MyMod/Const.txt"

</syntaxhighlight>

Antes de {{DRDForum|GZDoom 2.3.0|t=7453}}, 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 {{c|-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)
* [[ZScript data types#Constants|Constantes]]
* [[ZScript data types|Variáveis]] locais e no escopo da classe
* Capacidade de definir e manipular ponteiros de ator customizados
* Funções customizadas
* [[ZScript data types#Arrays|Arrays]]
* [[Dynamic arrays]]
* Acesso (e controle parcial) a dados do mapa (por exemplo, veja {{struct|LevelLocals}})
* [[ZScript menus|Definição de menus customizados]]
* {{class|BaseStatusBar|Substituto do SBARINFO}}

== Ordem de carregamento ==
Para um arquivo carregado no GZDoom, ele carrega o arquivo {{c|./zscript.txt}} em um [[Using ZIPs as WAD replacement|arquivo ZIP (PK3)]] ou o lump {{c|ZSCRIPT}} em um WAD. Para mais informações, veja [[Object scopes and versions|a página sobre versionamento de arquivos.]]

O ZScript é bem mais flexível e os {{c|include}}s podem ser feitos em qualquer ordem, exceto no caso de [[ZScript classes#Extending Classes|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 [[Deprecation|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 ==

* [[Coding language differences]]
* [[ZScript data types]]
* [[Operators (ZScript)|Operadores de ZScript]]
* [[Statements (ZScript)|Declarações/Statements de ZScript]]
* [[Object scopes and versions]]
* [[ZScript classes]]
* [[Structs]]
* [[ZScript actor flags]]
* [[ZScript spawn flags]]
* [[ZScript functions]]
* [[ZScript actor functions]]
* [[ZScript virtual functions]]
* [[ZScript mixins]]
* [[ZScript custom properties]]
* [[ZScript global variables]]
* [[ZScript named arguments]]
* [[Events and handlers]]
* [[:Categoria:Custom action functions|Funções de ação customizadas]]
* [[Controlling dynamic lights]]
* [[CVar (ZScript)|CVars em ZScript]]
* [[Associative maps]]
* [[ZScript special words]]

== 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.

* [[Function pointers]]
* [[Events and handlers]]
* [[ZScript menus]]
* [[ZScript status bars]]

== Guias de ZScript ==

* [[Creating non-interactive decorations (ZScript)]]
* [[Creating new monsters or other complex items (ZScript)]]
* [[Creating new projectiles (ZScript)]]
* [[Creating new inventory items (ZScript)]]
* [[Creating new weapons (ZScript)]]
* [[Creating interactive decorations]]
* [[Creating new player classes]]
* [[Using inheritance]]
* [[Converting DECORATE code to ZScript]]
* [[Creating multiplayer-friendly ZScript]]
* [[Using pointers in ZScript]]
* [[Using user variables in 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 [https://forum.zdoom.org/viewtopic.php?f=122&t=59770 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

ZScript - Histórico de revisão

MegaManx3: Criação da pagina do Zcript