ZScript Documentation

[Rachael]

Gez has done an excellent job with that and still does it to this day. If anyone knows how to make your documentation pretty and easy to navigate, it's him.

Just poke him in this thread when you're ready for him to help you with that.

[Major Cooke]

I'll keep that in mind. Thanks!

[Major Cooke]

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.

Sadly this most likely won't happen. Graf has stated time and again that he prefers someone else doing the documenting, and to me, the reason is obvious -- doing so would take a lot of time and effort which he is currently spending on converting the rest of the engine to ZScript where applicable.

If you truly want him to document things (which I fully support and agree upon, his clarity would be much more accurate than my guestimating), I think he might save that stuff for absolute last, (if at all) which means waiting quite a while.

-----

On another note, I've decided to mark a couple of the ZScript topics as 'advanced'. What does that mean?

• You should know how to work with the basics of ZScript at a minimum, including pretty much all of the regular topics in this page.
• These will not spoon feed anything outside the essentials of the topic itself. I.e. you should know how to work with pointers, objects, casting, etc. Menus are so large and so powerful, a step by step tutorial cannot be exactly written (IMO without going insane) -- the pages will serve as guides and document what things do in the menu where possible, and nothing else.

Of course anyone could write a tutorial, provided it's good and knowledgeable, but I'm not nearly familiar enough with it yet.

It took me 3 weeks just to change D4D's purchase menu from using CVars to creating an internal system for eventual multiplayer compatibility. Learning to take it apart is no easy task -- in fact, since I know people will want to make a purchase menu, I should probably work towards seeing the event systems documentation completed first since people will want player interaction.

[Kinsie]

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.

Sadly this most likely won't happen. Graf has stated time and again that he prefers someone else doing the documenting, and to me, the reason is obvious -- doing so would take a lot of time and effort which he is currently spending on converting the rest of the engine to ZScript where applicable.

If you truly want him to document things (which I fully support and agree upon, his clarity would be much more accurate than my guestimating), I think he might save that stuff for absolute last, (if at all) which means waiting quite a while.

I wasn't saying that he would do it, I was saying that he would probably appreciate it. :V

[Major Cooke]

Fair enough.

Currently still planning out how to address certain things and dealing with the event handlers. While I know a bit about the event handlers, it's not really enough yet. Going to see if ZZYZX can lend a hand with that.

[Major Cooke]

Before anyone asks, I have absolutely no idea how ZBARS (zscript status bars for the lay) work yet and haven't even touched it. If someone knowledgeable wants to go ahead and do something, the link is right in here.

[Graf Zahl]

The status bars is actually the simplest part of all. A function gets called, you draw stuff, done.
There's also a 'tick' function to have timed elements synchronized to the game, but it's the least complex thing on the user side. It only took so long because what was there was so bad.

[Major Cooke]

Curious, is there a scaling ability for these, or will that come when things like overlays are able to use alpha, roll, scale and renderstyle?

[Graf Zahl]

The special draw functions of the BaseStatusBar class respect the settings of hud_scale, st_scale or, if properly set, uiscale.
Of course, if you bypass those you are on your own. For more complex draw operations a new set of functions will be needed - the current ones were explicitly designed to make transition from SBARINFO as easy as possible.

[Major Cooke]

Is it planned to support such things eventually?

[Graf Zahl]

I added a transform function today so that you can do the transformation separately from the actual drawing in case you need more options.

[Major Cooke]

Awesome! Thanks!
I take it the rest won't come until overlays can handle them as well? Just curious.

(Rolling hud elements would work wonders with things like scoping in and displaying little rotating wheels until it stops.)

[Major Cooke]

Just an update, I know the menu system has remained barren for some time but I've been making the templates offline to ensure they're in working order when they do go up.

It's taking longer than I thought because documenting every little thing and how it works is quite exhausting, since all I can do is continuously testing things out.

Having said that, I think I will take a small break and switch to documenting status bars, something that's far easier to work with than menus. Graf was right in that regard, they're a lot simpler than they look.

They still require knowledge on how to work with ZScript, but once you know those, you merely need to know what functions to use to get things to draw. If you have any experience with working on ACS or SBARINFO, it combines the strengths of both and allows one to completely convert all systems truly over to ZScript.

HUGE thanks to Graf for all his hard work!

Unfortunately documenting this may take a long time as well -- there are many, MANY things to cover.

[camaxide]

Is there anywhere I can find info on the statscreen or on how to alter intermission?
I've looked at https://github.com/coelckers/gzdoom/blob/master/wadsrc/static/zscript/statscreen/statscreen.txt as well as https://github.com/coelckers/gzdoom/blob/master/wadsrc/static/zscript/statscreen/statscreen_sp.txt but can't really make out how to add the world map in addition to the things I've already got going between levels.
I made these two posts a long time ago but got no replies, likely because noone knows how to do it: https://forum.zdoom.org/viewtopic.php?f=3&t=55284 - https://forum.zdoom.org/viewtopic.php?f=3&t=55841
But according to graf it should be possible to do this with zscript now. https://mantis.zdoom.org/view.php?id=280

Any help on this would be greatly appreciated. I hope to find out how I can add one extra step into the intermission between levels, so that I can have the world-map show up without having to remove the full-picture enterpic I've already got in the intermission-cycle.

Might be something with CurState = LeavingIntermission; but I really can't understand how to alter the zscript code to do this - compared to ACS and the old decorate-type coding there seem to be a lot more code needed with zscript, and at least for my head the code seem way less logic and self-explanatory.

[Kinsie]

Here's a gotcha I haven't seen anywhere else that's worth mentioning: Apparently GetCVar, for what it's worth, can't be used by EventHandlers. Even with like, server cvars. It just causes an Unknown Function error on startup.

You can take a long way around using CVar.GetCVar. For example, CVar.GetCVar("CVARNAME", players[0]).GetInt() will get the cvar's value from player 1. There's probably a better way to do this, and I welcome suggestions. This is for a serverside cvar, though, so it'd be the same value for all players anyway, right?

Keep in mind, though, that typos and such are not acceptable this way around. If you try to call a cvar that doesn't exist, you'll get a Very Fatal Error that doesn't tell you jack about what caused it. It's a Very Unhelpful Very Fatal Error.

Thanks to DrPySpy for shepherding me through this. Hopefully it saves someone out there, like, at least 15 minutes of frustrated debugging.