ZScript Discussion

Ask about ACS, DECORATE, ZScript, or any other scripting questions here!

Moderator: GZDoom Developers

Forum rules
Before asking on how to use a ZDoom feature, read the ZDoom wiki first. If you still don't understand how to use a feature, then ask here.

Please bear in mind that the people helping you do not automatically know how much you know. You may be asked to upload your project file to look at. Don't be afraid to ask questions about what things mean, but also please be patient with the people trying to help you. (And helpers, please be patient with the person you're trying to help!)
User avatar
Major Cooke
Posts: 8182
Joined: Sun Jan 28, 2007 3:55 pm
Preferred Pronouns: He/Him
Location: QZDoom Maintenance Team

Re: ZScript Discussion

Post by Major Cooke »

Now that the event handling system is in, ever since you overhauled the GC stuff, is it now safe to use?
User avatar
ZZYZX
 
 
Posts: 1384
Joined: Sun Oct 14, 2012 1:43 am
Location: Ukraine

Re: ZScript Discussion

Post by ZZYZX »

Also it's probably a good idea to give the menu events an events.txt UiEvent, since it really gives the same information but in a more modder-friendly fashion. (UiEvent and not InputEvent because IIRC menus set the input mode to UI anyway)
(looking at InputEventData struct)
User avatar
Graf Zahl
Lead GZDoom+Raze Developer
Lead GZDoom+Raze Developer
Posts: 49094
Joined: Sat Jul 19, 2003 10:19 am
Location: Germany

Re: ZScript Discussion

Post by Graf Zahl »

Major Cooke wrote:Now that the event handling system is in, ever since you overhauled the GC stuff, is it now safe to use?

It goes the simple route and sets its elements as 'fixed'. which prevents them from getting cleaned. I've yet to check if that is ok or not, otherwise I have to add some GC management.
User avatar
Nash
 
 
Posts: 17450
Joined: Mon Oct 27, 2003 12:07 am
Location: Kuala Lumpur, Malaysia

Re: ZScript Discussion

Post by Nash »

ZZYZX wrote:Also it's probably a good idea to give the menu events an events.txt UiEvent, since it really gives the same information but in a more modder-friendly fashion. (UiEvent and not InputEvent because IIRC menus set the input mode to UI anyway)
(looking at InputEventData struct)
Agreed.
dpJudas
 
 
Posts: 3051
Joined: Sat May 28, 2016 1:01 pm

Re: ZScript Discussion

Post by dpJudas »

Been playing around a little bit with using the AST in GZDoom to build reference documentation ala doxygen. Currently what I got looks like this: ZScript Reference.

I generated it by adding -refdocs to the command line where it then outputs a .html file for each lump, like the -dumpast debugging function. So what do you think? Is this something people want?

Current implementation can be found in QZDoom's refdocs branch.
User avatar
ZZYZX
 
 
Posts: 1384
Joined: Sun Oct 14, 2012 1:43 am
Location: Ukraine

Re: ZScript Discussion

Post by ZZYZX »

Graf Zahl wrote:
Major Cooke wrote:Now that the event handling system is in, ever since you overhauled the GC stuff, is it now safe to use?

It goes the simple route and sets its elements as 'fixed'. which prevents them from getting cleaned. I've yet to check if that is ok or not, otherwise I have to add some GC management.
Only Static handlers set themselves as fixed. Regular ones don't, refer to these lines:
https://github.com/coelckers/gzdoom/blo ... ts.cpp#L63
https://github.com/coelckers/gzdoom/blo ... ents.h#L91
https://github.com/coelckers/gzdoom/blo ... nts.h#L155

So there still can be garbage collection issues with non-global handlers, if they aren't excluded from collection altogether (I have E_Shutdown anyway which deletes the map handlers manually).
Alternate solution would be what you said about adding prev/next to GC so that the registered handlers actually get pointed to "by the system".

Right now it may or may not crash depending on whether the GC calls OnDestroy when it finds out that nothing points at an object.
If it calls OnDestroy, the handler will get unregistered properly and there won't be any crashes, it will just silently stop handling.
dpJudas wrote:I generated it by adding -refdocs to the command line where it then outputs a .html file for each lump, like the -dumpast debugging function. So what do you think? Is this something people want?
Docs are always good, although I personally would like it a lot more if you generated a JSON or XML of some sorts so this can be added to the wiki, or used for syntax highlighting in GZDB, or used in DECORATE->ZScript converter, or whatever else, just a general-purpose type/method/const/property listing.
User avatar
Nash
 
 
Posts: 17450
Joined: Mon Oct 27, 2003 12:07 am
Location: Kuala Lumpur, Malaysia

Re: ZScript Discussion

Post by Nash »

@ ZZYZX - whenever it's convenient for you, can you dump some basic event handler examples into this thread? -> viewtopic.php?f=3&t=55274

Posting here because you wrote somewhere that you don't check all forums. Thanks in advance!
User avatar
Nash
 
 
Posts: 17450
Joined: Mon Oct 27, 2003 12:07 am
Location: Kuala Lumpur, Malaysia

Re: ZScript Discussion

Post by Nash »

@Graf Zahl: Will the Strife conversation menu receive scriptification? It is technically a menu too, right?
User avatar
Graf Zahl
Lead GZDoom+Raze Developer
Lead GZDoom+Raze Developer
Posts: 49094
Joined: Sat Jul 19, 2003 10:19 am
Location: Germany

Re: ZScript Discussion

Post by Graf Zahl »

Yes, it is a menu. No, for the time being there won't be any more scriptification. Maybe later.
User avatar
Xaser
 
 
Posts: 10772
Joined: Sun Jul 20, 2003 12:15 pm

Re: ZScript Discussion

Post by Xaser »

dpJudas wrote:I generated it by adding -refdocs to the command line where it then outputs a .html file for each lump, like the -dumpast debugging function. So what do you think? Is this something people want?
In my super-early prototyping of the eventual ZScript Library project, I was plunking in some Doxygen-style comments for eventual future use, so... yeah, I suppose that would indeed be useful. :P
User avatar
Major Cooke
Posts: 8182
Joined: Sun Jan 28, 2007 3:55 pm
Preferred Pronouns: He/Him
Location: QZDoom Maintenance Team

Re: ZScript Discussion

Post by Major Cooke »

I agree, dpJudas. Go for it!
User avatar
Xaser
 
 
Posts: 10772
Joined: Sun Jul 20, 2003 12:15 pm

Re: ZScript Discussion

Post by Xaser »

I do suppose somebody's going to ask "does this belong in ZDoom itself?", to which my answer is... I dunno, really. I'm interested from a standards point of view (i.e. declaring a convention for documenting ZScript so there's a standard-ish way of creating + generating docs going forward).
dpJudas
 
 
Posts: 3051
Joined: Sat May 28, 2016 1:01 pm

Re: ZScript Discussion

Post by dpJudas »

Xaser wrote:I do suppose somebody's going to ask "does this belong in ZDoom itself?", to which my answer is... I dunno, really. I'm interested from a standards point of view (i.e. declaring a convention for documenting ZScript so there's a standard-ish way of creating + generating docs going forward).
In an ideal world, where we have more devs than the one man army known as Graf, the ZScript parser and AST builder would be its own library. That would allow editors to use it for intellisense (autocomplete, compile errors underlined as you type, go to reference), and this refdocs feature wouldn't have to be part of the executable either. For now I'm willing to live with the "hack" that it is part of the executable, because:

My main motivation for creating a doxygen for GZDoom is that right now there's only three sources of information available: decorate stuff from the wiki, the actual .txt files in the pk3, and what's in Graf's head. It is unrealistic to expect Graf to document ZScript - the task is gigantic and let's face it, he got more than enough on his plate already. What I think we need is to lay the basic foundation for first class documentation. That consists of three parts: language documentation, API overview documentation and API reference documentation. The first one helps you understand the ZScript syntax, the second gets you started with doing stuff, and the third lets you quickly look up stuff without opening source files.

What Major Cooke has been working on is mostly API overview and a bit of language documentation. The only thing we have that gets close to reference docs are the old DECORATE things on the wiki. My hope is that by auto-generating the reference docs, even if they have no documentation initially, it will help shape the foundation. I made my refdocs test output pure .html files, but technically there's nothing preventing it from being json or something else if that helps us import it into the wiki. There's of course also the option of adding the documentation to the .txt files directly and grabbing it from there like the normal doxygen tool does.
Gez
 
 
Posts: 17836
Joined: Fri Jul 06, 2007 3:22 pm

Re: ZScript Discussion

Post by Gez »

Ideally it'd ouput raw wikicode and then a wikibot could automatically put it.
User avatar
Nash
 
 
Posts: 17450
Joined: Mon Oct 27, 2003 12:07 am
Location: Kuala Lumpur, Malaysia

Re: ZScript Discussion

Post by Nash »

Graf Zahl wrote:Yes, it is a menu. No, for the time being there won't be any more scriptification. Maybe later.
Ok understood. And what about the commented out Responder, MenuEvent, MouseEvent, Ticker and Drawer methods for ListMenu? Will they eventually be virtual?

Currently users can already go to town for OptionMenus but ListMenu is still stuck with the vanilla "vertical up/down list" menu and you can't do Doom 3-style menus where the list is spread horizontally, for example.

Return to “Scripting”