ZScript Language Documentation (WIP)

Ask about ACS, DECORATE, ZScript, or any other scripting questions here!
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.

Re: ZScript Language Documentation (WIP)

Postby Mikk- » Sat Mar 31, 2018 7:38 pm

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
Mikk-
yooooooooooo
 
Joined: 30 Jun 2009
Location: Somewhere off Kanagawa
Discord: Mikk0451#3922

Re: ZScript Language Documentation (WIP)

Postby Marrub » Fri Oct 12, 2018 6:54 pm

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
Marrub
Xevv Va Rkvyr
 
 
 
Joined: 26 Feb 2013
Discord: Marrub#5455
Twitch ID: marrubdaskuleion

Re: ZScript Language Documentation (WIP)

Postby Major Cooke » Fri Nov 09, 2018 4:54 pm

Maps? Huh, what will those do?
User avatar
Major Cooke
The road to Hell is paved in the carrion she leaves behind.
 
Joined: 28 Jan 2007
Discord: Major Cooke#0846

Re: ZScript Language Documentation (WIP)

Postby Player701 » Fri Nov 09, 2018 5:31 pm

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
Player701
You are now breathing manually.
 
Joined: 13 May 2009
Location: Russian Federation
Discord: Player701#8214

Re: ZScript Language Documentation (WIP)

Postby Graf Zahl » Sun Nov 11, 2018 11:28 am

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
Graf Zahl
Lead GZDoom Developer
 
Joined: 19 Jul 2003
Location: Germany

Re: ZScript Language Documentation (WIP)

Postby Marrub » Wed Nov 14, 2018 4:25 pm

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
Xevv Va Rkvyr
 
 
 
Joined: 26 Feb 2013
Discord: Marrub#5455
Twitch ID: marrubdaskuleion

Re: ZScript Language Documentation (WIP)

Postby Marrub » Sat Nov 17, 2018 4:37 pm

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
Marrub
Xevv Va Rkvyr
 
 
 
Joined: 26 Feb 2013
Discord: Marrub#5455
Twitch ID: marrubdaskuleion

Re: ZScript Language Documentation (WIP)

Postby Rip and Tear » Sat Nov 17, 2018 7:05 pm

Have you considered breaking this up into multiple pages?
User avatar
Rip and Tear
 
Joined: 02 May 2017

Re: ZScript Language Documentation (WIP)

Postby Marrub » Sun Nov 18, 2018 11:49 am

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
Marrub
Xevv Va Rkvyr
 
 
 
Joined: 26 Feb 2013
Discord: Marrub#5455
Twitch ID: marrubdaskuleion

Re: ZScript Language Documentation (WIP)

Postby Player701 » Tue Nov 20, 2018 3:50 pm

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
Player701
You are now breathing manually.
 
Joined: 13 May 2009
Location: Russian Federation
Discord: Player701#8214

Re: ZScript Language Documentation (WIP)

Postby Marrub » Tue Nov 20, 2018 6:15 pm

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
Xevv Va Rkvyr
 
 
 
Joined: 26 Feb 2013
Discord: Marrub#5455
Twitch ID: marrubdaskuleion

Re: ZScript Language Documentation (WIP)

Postby Marrub » Fri Nov 23, 2018 7:36 pm

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
Marrub
Xevv Va Rkvyr
 
 
 
Joined: 26 Feb 2013
Discord: Marrub#5455
Twitch ID: marrubdaskuleion

Re: ZScript Language Documentation (WIP)

Postby Player701 » Sat Nov 24, 2018 1:52 pm

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
Player701
You are now breathing manually.
 
Joined: 13 May 2009
Location: Russian Federation
Discord: Player701#8214

Re: ZScript Language Documentation (WIP)

Postby Marrub » Sat Nov 24, 2018 4:30 pm

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
Marrub
Xevv Va Rkvyr
 
 
 
Joined: 26 Feb 2013
Discord: Marrub#5455
Twitch ID: marrubdaskuleion

Re: ZScript Language Documentation (WIP)

Postby Player701 » Sun Nov 25, 2018 5:56 am

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.
User avatar
Player701
You are now breathing manually.
 
Joined: 13 May 2009
Location: Russian Federation
Discord: Player701#8214

PreviousNext

Return to Scripting

Who is online

Users browsing this forum: Tango and 2 guests