ZScript Documentation (2021 Redux!)

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!)
User avatar
Mikk-
Posts: 2274
Joined: Tue Jun 30, 2009 1:31 pm
Location: Somewhere off Kanagawa

Re: ZScript Language Documentation (WIP)

Post by Mikk- »

Major Cooke wrote:Quick note about properties, you can only use int, double, bool, class<name>, strings and names. I haven't had any luck using vectors.
State labels also do not work, but i think this has been covered in another thread
User avatar
Marrub
 
 
Posts: 1198
Joined: Tue Feb 26, 2013 2:48 pm
Preferred Pronouns: No Preference
Operating System Version (Optional): Arch Linux
Graphics Processor: ATI/AMD with Vulkan/Metal Support

Re: ZScript Language Documentation (WIP)

Post by Marrub »

Fairly major revision. Fixed some information, clarified things, added lots to the API section and added an introduction. Also cleaned up the table of contents.
User avatar
Major Cooke
Posts: 8196
Joined: Sun Jan 28, 2007 3:55 pm
Preferred Pronouns: He/Him
Location: QZDoom Maintenance Team

Re: ZScript Language Documentation (WIP)

Post by Major Cooke »

Maps? Huh, what will those do?
User avatar
Player701
 
 
Posts: 1651
Joined: Wed May 13, 2009 3:15 am
Graphics Processor: nVidia with Vulkan support

Re: ZScript Language Documentation (WIP)

Post by Player701 »

Major Cooke wrote:Maps? Huh, what will those do?
They will help me implement what I want in a much cleaner and less hackish way :) Too bad they are not in yet. I really hope they will be added someday.

Seriously though, a map is a collection of key-value pairs that implements a fast (in theory, O(1)) operation to look up a value by its key. For example, you have a collection of arbitrary objects identified by names (which take the form of a string), and you need to access these objects by their names (this is actually my own use case). If you use an array to store your objects, you will have to iterate through the whole array to find an object by its name, which is slow. A map will generally work much faster in this case, though it depends on the hash function it uses. Still, should be faster than traversing an array (O(N) on average). It really helps when you have a lot of objects, but if you only have a few, the difference probably wouldn't be noticeable.
User avatar
Graf Zahl
Lead GZDoom+Raze Developer
Lead GZDoom+Raze Developer
Posts: 49177
Joined: Sat Jul 19, 2003 10:19 am
Location: Germany

Re: ZScript Language Documentation (WIP)

Post by Graf Zahl »

The reason why there are no maps is that every variation needs a backing implementation. We needed 7 array versions, so by simple multiplication it means that 49 map versions would be needed.

Regarding performance, maps really need a somewhat larger number of objects to work well. Up to 10-20 entries an array will be faster, depending on the data type being stored.
User avatar
Marrub
 
 
Posts: 1198
Joined: Tue Feb 26, 2013 2:48 pm
Preferred Pronouns: No Preference
Operating System Version (Optional): Arch Linux
Graphics Processor: ATI/AMD with Vulkan/Metal Support

Re: ZScript Language Documentation (WIP)

Post by Marrub »

The documentation has been updated, adding better documentation for version differences, better organization, and missing descriptions for a number of things. The current priority is to document Screen, then the intermission screen things and Thinker. From there most of the basic classes should be finished, and I'll move on to Actor and its descendants. This will be extremely arduous so help would be appreciated. If you'd like to contribute (and acknowledge that this documentation is public domain and so your contributions will as well be,) don't hesitate to get at me on Discord, in the "#oh-no-not-things" channel on my public server.
User avatar
Marrub
 
 
Posts: 1198
Joined: Tue Feb 26, 2013 2:48 pm
Preferred Pronouns: No Preference
Operating System Version (Optional): Arch Linux
Graphics Processor: ATI/AMD with Vulkan/Metal Support

Re: ZScript Language Documentation (WIP)

Post by Marrub »

Updated the documentation again. Added concept explanations for sprites and game ticks, a class tree and structure tree, and partial or full documentation for the following classes:
  • Thinker
  • CVar
  • GIFont
  • State
  • StringTable
  • DehInfo
  • GameInfoStruct
  • PSprite
  • Console
Additionally, some errata has been fixed, including misspellings and incorrect behavioural information. (Errare humanum est.)
User avatar
Rip and Tear
Posts: 186
Joined: Tue May 02, 2017 3:54 pm

Re: ZScript Language Documentation (WIP)

Post by Rip and Tear »

Have you considered breaking this up into multiple pages?
User avatar
Marrub
 
 
Posts: 1198
Joined: Tue Feb 26, 2013 2:48 pm
Preferred Pronouns: No Preference
Operating System Version (Optional): Arch Linux
Graphics Processor: ATI/AMD with Vulkan/Metal Support

Re: ZScript Language Documentation (WIP)

Post by Marrub »

Rip and Tear wrote:Have you considered breaking this up into multiple pages?
This is a good idea, so I've gone and split it into 3 files, making it much easier to read.
User avatar
Player701
 
 
Posts: 1651
Joined: Wed May 13, 2009 3:15 am
Graphics Processor: nVidia with Vulkan support

Re: ZScript Language Documentation (WIP)

Post by Player701 »

ZScript Language Documentation wrote:
  • OnDestroy
Called when the object is collected by the garbage collector. Not deterministic.
This probably needs to be clarified. According to the source code, an object is first destroyed, and then GC'd. OnDestroy is called during the former, not the latter. Non-deterministic behavior is possible only for non-Thinker objects, since thinkers are normally destroyed outside of the GC routine. There is even a comment about this in dobjgc.cpp. If OnDestroy acted non-deterministically for thinkers (and hence actors), it would quickly lead to desyncs in network games.
User avatar
Marrub
 
 
Posts: 1198
Joined: Tue Feb 26, 2013 2:48 pm
Preferred Pronouns: No Preference
Operating System Version (Optional): Arch Linux
Graphics Processor: ATI/AMD with Vulkan/Metal Support

Re: ZScript Language Documentation (WIP)

Post by Marrub »

Player701 wrote:
ZScript Language Documentation wrote:
  • OnDestroy
Called when the object is collected by the garbage collector. Not deterministic.
This probably needs to be clarified. According to the source code, an object is first destroyed, and then GC'd. OnDestroy is called during the former, not the latter. Non-deterministic behavior is possible only for non-Thinker objects, since thinkers are normally destroyed outside of the GC routine. There is even a comment about this in dobjgc.cpp. If OnDestroy acted non-deterministically for thinkers (and hence actors), it would quickly lead to desyncs in network games.
Thanks, the description has been expanded.
User avatar
Marrub
 
 
Posts: 1198
Joined: Tue Feb 26, 2013 2:48 pm
Preferred Pronouns: No Preference
Operating System Version (Optional): Arch Linux
Graphics Processor: ATI/AMD with Vulkan/Metal Support

Re: ZScript Language Documentation (WIP)

Post by Marrub »

Added minor missing language information, added FOptionMenuSettings and SecSpecial, finished documenting State, clarified some text under Concepts, and added a new "Entry Points" section for direct interactions between ZScript and the engine (i.e. actor replacements and MAPINFO/GameInfo.)

EDIT: Moved to a GitHub repository and added more concise language documentation, among other things. Changes are now logged in the commit messages.
User avatar
Player701
 
 
Posts: 1651
Joined: Wed May 13, 2009 3:15 am
Graphics Processor: nVidia with Vulkan support

Re: ZScript Language Documentation (WIP)

Post by Player701 »

The description of GetDefaultByType should probably be expanded with a warning: instances returned by this function cannot be serialized in saved games. (See this discussion, apparently the current behavior can't be changed at the moment)
User avatar
Marrub
 
 
Posts: 1198
Joined: Tue Feb 26, 2013 2:48 pm
Preferred Pronouns: No Preference
Operating System Version (Optional): Arch Linux
Graphics Processor: ATI/AMD with Vulkan/Metal Support

Re: ZScript Language Documentation (WIP)

Post by Marrub »

Player701 wrote:The description of GetDefaultByType should probably be expanded with a warning: instances returned by this function cannot be serialized in saved games. (See this discussion, apparently the current behavior can't be changed at the moment)
Thanks, rewrote the description. Apparently I wrote the description before I knew what PClass was, so now it actually tells you properly what it does.
User avatar
Player701
 
 
Posts: 1651
Joined: Wed May 13, 2009 3:15 am
Graphics Processor: nVidia with Vulkan support

Re: ZScript Language Documentation (WIP)

Post by Player701 »

Marrub wrote:Thanks, rewrote the description. Apparently I wrote the description before I knew what PClass was, so now it actually tells you properly what it does.
Thank you too. A minor correction, though: right now it is not required to mark the returned value as transient, though I wish it were. Apparently, it is not that easy to implement because it's difficult to tell what objects are supposed to be serialized (and would thus need to enforce this rule) and what aren't. I would definitely recommend marking these fields transient, though - makes the code easier to understand.

Return to “Scripting”