Questions reguarding difference in script languages.
- TurboBabyShakes5000
- Posts: 26
- Joined: Sun Jul 18, 2021 3:22 pm
- Graphics Processor: Intel (Modern GZDoom)
- Location: The South :(
Questions reguarding difference in script languages.
I've begun scripting in ACS because most of the mods I really like use it, but I also see a lot of talk about Zscript and DECORATE and wonder if maybe I'm selling myself short as far where my learning will take me. What is a brief overview of the various languages scope and general expected relevance in the future?
- Caligari87
- Admin
- Posts: 6229
- Joined: Thu Feb 26, 2004 3:02 pm
- Preferred Pronouns: He/Him
- Contact:
Re: Questions reguarding difference in script languages.
ACS is mostly intended for map scripting. Things like opening doors, handling complex switches, elevators, spawning monsters, traps, etc. Basically similar to what can be done with linedef actions, but generally more flexible and robust. ACS has been used in the past to supplement gameplay scripting, but that's considered hacky and bad practice these days.
DECORATE was originally intended mostly for making simple decorations (lamps, barrels, etc) hence the name. Over time it got expanded to defining pickups, monsters, and weapons. However it was still fairly limited, so people used tricks to move data between DECORATE and ACS to facilitate more complex gameplay scripting. Again, considered hacky, but it's the best we had for a while.
ZScript is a proper gameplay scripting language, able to handle most of what used to require native engine features. It's extremely robust in comparison to anything else we've had before, and I highly recommend learning it. In fact, DECORATE is actually a "sub-language" of ZScript now, so it covers the old use cases as well as new ones, and doesn't require passing data over to ACS for more complex operations.
So in short: ACS for map scripts, ZScript for monsters/weapons/items. DECORATE can generally be safely ignored unless you're using old tutorials for learning, and even then you can easily translate them into ZScript.

DECORATE was originally intended mostly for making simple decorations (lamps, barrels, etc) hence the name. Over time it got expanded to defining pickups, monsters, and weapons. However it was still fairly limited, so people used tricks to move data between DECORATE and ACS to facilitate more complex gameplay scripting. Again, considered hacky, but it's the best we had for a while.
ZScript is a proper gameplay scripting language, able to handle most of what used to require native engine features. It's extremely robust in comparison to anything else we've had before, and I highly recommend learning it. In fact, DECORATE is actually a "sub-language" of ZScript now, so it covers the old use cases as well as new ones, and doesn't require passing data over to ACS for more complex operations.
So in short: ACS for map scripts, ZScript for monsters/weapons/items. DECORATE can generally be safely ignored unless you're using old tutorials for learning, and even then you can easily translate them into ZScript.

- TurboBabyShakes5000
- Posts: 26
- Joined: Sun Jul 18, 2021 3:22 pm
- Graphics Processor: Intel (Modern GZDoom)
- Location: The South :(
Re: Questions reguarding difference in script languages.
Thanks for your prompt and and informative post! I'm off to find baby's first Zscript tutorials.
- TurboBabyShakes5000
- Posts: 26
- Joined: Sun Jul 18, 2021 3:22 pm
- Graphics Processor: Intel (Modern GZDoom)
- Location: The South :(
Re: Questions reguarding difference in script languages.
I'm still on "probation" as far as needing my posts to be approved first, so I apologize for any awkwardness as for as continuity is concerned. I was wondering what your take, or anybody who may read this take on what this person said: https://gist.github.com/fadookie/310c3b ... 36fab24455.
[/code]
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.
[/code]
Should I do as they suggest and follow the history of coding for this game or is this more of a personal approach and not necessarily the rule of thumb?
[/code]
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.
[/code]
Should I do as they suggest and follow the history of coding for this game or is this more of a personal approach and not necessarily the rule of thumb?
- Caligari87
- Admin
- Posts: 6229
- Joined: Thu Feb 26, 2004 3:02 pm
- Preferred Pronouns: He/Him
- Contact:
Re: Questions reguarding difference in script languages.
It's decent advice I suppose. I personally think learning ACS is only really necessary if you need to do map scripting (which I don't because I rarely make maps anymore). The main downside with ACS as a starter language is that it has a lot of really primitive things (fixed point numbers and treating strings as ints, for example) that don't apply to more flexible languages. That said, it's also simple enough to get the basics down quickly (a script is basically a list of linedef-type actions in most cases), so you don't need to spend much time on it.
Between DECORATE and ZScript, DECORATE is indeed the simpler one and can be a good starting point. The problem is that 99.9% of the tutorials for it were written a long time ago, so the moment you get into anything more complex than a stock Doom actor, lots of nasty workarounds start appearing (inventory items as counter tokens, flash state abuse instead of overlays, passing data to ACS libraries for processing, etc). Be aware of this, but don't let it stop you I suppose. It mostly useful for learning how states and action functions work. My advice would be to just translate the DECORATE tutorials into ZScript as you go: [wiki]Converting_DECORATE_code_to_ZScript[/wiki]
Ideally, if you have some background in a "bracketed" programming language (C, C++, C#, D, Java, etc), that helps a lot with grasping basic syntax of ZScript. Here's a couple good resources that haven't quite made their way into prominence on the Wiki yet:
ZScript Basics for Non-Programmers
ZScript API
The best way to get started (in my opinion) is to copy the code for a simple actor like the DoomImp from gzdoom.pk3, rename the class to something like MyCustomDoomImp, and start modifying it. Make it fire three fireballs instead of one, for example. The only thing you can't use in a PWAD is the extend class Actor bit (because Actor is part of gzdoom.pk3), but you can change that to extend class MyCustomDoomImp instead.

Between DECORATE and ZScript, DECORATE is indeed the simpler one and can be a good starting point. The problem is that 99.9% of the tutorials for it were written a long time ago, so the moment you get into anything more complex than a stock Doom actor, lots of nasty workarounds start appearing (inventory items as counter tokens, flash state abuse instead of overlays, passing data to ACS libraries for processing, etc). Be aware of this, but don't let it stop you I suppose. It mostly useful for learning how states and action functions work. My advice would be to just translate the DECORATE tutorials into ZScript as you go: [wiki]Converting_DECORATE_code_to_ZScript[/wiki]
Ideally, if you have some background in a "bracketed" programming language (C, C++, C#, D, Java, etc), that helps a lot with grasping basic syntax of ZScript. Here's a couple good resources that haven't quite made their way into prominence on the Wiki yet:
ZScript Basics for Non-Programmers
ZScript API
The best way to get started (in my opinion) is to copy the code for a simple actor like the DoomImp from gzdoom.pk3, rename the class to something like MyCustomDoomImp, and start modifying it. Make it fire three fireballs instead of one, for example. The only thing you can't use in a PWAD is the extend class Actor bit (because Actor is part of gzdoom.pk3), but you can change that to extend class MyCustomDoomImp instead.

Re: Questions reguarding difference in script languages.
Regarding DECORATE, there is one particular thing worth mentioning. Zandronum supports DECORATE (and a very old version of it at that, it lacks a lot of functions and capabilities added in GZDoom, in particular anonymous functions), but not ZScript, and for reasons that are beyond the scope of this discussion, never will in its current form. As Zandronum is by far the most popular multiplayer Doom port, DECORATE is still frequently used for projects that rely very heavily on multiplayer (i.e. Samsara). For practical purposes, I would say this is the only real reason to use DECORATE nowadays; there are technically other ports that have DECORATE support, but in practice, the only ones widely used nowadays are Zandronum and GZDoom. Zandronum's DECORATE is far older and more primitive (which leads to clunkier and hackier code) than GZDoom's ZScript though, so consider seriously if you're project critically depends on multiplayer.
Also related to this that is worth knowing about as far as these kind of things go is DEHACKED. It used to be a way of modifying Doom by modifying the exe directly, but nowadays exists as a "language" that emulates the modifications without changing anything about the exe. It is even more primitive than DECORATE, and has severe limitations; in particular, you cannot define new actors or actions, only modify/use pre-existing stuff that was already in the original Doom exe's (sort of; there are sorts of work-arounds, but don't worry about that for now). It is commonly used in Vanilla/Boom/MBF mapsets, as DEHACKED is supported by almost all major source ports. It's poorly suited for complex gameplay mods in general, but is fine for making "small" tweaks for stuff that is designed to target Vanilla/Boom/MBF source ports. In essence, DEHACKED is the highest scripting ability you have for non-advanced ports.
Also related to this that is worth knowing about as far as these kind of things go is DEHACKED. It used to be a way of modifying Doom by modifying the exe directly, but nowadays exists as a "language" that emulates the modifications without changing anything about the exe. It is even more primitive than DECORATE, and has severe limitations; in particular, you cannot define new actors or actions, only modify/use pre-existing stuff that was already in the original Doom exe's (sort of; there are sorts of work-arounds, but don't worry about that for now). It is commonly used in Vanilla/Boom/MBF mapsets, as DEHACKED is supported by almost all major source ports. It's poorly suited for complex gameplay mods in general, but is fine for making "small" tweaks for stuff that is designed to target Vanilla/Boom/MBF source ports. In essence, DEHACKED is the highest scripting ability you have for non-advanced ports.
- TurboBabyShakes5000
- Posts: 26
- Joined: Sun Jul 18, 2021 3:22 pm
- Graphics Processor: Intel (Modern GZDoom)
- Location: The South :(
Re: Questions reguarding difference in script languages.
Thanks for all the thoughtful advice! The zeitgeist has shifted pretty heavily towards zscript from what I can tell. Will likely gravitate towards that, but not before trying to get a grasp of the older stuff as advised.