2019-04-02 08:28:16 -07:00
|
|
|
# Entry Points
|
2018-11-23 16:31:53 -08:00
|
|
|
|
|
|
|
<!-- vim-markdown-toc GFM -->
|
|
|
|
|
2019-01-11 06:08:51 -08:00
|
|
|
* [ACS](#acs)
|
2018-11-23 16:31:53 -08:00
|
|
|
* [Actors](#actors)
|
2019-08-14 03:31:41 -07:00
|
|
|
* [Examples: Actor Replacement](#examples-actor-replacement)
|
2019-04-02 05:56:03 -07:00
|
|
|
* [Console Commands](#console-commands)
|
2018-11-23 16:31:53 -08:00
|
|
|
* [CVARINFO](#cvarinfo)
|
|
|
|
* [DECALDEF](#decaldef)
|
|
|
|
* [DECORATE](#decorate)
|
|
|
|
* [LOCKDEFS](#lockdefs)
|
|
|
|
* [GLDEFS](#gldefs)
|
|
|
|
* [KEYCONF](#keyconf)
|
|
|
|
* [MAPINFO](#mapinfo)
|
|
|
|
* [MENUDEF](#menudef)
|
|
|
|
* [TERRAIN](#terrain)
|
|
|
|
|
|
|
|
<!-- vim-markdown-toc -->
|
|
|
|
|
2019-02-02 18:06:35 -08:00
|
|
|
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.
|
2018-11-23 16:31:53 -08:00
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
## ACS
|
2019-01-11 06:08:51 -08:00
|
|
|
|
2019-02-02 18:06:35 -08:00
|
|
|
ACS has several functions for interfacing with ZScript: `SetUserVariable`
|
|
|
|
(callfunc `24`,) `GetUserVariable` (callfunc `25`,) `SetUserArray` (callfunc
|
|
|
|
`28`,) `GetUserArray` (callfunc `29`) and `ScriptCall` (callfunc `210`.)
|
|
|
|
|
|
|
|
`GetUserVariable` may be used to get any `float` or `double` (converted to
|
|
|
|
fixed-point,) `name` or `string` (converted to ACS string,) `bool` (converted
|
|
|
|
to integer,) or integer (of any type including `enum`, converted to a 32-bit
|
|
|
|
signed integer) member of an `Actor`, by TID or by the script activator. The
|
|
|
|
member may be `native`, though it may not be `meta`. If the type is an `array`
|
|
|
|
or fixed-size array, the first element is used.
|
|
|
|
|
|
|
|
`SetUserVariable` follows the same rules as `GetUserVariable`, although
|
|
|
|
`native` variables may not be set. `name` is not handled.
|
|
|
|
|
|
|
|
`SetUserArray` and `GetUserArray` follow the same rules as `SetUserVariable`
|
|
|
|
and `GetUserVariable`, but the index of an array may be used. The variable does
|
|
|
|
not have to be an array if the index is `0`.
|
|
|
|
|
|
|
|
`ScriptCall` may be used to call any `static` function on any class. It cannot
|
|
|
|
call functions on `struct`s. If the first argument of the function is type
|
|
|
|
`Actor`, the activator is passed to this argument (or `null` if there is no
|
|
|
|
activator.) Each argument may be of type `int` (or its aliases,) `color` or
|
|
|
|
`bool` (converted from integer,) `double` (converted from fixed-point,) `name`,
|
|
|
|
`string` or `sound` (converted from ACS string.)
|
|
|
|
|
|
|
|
The function may have default arguments. The function may return zero or more
|
|
|
|
values, although more than one value will be ignored. The returned value may be
|
|
|
|
`int` (or one of its aliases,) `bool` or `color` (converted to integer,)
|
|
|
|
`double` (converted to fixed-point,) `name`, `sound` or `string` (converted to
|
|
|
|
ACS string.) If it is not one of these types, it will be ignored.
|
2019-01-11 06:08:51 -08:00
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
## Actors
|
2018-11-23 16:31:53 -08:00
|
|
|
|
2019-02-02 18:06:35 -08:00
|
|
|
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.
|
2018-11-23 16:31:53 -08:00
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
### Examples: Actor Replacement
|
2018-11-23 16:31:53 -08:00
|
|
|
|
|
|
|
```
|
2019-04-05 16:34:55 -07:00
|
|
|
// Some actor.
|
|
|
|
class OtherActor : Actor
|
|
|
|
{
|
|
|
|
}
|
|
|
|
|
|
|
|
// OtherActor will be dynamically replaced with MyActor.
|
|
|
|
class MyActor : Actor replaces OtherActor
|
|
|
|
{
|
|
|
|
}
|
|
|
|
|
|
|
|
// OtherActor will now be replaced with MyOtherActor instead of MyActor.
|
|
|
|
class MyOtherActor : Actor replaces OtherActor
|
|
|
|
{
|
|
|
|
}
|
2018-11-23 16:31:53 -08:00
|
|
|
```
|
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
## Console Commands
|
2019-04-02 05:56:03 -07:00
|
|
|
|
|
|
|
While ZScript cannot be directly called by console commands, one can use the
|
2019-04-02 10:37:02 -07:00
|
|
|
`event` and `netevent` console commands. `event` will dispatch a non-player
|
|
|
|
network event, and `netevent` will dispatch a network event for the player that
|
|
|
|
ran it.
|
2019-04-02 05:56:03 -07:00
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
## CVARINFO
|
2018-11-23 16:31:53 -08:00
|
|
|
|
2019-02-02 18:06:35 -08:00
|
|
|
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.
|
2018-11-23 16:31:53 -08:00
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
## DECALDEF
|
2018-11-23 16:31:53 -08:00
|
|
|
|
2019-02-02 18:06:35 -08:00
|
|
|
`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.
|
2018-11-23 16:31:53 -08:00
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
## DECORATE
|
2018-11-23 16:31:53 -08:00
|
|
|
|
|
|
|
TODO: lots of things to note here
|
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
## LOCKDEFS
|
2018-11-23 16:31:53 -08:00
|
|
|
|
2019-02-02 18:06:35 -08:00
|
|
|
Key and lock groups in `LOCKDEFS` are defined as groups of `Inventory` or `Key`
|
|
|
|
descendants.
|
2018-11-23 16:31:53 -08:00
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
## GLDEFS
|
2018-11-23 16:31:53 -08:00
|
|
|
|
|
|
|
Lights can be associated with `Actor` classes and frames in `GLDEFS`.
|
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
## KEYCONF
|
2018-11-23 16:31:53 -08:00
|
|
|
|
|
|
|
TODO: this can be used for custom buttons
|
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
## MAPINFO
|
2018-11-23 16:31:53 -08:00
|
|
|
|
2019-02-02 18:06:35 -08:00
|
|
|
In `MAPINFO`, the `GameInfo` block (referred to as `MAPINFO`/GameInfo in this
|
|
|
|
document) the following properties interact directly with ZScript:
|
2018-11-23 16:31:53 -08:00
|
|
|
|
2019-08-14 03:31:41 -07:00
|
|
|
* `EventHandlers` and `AddEventHandlers` override or add to the list of
|
2019-04-05 16:34:55 -07:00
|
|
|
`StaticEventHandler` or `EventHandler` classes registered by the game (as
|
|
|
|
opposed to event handlers registered per-map.)
|
2019-08-14 03:31:41 -07:00
|
|
|
* `MessageBoxClass` sets the `MessageBoxMenu` class to use for message boxes
|
2019-04-05 16:34:55 -07:00
|
|
|
used by the engine's GUI.
|
2019-08-14 03:31:41 -07:00
|
|
|
* `PlayerClasses` and `AddPlayerClasses` override or add to the list of
|
2019-04-05 16:34:55 -07:00
|
|
|
`PlayerPawn` classes the game provides.
|
2019-08-14 03:31:41 -07:00
|
|
|
* `PrecacheClasses` will pre-cache all sprites used by an `Actor` class. Note
|
2019-04-05 16:34:55 -07:00
|
|
|
that this also works for `StateProvider` degenerates like `Weapon`.
|
2019-08-14 03:31:41 -07:00
|
|
|
* `StatScreen_CoOp` sets the `StatusScreen` class to use for co-op intermission
|
2019-04-05 16:34:55 -07:00
|
|
|
screens.
|
2019-08-14 03:31:41 -07:00
|
|
|
* `StatScreen_DM` sets the `StatusScreen` class to use for Deathmatch
|
2019-04-05 16:34:55 -07:00
|
|
|
intermission screens.
|
2019-08-14 03:31:41 -07:00
|
|
|
* `StatScreen_Single` sets the `StatusScreen` class to use for single-player
|
2019-04-05 16:34:55 -07:00
|
|
|
intermission screens.
|
2019-08-14 03:31:41 -07:00
|
|
|
* `StatusBarClass` sets the status bar class used by the game to the provided
|
2019-04-05 16:34:55 -07:00
|
|
|
`BaseStatusBar` class.
|
2019-08-14 03:31:41 -07:00
|
|
|
* `WeaponSlot` sets the game's default weapon slots to the provided `Weapon`
|
2019-04-05 16:34:55 -07:00
|
|
|
classes.
|
2018-11-23 16:31:53 -08:00
|
|
|
|
|
|
|
TODO: there are other things here as well, like map event handlers
|
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
## MENUDEF
|
2018-11-23 16:31:53 -08:00
|
|
|
|
|
|
|
TODO: this directly uses ZScript classes
|
|
|
|
|
2019-04-05 16:34:55 -07:00
|
|
|
## TERRAIN
|
2018-11-23 16:31:53 -08:00
|
|
|
|
2019-02-02 18:06:35 -08:00
|
|
|
The `SmallSplash`, `SplashBase` and `SplashChunk` properties of `Splash` blocks
|
|
|
|
use `Actor`s.
|
2018-11-23 16:31:53 -08:00
|
|
|
|
|
|
|
<!-- EOF -->
|