Rant about learning GZDoom scripting/Zscript

Zscript-learning-rant.md

In response to Which ZDooM Script Language to Use?

Just wanted to chime in here as someone who recently learned all three for my first WAD project. I was also given the advice "Learn Zscript", so I did. But I have to say, coming as a total beginner in Doom modding and learning Zscript was definitely jumping off the deep end, even for an experienced programmer like myself. Please excuse my ignorance if I am missing out on things here, and I would love to be enlightened to the contrary, but I would like to share from my recent and hard-won experiences.

There is an awful lot of context that you need to understand in order to be productive as a Doom scripter. And currently, since Zscript is the newest and most advanced scripting language, it has the least documentation of any of them (and what documentation there is tends to assume familiarity with the other two systems.)

I've heard several folks mention similarity to C++ as a reason to learn it. And it's true that the syntax resembles C++, but it's not the same thing. I don't know if it would help you learn C++ any more than other languages in the object-oriented, imperative, weakly typed, C-style family such as C#, Java, or Objective-C. There are some major and important differences to C++ such as lack of access to the standard library, the fact that it's interpreted rather than compiled, lack of pointers and reference manipulation, lack of const objects and methods, etc. It's true that it's a member of this family, and much closer to a general-purpose, modern, object-oriented language than any of the other doom scripting languages. But if you want to learn C++, I'd just study C++. There are way more resources out there for that or any of the other languages in this family than for Zscript itself. In fact, I'd say that learning any of these languages first - at least, running through some basic tutorials and starter projects, would be helpful to learn Zscript rather than the other way around, simply because there are so many more resources for total beginners that introduce the basic concepts.

So I guess what I would advocate, at least until we as a community provide more resources for total beginners to learn Zscript from the get-go, is actually to learn them in the order that they were developed:

1. ACS - this is the simplest and best documented language. It's a bit primitive but you'll likely need it to trigger events that happen in the level. It's easy to trigger an ACS script from a linedef in a map for example - I don't know of a similar way to do such a thing with Zscript, at least not without an awful lot of boiler plate that probably you'd need to figure out for yourself. ZDoom wiki has a lot on ACS and ChubZDoomer has a video tutorial series.

2. DECORATE - This is essentially a subset of Zscript with slightly different syntax, but it's better documented and thus easier to learn. The syntax differences with Zscript are simple and summarized on the wiki. Worth learning as a stepping stone to ZScript to try to create custom enemies, players, weapons, etc. Once you learn Zscript it becomes obsolete. In addition to ZDoom wiki I found some good tutorials on YouTube for DECORATE by Juancho's MRL.

3. Zscript - I think at this point you will be ready. I'd recommend reading ALL the pages about it on the ZDoom wiki. And I wish I had figured this out sooner, but definitely pop open gzdoom.pk3 in SLADE - it's an incredible treasure trove of class/function reference material and some example code as well.

In all cases I think downloading and inspecting WADs by others is an invaluable learning tool. I learned a ton about Zscript looking at JP LeBreton's keymaster mod. I am sure there are some other fantastic examples of Zscript code out there but I am not familiar with them... I'd love if more people posted links!

I'll also offer up my own ZScript-heavy projects here which are still under active development: My team's Global Game Jam 2018 Entry, Imps 'R Us and my very much WIP implementation of Conway's Game of Life.

Also I'd highly reccomend looking at the project layout for those above which I got mostly from Nash's Zdoom project template. You can learn more about PK3 format on the Zdoom Wiki. GZDoom and SLADE can load unpacked directories in PK3 format which makes development a lot easier than using WADs since you can more easily place the contents in version control. This is great for team projects but also helps make history more inspectable for solo projects.

Anyway, that's my two cents. I hope this might help future sojourners. At some point I also hope to contribute to the community efforts at providing better documentation for modding and Zscript. This post is my first attempt!

Cool read. Thanks for the help!