Which ZDooM Script Language to Use?

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!)
Post Reply
User avatar
Ligmatism
Posts: 21
Joined: Sat Feb 03, 2018 1:15 pm

Which ZDooM Script Language to Use?

Post by Ligmatism »

Well, after many unsuccessful hunts for loopholes around the coding process for DooM WADs (I know, pathetic :roll:), 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.
Last edited by Ligmatism on Tue Feb 15, 2022 5:16 am, edited 1 time in total.
User avatar
Matt
Posts: 9696
Joined: Sun Jan 04, 2004 5:37 pm
Preferred Pronouns: They/Them
Operating System Version (Optional): Debian Bullseye
Location: Gotham City SAR, Wyld-Lands of the Lotus People, Dominionist PetroConfederacy of Saudi Canadia
Contact:

Re: Which ZDooM Script Language to Use?

Post by 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.
User avatar
phantombeta
Posts: 2084
Joined: Thu May 02, 2013 1:27 am
Operating System Version (Optional): Windows 10
Graphics Processor: nVidia with Vulkan support
Location: Brazil

Re: Which ZDooM Script Language to Use?

Post by phantombeta »

Here's a list of pros and cons. (May or may not be slightly influenced by my own opinions.)
Spoiler:
User avatar
krokots
Posts: 266
Joined: Tue Jan 19, 2010 5:07 pm

Re: Which ZDooM Script Language to Use?

Post by 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.
User avatar
gwHero
Posts: 360
Joined: Mon May 08, 2017 3:23 am
Graphics Processor: Intel with Vulkan/Metal Support
Location: The Netherlands

Re: Which ZDooM Script Language to Use?

Post by 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.
User avatar
Nash
 
 
Posts: 17434
Joined: Mon Oct 27, 2003 12:07 am
Location: Kuala Lumpur, Malaysia
Contact:

Re: Which ZDooM Script Language to Use?

Post by 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... :mrgreen:
User avatar
Rachael
Posts: 13531
Joined: Tue Jan 13, 2004 1:31 pm
Preferred Pronouns: She/Her
Contact:

Re: Which ZDooM Script Language to Use?

Post by Rachael »

Last I remember Graf specifically stated there were no such plans.
User avatar
Matt
Posts: 9696
Joined: Sun Jan 04, 2004 5:37 pm
Preferred Pronouns: They/Them
Operating System Version (Optional): Debian Bullseye
Location: Gotham City SAR, Wyld-Lands of the Lotus People, Dominionist PetroConfederacy of Saudi Canadia
Contact:

Re: Which ZDooM Script Language to Use?

Post by Matt »

gwHero wrote: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
 
 
Posts: 17833
Joined: Fri Jul 06, 2007 3:22 pm

Re: Which ZDooM Script Language to Use?

Post by Gez »

Be a rebel and learn [wiki]FraggleScript[/wiki] instead.
Spoiler:
User avatar
Eliot_L
Posts: 34
Joined: Thu Mar 08, 2018 3:40 am
Contact:

Re: Which ZDooM Script Language to Use?

Post by 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!
User avatar
phantombeta
Posts: 2084
Joined: Thu May 02, 2013 1:27 am
Operating System Version (Optional): Windows 10
Graphics Processor: nVidia with Vulkan support
Location: Brazil

Re: Which ZDooM Script Language to Use?

Post by 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.
User avatar
Eliot_L
Posts: 34
Joined: Thu Mar 08, 2018 3:40 am
Contact:

Re: Which ZDooM Script Language to Use?

Post by Eliot_L »

phantombeta wrote: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.
phantombeta wrote:
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. :D I was just trying to highlight some of the differences between it and a more general purpose language.
phantombeta wrote:
the fact that it's interpreted rather than compiled
Not quite. It's compiled into ZScriptVM bytecode.
Interesting! Makes sense.
phantombeta wrote:
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.
phantombeta wrote: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.
phantombeta wrote: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.
User avatar
Major Cooke
Posts: 8170
Joined: Sun Jan 28, 2007 3:55 pm
Preferred Pronouns: He/Him
Location: QZDoom Maintenance Team

Re: Which ZDooM Script Language to Use?

Post by Major Cooke »

Rachael wrote: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).
User avatar
Rachael
Posts: 13531
Joined: Tue Jan 13, 2004 1:31 pm
Preferred Pronouns: She/Her
Contact:

Re: Which ZDooM Script Language to Use?

Post by Rachael »

Major Cooke wrote:
Rachael wrote: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?
Post Reply

Return to “Scripting”