ZScript Language Documentation (WIP)

[Mikk-]

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

[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.

[Major Cooke]

Maps? Huh, what will those do?

[Player701]

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.

[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.

[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.

[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.)

[Rip and Tear]

Have you considered breaking this up into multiple pages?

[Marrub]

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.

[Player701]

• 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.

[Marrub]

• 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.

[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.

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

[Marrub]

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.

[Player701]

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.