diff --git a/zscript-doc-1-language.md b/zscript-doc-1-language.md index 34235f0..386ae4c 100644 --- a/zscript-doc-1-language.md +++ b/zscript-doc-1-language.md @@ -325,6 +325,15 @@ Integer types are basic integral numbers. They include: | `int8` | No | 8 | -128 | 127 | | `uint8` | No | 8 | 0 | 255 | +Some types have aliases as well: + +| Name | Aliases | +| ---- | ------- | +| `sbyte` | `int8` | +| `byte` | `uint8` | +| `short` | `int16` | +| `ushort` | `uint16` | + ## Floating-point types Floating-point types hold exponents, generally represented as regular decimal numbers. There are two such types available to ZScript: @@ -795,14 +804,13 @@ Or, if you want multiple members with the same type and flags: [Member declaration flags...] Type name[, name...]; ``` -Note that the types `Font` and `CVar` are unserializable as members and must be marked transient. - ## Member declaration flags | Flag | Description | | ---- | ----------- | | `deprecated("ver")` | If accessed, a script warning will occur on load if the archive version is greater than `ver`. | | `internal` | Member is only writable from the base resource archive (`gzdoom.pk3`.) | +| `latent` | Does nothing. Purpose unknown. | | `meta` | Member is read-only static class data. Only really useful on actors, since these can be set via properties on them. | | `native` | Member is from the engine. Only usable internally. | | `play` | Member has Play scope. | diff --git a/zscript-doc-2-api.md b/zscript-doc-2-api.md index 39a2f4a..763bb22 100644 --- a/zscript-doc-2-api.md +++ b/zscript-doc-2-api.md @@ -36,7 +36,8 @@ Table of Contents * [State](#state) * [StringTable](#stringtable) * [Globals](#globals) - * [DehInfo](#dehinfo) + * [DEHInfo](#dehinfo) + * [FOptionMenuSettings](#foptionmenusettings) * [GameInfoStruct](#gameinfostruct) * [LevelLocals](#levellocals) * [Level Data](#level-data) @@ -410,7 +411,7 @@ readonly array PlayerClasses; readonly array PlayerSkins; readonly array Teams; -play DehInfo DEH; +play DEHInfo DEH; readonly GameInfoStruct GameInfo; readonly FOptionMenuSettings OptionMenuSettings; readonly textureid SkyFlatNum; @@ -443,7 +444,7 @@ readonly Weapon WP_NOCHANGE; - `OptionMenuSettings` - TODO + Defaults for `OptionMenu`s as defined in `MENUDEF`'s `OptionMenuSettings` block and `MAPINFO`/GameInfo. - `SkyFlatNum` @@ -1198,13 +1199,13 @@ struct State readonly uint16 TicRange; readonly uint8 UseFlags; - readonly bool bCANRAISE; - readonly bool bDEHACKED; - readonly uint16 bFAST; - readonly bool bFULLBRIGHT; - readonly bool bNODELAY; - readonly bool bSAMEFRAME; - readonly uint16 bSLOW; + readonly bool bCANRAISE; + readonly bool bDEHACKED; + readonly bool bFAST; + readonly bool bFULLBRIGHT; + readonly bool bNODELAY; + readonly bool bSAMEFRAME; + readonly bool bSLOW; int DistanceTo(State other); bool ValidateSpriteFrame(); @@ -1230,32 +1231,29 @@ struct State The number of game ticks this state lasts. - `Misc1` - - TODO - - `Misc2` - TODO + Primarily used in DeHackEd compatibility. Don't use this. - `TicRange` - TODO + The maximum amount of tics to add for random tic durations, or `0` if the duration is not random. For example, `TNT1 A random(5, 7)` would have a `Tics` value of `5` and a `TicRange` of `2`. - `UseFlags` - TODO + The scope of this state. See *Action Scoping*. Can have any of the `DefaultStateUsage` flags. - `bCANRAISE` - State has the `CANRAISE` flag, allowing `A_VileChase` to target this actor for healing. + State has the `CANRAISE` flag, allowing `A_VileChase` to target this actor for healing without entering an infinitely long state. - `bDEHACKED` - TODO + `true` if the state has been modified by DeHackEd. - `bFAST` - TODO + State has the `FAST` flag, halving the duration when fast monsters is enabled. - `bFULLBRIGHT` @@ -1267,23 +1265,23 @@ struct State - `bSAMEFRAME` - TODO + `true` if the state's frame is to be kept from the last frame used, i.e., is `#`. - `bSLOW` - TODO + State has the `SLOW` flag, doubling the duration when slow monsters is enabled. - `DistanceTo` - TODO + Returns the offset between this state and `other` in the global frame table. Only works if both states are owned by the same actor. - `ValidateSpriteFrame` - TODO + Returns `true` if the sprite frame actually exists. - `GetSpriteTexture` - TODO + Returns the texture, if the texture should be flipped horizontally, and scaling of this state's sprite. Scaling will return `scale` unless `skin` is nonzero. `skin` determines the player skin used. ### StringTable @@ -1303,12 +1301,12 @@ struct StringTable Globals ------- -### DehInfo +### DEHInfo Static DeHackEd information. ``` -struct DehInfo +struct DEHInfo { readonly int BFGCells; readonly int BlueAC; @@ -1343,8 +1341,60 @@ struct DehInfo Overrides generic freezing deaths if not zero, making all actors act as if they had the `NOICEDEATH` flag. +### FOptionMenuSettings + +Defaults for `OptionMenu`s as defined in `MENUDEF`'s `OptionMenuSettings` block and `MAPINFO`/GameInfo. + +``` +struct FOptionMenuSettings +{ + int mTitleColor; + int mFontColor; + int mFontColorValue; + int mFontColorMore; + int mFontColorHeader; + int mFontColorHighlight; + int mFontColorSelection; + int mLineSpacing; +} +``` + +- `mTitleColor` + + TODO + +- `mFontColor` + + TODO + +- `mFontColorValue` + + TODO + +- `mFontColorMore` + + TODO + +- `mFontColorHeader` + + TODO + +- `mFontColorHighlight` + + TODO + +- `mFontColorSelection` + + TODO + +- `mLineSpacing` + + The spacing in virtual pixels between two lines in an `OptionMenu`. + ### GameInfoStruct +Static information from `MAPINFO`/GameInfo. + ``` struct GameInfoStruct { @@ -1977,6 +2027,42 @@ TODO TODO +``` +struct SecSpecial play +{ + int DamageAmount; + int16 DamageInterval; + name DamageType; + int Flags; + int16 LeakyDamage; + int16 Special; +} +``` + +- `DamageAmount` + + TODO + +- `DamageInterval` + + TODO + +- `DamageType` + + TODO + +- `Flags` + + TODO + +- `LeakyDamage` + + TODO + +- `Special` + + TODO + ### SecPlane TODO diff --git a/zscript-doc-3-entry.md b/zscript-doc-3-entry.md new file mode 100644 index 0000000..b08ed0c --- /dev/null +++ b/zscript-doc-3-entry.md @@ -0,0 +1,94 @@ +Table of Contents +================= + + + +* [Entry Points](#entry-points) +* [Actors](#actors) +* [CVARINFO](#cvarinfo) +* [DECALDEF](#decaldef) +* [DECORATE](#decorate) +* [LOCKDEFS](#lockdefs) +* [GLDEFS](#gldefs) +* [KEYCONF](#keyconf) +* [MAPINFO](#mapinfo) +* [MENUDEF](#menudef) +* [TERRAIN](#terrain) + + + +Entry Points +============ + +For backwards compatibility reasons and so as to not bloat the ZScript language itself, many interactions with the engine are not defined in ZScript. This section describes all ZScript interactions with the engine, both inside and outside of ZScript itself. + +Actors +====== + +Actor classes can be replaced by the `replaces` class flag, which during dynamic actor replacement will choose to spawn this class over its replaced actor, unless the replaced actor is later replaced again by another class. Dynamic actor replacement can also be overridden with an event handler's `CheckReplacement` virtual function. + +For example: + +``` +class MyActor : Actor replaces OtherActor {} // OtherActor will be dynamically replaced with MyActor +class MyOtherActor : Actor replaces OtherActor {} // OtherActor will now be replaced with MyOtherActor instead of MyActor +``` + +CVARINFO +======== + +Any CVars declared as a server CVar in `CVARINFO` or by the engine will be accessible as a global variable in ZScript, which has a special type that can be implicitly cast to the type of the CVar. They cannot be set this way, only accessed. + +DECALDEF +======== + +`DECALDEF` can set the decal generator for a specific `Actor` class with the `generator` keyword. An actor can also define its generator and inherited classes' generators with the `Decal` property. + +DECORATE +======== + +TODO: lots of things to note here + +LOCKDEFS +======== + +Key and lock groups in `LOCKDEFS` are defined as groups of `Inventory` or `Key` descendants. + +GLDEFS +====== + +Lights can be associated with `Actor` classes and frames in `GLDEFS`. + +KEYCONF +======= + +TODO: this can be used for custom buttons + +MAPINFO +======= + +In `MAPINFO`, the `GameInfo` block (referred to as `MAPINFO`/GameInfo in this document) the following properties interact directly with ZScript: + +- `EventHandlers` and `AddEventHandlers` override or add to the list of `StaticEventHandler` or `EventHandler` classes registered by the game (as opposed to event handlers registered per-map.) +- `MessageBoxClass` sets the `MessageBoxMenu` class to use for message boxes used by the engine's GUI. +- `PlayerClasses` and `AddPlayerClasses` override or add to the list of `PlayerPawn` classes the game provides. +- `PrecacheClasses` will pre-cache all sprites used by an `Actor` class. Note that this also works for `StateProvider` degenerates like `Weapon`. +- `StatScreen_CoOp` sets the `StatusScreen` class to use for co-op intermission screens. +- `StatScreen_DM` sets the `StatusScreen` class to use for Deathmatch intermission screens. +- `StatScreen_Single` sets the `StatusScreen` class to use for single-player intermission screens. +- `StatusBarClass` sets the status bar class used by the game to the provided `BaseStatusBar` class. +- `WeaponSlot` sets the game's default weapon slots to the provided `Weapon` classes. + +TODO: there are other things here as well, like map event handlers + +MENUDEF +======= + +TODO: this directly uses ZScript classes + +TERRAIN +======= + +The `SmallSplash`, `SplashBase` and `SplashChunk` properties of `Splash` blocks use `Actor`s. + + diff --git a/zscript-doc-9-glossary.md b/zscript-doc-9-glossary.md index 78ff201..6817ab4 100644 --- a/zscript-doc-9-glossary.md +++ b/zscript-doc-9-glossary.md @@ -56,7 +56,7 @@ Concepts Action Scoping -------------- -On classes derived from Actor, states and methods can be scoped to a certain subset of uses. This is mainly to differentiate actions which take place in inventory items and weapons, and actions which take place in the actual game map. The available scopes are: +On classes derived from Actor, states and methods can be scoped to a certain subset of uses. This is mainly to differentiate actions which take place in inventory items and weapons, and actions which take place in the actual game map, for disambiguating the `self` pointer usage. The available scopes are: | Name | Description | | ---- | ----------- | @@ -65,6 +65,15 @@ On classes derived from Actor, states and methods can be scoped to a certain sub | `overlay` | Actions are called from a weapon overlay. | | `weapon` | Actions are called from a weapon. | +These can be defined either in the `states` block header as-is, or in `Actor`'s `DefaultStateUsage` property with the following bit flags: + +| Name | Scope | +| ---- | ----- | +| `SUF_ACTOR` | `actor` | +| `SUF_ITEM` | `item` | +| `SUF_OVERLAY` | `overlay` | +| `SUF_WEAPON` | `weapon` | + Object Scoping -------------- @@ -96,7 +105,7 @@ Sprite A sprite is stored in two numbers: the *sprite ID* (represented by the `spriteid` type or sometimes `int`) and the *sprite frame* (represented by an `int` or `uint8` usually.) The rotation is generally irrelevant as only the `0` (front rotation) frame is used in most contexts. The sprite frame is, unlike the file and state block representations, not a character, but an integer. The number `0` for instance represents the letter `A`, `1` to `B`, etc. -For more information on sprites and rotations, please refer to [the Doom Wiki article on sprites](https://doomwiki.org/wiki/Sprite). +For more information on sprites and rotations, please refer to [the relevant Doom Wiki article](https://doomwiki.org/wiki/Sprite). Game Tick --------- @@ -115,6 +124,8 @@ The Doom engine, as long as it has existed and into every faithful-enough port o All information from the *current* game tick is rendered. This usually happens more often than the game is actually ticked. In ZDoom, Eternity Engine, and some other ports, the information is interpolated between the last and current game tick when there is extra time available to give smoother rendering. +For more information on ticks, please refer to [the relevant Doom Wiki article](https://doomwiki.org/wiki/Tic). + Interpolation -------------