Which ZDooM Script Language to Use?

[Ligmatism]

Well, after many unsuccessful hunts for loopholes around the coding process for DooM WADs (I know, pathetic ), I caved and decided to learn one of the languages available for ZDooM-based WADs and mods (DECORATE, Zscript, DeHackED, ACS, etc.). I am extremely interested in creating custom DooM WADs, but I am at a loss of which language to learn. So, I was hoping one of you fine lads with experience in any of these languages could provide a super basic rundown comparison of each language (pros vs. cons or something).


Thanks, Ligmatism.

[Matt]

ZScript.

Second fewest arbitrary quirks and limitations (i.e., those not found in more usual programming languages) you need to deal with, after ACS.
More general applicability than ACS and no need to compile a blob.

There is nothing you can do in Decorate (itself extremely versatile) that cannot be done in ZScript (any commands they share in common count as ZScript when I say this).

Most Decorate tutorials and precedents out there would basically work in ZS once you convert all the syntax (and get around a few deprecated functions) - the only way they're potentially "wrong" is inasmuch as ZS would allow much more efficient ways to accomplish the same goals.

It's also vastly easier to add Decorate to a ZScript project than the other way around - the former just requires the new code, the latter requires you to restructure your entire mod and possibly rewrite a bunch of stuff in ZS anyway before you can get it working again.


I don't see the point in learning Dehacked these days except to get a better understanding of why Decorate/ZScript look the way they do.

[phantombeta]

Here's a list of pros and cons. (May or may not be slightly influenced by my own opinions.)

---

DECORATE:
DECORATE is a scripting language for actors. (game objects)

Pros:

• Easy to learn.
• Parser is less strict than ZScript's, allowing you to get away with things that wouldn't work in ZScript.

Cons:

• Inflexible.
• Parser is less strict than ZScript's, meaning it won't catch some errors that ZScript would.
• Has to resort to ACS or ZScript for more complex things.
• Usually has to write more code.

================================================================================

ACS:
ACS is a scripting language for map manipulation. Due to the lack of a better alternative, lots of gameplay scripting-related functions were hacked onto it.

Pros:

• Easy to use for map manipulation.

Cons:

• Has to be compiled with an external program, complicating testing.
• Has to resort to hacks often when used for gameplay scripting.
• Slow and not meant for gameplay scripting. (even though it's used for that)

================================================================================

ZScript:
ZScript is a more powerful and lower level scripting gameplay scripting language. It's used for scripting actors and anything gameplay-related.

Pros:

• Parser is stricter, meaning that some errors are caught before the game even starts.
• More flexible and powerful than DECORATE, while allowing to do anything DECORATE does with usually only very small differences.

Cons:

• Needs some programming knowledge. (... But only if you're using the more complex features! Otherwise it's almost as easy as DECORATE.)
• Parser is less forgiving of shitty code. (Actually a pro, since then your mod is less likely to break in the future.)

================================================================================

Dehacked:
Dehacked was made for modifying vanilla Doom.

Pros:

• Made for the vanilla game, so most (if not all) ports support it.

Cons:

• Inflexible as fuck.
• Can't do much.
• Useless if you're making a ZDoom mod.
• Hard to use.

[krokots]

Using ZScript also will give you some understanding of C++/C#. The only point of choosing ACS or Decorate over ZScript is if you really don't have any programming experience and want to start with something easy. ZScript is just too powerful to not use it right now.

[gwHero]

I agree with previous speakers: ZScript is the most powerful and preferred scripting language in GZDoom. Nevertheless, sometimes you will have to rely on ACS as well. For instance, when you want to trigger a script from the map, it's not yet possible to call ZScript functions directly from it. You will have to call a ACS script in that case; from there, you can decide to handle stuff in ACS itself or parsing it to ZScript with ScriptCall. It's all made quite flexible; vice versa calling ACS from ZScript is also possible.

[Nash]

Are there any official plans to deprecate ACS and allow ZScript to do full map scripting? To be honest, I only have acc.exe kept around because of map scripting and I wouldn't mind doing without it...

[Rachael]

Last I remember Graf specifically stated there were no such plans.

[Matt]

Nevertheless, sometimes you will have to rely on ACS as well. For instance, when you want to trigger a script from the map, it's not yet possible to call ZScript functions directly from it. You will have to call a ACS script in that case; from there, you can decide to handle stuff in ACS itself or parsing it to ZScript with ScriptCall. It's all made quite flexible; vice versa calling ACS from ZScript is also possible.

This.

And not just for mapping, either - HudMessages are still the only simple minimum-nonsense way to draw stuff on a player's screen without replacing a important actors and redefining basic parts of the game.

[Gez]

Be a rebel and learn [wiki]FraggleScript[/wiki] instead.

---

(Not a serious suggestion.)

[Eliot_L]

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. As gwHero mentioned, 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. And as Matt mentioned, it's the only sane way to do something like a HudMessage.

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

[phantombeta]

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

That's in part because a big chunk of ZScript is literally just DECORATE with a slightly different syntax.

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.

Knowing C# or Java helps more than C++, but the best would be knowing both, so it's easier to understand why things are the way they are in ZScript.

such as lack of access to the standard library

???

the fact that it's interpreted rather than compiled

Not quite. It's compiled into ZScriptVM bytecode.

lack of const objects and methods

There's readonly variables and AFAIK there's const methods.

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.

I'm not sure I've ever seen anyone recommend learning ZScript to learn C++ - In fact, what I've seen is people recommending learning C++ to make learning ZScript easier.

One thing to note is that ZScript has a ton of undocumented features. Some of them were documented by marrub. Since I'm not sure if he wants it posted on this forum at the moment, you can ask him for a link.

[Eliot_L]

That's in part because a big chunk of ZScript is literally just DECORATE with a slightly different syntax.

Right, which is why I suggested learning DECORATE first, since it's targeted by the existing documentation. An experienced programmer should have no trouble translating the syntax on the fly but I think that might be a lot for a beginner to handle.

such as lack of access to the standard library

???

This comment was mostly stemming from my frustration at the lack of certain facilities in ZScript for less common tasks such as obtaining freeform text input from the player, parsing ints from strings, etc. In the past I have used Lua for scripting, which could provide a transparent FFI to leverage functions in the native library on the host runtime (in that case, Objective-C/Cocoa) - although this is understandably more difficult here. Perhaps due to security considerations and the lack of support for reflection in the C++ runtime. And maybe also due to being a mature Doom source port so having to support all these other scripting mechanisms too. Totally understandable if this was never a design goal to begin with.

I didn't really intend this as a dig against ZScript. In fact, now that I'm getting the hang of it, I'm finding it quite robust for what it's designed to do. Not to mention that it's more my style than the strange beast that is Lua. I was just trying to highlight some of the differences between it and a more general purpose language.

the fact that it's interpreted rather than compiled

Not quite. It's compiled into ZScriptVM bytecode.

Interesting! Makes sense.

lack of const objects and methods

There's readonly variables and AFAIK there's const methods.

Cool - I did know about and use const variables, but chalk up another one to gaps in my own knowledge regarding const methods. I'll have to try that out.

I'm not sure I've ever seen anyone recommend learning ZScript to learn C++ - In fact, what I've seen is people recommending learning C++ to make learning ZScript easier.

Perhaps I misunderstood - this makes a lot more sense to me and is also what I was suggesting.

One thing to note is that ZScript has a ton of undocumented features. Some of them were documented by marrub. Since I'm not sure if he wants it posted on this forum at the moment, you can ask him for a link.

This sounds incredibly useful, I will do so. Thanks for the tip.
Although this kind of backs up my earlier comments about the general lack of documentation for ZScript.

[Major Cooke]

Last I remember Graf specifically stated there were no such plans.

He will eventually export all the ACS functionality. However, it's not deprecated for map control purposes since that's pretty much a map made in heaven.

Phantombeta wrote up a very good list of comparisons and I quite agree with it.

Just be careful; some functions like A_DropItem will NOT work properly for actors that are still part of DECORATE and the function's called in ZScript (though I think that's a bug, because DropItem's properties work just fine with A_Fall).

[Rachael]

Last I remember Graf specifically stated there were no such plans.

He will eventually export all the ACS functionality. However, it's not deprecated for map control purposes since that's pretty much a map made in heaven.

Really? Where'd he say this?