ZScript Discussion

[Kinsie]

Why are people still mocking the lack of documentation? The people testing it for merge are the people who have kept up with its development, kept in touch with the developers, and know how to use it. Don't worry about it. It is not necessary for you to use (you know, it's not even merged yet...). It won't affect your existing mods. It's a futile effort to write documentation on a scripting language where any feature may change on whim, which is the case here because, you know, it's still in development—the only difference here is that the development is public.

Was this your position when the MAPINFO format got overhauled? I can't figure out what you want: it seems you do not want zscript to succeed DECORATE, and also do not want them to be the same thing. Unless, you're telling the developers to neither extend DECORATE nor add zscript? Your example case also won't happen because, at that point, zscript would be more set in stone and there would be actual documentation.

There are two issues here:

For one, I can't test it if I don't have the foggiest how it works. This, as far as I can tell, is not an uncommon opinion, if not one expressed frequently publicly what with all the stonewalling. I've talked to a non-zero number of gameplay mod devs - prominent sorts with big, complex releases under their belts - who pretty much gave up trying to make sense of the D4D port. This is both discouraging (if people with a deep knowledge of manipulating the engine don't know what the fuck, what hope does anyone else have?) and continues the unfortunate feeling I've been getting lately through Feature Requests, Bug Reports, developer focus/attention etc. that GZDoom is rapidly becoming The D4D Engine Where Support For Other Mods Is More Or Less A Bonus.

And then, of course, there's the second issue, and one that understandably, nobody wants to talk about. At this point, Graf is by and large the sole driving force behind ZScript, doing most of the work. By his own admission, in the previous post, he sees documentation as unnecessary because he knows what everything is. So, what happens if something happens to him? Like, if he gets completely swallowed up by his job for a year, or arrested for transporting a swan across international borders or something. If that happens, without any information as to what does what (or what's supposed to do what), we're left with an unfinished, undocumented, potentially unmaintainable feature that has completely uprooted everything in the engine. In other words, we basically get the Deus Ex 2 engine. Definitely a great situation to be in, and one we should absolutely continue to encourage.

I'm sorry if I'm nagging with this, but I do this because I care probably a bit more than I really should. I have a great deal of fun modding for ZDoom, and over the past year or two alone it's probably overtaken most of my other hobbies. And watching the engine change in a way that's gone from vague theory to indecipherable fact is honestly worrying - a great deal of the method behind this, from where I've been sitting, has been shortsighted at best, and built with one single mod in mind at worst. And it's even more frustrating because frankly, there's sweet fuck-all I can do about it. I just have to sit on my hands, work on my obsolete-format mods while praying they don't break (again!) and hope the thing I enjoy doing will still be enjoyable in a month's time, a month at a time. I'm sure you've gone through something similar where you can relate with how frustrating and perhaps saddening this can be.

[Major Cooke]

I mainly converted D4D early so it could be used as a guinnea pig. I don't expect addon devs to catch up until sometime after ZScript's release, when Graf actually does the documentation.

Yes, I might have some extensible knowledge on how it works, but clearly not enough to be of much use. I too am waiting on Graf to follow up with documentation sometime.

He wants to get it out the door first so people who like to tear into the source code can get a head start, and the thought of the rest of the to-do list can be taken care of first, which IMO is the right way to go. At least we can HAVE zscript.

We can all put our heads together and figure it out, at the very least, while waiting on him.

[Graf Zahl]

For one, I can't test it if I don't have the foggiest how it works. This, as far as I can tell, is not an uncommon opinion, if not one expressed frequently publicly what with all the stonewalling.

Seriously, what do you expect? Everyone right now is in the learning/experimentation phase. They simply cannot tell you what they have to comprehend first themselves.

I've talked to a non-zero number of gameplay mod devs - prominent sorts with big, complex releases under their belts - who pretty much gave up trying to make sense of the D4D port.

Seriously, that's some of the most involved stuff I have seen myself. I'm not surprised that people are baffled by it. It's also not the right thing to start, it's way too complicated for that. If you want to start, start with the internal actors I have converted from C++. That's far more along the lines how things should be done cleanly.
Also, since the entire thing is directly exposing engine internals, it may also not hurt studying the C++ code itself a bit. Having some basic understanding of how Doom works internally will go a long way to understand what you can do and how you can do it.
If you want to dive in head-first you are going to fail. If you need everything spoon-fed as ready-to-read documentation it's clear that you are not ready for it. Start simple, using DECORATE as a base and experiment with the stuff the internal code does. No documentation can make you ready to fully understand it after having read it. It can only give you some guidance about the rough concepts.

One last thing: Patience is a virtue. You are being extemely impatient here by wanting to have it all before it's even done!

[arookas]

By his own admission, in the previous post, he sees documentation as unnecessary because he knows what everything is.

But, he didn't say this, though. He said he could be the one to write documentation, but it's either that or actually finish zscript. He's only one person, and I vote for finishing zscript. If something takes Graf away from zdoom, then almost the entire engine comes to a halt, not just zscript, because The One Cod has been busy elsewhere.

For one, I can't test it if I don't have the foggiest how it works.

Like I said: the people who don't know are testing it to make sure none of their existing mods break. If you find your own or someone else's mod breaks in the zscript branch, you post a bug report, and it gets noticed and/or addressed, you helped. Congratulations, you didn't need to know how to "pointer the thinker into the method interface".

[Kinsie]

But, he didn't say this, though.

Ahem.

Hint hint: If I was writing documentation now, while the thing is still in develoment - as I am clearly the only person knowing all the facts - I wouldn't be able to code the goddamn thing

That's a dangerous position for any project to be in, open-source or no.

[Graf Zahl]

That's pretty much par for course with stuff that's under active development, that the actual developers are the ones in the know. What do you want? Should I split myself in half? Should I cast a magic spell and summon Randi so that I am not the only one sitting here?

It seems to me you want it all - and you want it now!

Again: If you want to contribute, choose something you are comfortable with, but right now it's most definitely not ready for primetime yet, and as an alpha tester you normally do not have the luxury of documentation. Because nobody is stupid enough to write docs when there's more important things to do first (like, well, make the damn thing ready for use???)

[Rachael]

That's a dangerous position for any project to be in, open-source or no.

You're absolutely right - and no one is going to disagree with you here.

But there is a huge problem with trying to fix it - no one has stepped up to the plate and volunteered. Leonard2 came in with some bits of code here and there but not everything went well, with that, and there have been minor contributions from the other usual suspects (Cooke, _mental_, Edward-san, and probably a few others that I am not remembering off the top of my head). And as Arookas has said - there's someone with a huge role in the development who has not even really participated in it since Graf took it over. (Yes, she has made a few contributions to it, too, I won't discount that, but there are other issues and probably not worth discussing here)

Suffice to say, the main reason why Graf is the only one who really knows the code inside and out is because he is the only one willing to do it in the first place. Insert some other programmers into the fold and not only will it be easier for Graf but this situation will not be such a major issue.

[Gez]

Also I'm just going to go out and say that I don't see the point of writing documentation since people will not read it anyway, and instead just whine that they have read it already (lies) but it's just too vague, or that they only understand explanations given in the form of youtube tutorials because their brains shut down when they read more than a single paragraph.

[Rachael]

I disagree there, Gez. There are a lot of people who are lazy and vocal about it, sure, but there are a lot of people who can consume and understand whatever documentation is given to them and make very good use of it. The former you hear from a LOT (I know you know this from your experience maintaining 2 wikis), but the latter you rarely hear from - you just see mods get produced from them.

[arookas]

Ahem.

Hint hint: If I was writing documentation now, while the thing is still in development - as I am clearly the only person knowing all the facts - I wouldn't be able to code the goddamn thing

My point still stands. You are telling us that he said documentation is "unnecessary" because he already knows what everything is. If you cared to read the entire sentence (i.e. the words surrounding the part in red), you'll notice he's actually saying this:

If I was writing documentation now, while the thing is still in development, I wouldn't be able to code the goddamn thing.

This is what he is actually saying. Everybody wants this thing to be finished, so he's (thankfully) prioritizing that rather than writing documentation on an unfinished product.

Yes, there being only one active developer can be scary. But, that's not Graf's fault, not zscript's fault, and certainly not documentation's fault.

[Dynamo]

Ahem.

Hint hint: If I was writing documentation now, while the thing is still in development - as I am clearly the only person knowing all the facts - I wouldn't be able to code the goddamn thing

My point still stands. You are telling us that he said documentation is "unnecessary" because he already knows what everything is. If you cared to read the entire sentence (i.e. the words surrounding the part in red), you'll notice he's actually saying this:

If I was writing documentation now, while the thing is still in development, I wouldn't be able to code the goddamn thing.

This is what he is actually saying. Everybody wants this thing to be finished, so he's (thankfully) prioritizing that rather than writing documentation on an unfinished product.

Yes, there being only one active developer can be scary. But, that's not Graf's fault, not zscript's fault, and certainly not documentation's fault.

Completely agreed there, but also fully agreed with Eruanna in regards to what Gez said. Keep up the good work, in any case

[XxMiltenXx]

And even if there isn't any documentation yet, anything unclear can be discussed here. I think everyone who had a question on how to do things got a good and qualified answer so far. While I agree that documentation would make it easier to check stuff (since I was also one of them who asked for documentation), I agree and understand that the product should be finished first, esp. since things may still change drastically.

So, if you want to help development simply give it a try and ask here if you find a problem you cannot solve, or wait until there is actual documentation on a finished product.

[Nash]

Kinsie:

All that mental energy you're putting into whining could be used to actually fire up Notepad or SLADE or whatever and start writing your first ZScript actor. AKA actually learning the language. Start with something simple and silly first like making a zombieman infinitely scale its size or something goofy like that. You've used ACS before; ZScript isn't far off from ACS.

Also if ANYONE (even "pro" modders) are expecting ZScript to be easy... if you want to do something complicated, you cannot expect something that gives so much low level access to be "easy". This is like complaining "C++ is too damn hard, how do I make a full game like Doom 4 using C++ easy and fast".

You can write a Hello World C++ program in 2 minutes, but you sure as hell cannot expect to write a full game like Doom 4 and expect it to be easy like writing a Hello World program. That's just the reality of programming.

My general advice to everyone: stop being scared and just write your first simple ZScript actor. The syntax isn't that much different from DECORATE, you just have to adhere to the new format (like adding semicolons etc, which is already written on the wiki).

I won't say much about the documentation issue as everyone has said what needs to be said and the only thing that needs to be said (it's still WIP, Graf's time is better utilized actually coding the damn thing first, when it's done, people will slowly fill the wiki in, in the mean time if you ACTUALLY tried to write something and if you asked questions, people will answer what they know)

[Ed the Bat]

I really don't understand anyone's apprehension... I mean, I'm an idiot, and even I'm making SOME progress working with ZScript.

[YukiHerz]

Also if ANYONE (even "pro" modders) are expecting ZScript to be easy... if you want to do something complicated, you cannot expect something that gives so much low level access to be "easy". This is like complaining "C++ is too damn hard, how do I make a full game like Doom 4 using C++ easy and fast".

You can write a Hello World C++ program in 2 minutes, but you sure as hell cannot expect to write a full game like Doom 4 and expect it to be easy like writing a Hello World program. That's just the reality of programming.

My general advice to everyone: stop being scared and just write your first simple ZScript actor. The syntax isn't that much different from DECORATE, you just have to adhere to the new format (like adding semicolons etc, which is already written on the wiki).

^This, great advice, I've begun learning ZScript's syntax by translating my doom 64 mod from decorate to zscript, and now I'm about to dive into the new and complicated parts of it.