ZScript Basics: a guide for non-programmers

Handy guides on how to do things, written by users for users.

Moderators: GZDoom Developers, Raze Developers

Forum rules
Please don't start threads here asking for help. This forum is not for requesting guides, only for posting them. If you need help, the Editing forum is for you.
User avatar
Jekyll Grim Payne
 
 
Posts: 936
Joined: Mon Jul 21, 2008 4:08 am
Discord: Agent_Ash#4401
Github ID: jekyllgrim
Graphics Processor: nVidia (Modern GZDoom)

ZScript Basics: a guide for non-programmers

Post by 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.
Last edited by Jekyll Grim Payne on Mon Mar 28, 2022 10:28 am, edited 3 times in total.
Kzer-Za
Posts: 507
Joined: Sat Aug 19, 2017 11:52 pm
Graphics Processor: nVidia (Modern GZDoom)

Re: ZScript Basics: a guide for non-programmers

Post by 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!
User avatar
3saster
Posts: 199
Joined: Fri May 11, 2018 2:39 pm
Location: Canada

Re: ZScript Basics: a guide for non-programmers

Post by 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
Posts: 507
Joined: Sat Aug 19, 2017 11:52 pm
Graphics Processor: nVidia (Modern GZDoom)

Re: ZScript Basics: a guide for non-programmers

Post by Kzer-Za »

Thanks!
User avatar
Lagi
Posts: 667
Joined: Sat Jun 23, 2018 12:51 pm
Location: Thou shalt alter thy beliefs with new evidence

Re: ZScript Basics: a guide for non-programmers

Post by 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"
User avatar
Gifty
Posts: 615
Joined: Sat Jun 15, 2013 8:21 pm

Re: ZScript Basics: a guide for non-programmers

Post by Gifty »

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

Re: ZScript Basics: a guide for non-programmers

Post by Guest »

Appreciate tutorials like these. Thank you for making this!
User avatar
ASO3000
Posts: 67
Joined: Fri Jun 14, 2019 5:38 am

Re: ZScript Basics: a guide for non-programmers

Post by 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.
User avatar
Jekyll Grim Payne
 
 
Posts: 936
Joined: Mon Jul 21, 2008 4:08 am
Discord: Agent_Ash#4401
Github ID: jekyllgrim
Graphics Processor: nVidia (Modern GZDoom)

Re: ZScript Basics: a guide for non-programmers

Post by 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.
User avatar
Sir Robin
Posts: 392
Joined: Wed Dec 22, 2021 7:02 pm
Graphics Processor: Intel (Modern GZDoom)
Location: Medellin, Colombia

Re: ZScript Basics: a guide for non-programmers

Post by 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
Posts: 507
Joined: Sat Aug 19, 2017 11:52 pm
Graphics Processor: nVidia (Modern GZDoom)

Re: ZScript Basics: a guide for non-programmers

Post by 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.
User avatar
Jekyll Grim Payne
 
 
Posts: 936
Joined: Mon Jul 21, 2008 4:08 am
Discord: Agent_Ash#4401
Github ID: jekyllgrim
Graphics Processor: nVidia (Modern GZDoom)

Re: ZScript Basics: a guide for non-programmers

Post by 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
Posts: 18
Joined: Wed Feb 16, 2022 9:04 pm
Discord: Dre#2260
Graphics Processor: nVidia with Vulkan support

Re: ZScript Basics: a guide for non-programmers

Post by andreboomer »

Could you please expand upon Action Functions with an example when you have time?
Thanks.
User avatar
Jekyll Grim Payne
 
 
Posts: 936
Joined: Mon Jul 21, 2008 4:08 am
Discord: Agent_Ash#4401
Github ID: jekyllgrim
Graphics Processor: nVidia (Modern GZDoom)

Re: ZScript Basics: a guide for non-programmers

Post by 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.
User avatar
Jekyll Grim Payne
 
 
Posts: 936
Joined: Mon Jul 21, 2008 4:08 am
Discord: Agent_Ash#4401
Github ID: jekyllgrim
Graphics Processor: nVidia (Modern GZDoom)

Re: ZScript Basics: a guide for non-programmers

Post by Jekyll Grim Payne »

andreboomer wrote: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.

Return to “Tutorials”