Zdoom's scripting lumps, thoughts

I'm interested to know people's thoughts on the quality of ZDoom's scripting lumps, problems/criticisms on them, but also importantly what you like about them. Having a standard set of scripting lumps with well defined outlines that promote extensibility and ease of use would be a great boon for modders and sourceport developers.

I'm not much experienced with ZDoom's scripting lumps much past DECORATE, but here are my thoughts on some of them. I'd love to hear from people who use them a lot.

ANIMDEFS

This lump seems to have a very simple syntax, no braces, and simple functionality. extending it to do anything more powerful that just tagging with properties (such as the cameratex property) seems like things would get messy rather quickly. Anything new to add needs to fit on just one line for risk of making it unreadable.

However, it is developed for some specific functions, and does them in a pretty simple way. This is handy for modders. I would argue that the syntax still has room for improvement if you were to make it easier to use (probably at further risk of losing extensibility)

CVARINFO

Looks and acts like a header file. Does it's job, and I'm assuming it's very handy for gameplay modders.

Initial impression is that it seems weird that this has a lump of it's own. It feels like it should be part of another lump, but I wouldn't personally know where to put it. It's not a huge problem by any means though.

DECORATE

Very powerful stuff indeed, but steeped with problems.

The #include functionality and actor definition means you can code in a vaguely object-oriented way, which is fantastic for keeping code organised. Some more functionality in scripting editors like Slade 3 could also help for making writing decorate code a lot easier, but this isn't an issue with the language.

The fact that the language stemmed from just defining decoration Things (hence the name) doesn't seem to have harmed the syntax too much, probably because the original syntax was depricated? I haven't checked out the old syntax.

Problems I find with it I think are because of the DEHACKED format, which while decorate is far removed from, still has eccentricities that seem to be because of it.

actor classname [ : parentclassname] [replaces replaceclassname] [doomednum]
{
  properties
  flags
  ...
}

The actor definition has nice functionality, and doesn't have too much information that the syntax gets too confusion.

The code before we get to the States section functions well as a header info for information in the actor. Being able to define new properties somewhere in here (for use in ACS, maybe?) might be a nice feature. Maybe this is already possible, and I don't know :)

states
{
Label:
  FRAME sprite(s) frametime [state_keyword] [Action_Function[(arguments)]]
  flowcontrol (stop, loop, goto x)
}

The states code I remember being a little daunting for me when I first approached it, but was quickly learned. The syntax isn't too complicated, just a little esoteric when arriving from a different coding language.

As it is a state machine, and not a more dynamic language, everything is written linearly. It makes use of GOTOs and labels (which haven't been seen used in modern coding for many years (ideally)), but it seems a necessity here. Since it is so simple, this is not an issue. The action functions are often powerful and there is a huge library to choose from.

The only ideas I have particularly to extend it are:

Being able to use brackets to define a block of action functions at once, eg

POSS A 5 {
  A_Flash
  A_FacePlayer
}

Being able to define ACS scripts inside the state machine, eg

POSS A 5 A_CUSTOM({
  while(AvailableToAllScripts == 101){
        ScriptVariable++;
        Delay(1);
    }
})

(my proposed syntax here is not very good, I'll have to consider some better options)

Decorate does it's job well, and provides huge amounts of functionality further than what would be expected. I'd love to hear other people's thoughts about the caveats or improvements that could be made here.

I also suggest a name-change, DECORATE doesn't describe it's function well at all. ZACTORS maybe? ACTORDEF?

Edit: I forgot to mention the fact that decorate relies on the very strict naming convention for sprites (4 character name, frame character then sprite direction)

A new and less strict method of handling sprites with animation and rotations would be an absolute godsend. Being able to name sprites with more than 4 characters seems like standard stuff. Maybe it could just read the last 2 or 4 characters of the filename? It could be defined elsewhere, in a different lump? ANIMDEFS?

GAMEINFO

Startup scripts for ZDoom, looks like another very useful lump. However, the confusion with MAPINFO's GameInfo section can't be ignored. I think this lump could be renamed to make this clearer, such as STARTUP or similar.

~~

I'll continue with more lumps later, I'm particularly interested in looking at the MENUDEF and SBARINFO lumps.

Like if reviewing maps, mods, graphics and music wasn't enough, now we also criticize editing tools. :P

I've learned and somewhat comprehended MAPINFO, DECORATE, ANIMDEFS, SBARINFO, SNDINFO, LANGUAGE, LOADACS and KEYCONF. I'm comfortable with them all. They work as they should and allow a lot of flexibility, even if not an absolute one. I realize that implementing a flexible text-based script language might not be easy at all (due to compatibility, side effects and such), that's why I better take the tools as they are, as I know nothing behind their obvious interface (that's the developer's job).

I have perspective on how the big mix of different language things can happen and have been trying to avoid it in Eternity by making as many things EDF-based as is possible, and making the older Hexen lump languages secondary and only supported for backwards compat.

I try to avoid criticizing other ports' implementations though the one I do have to say something about is SBARINFO. It started out relatively simple and gradually increased until, today, it is basically a Turing complete language but with extremely unwieldy, inorthogonal, custom syntax. Basically it reinvents the wheel, but as an octogon. I think if there was the power to change it in retrospect, even the devs would have to agree it'd have been better to simply adapt an existing Turing complete language to that purpose.

The problem being of course how so many of them totally suck for embedding into game engines. In Eternity I really want to use JavaScript, but, the only buildable version of SpiderMonkey is from before they added generational GC, so it tends to bog down if a shitton of objects are thrown at it, and after seeing what people have done with ZDoom, I don't trust that it wouldn't be strained to its uttermost limits if I were to implement it.

Every language I've looked at so far has at least one giant gnarly problem that puts me off of adopting it.

For fun, I'll try to write some responses for each one.

jmickle66666666 said:

ANIMDEFS

One thing to note is a number of scripting languages, like this one, stem from Hexen. ZDoom has its extensions in them of course, but it might explain the weird syntax some times.

jmickle66666666 said:

CVARINFO

I actually don't remember any more if there was a rationale for putting this in a separate lump. Probably because the syntax wouldn't have fit into ZMAPINFO which is basically the only other place we would put it.

jmickle66666666 said:

DECORATE

As for custom action functions, that's what the point of waiting for ZScript is. ;)

That said, DECORATE itself is probably best described as a declarative language for a finite state machine. The use of goto here really isn't quite the same as goto in an imperative programming language. The purpose is to have a 1:1 mapping with the internal state structure, which is probably why it feels a little bit like readable DeHackEd.

jmickle66666666 said:

GAMEINFO

The GAMEINFO lump was actually a submission I did. Most of my work got moved into MAPINFO and what remained later got added as the GAMEINFO lump. The separation basically comes down to the stuff in the GAMEINFO lump is processed before the game starts, that is before the IWAD selection screen. So they once were the same thing and I guess we never thought about giving the other part a different name.

Quasar said:

I think if there was the power to change it in retrospect, even the devs would have to agree it'd have been better to simply adapt an existing Turing complete language to that purpose.

Everything you said is basically true, but I think we disagree about the language needing to be Turing complete. When I redesign it for ECWolf I do intend to try to avoid that, but the syntax will be many times better as it will be designed from the ground up to do complex status bar layouts.

For those who don't know the back story: SBarInfo was originally designed for this mod and was originally called LAZBAR by Lazureus who wanted a way to use the Heretic status bar in Doom. The rest was added later since it seemed easy enough.

Yeah it seems that everything I brought up was issues with the way it developed; where we are now with zdoom was not a planned venture, everything was developed by adding to and modifying things.

Developing a new (cross-port) standard for a lot of the features (in a similar vein to UDMF) might be an interesting task, to aide in the development of new sourceports and help modders with better port compatibility. Although that is a big task.

I'll admit I've never been able to grok SBARINFO's syntax. I'm sure if I seriously tried, I would get it, but since there isn't anything I really want to do with the status bar...

ANIMDEFS, SNDINFO, SNDSEQ, and MAPINFO all originate from Hexen. In MAPINFO, the original syntax ended up being changed (yielding ZMAPINFO) because it had too many problems trying to extend it, including the thorny issue of compatibility with other ports also extending MAPINFO in their own way. ANIMDEFS was extended to give it some features it did not have in Hexen (like Doom-style animations and Strife's animated doors). SNDSEQ got an extension that is a bit weird-looking, but it isn't too much of a problem because it's quite unlikely to get further extensions. SNDINFO has the advantage that keywords begin with $ (or *, for aliases). In all these cases, there was a choice to make between "this already exists, and we can add that to it" and "this would make sense if it worked this way". ZDoom did not choose the latter. :p

DECORATE's first syntax was very different indeed. Here's an example:

   SmallLamp
   {
       DoomEdNum 20001
       Sprite SLMP
       Frames "ABCD"
       Solid
       Radius 16
       Height 56
       //$Category lights
   }

The limitations are obvious: there is no inheritance, states cannot have action functions associated to them, actors can only use one set of sprite, etc.

It got its first extension by being able to define other simple actors: projectiles, breakable objects, and pickups. Those are defined by starting the declaration with the relevant keyword (projectile, breakable, or pickup) before the actor name. So for backward compatibility, a DECORATE parser must handle six different types of declaration:

1. Actor blah {} (normal actor declaration in modern format)
   
2. DamageType blah {} (yeah, damage types can be defined in DECORATE)
   
3. projectile blah {}
   
4. breakable blah {}
   
5. pickup blah {}
   
6. blah {}

It was fun patching SLADE's DECORATE parser so as not to choke on mods using the old syntax alongside the new (Urban Brawl being the most recent I've seen doing that).

I'm rather sketchy with most of it, I'm a slow learner with it all. However I have been able to achieve with decorate mostly, some custom things and actions.

At the moment I'm trying to get my head around dynamic lighting. Using GLDEFS I haven't gotten anything to work yet. Before today I didn't know there were any GLDEFS...there seems to be a lot of these lump files about.

As I'm not really a coder or programmer I find all of this a bit tough, even when looking for help. But what I have managed to do I'm quite proud of, even if isn't mastery of the craft...It's something.

Blzut3 said:

When I redesign it for ECWolf I do intend to try to avoid that, but the syntax will be many times better as it will be designed from the ground up to do complex status bar layouts.

When you do do that, don't forget to port the changes to ZDoom :p

The thing about SBARINFO that bugs me a little is that when a little bit of complexity is introduced, the lump can't handle it on its own, and requires to be backed up by both ACS and DECORATE.

When i started modding with ZDoom, i had no idea what i was doing.
Looking at the wiki and some other wads i got to know a bit about how lumps worked, then i heard about this magical thing called ACS...

Well once i got the basics down, it was mostly just trial-and-error to get the effect i was aiming for. So yeah i find ZDoom's lumps fairly easy to work with (doesn't mean im good at it haha).

Yeah, trial and orror is a big part of it. I got quite far with the GLDEFS, I used the ZDoom site for help, but I don't think it a very good site for explanation.

http://zdoom.org/wiki/GLDEFS

It tells the whats but not always the hows. Well, either way as someone who only went into trying to make a GLDEFS yesterday, I have successfully managed to make a working light source.

Due to lack of knowledge and understanding about it all I'm happy with what I have until I fine tune it later.

Because my WAD I'm working on uses resources from both Doom 1 and 2, I get displeased with the Burning Barrel having a bad offset number with Ultimate Doom for one of it's frames, and when playing my WAD it likes to show off the Barrel with a crap offset...but if you use Doom 2 only it chooses the proper Barrel Doom 2 has with no bad offset, it is perfectly fine. I got sick of this and after failing to find a fix for it...well, I made my own barrel.



There's a comparison between the dodgy offset barrel and mine.

Gotta tweak it a little but it is doing well. The code for the GLDEFs files it uses went though so many variations and changes....I'm happy it worked. I learned something.

I guess what I'm trying to say is, even for someone like me, who doesn't know much about this sort of thing, it can be learned. Overnight too in this case heh.

A tip: zdoom.pk3 or gzdoom.pk3 files make a good source for examples on how to uses these lumps. You can learn from them.