Warpball templates

Warpball templates #

Warpball is a set of visual and sound effects usually played when the alien monster spawns (gets teleported plot-wise) via the monstermaker entity. In original Half-Life such effect usually was implemented as a combination of env_sprite, env_beam and a couple of ambient_generic entities. Of course such approach is tedious and is prone to errors as a level designer needs to create bunch of entities for every spawn.

Featureful SDK aims at making the level designer life easier and provides ways of defining the warpball effect once. Then monstermakers can refer to the template and reproduce the effect defined by the template when they spawn a monster.

Defining warpball templates #

Featureful SDK provides two ways to define warpball templates:

  1. Via the templates/warpball.json file (global for the mod, preferred).
  2. Via the env_warpball entity placed on the map (local for the map, deprecated).

The sample mod provides quite elaborate example of the templates/warpball.json file which you can use in your mod without modifications or adjust for your own needs. Using this method is preferred over the env_warpball as it doesn’t require the modifications to the map if the level designer decides to change the template parameters. Also, the definitions are global for the mod, so the level designer doesn’t need to put env_warpball on every map (and thus is free of burden of ensuring that every env_warpball on all maps is up to date with a current vision) which ensures that the played effect is universal for the mod.

Using warpball templates #

To use a warpball template with a monstermaker the level designer should set a template name in the Warpball template parameter of the monstermaker entity. The template name is either from templates/warpball.json or the targetname of the env_warpball entity on the map. The templates from the file have a priority over the env_warpball entities with the same name.

For a quick start:

  1. Copy the templates subdirectory from the sample mod to your mod directory.
  2. Set Warpball template parameter of the monstermaker to auto.
  3. Upon triggering the monstermaker, the warpball effect will be played depending on the type of the monster it spawns.

Format of templates/warpball.json #

The root document has two properties: entity_mappings and templates.

Entity mappings #

The entity_mappings object defines named mappings between the monster classnames and the preferred warpball templates. The mapping name acts as a template name itself.

Example:

{
//...
  "entity_mappings": {
    "auto": {
      "monster_alien_slave": "xen",
      "monster_alien_grunt": "xen_big",
      "monster_headcrab": "xen_small",
      "default": "xen"
    }
  }
//...
}

The monstermaker which has auto as a value for the Warpball template parameter will choose the template depending on the monster’s classname it’s going to spawn. In this particular example the monstermakers that spawn alien grunts will use a xen_big warpball template and the monstermakers that spawn headcrabs will use a xen_small template. The default property allows to define which template should be used if the monster’s classname is not in the list.

Entity mappings allow a level designer to care less about the template they want to choose for the particular monster as they can just rely on one mapping, e.g. auto.

The auto is not some hardcoded property. The user can give it a different name or define other entity mappings.

Templates #

The templates object defines a list of named warpball templates with all of their parameters such as sprites, sounds, dynamic light, shake, etc.

Example of the named template:

{
//...
    "xen": {
      "sprite1": {
        "sprite": "sprites/fexplo1.spr",
        "alpha": 255,
        "color": [77, 210, 130],
        "framerate": 12,
        "scale": 1.0
      },
      "sprite2": {
        "sprite": "sprites/xflare1.spr",
        "alpha": 255,
        "color": [77, 210, 130],
        "framerate": 12,
        "scale": 1.0
      },
      "sound1": {
        "sound": "debris/beamstart2.wav",
        "volume": 1,
        "pitch": 100,
        "attenuation": 0.8
      },
      "sound2": {
        "sound2": "debris/beamstart7.wav",
        "volume": 1.0,
        "pitch": 100,
        "attenuation": 0.8
      },
      "beam": {
        "sprite": "sprites/lgtning.spr",
        "color": [20, 243, 20],
        "alpha": 220,
        "width": 30,
        "noise": 65,
        "life": [0.5, 1.6]
      },
      "beam_radius": 192,
      "beam_count": [10, 20],
      "light": {
        "color": [77, 210, 130],
        "radius": 200
      },
      "shake": null,
      "spawn_delay": 0.4
    }
//...
}

sprites #

"sprite1" and "sprite2" objects define sprites to be played. Each can define:

  • "sprite" - path to the sprite. Default value is "sprites/fexplo1.spr" for "sprite1" and "sprites/xflare1.spr" for "sprite2".
  • "color" - sprite color. Default color is [77, 210, 130].
  • "alpha" - sprite opacity. Default value is 255.
  • "scale" - the sprite scale. Default value is 1.0.
  • "framerate" - the animation speed (frames per second). Default value is 12.0.

"sprite1" and "sprite2" can be set to null to disable sprite effects.

sounds #

"sound1" and "sound2" objects define sounds to be played. Each can define:

  • "sound" - path to the sound in sound directory. Default value is "debris/beamstart2.wav" for "sound1" and "debris/beamstart7.wav" for "sound2".
  • "volume" - the maximum is 1.0. Can be a range (the volume will be randomized on each play). Default value is 1.0.
  • "pitch" - the norm is 100 (the maximum is 255). Can be an integer range (the pitch will be randomized on each play). Default value is 100.
  • "attenuation" - how the sound’s volume decreases depending on the distance. 0.8 means large radius, 1.25 means medium radius. Default value is 0.8. The following string aliases are supported as well instead of numeric values: "norm" (large radius), "static" (medium radius), "idle" (small radius), "none" (play everywhere).

"sound1" and "sound2" can be set to null to disable sprite effects.

beam #

"beam" defines the parameters of beams to be played.

  • "sprite" - path to the sprite used as a beam texture. Default value is "sprites/lgtning.spr".
  • "color" - beam color. Default color is [20, 243, 20].
  • "alpha" - beam opacity. Default value is 220.
  • "width" - how wide the beam is. The max is 255. Default value is 30.
  • "noise" - the amplitude of the beam. The max is 255. Default value is 65.
  • "life" - for how long (in seconds) the beams will render. Range. Default range is [0.5, 1.6].

Set "beam" to null to disable beam effect.

beam_radius #

"beam_radius" - the maximum length of the beams. When the effect is played beams will try to reach the surrounding walls. Default value is 192.

beam_count #

"beam_count" - the number of the beams to spawn. Integer range. Default range is [10, 20].

light #

"light" defines parameters for the dynamic light. By default a warpball template doesn’t use dynamic light.

  • "color" - light color. This is required (but can be inherited from other template).
  • "radius" - light radius in units (default provided or inherited if not explicitly set)
  • "life" - duration in seconds (default provided or inherited if not explicitly set)

Set "light" to null to disable dynamic light effect inherited from the parent warpball template.

shake #

"shake" defines the shake effect.

  • "radius" - an integer number. Radius in units.
  • "duration" (must be higher than 0 to enable the shake).
  • "frequency" - a number in range from 0 to 255.
  • "amplitude" - an integer number in range from 0 to 16.

Refer to env_shake documentation to understand the meaning of these parameters.

By default a warpball template doesn’t have shake.

Set "shake" to null to disable shake effect inherited from the parent warpball template.

ai_sound #

"ai_sound" defines the optional AI sound produced when the effect starts (e.g. to attract other monsters’ attention).

  • "type" - the type of AI sound. Possible values are "combat" and "danger".
  • "duration" - duration of sound. Default value is 0.3.
  • "radius" - the effective radius. Default value is 192.

By default a warpball template doesn’t make AI sounds.

Set "ai_sound" to null to disable AI sound inherited from the parent warpball template.

spawn_delay #

"spawn_delay" - the delay (in seconds) between the start of the warpball effect and the spawn of the monster. This is not a part of the visual or sound effects, but it’s convenient to define it in the template, so all monstermakers that use the warpball template will have this delay before monster spawn. The monstermaker instance can redefine the delay by providing the Delay before spawn parameter.

The spawn delay is an important for the gameplay: the player will have some time to react to the incoming portal before the actual monster appears. The numbers between 0.3 and 0.5 are good. While the delay is in effect the invisible hull is created to prevent other monsters and players from blocking the monster’s spawn (note that other entities like doors and trains still can get in the way).

Default value is 0.0 (no delay).

position #

"position" - the object that defines the custom position of the warpball effect relative to the monster’s origin. Currently has only one parameter:

  • "vertical_shift" - the distance (in units) between the monster’s origin (usually at the monster’s feet) and the center of the warpball effect.

If "position" is not defined the center of the monster’s body is used.

Template inheritance #

The warpball template can inherit values of another template via inherits property. This can save time when defining new templates.

Example:

{
//...
    "xen_big": {
      "inherits": "xen",
      "sprite1": {
        "scale": 1.25
      },
      "sprite2": {
        "scale": 1.25
      },
      "beam_radius": 256,
      "shake": {
        "radius": 192,
        "duration": 1.0,
        "frequency": 160,
        "amplitude": 6
      },
      "sound1": {
        "attenuation": 0.6
      },
      "sound2": {
        "attenuation": 0.6
      },
      "position": {
        "vertical_shift": 42
      }
    }
//...
}

The template “xen_big” copies all parameters from “xen” tempalte and overrides the scale of the sprites, the attenuation of the sounds, the beam radius and also adds a shake effect.

Use inherits property to specify another template as a base.