ZScript Documentation

Discuss anything ZDoom-related that doesn't fall into one of the other categories.

Re: ZScript Documentation

Postby Major Cooke » Sat Feb 11, 2017 6:38 pm

Oh and Vaecrius, that edit about A_Jump* is wrong. That only applies to anonymous functions.
User avatar
Major Cooke
Slaughterer of Sewers
 
Joined: 28 Jan 2007
Discord: Major Cooke#0846

Re: ZScript Documentation

Postby Kinsie » Wed Mar 22, 2017 5:28 am

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
Kinsie
A Concept Utterly Obsolete
 
Joined: 22 Oct 2004
Location: MAP33
Discord: Find Me...
Twitch ID: thekinsie

Re: ZScript Documentation

Postby Major Cooke » Wed Mar 22, 2017 10:20 am

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 allExpand view
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 Thu Mar 23, 2017 12:29 am, edited 1 time in total.
User avatar
Major Cooke
Slaughterer of Sewers
 
Joined: 28 Jan 2007
Discord: Major Cooke#0846

Re: ZScript Documentation

Postby Major Cooke » Wed Mar 22, 2017 4:00 pm

Forgot to mention you need to add:

version "2.4"

at the top of the ZScript.txt files in my linked examples.
User avatar
Major Cooke
Slaughterer of Sewers
 
Joined: 28 Jan 2007
Discord: Major Cooke#0846

Re: ZScript Documentation

Postby Nash » Wed Mar 22, 2017 11:18 pm

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
Nash Muhandes
 
 
 
Joined: 27 Oct 2003
Location: Kuala Lumpur, Malaysia

Re: ZScript Documentation

Postby Nash » Wed Mar 22, 2017 11:46 pm

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
Nash
Nash Muhandes
 
 
 
Joined: 27 Oct 2003
Location: Kuala Lumpur, Malaysia

Re: ZScript Documentation

Postby AFADoomer » Thu Mar 23, 2017 12:16 am

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
AFADoomer
 
Joined: 15 Jul 2003

Re: ZScript Documentation

Postby Nash » Thu Mar 23, 2017 12:29 am

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
Nash
Nash Muhandes
 
 
 
Joined: 27 Oct 2003
Location: Kuala Lumpur, Malaysia

Re: ZScript Documentation

Postby Major Cooke » Thu Mar 23, 2017 12:38 am

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
Major Cooke
Slaughterer of Sewers
 
Joined: 28 Jan 2007
Discord: Major Cooke#0846

Re: ZScript Documentation

Postby Kinsie » Thu Mar 23, 2017 3:01 am

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
Kinsie
A Concept Utterly Obsolete
 
Joined: 22 Oct 2004
Location: MAP33
Discord: Find Me...
Twitch ID: thekinsie

Re: ZScript Documentation

Postby Nash » Thu Mar 23, 2017 3:13 am

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
Nash
Nash Muhandes
 
 
 
Joined: 27 Oct 2003
Location: Kuala Lumpur, Malaysia

Re: ZScript Documentation

Postby Rachael » Thu Mar 23, 2017 3:15 am

You both are better than this - stop that.
User avatar
Rachael
QZDoom + Webmaster
 
Joined: 13 Jan 2004

Re: ZScript Documentation

Postby Gez » Thu Mar 23, 2017 5:45 am

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.
Gez
 
 
 
Joined: 06 Jul 2007

Re: ZScript Documentation

Postby juizzysquirt » Thu Mar 23, 2017 10:28 am

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
juizzysquirt
 
Joined: 04 Jan 2009
Location: Knee-Deep in L.A. Meltdown

Re: ZScript Documentation

Postby Major Cooke » Thu Mar 23, 2017 11:15 am

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.
User avatar
Major Cooke
Slaughterer of Sewers
 
Joined: 28 Jan 2007
Discord: Major Cooke#0846

PreviousNext

Return to General

Who is online

Users browsing this forum: No registered users and 5 guests