Wiki

Clone wiki

lzwolf / Home

Welcome

Welcome to the LZWolf project! This is a fork of Blzut3's ecwolf, development version 1.3.99999.

This project provides additional features not necessarily present in the official ECWolf project. Be warned the decorate API or other feature implementations in LZWolf may not conform or be consistent with ZDoom or the official ECWolf. Please do not send feature requests to the ECWolf maintainer(s) based on features and implementations present in LZWolf.

This page should be read in conjunction with Blzut3's ecwolf wiki.

Decorate

Action Function Namespaces

The LZWolf engine provides multiple implementations of some action functions, particularly A_Explode. A_Explode has two implementations in LZWolf. One version will adhere to the official ECWolf API where damage types are not accepted. The other version will include an extra damage type argument.

A mod may choose which version of an action function to invoke using a resolution "::". As an example consider this fragment:

    Spawn:
        GREN E 0 bright lz::A_Explode(random(50, 177), 128, 0, 0, 0, "FireDamage")
        GREN E 0 bright A_Stop
        stop

The extra argument "FireDamage" was supplied to the action function and lz:: was used to explicitly call the version of A_Explode which expects it. To call the default implementation the "::" operator would be left out.

As an added convenience LZWolf provides an actor property called actionns. The base package in LZWolf sets this property as follows:

actor Actor native
{
    actionns "lz"
    damage 0
    radius 20
    ...
}

As a result, all mods running on LZWolf will use the "lz" version of A_Explode. However it is possible to override this property value in specific classes to go back to the official ECWolf version of A_Explode.

Constants

Constants are available and can be used in place of integer parameters in action functions.

DIR - Directions

DIR Value
DIR_EAST 0
DIR_NORTHEAST 1
DIR_NORTH 2
DIR_NORTHWEST 3
DIR_WEST 4
DIR_SOUTHWEST 5
DIR_SOUTH 6
DIR_SOUTHEAST 7
DIR_NODIR 8

CHAN - Sound Channels

Sound channels are specified using these predefined constants.

CHAN Channels Purpose
CHAN_AUTO 2+ searches for a channel not in use in "other channels"
CHAN_WEAPON 0 is for weapons
CHAN_VOICE 1 is for oof, sight, or other voice sounds
CHAN_ITEM 2+ is for small things and item pickup
CHAN_BODY 2+ is for generic body sounds

In LZWolf the three values CHAN_BODY, CHAN_ITEM and CHAN_AUTO all perform the same function.

ATTN - Attenuation

Attenuation is specified directly in decimal or via these predefined constants.

ATTN Value
ATTN_NONE 0.0
ATTN_NORM 1.0
ATTN_IDLE 1.001
ATTN_STATIC 3.0
  • Special handling of attenuation flags in LZWolf:
    • ATTN_NONE - full volume the entire level; left/right ear approximation is also disabled
    • ATTN_NORM - vanilla
    • ATTN_IDLE - vanilla; extra diminishing with distance
    • ATTN_STATIC - vanilla; extra 3x faster diminishing with distance

Action flags

Actor flags can be enabled and disabled using existing API A_ChangeFlag.

DRAWRELATIVE

An actor with FL_DRAWRELATIVE enabled is positioned using view centered coordinates, not absolute world coordinates like most actors, and causes the actor to draw in front of the camera at all times. While this flag is enabled, the player cannot move/turn away from the actor to put it out of view. However the actor may change its position (in view centered coordinates) to leave the player's view if it so chooses.

STATUSBAR

Enable FL_STATUSBAR to cause an actor to be rendered into the status bar. Use A_SetPicXY to control its precise location on the screen.

Action Functions

A_BeginHeightAnim

A_BeginHeightAnim (float newheight, int period)

Starts an animation on the player's view height. The animation will smoothly interpolate the player's view height from its current value to the value provided (newheight) using a sinusoidal function over the given time period. The period is expressed in tics or in 1/70'ths of a second.

A_EnableHaloLight

A_EnableHaloLight [(int id, bool enabled)]

Enables or disables the given Halo light for this actor as specified by the ID parameter.

See Halo light actor property for more on how to add your own Halo light definitions.

A_EnableZoneLight

A_EnableZoneLight [(int id, bool enabled)]

Enables or disables the given Zone light for this actor as specified by the ID parameter.

See Zone light actor property for more on how to add your own Zone light definitions.

lz::A_Explode

lz::A_Explode [(int damage[, int radius[, int flags[, bool alert[, int fulldamageradius[, string damagetype = ""]]]]])]

Deals damage to all actors within a given radius of the caller. Damage drops off linearly after the fulldamageradius is passed. The only valid flag is XF_HURTSOURCE which is on by default and allows the explosion to damage the source (the source isn't the same as the caller). For example a missile without this flag will not damage the actor that fired the missile. Enabling alert will allow the explosion to wake up nearby enemies. Set damagetype to inflict actors with a specific damage type.

See Damage type actor class for more on how to add your own damage types.

A_InertMove

A_InertMove(float move, int dir)

The actor will move in a specified direction, by the specified distance. The distance is expressed in tile coordinates as a decimal number. The direction can be expressed either as a value between 0 and 8 or in string form.

A_PlaySound

  • A_PlaySound (string sound [, int slot [, float volume [, bool looping [, float attenuation]]]])
    • Plays the specified sound.
    • sound - the desired sound to play.
    • slot - the sound slot used for the sound. Default is CHAN_BODY. See Sound Channel Constants for specific rules.
    • volume - the volume of the sound. Default is 1.0.
    • looping - if true, the sounds loops. Looping sounds can be stopped by using A_StopSound. Default is false.
    • attenuation - this is a positive value that specifies how quickly the sound fades with distance from its source. The higher the value the quicker it fades out. Vanilla falloff and left/right ear approximation is enabled by default (ATTN_NORM). See Attenuation Constants for specific rules.

A_RadiusWake

A_RadiusWake[(int radius)]

Looks for a shootable actor in the near vicinity, no further than the specified radius. If no radius is supplied it defaults to 128 which corresponds to one tile.

If found the Radius Wake state will be triggered.

A_ResetPosition

A_ResetPosition[(float x, float y)]

Sets the position of an actor to the given location expressed in global coordinates. If no parameters are provided, the actor will be relocated to the origin (0,0).

A_SelectWeapon

A_SelectWeapon[(int slot)]

Makes the weapon in the given slot the active one as if the player activated it using the appropriate key. Bring up the Knife by passing slot 1, the Pistol by passing slot 2, and so on.

A_SetPicXY

A_SetPicXY[(int picX, int picY)]

An actor with the STATUSBAR flag enabled can call this function to control where it is rendered on the screen. The provided coordinates will correspond to the lower left corner of the rendered texture.

The top left screen coordinate is (0,0). The bottom right is (320,200).

This API need only be called once, probably within its Spawn state, to specify where in the status bar it should be rendered.

A_StopSound

A_StopSound[(int slot)]

Stops the sound currently playing on the specified channel for the calling actor. The function can only stop sounds that have an actor source and were played with looping enabled.

In LZWolf the slot argument to A_StopSound is currently ignored.

Actor Properties

Actor damage resistance

You may reduce the effect of certain types of damage by adding the damageresistance actor property. The first parameter of this property specifies a damage type, the second a percentage. As an example the line below gives an actor 50% resistance to fire damage.

damageresistance "FireDamage", 50

Weapon damage type

Weapons may be assigned a predefined damage type. The damage type affects:

  1. The amount of damage dealt by a weapon.
  2. The death state triggered by the weapon when it kills an actor.
  3. The pain state triggered by the weapon when it damages an actor.

As an example, the actor property below will assign the "FireDamage" damage type to a weapon.

weapon.damagetype "FireDamage"

See Damage type actor class for more on how to add your own damage types.

Enemy faction

You may assign an actor one or more enemy factions.

enemyfaction "Nazis", "AlliedForces"

If the actor is a monster and at least one enemy faction is provided, it will only target actors belonging to one of those enemy factions. It is acceptable for an actor to an enemy of its own faction but it will not target itself.

Faction

An actor may be assigned to a particular faction. As an example, to make an actor a Nazi the following property setting is used.

faction "Nazis"

See Faction actor class for more on how to add your own factions.

FilterposThrust actor property

filterposthrust <axis>,<src>

The FilterposThrust property causes an actor to move along an axis based upon a source of thrust.

//                 axis      src
filterposthrust       0,       0
Parameter Value Meaning
axis 0 X-axis
axis 1 Y-axis
axis 2 Z-axis
src 0 Player forward thrust
src 1 Player sideward thrust
src 2 Player rotation in fine-angles

Filterpos properties will be executed in the order given.

FilterposWave actor property

filterposwave <axis>,<amplitude>,<period>,<usesine>

The FilterposWave property causes an actor's position to move in a wave pattern (either sine or cosine) along an axis.

The following property will cause an actor's X-position to move smoothly back and forth one tile in a sine-wave. The wave cycle is set to complete in 3 seconds.

//               axis    amplitude     period    usesine
filterposwave       0,         1.0,       3.0,         1
Parameter Meaning
axis 0, 1 or 2 for the X-, Y- or Z-axis respectively
amplitude In global coordinates the height of wave
period The time duration in seconds of the wave
usesine 0 or 1 for a cosine or sine wave, respectively

Filterpos properties will be executed in the order given.

FilterposWrap actor property

filterposwrap <x1>,<x2>,<axis>

The FilterposWrap property causes an actor's position to rollover within the coordinates specified.

The following property will cause an actor's position along the X axis to return to X=3 from X=0 and vice versa, as it moves.

//             x1   x2  axis
filterposwrap 0.0, 3.0,    0
Parameter Meaning
x1,x2 The limits against which to apply this property
axis 0, 1 or 2 for the X-, Y- or Z-axis respectively

Filterpos properties will be executed in the order given.

Halo light actor property

halolight <id>,<radius>,<light>[,<littype>]

The Halo light effect emits a round halo light pattern centered on the actor.

You may define up to 31 different Halo lights for an actor. In this example we define two Halo lights for a single actor. Each can be turned on or off using A_EnableHaloLight.

halolight 0, 1.0, 5
halolight 1, 0.5, 10
Parameter Meaning
id A unique integer starting from zero; necessary for A_EnableHaloLight
radius The Radius in tiles which is expressed as a decimal number
light The amount of light emitted; a value between -20 and 20
littype The string name of the Lit type

Lit filter actor property

An actor with the litfilter property set to a valid Lit type will only draw if the area beneath it is lit by a light source and only if that light source is linked to the same Lit type. A Halo light is an example of one such light source.

No XDeath actor property

You may disable XDeath for certain types of damage within the Damage type actor class.

actor RifleDamage : Damage
{
    damage.noxdeath 1
}

Single spawn actor property

An actor with the singlespawn property set to 1 will ensure only a single instance of this actor will spawn in a level. Even if A_SpawnItem is called more than once to spawn the actor, it will still only spawn once.

singlespawn 1

Zone light actor property

zonelight <id>,<light>

The Zone light effect evenly fills the room with a given amount of light.

You may define up to 31 different Zone lights for an actor. In this example we define two Zone lights for a single actor. Each can be turned on or off using A_EnableZoneLight.

zonelight 0, 5
zonelight 1, 10
Parameter Meaning
id A unique integer starting from zero; necessary for A_EnableZoneLight
light The amount of light emitted; a value between -20 and 20

Actor States

Damage Death states

An actor may define death states for different damage types. If this is not provided LZWolf will trigger the existing Death or XDeath state.

Place the name of the damage type after the state name with an underscore separating them. Here is an example:

Death_FireDamage:
    GARD K 7.5 A_Fall
    //GARD L 7.5 A_Scream
    GARD M 7.5
    GARD N -1
    stop

See Damage type actor class for more on how to add your own damage types.

Damage Pain states

An actor may define pain states for different damage types. If this is not provided LZWolf will trigger the existing Pain.

Place the name of the damage type after the state name with an underscore separating them. Here is an example:

Pain_FireDamage:
    GARD N 5 A_JumpIf(health & 1, 1)
    goto See
    GARD N 5
    goto See

See Damage type actor class for more on how to add your own damage types.

Radius Wake state

An actor using the A_RadiusWake action will transition to the RadiusWake state.

Actor Classes

Damage type actor class

This actor defines damage types. Any actor inheriting directly from this class is a new damage type.

actor Damage : Inventory native
{
    damage.noxdeath 0
}

Here is an example of how to inherit from this class to define a new damage type.

actor FireDamage : Damage
{
}

For convenience, the LZWolf base pk3 defines the FireDamage actor class in wolfdamage.txt.

Faction actor class

This actor defines factions. Any actor inheriting directly from this class is a new faction.

actor Faction : Inventory native
{
}

Here is an example of how to inherit from this class to define a new faction.

actor Zombies : Faction
{
}

For convenience, the LZWolf base pk3 defines two commonly used factions in wolffaction.txt.

actor Nazis : Faction
{
}

actor AlliedForces : Faction
{
}

Lit type actor class

The native Lit class must be inherited from to define a new Lit type.

actor DustLit : Lit
{
}

DustCeilingLight actor class

The DustCeilingLight actor is available in LZWolf.

actor DustCeilingLight
{
    // (details not shown)
}

A game's decorate may define a new actor inheriting from DustCeilingLight to give all CeilingLight actors two effects:

  1. A round halo light pattern on the ground and ceiling.
  2. A dust cloud effect inside the lit region beneath the ceiling light.

As an example, a game called "Schabbs Must Die" could enable those two effects by defining an actor such as the one below:

actor SchabbsCeilingLight : DustCeilingLight replaces CeilingLight
{
}

MapInfo

Parallax sky textures

To enable parallax sky for a map you need to add a property called parallaxsky and specify for it one or more parallax sky texture names. It is customary to provide exactly 16 textures for parallax sky. However ECWolf allows for any number of parallax sky texture tiles.

The Decorate for Wolf3d "MAP01" in mapinfo/wolf3d.txt might appear as follows when parallax sky is present:

map "MAP01"
{
    next = "MAP02"
    secretnext = "MAP10"
    floornumber = 1
    par = 90
    music = "GETTHEM"
    cluster = 1
    parallaxsky = "GSTONEA1", "GSTONEA2", "GSTONEB1", "GSTONEB2", "GSTFLAG1", "GSTFLAG2", "GSTHTLR1", "GSTHTLR2", "BSTCELA1", "BSTCELA2", "GSTEAGL1", "GSTEAGL2", "BSTCELB1", "BSTCELB2", "BSTONEA1", "BSTONEA2"
}

Semi-transparent ceiling support for parallax sky

Semi-transparent ceiling texture support must be explicitly enabled in gameinfo. The transparent key can be set using the parallaxskyceilcolor parameter in gameinfo. Set the red component to zero, the green component to 1 and blue component to the transparent color key. In the example below the value 00 is used as the transparent color key.

This setting will only take effect on maps with parallax sky.

gameinfo
{
    signon = "WLFSGNON"
    // ...
    quitmessages = "$ENDSTR01", "$ENDSTR02", "$ENDSTR03", "$ENDSTR04", "$ENDSTR05", "$ENDSTR06", "$ENDSTR07", "$ENDSTR08", "$ENDSTR09"
    parallaxskyceilcolor = "00 01 00"
}

Parallax sky below horizon

To enable parallax sky below the horizon, set the numparallaxtiles property to half the number of parallax sky textures set in parallaxsky. For example if there are 16 parallax sky textures then set the number of tiles to 8:

    parallaxsky = "GSTONEA1", "GSTONEA2", "GSTONEB1", "GSTONEB2", "GSTFLAG1", "GSTFLAG2", "GSTHTLR1", "GSTHTLR2", "BSTCELA1", "BSTCELA2", "GSTEAGL1", "GSTEAGL2", "BSTCELB1", "BSTCELB2", "BSTONEA1", "BSTONEA2"
    numparallaxtiles = 8

In xlat, a tile with the showsky property set to true will not draw over parallax sky. As an example, this entry in xlat will allow sky to draw over tile 5:

tile 5
{   
    texturenorth = "BSTCELA1";
    texturesouth = "BSTCELA1"; 
    textureeast = "BSTCELA2";
    texturewest = "BSTCELA2";
    showsky = true;
}   

Atmos

You may enable atmos effects in mapinfo. The supported atmos effects from SDL are:

  • StarSky
  • Rain
  • Snow

One new atmos effect is available exclusively in LZWolf:

  • HighQualityStarSky; this effect:
    • Is expected to look nicer than StarSky at resolutions above 320x200,
    • Renders stars using a diamond pattern,
    • Supports a bigger moon graphic:
      • 30x30 pixels to be exact (the moon rendered in StarSky is only 10x10)
      • A pk3 can override the moon graphic by adding the FULLMOON lump to its graphics folder
      • The base lzwolf.pk3 ships with a default copy of FULLMOON
    • Allows the moon position to be controlled from mapinfo.
      • Just set atmoshqstarsky to a value between 1 and 399!

As an example, this is how "MAP01" can enable StarSky in mapinfo:

map "MAP01"
{
    next = "MAP02"
    secretnext = "MAP10"
    floornumber = 1
    par = 90
    music = "GETTHEM"
    cluster = 1
    atmosstarsky = 1
    //atmosrain = 1
    //atmossnow = 1
    //atmoshqstarsky = 1
}

You can enable none, one or several atmos types at a time.

Playing an intermission after level complete

Add the property intermission to a map to play an intermission sequence after a level is completed. The regular level statistics intermission screen will be played just prior.

map "MAP01"
{
    next = "MAP02"
    secretnext = "MAP10"
    floornumber = 1
    intermission = "DemoLoop"
}

Action Specials

Change_Music

  • Change_Music( musicid )
    • Activates the specified music track.
    • musicid - A number identifying the music track to play as defined in xlat.

Teleport_Relative

  • Teleport_Relative( tag, angle, flags )
    • Moves activator to a new map spot
    • tag - The tag of the map spot.
    • angle - The new angle after move.
    • flags - A bitwise OR of teleport flags.
      • TELEPORT_NoStop = 1 The half-second pause will not take effect.
      • TELEPORT_NoFog = 2 The fog actor of class "TeleportFog" will not be spawned.
      • TELEPORT_Center = 4 Center onto destination tile.
      • TELEPORT_AbsoluteAngle = 8 Set absolute angle instead of relative.
      • TELEPORT_ActivationAngle = 16 Face the activation point (typically used with AbsoluteAngle).

WDC Format Maps

Info Plane

An additional, fourth, map plane is read by LZWolf called the Info Plane.

Music selection is available along the first map row in the info plane, within the low-byte, provided the high-byte is set to 0xBA.

If the Z-Heights feature flag is enabled in Xlat, the low-byte of the info plane can control the spawn height of an actor, so long as the high-byte is set to 0xB0.

Extra Planes

An extra fifth, sixth and seventh map plane is read from a WDC format map to provide an additional logical plane within LZWolf. The rendered position of a logical plane can be controlled via Plane view depth.

The extra fifth, sixth and seventh map planes are similar to the first three map planes in a WDC format map. They provide an additional set of walls, things and flats, respectively. The same Xlat is used by LZWolf to interpret the extra map planes.

Map translator

This section builds upon the ecwolf map translater. The map translator is also known as Xlat.

Feature flags

Planeviewdepth

  • enable planeviewdepth;
    • Enables view depth for the logical planes generated from a WDC format map. The value of the upper-right tile of the thing plane will be used to determine the viewing height of its constituent logical plane. A value of 64 will place the plane one tile higher from ground level. Values equal to or in excess of 2048 will place the plane below ground level in a similar fashion (i.e., 2048+64 = 2112 will locate the plane one tile below ground level).

Things

Elevator

  • elevator oldnum
    • Creates a Rise of the Triad compatible elevator destination point. Place these between a door and switch (the door and switch must be in line with each other) and the elevator will round robin between the destination points. The elevator starts in the uppermost spot (or leftmost if in same y position).

Teleporter

  • teleporter oldnum
    • Creates a Bi-directional teleporter. Place these into two different spots on the map.

UWMF properties

Some new optional properties are available in the UWMF under LZWolf. The Xlat uses UWMF to specify translations.

Tiles

Showsky

  • showsky = <bool>;
    • A tile with the showsky property set to true will not draw over parallax sky. The drawn ray will stop traversing the world when it reaches a tile with this property set to true. The default value of this property is false.

Blockray

  • blockraynorth = <bool>;
  • blockraysouth = <bool>;
  • blockrayeast = <bool>;
  • blockraywest = <bool>;
    • Allows for a drawn ray to pass through on each side of a tile, if set to false. The default value is true. This option allows one or more sides of a tile to show through to the next tile.

Updated