jekyllgrim/zscript_basics

ZScript entry guide

ZScript Basics: A Guide for Non-Programmers (from a non-programmer)

This guide is a beginner-friendly introduction to ZScript, a primary coding language used to code gameplay, UI and menus in GZDoom source port.

☕ Support me on Boosty: https://boosty.to/agent_ash

Important notes

1. This document was written by a person who learned to use ZScript without any prior programming experience. I strive to use the correct terminology and not dumb things down but I may also purposefully overexplain certain things or initially present them in a simplified manner for the sake of beginner-friendliness.
2. While most code examples in the guide are made to be runnable, it's not recommended to use them as is: many of them are purposefully inefficient, and the guide tends to iterate over them, improving various aspects while explaining new techniques. Examples are meant to be just that: examples—not ready-made solutions.
3. This document is a guide, not a wiki. As such, it's designed to be read from beginning to end. Chapters are not self-contained and often rely on information explained earlier in the guide, so it's not recommended to skip anything. The only exception to this is the appendix chapters that can be found at the end—they contain additional information that may be referenced throughout the guide, so you may familiarize yourself with the contents of those chapters as needed.

🔶 CHOOSE YOUR PATH 🔶

• If you do NOT have prior DECORATE experience and want to learn ZScript from scratch, start here: 🔵 >> Where to start.

• If you DO have prior DECORATE experience and are considering switching to ZScript, start here: 🔵 >> Why ZScript?

Table of Contents

1. Where to start

2. Defining ZScript classes

3. Why ZScript?

4. Classes instead of actors

5. How to see your classes in the game

6. Anonymous functions

7. Variables and data types

8. Pointers and casting

9. Custom functions and function types

10. Virtual Functions

11. Event Handlers

12. Player, PlayerInfo and PlayerPawn

13. Inventory

14. Weapons, PSprite and overlays

15. Arrays and linked lists

16. Constants

17. HUD

Appendix chapters

• Appendix 1: Flow Control

• Appendix 2: Best Practices and Rules of Thumb

• Appendix 3: Glossary

zscript_basics's Issues

Bare bones example

Hello!

Thank you very much for the comprehensive guide.

I've made a bare bones example here. Perhaps you'd like to link to it or otherwise include it.

Missing keyword

In the section about static functions your example function int Sign (double i) is missing the static keyword

Ambiguities in "Custom functions" section

In the end of this section there is an example of custom version of A_MonsterRefire. The Missile state has TNT1 A 0 A_MonsterRefire(5,"AttackEnd");

Isn't it supposed to be CustomMonsterRefire(5,"AttackEnd")?

Also, the first condition in the function CustomMonsterRefire checks whether the monster has run out of ammo. However, I don't see anywhere the value of monstermag being decreased. For me, at least, it seems confusing. Maybe it's supposed to be decreased after A_CPosAttack? Then what the code should be? Something like:

CPAS F 2 A_CPosAttack;
TNT1 A 0 {monstermag--;}

?

And, by the way, isn't it better to check if (monstermag <= 0)?

Some incorrect things I've noticed

In "Classes Instead of Actors", it says you can't have a class that inherits from nothing. This isn't true; The Le_ProjScreen class from Libeye inherits from nothing, but then again, it isn't an actor.

In "Anonymous Functions", it says you need to include a pair of empty parentheses at the end to call a function. No, you don't; just look at some of the actor code in gzdoom.pk3 to see action function calls without parentheses.

In "Variables and Data Types", you can access the XY components of a 3D vector, as a 2D vector, using .xy.