ZScript Discussion

[Major Cooke]

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

[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)

[Graf Zahl]

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.

[Nash]

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]

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.

[ZZYZX]

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.

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.

[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!

[Nash]

@Graf Zahl: Will the Strife conversation menu receive scriptification? It is technically a menu too, right?

[Graf Zahl]

Yes, it is a menu. No, for the time being there won't be any more scriptification. Maybe later.

[Xaser]

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.

[Major Cooke]

I agree, dpJudas. Go for it!

[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]

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]

Ideally it'd ouput raw wikicode and then a wikibot could automatically put it.

[Nash]

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.