ZScript Basics: a guide for non-programmers

[Jekyll Grim Payne]

ZScript Basics: a guide for non-programmers from a non-programmer


I started on zscript in early 2019 and have been familiarizing myself with it as a person with zero coding and little math experience, having only worked with DECORATE/ACS in the past. I'm now writing and compliting this basics guide on github:

The Guide:
https://jekyllgrim.github.io/ZScript_Basics/
You can also download the whole repository and read it with a Markdown reader, such as Mark Text, although I wouldn't recommend that since you'd miss the frequent updates.


You could argue that it's better to read an actual coding guide, like on C#, and you're probably right. But there are tons of people out there who have been doing DECORATE hacks for years and are now in a pickle, since all the cool kids are doing ZScript, and they don't know how to join the fun and aren't necessarily willing to learn actual coding for that. This guide is for them.

Please note the following:

• This is a work in progress. Some chapters aren't finished yet but are planned or have a draft (i.e. they're mentioned in Contents but don't have active links). Some are only in my head.
• This guide won't cover everything. The chapter names you can see under Contents are close to being a complete plan. The guide is intended for people who are willing to continue learning new stuff on their own, and it only really covers the basics of the main aspects of ZScript.
• Some examples and explanations in the guide are purposefully simplified. I try to make sure they're never incorrect for the sake of simplicity, but they can be incomplete.
• There are no collaborators right now, but once I'm done with the main bulk, I'll probably be accepting help.

[Kzer-Za]

Hi!

I've been reading your guide again and found one thing in Virtual Functions section that I've looked over the first couple times:

Code: Select all

if (source && source is "Zombieman")

Can I ask what is "is"? What are the rules for using it? Until now I thought that the way to check the class of the source of the damage was

Code: Select all

if(source.GetClass() == "Zombieman")

PS. I must say that your guide is great!

[3saster]

"is" is a special keyword in ZScript. To use the "Zombieman" example you provided,

Code: Select all

source is "Zombieman"

will return true if source is a class of type "Zombieman" OR is a class derived from "Zombieman". By comparison, the example you posted using GetClass will only return true if the source is a class of type "Zombieman" (and will return false for classes derived from it). To use an actual example, suppose the source is a "HellKnight" (which is derived from "BaronOfHell"). Then

Code: Select all

source is "BaronOfHell"

will return true, while

Code: Select all

source.GetClass() == "BaronOfHell"

or (a more common and slightly more robust way a specific class can be checked against)

Code: Select all

source.GetClassName() == "BaronOfHell" //replace == with ~== for a case insensitive compare

will both return false.

[Kzer-Za]

Thanks!

[Lagi]

this is a great tutorial,

not that i want to understand what all that means, but it was nice to read. I very quickly get the concept of things, and your examples from doom help a lot to get the concept behind some "code structures"

[Gifty]

This is just what I was looking for, thanks for putting this together!

[Guest]

Appreciate tutorials like these. Thank you for making this!

[ASO3000]

This is definitely the best thing I have read so far on ZScript. I am still far from doing anything worthwhile, but at least it's a start. And it's easily understandable. Thank you.

[Jekyll Grim Payne]

Good news everyone!
I've just pushed a big update. This isn't the first update this guide received over the past months but the first one I remembered to post about here...

I've added two chapters for people without prior DECORATE experience (Where to start and Defining ZScript classes).

Some things were moved. The updated Introduction allows you to choose which chapter to jump to based on whether you have DECORATE experience or starting fresh.

I've also finally added a chapter on Arrays. It describes static constant and dynamic arrays. No fixed size or multidimensional ones, at least for now.

[Sir Robin]

Hello, brand new mapper/coder here, trying to understand this ZScript and everything else. Thank for very much for writing this document, I'm sure it's going to be very helpful.

I'm trying to create a custom weapon, so I'm modeling code based on your example here. I couldn't get it to work, even when copying your entire code block, so after some hair-pulling on my end I realized my gzdoom (version 4.7.1) won't build that code unless the default section lines end in semi-colons. So I don't know if that's a typo from you or if something changed in the zscript spec or what, but I thought I'd mention it.

Secondly, and I don't know if this is within the scope of your document, but it would be nice if right after those weapon definitions you'd tell us how to make that weapon appear in the game so we can test it out. I see it has a spawn state, so I think that means I can place a thing on the map that will let me pick up this weapon, but I don't understand how to do that. I don't see any new thing listed when I load Ultimate Doom Builder.

[Kzer-Za]

I think I can answer that.

Regarding the first question, you are probably talking about the Pistol example. It is likely a typo. You can see that in all other examples the lines in the Default section do end in semicolons. Well, except the flags, semicolons can be omitted on the lines that assign flags. (Though it won't hurt to end these lines in semicolons either).

Regarding putting the things on a map. You need to either replace one of the existing things or give your item a DoomEd number.

To replace something, simply put "replaces X" at the end of the class line, where X is the name of the thing being replaced. If we take a pistol as the example:

Code: Select all

class MyCoolPistol : Pistol replaces Pistol

Though, of course, you can just as easily make MyCoolPistol replace not a pistol, but a DoomImp, for example.

Regarding DoomEd numbers see these links: https://zdoom.org/wiki/Magic_numbers, https://zdoom.org/wiki/Editor_number, https://zdoom.org/wiki/MAPINFO/Editor_number_definition

Seeing as you are making practically a separate game, probably the way to go is DoomEd numbers. A simple example would be to create a MAPINFO.txt with content approx like this:

Code: Select all

DoomEdNums
{
	X = UltimaPole
	Y = UltimaAxe
	Z = UltimaMace
}

Where X, Y, Z are arbitrarily chosen numbers (just make sure they are not from the ranges described in https://zdoom.org/wiki/Standard_editor_numbers) and after the equal sign are the names of your items, monsters, etc.

[Jekyll Grim Payne]

I think it's worth writing a separate chapter on replacements, so I'll look into that.

For now, just seeing something in the game is a matter of typing "summon <class name>" in the console (e.g. "summon Pistol").

[andreboomer]

Could you please expand upon Action Functions with an example when you have time?
Thanks.

[Jekyll Grim Payne]

I just pushed a very big update to the Weapons, Overlays and PSprite chapter: https://github.com/jekyllgrim/ZScript_B ... PSprite.md

Note, it's still WIP, probably contains a bunch of incomplete, awkward, and incorrect stuff, but it should be pretty useful as is. Hope it helps.

[Jekyll Grim Payne]

Could you please expand upon Action Functions with an example when you have time?
Thanks.

I expanded a bit on it in the weapons chapter here.