ZScript Modules: A Proposal

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

After reading the specification, do you believe this should be an accepted standard?

Yes
3
30%
Yes, but only after the specification has received changes (please specify)
5
50%
No
2
20%
No, I do not believe modules are the right solution
0
No votes
 
Total votes: 10

User avatar
The Zombie Killer
Posts: 1528
Joined: Thu Jul 14, 2011 12:06 am
Discord: Zombie#1795
Location: Gold Coast, Queensland, Australia

ZScript Modules: A Proposal

Post by 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
Last edited by The Zombie Killer on Thu Nov 16, 2017 9:33 am, edited 1 time in total.
User avatar
Graf Zahl
Lead GZDoom+Raze Developer
Lead GZDoom+Raze Developer
Posts: 48033
Joined: Sat Jul 19, 2003 10:19 am
Location: Germany

Re: ZScript Modules: A Proposal

Post by 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.
User avatar
The Zombie Killer
Posts: 1528
Joined: Thu Jul 14, 2011 12:06 am
Discord: Zombie#1795
Location: Gold Coast, Queensland, Australia

Re: ZScript Modules: A Proposal

Post by 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);
User avatar
Marisa the Magician
 
 
Posts: 3816
Joined: Fri Feb 08, 2008 9:15 am
Discord: Marisa the Magician#1666
Twitch ID: MarisaDOOM
Github ID: OrdinaryMagician
Preferred Pronouns: She/Her
Graphics Processor: nVidia with Vulkan support
Location: Vigo, Galicia

Re: ZScript Modules: A Proposal

Post by 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.
User avatar
Marrub
 
 
Posts: 1166
Joined: Tue Feb 26, 2013 2:48 pm
Discord: agw.systems#7777
Twitch ID: marrubdaskuleion
Github ID: marrub--
Preferred Pronouns: They/Them
Operating System Version (Optional): Arch Linux
Graphics Processor: ATI/AMD with Vulkan Support

Re: ZScript Modules: A Proposal

Post by Marrub »

Marisa Kirisame wrote: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. :D
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
Posts: 111
Joined: Wed Jun 15, 2016 2:49 pm

Re: ZScript Modules: A Proposal

Post by ZippeyKeys12 »

Marisa Kirisame wrote: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 :?
User avatar
The Zombie Killer
Posts: 1528
Joined: Thu Jul 14, 2011 12:06 am
Discord: Zombie#1795
Location: Gold Coast, Queensland, Australia

Re: ZScript Modules: A Proposal

Post by 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.
User avatar
Gutawer
User Accounts Assistant
Posts: 462
Joined: Sat Apr 16, 2016 6:01 am
Discord: Gutawer#3431
Preferred Pronouns: She/Her

Re: ZScript Modules: A Proposal

Post by 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.
User avatar
Xaser
 
 
Posts: 10771
Joined: Sun Jul 20, 2003 12:15 pm

Re: ZScript Modules: A Proposal

Post by Xaser »

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

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.
Last edited by Xaser on Thu Nov 16, 2017 7:40 pm, edited 1 time in total.
User avatar
Kinsie
Posts: 7312
Joined: Fri Oct 22, 2004 9:22 am
Discord: Wow, this side panel's getting cluttered
Twitch ID: thekinsie
Github ID: TheKins
Graphics Processor: nVidia with Vulkan support
Location: MAP33

Re: ZScript Modules: A Proposal

Post by Kinsie »

Xaser wrote: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.
User avatar
Nash
 
 
Posts: 17296
Joined: Mon Oct 27, 2003 12:07 am
Twitch ID: nashmuhandes
Github ID: nashmuhandes
Location: Kuala Lumpur, Malaysia

Re: ZScript Modules: A Proposal

Post by 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
User avatar
Rachael
Admin
Posts: 12950
Joined: Tue Jan 13, 2004 1:31 pm
Discord: Rachael#3767
Twitch ID: madamerachelle
Github ID: madame-rachelle
Preferred Pronouns: She/Her

Re: ZScript Modules: A Proposal

Post by 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.
User avatar
Xaser
 
 
Posts: 10771
Joined: Sun Jul 20, 2003 12:15 pm

Re: ZScript Modules: A Proposal

Post by Xaser »

Kinsie wrote: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.
User avatar
Kinsie
Posts: 7312
Joined: Fri Oct 22, 2004 9:22 am
Discord: Wow, this side panel's getting cluttered
Twitch ID: thekinsie
Github ID: TheKins
Graphics Processor: nVidia with Vulkan support
Location: MAP33

Re: ZScript Modules: A Proposal

Post by Kinsie »

Nash wrote: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?
User avatar
phantombeta
Posts: 2000
Joined: Thu May 02, 2013 1:27 am
Graphics Processor: nVidia with Vulkan support

Re: ZScript Modules: A Proposal

Post by phantombeta »

Just wanna drop in my opinion on this.
Xaser wrote: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.
Rachael wrote:- 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.
Kinsie wrote:
Nash wrote: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. :wink:

Return to “Scripting”