ZScript Modules: A Proposal

[The Zombie Killer]

I just finished writing the first draft of my specification for writing ZScript "modules."

I am very interested in hearing all of your thoughts and suggestions, as I think this could be a very useful system to adopt.

While writing the specification I created a series of sample modules. They are:

• zk-acsbridge: Exposes various ACS functions to ZScript, such as [wiki]CreateTranslation[/wiki] and [wiki]PickActor[/wiki]
• zk-stream: Provides a C# Stream-like API along with a tokenizer, for working with custom text lumps
• zk-testsuite: A unit testing solution for ZScript

[Graf Zahl]

zk-acsbridge: I'm not sold on this. Most ACS functions are geared towards how ACS works and make little sense out there. Translations, for example, would require quite a bit of refactoring first, most importantly making a translation a garbage collected object instead of some flat data type like it currently is.

Long term, scripting features should be taken out of ACS and put into a common module accessible to all scripting languages.

zk-stream: Export ScriptMan as a garbage collected object and you should be done.

zk-testsuite: Feel free to write it. I don't have time to conceptualize and develop such a thing.

[The Zombie Killer]

I may not have been clear enough, I've already written those modules.

With zk-acsbridge you can do things like

Code: Select all

ACS.CreateTranslationStart(1);
ACS.CreateTranslationPalette(64, 79, 32, 47);
ACS.CreateTranslationPalette(48, 63, 47, 32);
ACS.CreateTranslationPalette(144, 151, 32, 47);
ACS.CreateTranslationPalette(32, 47, 192, 207);
ACS.CreateTranslationPalette(168, 191, 192, 207);
ACS.CreateTranslationRGB(224, 231, 255, 255, 255, 128, 128, 255);
ACS.CreateTranslationPalette(208, 223, 192, 207);
ACS.CreateTranslationEnd(); 

And then just do Thing_SetTranslation(0, 1);

[Marisa the Magician]

I'm all for this but I'm not exactly a fan of the "four spaces for indentation instead of tabs" choice.

[Marrub]

I'm all for this but I'm not exactly a fan of the "four spaces for indentation instead of tabs" choice.

Obviously, we should all be using three spaces for indentation.
Also, my two cents: That we finally have a way of writing proper library code in ZDoom is great, standardizing it like this is a great idea.

[ZippeyKeys12]

I'm all for this but I'm not exactly a fan of the "four spaces for indentation instead of tabs" choice.

Exactly what I'm thinking

[The Zombie Killer]

The style stuff is mostly a set of guidelines rather than rules. If you're a fan of tabs over spaces, use tabs.

[Gutawer]

I'm interested in this, I was struggling with this here viewtopic.php?f=3&t=58377 and this would be a nice way to get around it. I've voted for the specification needing changes for reasons I've explained on the ZDoom Discord.

[Xaser]

Super-thanks for leading the charge on this! About time.

At any rate, the gears are turning on a few additional thoughts, but the core seems pretty solid thus far. I'm 200% behind the concept, for sure.

The biggest omission at the moment (IMO) is the lack of versioning; distributed modules really ought to have a version number in the filename. Suppose there are two mods that utilize different versions of "zk-stream.pkm"; well, the user can only have one file by that name on their HDD, so it's liable that one of the two mods will become unplayable.

Proposal: semver is awesome and we should adopt it. In such a world, we'll not only know that "zk-stream_1.0.0.pkm" and "zk-stream_2.0.0.pkm" are incompatible versions, but the user can also have them both "installed" and mods that depend on each version will work swimmingly.

Also, while there's nothing wrong with coding/style guidelines, I think they're a bit out of place here -- I'd suggest splitting that off into its own proposal since it's pretty bikeshed-prone and I don't wish to distract from the actual topic.

[Kinsie]

The biggest omission at the moment (IMO) is the lack of versioning; distributed modules really ought to have a version number in the filename. Suppose there are two mods that utilize different versions of "zk-stream.pkm"; well, the user can only have one file by that name on their HDD, so it's liable that one of the two mods will become unplayable.

I'm seeing big issues with doing this, and also with not doing this.

Having every version be a seperate incompatible PK3 will lead to lots of clutter (having 20 different versions of the same module) and will inevitably lead to a situation where, say, the user wants to play a mod that uses v1.1 of a module, but only has v1.0 and v1.2 installed, leading to lots of trying to hunt down the right version (which will inevitably have a broken link).

However, making each version supercede the previous version will result in a situation where the module updating will potentially break every mod that uses the older version unless the module author is very, very careful (they won't be), cue a lot of frustration and confusion and mod authors finding out how Graf feels every day.

Given the ZDoom community's violent phobia for standardization and the "right thing" (reminder that Brutal Doom still ships with instructions to throw it in the skins folder!) I feel like an Elder Scrolls-esque external dependencies system for mods will create more problems than it'll solve.

[Nash]

Just dumping my quick thoughts before heading out for now:

- Not a fan of the .pkm extension
- Keyword casing: why not follow what GZDoom (for the most part) uses? The special ones like Sound, Sector, String, TextureID, Class, Vector3, while the "normal" ones like int, double, etc
- Tabs, not 4 spaces. Following GZDoom's engine source

EDIT: I am actually concerned about how all this fits into a TC/stand-alone workflow. I am making a stand-alone game and will most likely bundle any modules into my game's main ZScript

[Rachael]

I think I will only throw my support behind this if the following conditions are met:

- The libraries are designed for compatibility, as much as possible, with every gameplay mod out there.
- Agreed with others - tabs, not spaces. Sorry.
- These libraries are LGPLv3 licensed and special care is taken not to include non-GPL conforming content. If these are to reach any sort of standard, they have to be something that myself and Graf can officially sanction without worry of the implications this may have. This means, of course, among other things, that all submissions may be used by others without permission (if credit is given, of course), and must be 100% original work by the author submitting them. (Another reason this is important is because including them with the distribution - if this even goes that far - would do a lot towards reaching a standardization point)
- Also I think these should be put on Github. I don't feel as strongly about this point as the other 3, but it's important and still hugely helpful.

[Xaser]

Having every version be a seperate incompatible PK3 will lead to lots of clutter (having 20 different versions of the same module) and will inevitably lead to a situation where, say, the user wants to play a mod that uses v1.1 of a module, but only has v1.0 and v1.2 installed, leading to lots of trying to hunt down the right version (which will inevitably have a broken link).

It's definitely not a perfect scenario, but it's much better than the everything-breaks alternative by a long shot. Improving module distribution problem can be done down the line; accepting some sort of standard is a necessary first step.

[Kinsie]

I am actually concerned about how all this fits into a TC/stand-alone workflow.

Simple: It doesn't.

I feel like you guys are busying themselves coming up with standards and regulations and so on and so forth to avoid actually having to write stuff using ZScript. How's HOERS or whatever it was coming along, anyway?

[phantombeta]

Just wanna drop in my opinion on this.

Also, while there's nothing wrong with coding/style guidelines, I think they're a bit out of place here -- I'd suggest splitting that off into its own proposal since it's pretty bikeshed-prone and I don't wish to distract from the actual topic.

I agree very much with this.
The only part of the coding guidelines that I really agree with is the part about having the "constructor" method be named Create, because having several different modules follow different conventions for "constructor" methods would be extremely annoying and confusing.

- Agreed with others - tabs, not spaces. Sorry.

(See above.)

- These libraries are LGPLv3 licensed and special care is taken not to include non-GPL conforming content. If these are to reach any sort of standard, they have to be something that myself and Graf can officially sanction without worry of the implications this may have. This means, of course, among other things, that all submissions may be used by others without permission (if credit is given, of course), and must be 100% original work by the author submitting them. (Another reason this is important is because including them with the distribution - if this even goes that far - would do a lot towards reaching a standardization point)

While I agree that they must have an actual license, I very much highly disagree with forcing LGPL onto everyone.

I am actually concerned about how all this fits into a TC/stand-alone workflow.

Simple: It doesn't.

I feel like you guys are busying themselves coming up with standards and regulations and so on and so forth to avoid actually having to write stuff using ZScript. How's HOERS or whatever it was coming along, anyway?

I imagine you're kinda wrong there. At least in TZK's case, you can see he definitely would do this...
Specially considering he already posted three modules he made in the OP.