ZScript Documentation

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
Major Cooke
Posts: 8170
Joined: Sun Jan 28, 2007 3:55 pm
Preferred Pronouns: He/Him
Location: QZDoom Maintenance Team

Re: ZScript Documentation

Post by Major Cooke »

Oh and Vaecrius, that edit about A_Jump* is wrong. That only applies to anonymous functions.
User avatar
Kinsie
Posts: 7399
Joined: Fri Oct 22, 2004 9:22 am
Graphics Processor: nVidia with Vulkan support
Location: MAP33
Contact:

Re: ZScript Documentation

Post by Kinsie »

Kicking this thread back up since 2.4.0 is out and documentation is still a bit spotty. Some extra work would be appreciated, especially by engine programmers who'd probably rather that people stop writing gamemode logic and custom menus in terrible, hacky, HUDMessage-heavy, basically-depreciated ACS.

For reference, things that are in need of a write-up:
  • Menu Scripting - I think only one or two people have even been able to scratch this, putting their knowledge together may help both of them grok some stuff, to say nothing of everyone else
  • Events and Handlers - These are an important new feature, but they don't even have a page on the wiki yet
  • More detail/explanation on the kinds of map data that can be touched by ZScript
  • Code examples for Dynamic Arrays (code examples for any page that has an empty "examples" section is vital, but dynamic arrays are the most relevant to this thread)
And these aren't as vital, but would be greatly appreciated:
  • Some explanations of ZScript-centric programming logic, ala the explanations that are rife throughout ACS's documentation... if only for consistency!
  • Either filling out or deleting the ZScript Builtin Functions page
  • Information on how obituaries have been changed with scriptification - additional obit customization has been something people have asked for for a while
  • Disambiguation pages where concepts are shared (but executed differently) between ACS and ZScript (for example, Scope)
User avatar
Major Cooke
Posts: 8170
Joined: Sun Jan 28, 2007 3:55 pm
Preferred Pronouns: He/Him
Location: QZDoom Maintenance Team

Re: ZScript Documentation

Post by Major Cooke »

Agreed.

Menus: These are by far the hardest things to work with in ZScript. I'm still working with the menus at the moment, but as soon as I can figure out this last problem I'll happily dive into documenting everything that I can. I just want to make sure everything does what it sounds like it's doing first.

If you're looking for two immediate examples, here's one involving modifying the player during gameplay with a health up button in the option menu, and here's an example on how to make the main doom menu scroll in different directions when selecting on a menu. Each menu will make it scroll in a different direction too.

I'm very close to finishing my experimentations but it's been tricky.

Event and handlers: I'll... take a stab at it but chances are I might be wrong. But then again, I'm going to be expanding my knowledge in a bit on how to work with it via converting D4D's kill bonus from ACS to ZScript soon after I finish the menus.

Sure, I'll add examples of Dynamic Arrays and how they are.

I don't know much about the map data, truth be told.

Obituaries is easy, and I'll toss this up on the wiki too. All you have to do is override the GetObituary function on the monster and you can a random string generator like this. Mod is the damagetype the player received which killed them.

Code: Select all

override String GetObituary(Actor victim, Actor inflictor, Name mod, bool playerattack)
{
	static const String picker[] =
	{
		"%o message 1",
		"%o message 2",
		"%o message 3"
	};
	return picker[random(0,picker.Size())];
	// If you want to do a fallback to the default message, simply do:
	// return Super.GetObituary(victim, inflictor, mod, playerattack);
}
And sure, I can work on a few disambiguation pages. Ideas on what people want for examples would help me come up with them. Please try to keep it simple.
Last edited by Major Cooke on Wed Mar 22, 2017 11:29 pm, edited 1 time in total.
User avatar
Major Cooke
Posts: 8170
Joined: Sun Jan 28, 2007 3:55 pm
Preferred Pronouns: He/Him
Location: QZDoom Maintenance Team

Re: ZScript Documentation

Post by Major Cooke »

Forgot to mention you need to add:

version "2.4"

at the top of the ZScript.txt files in my linked examples.
User avatar
Nash
 
 
Posts: 17434
Joined: Mon Oct 27, 2003 12:07 am
Location: Kuala Lumpur, Malaysia
Contact:

Re: ZScript Documentation

Post by Nash »

Major Cooke wrote: Menus: These are by far the hardest things to work with in ZScript.
Hahaha oh man, this needs to be printed in font size 200.

Out of all the things you could do with ZScript, menus are by far the closest you'll get to C++'isms - very low level stuff. There are no convenience functions, no helpers, nothing like that. Of course the plus side is that you are given (pretty close to) free reign to design your menus - you literally could make a menu from scratch that does not even look like the built-in menu at all.

I remember every now and then there were talks of how "no matter what you do, menus will basically just end up looking like re-skinned menus" - well, ZScript menus will let you tear everything down and build menus from scratch.

If you barely understood the concept of building menus in ACS, don't expect to be building from-scratch menus with ZScript within the first few months. I mean, I'm not trying to intimidate or scare people away, but this is the truth that people need to realize before spending many hours and end up being disappointed and then grumpy.

What I'm trying to say is, if you expect to just sit and wait for people to spoonfeed you documentation, it's not going to make you suddenly become a ZScript menu wizard. Of course, I agree that the BASICS should be documented (like, where the entry points are, how to do a basic bare-bones menus, things like that) but other than that, the ONLY way to master ZScript menus is to actually DO menus.

I have done some ACS menus in my time, and even then, I'm still fairly confused when it comes to ZScript menus currently. So yeah, expect a very high learning curve. And no, I'm not looking for a pat on the back and I'm definitely not bragging - I'm just saying the truth. Menus are hard. Expect a looooooooot of frustration during your lifetime of learning to make them.

Hopefully when the wiki starts filling up, it will be a good foundation for people to start experimenting.

Now that the scary stuff has been said, what I CAN tell you is, the best way to learn is to make menus and post questions on whatever you don't understand. You have to break several eggs before you get to make an omelet.
User avatar
Nash
 
 
Posts: 17434
Joined: Mon Oct 27, 2003 12:07 am
Location: Kuala Lumpur, Malaysia
Contact:

Re: ZScript Documentation

Post by Nash »

Sorry for the double post but I think this is also pretty important for the wiki and deserves a special mention:

Each built-in function needs to have all of their parameters documented. Right now, I have gzdoom.pk3 opened in SLADE to look up an Actor function, and I see these string of parameters and I have no idea what that bool parameter is supposed to do... then I have to open Visual Studio (thank you Intellisense) to look it up... very time consuming...
User avatar
AFADoomer
Posts: 1322
Joined: Tue Jul 15, 2003 4:18 pm
Contact:

Re: ZScript Documentation

Post by AFADoomer »

Nash wrote:Sorry for the double post but I think this is also pretty important for the wiki and deserves a special mention:

Each built-in function needs to have all of their parameters documented. Right now, I have gzdoom.pk3 opened in SLADE to look up an Actor function, and I see these string of parameters and I have no idea what that bool parameter is supposed to do... then I have to open Visual Studio (thank you Intellisense) to look it up... very time consuming...
Could be worse! I don't have Visual Studio installed on my current machine... I usually keep at least 2 or 3 browser windows open to different pages in the GZDoom github site. At least the repository is searchable now - or wasn't until fairly recently!
User avatar
Nash
 
 
Posts: 17434
Joined: Mon Oct 27, 2003 12:07 am
Location: Kuala Lumpur, Malaysia
Contact:

Re: ZScript Documentation

Post by Nash »

AFADoomer wrote:Could be worse! I don't have Visual Studio installed on my current machine... I usually keep at least 2 or 3 browser windows open to different pages in the GZDoom github site. At least the repository is searchable now - or wasn't until fairly recently!
Damn, the grind is real. My hats off to you. :mrgreen: Thanks for the heads up on Github being searchable, though! I didn't notice that search box at the top for some strange reason. :S This will come in very handy indeed!
User avatar
Major Cooke
Posts: 8170
Joined: Sun Jan 28, 2007 3:55 pm
Preferred Pronouns: He/Him
Location: QZDoom Maintenance Team

Re: ZScript Documentation

Post by Major Cooke »

Nash wrote:Hahaha oh man, this needs to be printed in font size 200.
Done.

Out of all the things you could do with ZScript, menus are by far the closest you'll get to C++'isms - very low level stuff. There are no convenience functions, no helpers, nothing like that. Of course the plus side is that you are given (pretty close to) free reign to design your menus - you literally could make a menu from scratch that does not even look like the built-in menu at all.
If there was a boot camp for programmers... This is all just day 1.

I remember every now and then there were talks of how "no matter what you do, menus will basically just end up looking like re-skinned menus" - well, ZScript menus will let you tear everything down and build menus from scratch.
And will also tear one's sorry ass asunder from the amount of headache one can induce because of the sheer heightened amount of possibilities to do stuff with it. It's insane.

If you barely understood the concept of building menus in ACS, don't expect to be building from-scratch menus with ZScript within the first few months. I mean, I'm not trying to intimidate or scare people away, but this is the truth that people need to realize before spending many hours and end up being disappointed and then grumpy.
The examples I've made I feel have contributed as some of the harder parts, though not the hardest. The hardest will soon come when I finish them for D4D. And agreed, making them in ACS does not transfer over to ZScript. If you are an ACSer, you are a goose. If you are a ZScripter, it becomes a duck. Incomparable. Or, y'know, the whole apples to oranges crap...

What I'm trying to say is, if you expect to just sit and wait for people to spoonfeed you documentation, it's not going to make you suddenly become a ZScript menu wizard. Of course, I agree that the BASICS should be documented (like, where the entry points are, how to do a basic bare-bones menus, things like that) but other than that, the ONLY way to master ZScript menus is to actually DO menus.
Eh, kinda hard to motivate people towards coding if they don't want to code in general. But you speak truth. One has to grind one's face in the dirt to get it going.

I have done some ACS menus in my time, and even then, I'm still fairly confused when it comes to ZScript menus currently. So yeah, expect a very high learning curve. And no, I'm not looking for a pat on the back and I'm definitely not bragging - I'm just saying the truth. Menus are hard. Expect a looooooooot of frustration during your lifetime of learning to make them.
Been going on for 3 weeks on trying to make this damned menu work for D4D, all for the sake of making it multiplayer compatible when that time comes. Not to mention breaking down the ability to cheat by changing the cvar prices...

Hopefully when the wiki starts filling up, it will be a good foundation for people to start experimenting.
Sadly you can have some of the most well-documented materials and people will still feel like it's pulling teeth.

Now that the scary stuff has been said, what I CAN tell you is, the best way to learn is to make menus and post questions on whatever you don't understand. You have to break several eggs before you get to make an omelet.
Welcome to Development Hell.
User avatar
Kinsie
Posts: 7399
Joined: Fri Oct 22, 2004 9:22 am
Graphics Processor: nVidia with Vulkan support
Location: MAP33
Contact:

Re: ZScript Documentation

Post by Kinsie »

Nash wrote:Of course, I agree that the BASICS should be documented (like, where the entry points are, how to do a basic bare-bones menus, things like that) but other than that, the ONLY way to master ZScript menus is to actually DO menus.
And therein lies the problem. The basics aren't being documented. And given that the attitude whenever it's asked about is "Oh, no way, man, shit's too hardk0er for mortals", it never will be.
User avatar
Nash
 
 
Posts: 17434
Joined: Mon Oct 27, 2003 12:07 am
Location: Kuala Lumpur, Malaysia
Contact:

Re: ZScript Documentation

Post by Nash »

Kinsie wrote:And given that the attitude whenever it's asked about is "Oh, no way, man, shit's too hardk0er for mortals", it never will be.
I don't know where you're getting this from... me and MajorCooke just agreed that the stuff has to be documented... and will be, the ZDoom wiki as it is today wasn't filled up in a few days, calm your tits man. Should I start placing a $10 bet that even after everything's documented, you will still whine that shit is too hard to understand and "boohoo ZScript is only reserved for The Elite Programming Master Race, gg"?
User avatar
Rachael
Posts: 13531
Joined: Tue Jan 13, 2004 1:31 pm
Preferred Pronouns: She/Her
Contact:

Re: ZScript Documentation

Post by Rachael »

You both are better than this - stop that.
Gez
 
 
Posts: 17833
Joined: Fri Jul 06, 2007 3:22 pm

Re: ZScript Documentation

Post by Gez »

Nash wrote:Each built-in function needs to have all of their parameters documented. Right now, I have gzdoom.pk3 opened in SLADE to look up an Actor function, and I see these string of parameters and I have no idea what that bool parameter is supposed to do... then I have to open Visual Studio (thank you Intellisense) to look it up... very time consuming...
In other words, you have a workflow figured out for finding the lists of parameters and what they do. You should put your findings on the wiki.
User avatar
juizzysquirt
Posts: 126
Joined: Sun Jan 04, 2009 3:29 pm
Location: Knee-Deep in L.A. Meltdown

Re: ZScript Documentation

Post by juizzysquirt »

Is there something like "ZScript for dummies"? The reason why ACS stuck on me so well was because I found everything in the Zdoom wiki from get-go. No need to ask silly questions, and wait few hours or even days for forum replies. Almost any obstacle I had, there was already discussions with someone with similar problems.

I realize a lot of discussion have been revolving around menu and inventory stuff that's really complicated to begin with, and it's the more advanced stuff that's being showcased first. It's just that they don't even resemble anything I've seen previously in ACS, more like stuff found in source codes and C++ -isms which I'm not familiar at all. It's quite intimidating for amateur programmer as me, especially since I'm told that everything I know about "ye old way" of making ACS-driven menus and inventories is a "gross hack" and being deprecated in future. Well, I haven't yet seen any simpler ways in ZScript either. :roll:
User avatar
Major Cooke
Posts: 8170
Joined: Sun Jan 28, 2007 3:55 pm
Preferred Pronouns: He/Him
Location: QZDoom Maintenance Team

Re: ZScript Documentation

Post by Major Cooke »

I think the big stinker to keep in mind is, those who originally did document things from way back when are either disinterested or no longer active -- and they had a set layout of everything that actually worked. No one's really established a 'standard' for how ZScript's documentation aught to be done, and as such I've just been plastering what I do know onto the wiki, which may appear quite confusing and/or poorly explained.

And I'll admit it, I'm pretty terrible at explaining it when there's little organization. I wish someone could do the organizing of the pages and making it look neat/easy to read so I can focus on detailing what each thing does.
Post Reply

Return to “Tutorials”