ACS built-in functions: Difference between revisions

From Eternity Wiki
Jump to navigationJump to search
 
(86 intermediate revisions by 3 users not shown)
Line 1: Line 1:
These ACS functions are imported from ZDoom.
These are predefined ACS functions with no [[parameterized linedef specials|parameterized linedef special]] equivalents, accessible only through ACS scripts.
 
NOTE: most of these functions are meant to be compatible with those from ZDoom. For any ones not yet documented on this wiki, you can check the ZDoom wiki. A few of them may be incompletely implemented in Eternity. Don't hesitate to update the wiki in case of any mistakes.  
==Special TID info==
==Special TID info==
For functions affecting things, some TIDs (thing tags) carry special meaning. TID 0 means the activator, and TIDs -1 ... -4 mean each of the four players in the game -- this in an Eternity extension
For functions affecting things, some TIDs (thing tags) carry special meaning. TID 0 means the activator, and TIDs -1 ... -4 mean each of the four players in the game -- this is an Eternity extension
==Sound and music==
==Data type info==
*void ActivatorSound(str sound, int volume)
You may see specifiers such as ''void'', ''str'', ''int'' and others in ACS function signatures. They act as a guide on what kinds of values are expected, but in ACS there really are only two types: '''str''' and '''int''' (and '''str''' internally is merely a string ID number). Most importantly:  
:Starts a sound from script's activator, at the given volume. If there's no activating thing, the sound will be ambient.
*''void'' means that a function should be used as a procedure (command) without returning anything,
*void AmbientSound(str sound, int volume)
*''fixed'' means you can use the decimal point notation: 1.0 is equivalent to 65536, 1.5 to 98304 etc. In ACS, such values are still of '''int''' type, but whether you use the decimal point or not is quite relevant. A value such as 128.0 is ''not'' the same as 128: it's actually equal to 8388608 (no decimal point).
:Starts an ambient sound.
==Function list==
*void LocalAmbientSound(str sound, str volume)
===Sound and music===
:Starts an ambient sound that can only be heard by the activator, normally a player.
*[[ActivatorSound]]
*void PlaySound (int tid, str sound [, int channel [, fixed volume [, bool looping [, fixed attenuation]]]])
*[[AmbientSound]]
*void PlayActorSound (int tid, int sound, int channel, fixed volume, bool looping, fixed attenuation)
*[[LocalAmbientSound]]
*void SectorSound(str sound, int volume);
*[[PlayActorSound]]
*void SetMusic (str song [, int order [, int unused]])
*[[PlaySound]]
*void LocalSetMusic (str song [, int order [, int unused]])
*[[SectorSound]]
*void SoundSequence (str sndseq);
*[[SetMusic]]
*void SoundSequenceOnActor (int tid, str sndseq);
*[[LocalSetMusic]]
*void StopSound (int tid, int channel);
*[[SoundSequence]]
*void ThingSound (int tid, str sound, int volume);
*[[SoundSequenceOnActor]]
*[[StopSound]]
*[[ThingSound]]


==Sectors==
===Sectors===
*void ChangeCeiling(int tag, str flatname)
{|class="wikitable sortable
:Changes the ceiling texture of tagged sectors to flatname.
! Name
*void ChangeFloor(int tag, str flatname)
! Description
:Changes the floor texture of tagged sectors to flatname.
|-
*fixed GetSectorCeilingZ (int tag, int x, int y)
||[[ChangeCeiling]]||Changes the ceiling texture.
:Gets sector ceiling height. Currently x and y are reserved for the time Eternity gets working slope physics.
|-
*fixed GetSectorFloorZ (int tag, int x, int y)
||[[ChangeFloor]]||Changes the floor texture.
:Gets sector floor height. Currently x and y are reserved for the time Eternity gets working slope physics.
|-
*int GetSectorLightLevel (int tag)
||[[GetSectorCeilingZ]]||Gets the ceiling height.
==Things==
|-
||[[GetSectorFloorZ]]||Gets the floor height.
|-
||[[GetSectorLightLevel]]||Gets the light level.
|-
||[[SectorDamage]]||Damages things in sector.
|-
||[[SetSectorDamage]]||Modifies the damaging floor status.
|-
||[[TagWait]]||Waits for sectors to stop movement.
|}
 
===Things===
*[[ActivatorTID]]
*[[ChangeActorAngle]]
*[[ChangeActorPitch]]
*[[CheckActorCeilingTexture]]
*[[CheckActorClass]]
*[[CheckActorFloorTexture]]
*[[CheckActorProperty]]
*bool [[CheckFlag]](int tid, str flag)
:Returns true if the first thing with the given tid has the given flag enabled.
*[[CheckProximity]]
*bool CheckSight(int source, int dest, int flags)
*bool CheckSight(int source, int dest, int flags)
:Returns true if there's a line of sight between at least one thing tagged as source and one thing tagged as dest. Currently flags is reserved and must be 0.
:Returns true if there's a line of sight between at least one thing tagged as source and one thing tagged as dest. Currently flags is reserved and must be 0.
*bool CheckFlag(int tid, str flag)
*int [[ClassifyActor]](int tid)
:Returns true if the first thing with the given tid has the given flag enabled.
*bool CheckActorClass(int tid, str class)
:Returns true if the first thing with the given tid is of the given class.
*bool CheckActorProperty(int tid, int property, int/float/bool value)
:Returns true if the first thing with the given tid has a property with the given value. Currently the following properties are supported:
:*APROP_HEALTH: hit points
:*APROP_SPEED: thing nominal speed, as defined in EDF. Depending on movement type, this can be expressed in units (e.g. 8 for zombieman) or multiples of 65536 (e.g. 655360 for imp fireball).
:*APROP_DAMAGE: thing nominal damage, such as the one set for projectiles (e.g. 3 for imp fireballs).
:*APROP_ALPHA: thing opacity. 65536 or 1.0 means full opacity, 0 means invisible.
:*APROP_Ambush: whether the thing has the AMBUSH flag, either as set in the editor or EDF.
:*APROP_Invulnerable: whether the thing has the INVULNERABLE flag
:*APROP_Friendly: whether the thing has the FRIEND flag
:*APROP_SpawnHealth: initial health
:*APROP_Dropped: whether the thing has the DROPPED flag, such as being dropped ammo that doesn't respawn and disappears if crushed
:*APROP_TargetTID: the thing's current enemy's TID
:*APROP_TracerTID: the thing's current "tracer"'s TID. A tracer has various meanings, most notable the homing missile target, the archvile fire target or a friend's guide player.
:*APROP_ScaleX, APROP_ScaleY: the thing sprite's scale, expressed in floating point (0.0 - 1.0 - ...) or fixed point (0 - 65536 - ...)
:*APROP_Dormant: whether the thing has the DORMANT flag
:*APROP_Mass: thing's "mass" as defined in EDF, i.e. how much it's thrusted when damaged.
:*APROP_Height: thing's height, in floating point / fixed point.
:*APROP_Radius: thing's radius (half of bounding box width), in floating point / fixed point.
:*APROP_ReactionTime: thing's reaction time, usually defined to 8 in EDF
:*APROP_MeleeRange: thing's melee range, currently constant to 64.0
*int ClassifyActor(int tid)
:Checks the kind of thing tagged tid. It returns a set of flags, possibly combined:
:Checks the kind of thing tagged tid. It returns a set of flags, possibly combined:
:*ACTOR_PLAYER (2): it's player-controlled
:*ACTOR_PLAYER (2): it's player-controlled
Line 67: Line 69:
:*ACTOR_NONE (0): no thing found with this TID
:*ACTOR_NONE (0): no thing found with this TID
:*ACTOR_WORLD (1): TID is 0 but activator isn't a thing
:*ACTOR_WORLD (1): TID is 0 but activator isn't a thing
*int GetActorProperty (int tid, int property)
*[[GetActorAngle]]
*bool IsTIDUsed (int tid)
*[[GetActorCeilingZ]]
*void SectorDamage (int tag, int amount, str type, str protection_item, int flags)
*[[GetActorFloorZ]]
*int SetActivator (int tid[, pointer_selector])
*[[GetActorLightLevel]]
*bool SetActivatorToTarget (int tid)
*[[GetActorPitch]]
*[[GetActorProperty]]
*[[GetActorVelX]]
*[[GetActorVelY]]
*[[GetActorVelZ]]
*[[GetActorX]]
*[[GetActorY]]
*[[GetActorZ]]
*[[IsTIDUsed]]
*[[SetActivator]]
*[[SetActivatorToTarget]]
*void SetActorAngle (int tid, fixed angle)
*void SetActorAngle (int tid, fixed angle)
*bool SetActorVelocity (int tid, fixed velx, fixed vely, fixed velz, bool add, bool setbob)
*[[SetActorVelocity]]
*void SetActorPitch (int tid, int pitch)
*void SetActorPitch (int tid, int pitch)
*bool SetActorPosition (int tid, fixed x, fixed y, fixed z, bool fog)
*[[SetActorPosition]]
*void SetThingSpecial (int tid, int special [, int arg0 [, int arg1 [, int arg2 [, int arg3 [, int arg4]]]]])
*void SetThingSpecial (int tid, int special [, int arg0 [, int arg1 [, int arg2 [, int arg3 [, int arg4]]]]])
*int SetActorState(int tid, str statename[, bool exact]);
*int SetActorState(int tid, str statename[, bool exact]);
Line 81: Line 93:
*int Spawn (str classname, fixed x, fixed y, fixed z [, int tid [, int angle]])
*int Spawn (str classname, fixed x, fixed y, fixed z [, int tid [, int angle]])
*int SpawnForced (str classname, fixed x, fixed y, fixed z [, int tid [, int angle]])
*int SpawnForced (str classname, fixed x, fixed y, fixed z [, int tid [, int angle]])
*void SpawnProjectile (int tid, string type, int angle, int speed, int vspeed, int gravity, int newtid);
*[[SpawnProjectile]]
*int SpawnSpot (str classname, int spottid [, int tid [, int angle]])
*[[SpawnSpot]]
*int SpawnSpotForced (str classname, int spottid [, int tid [, int angle]])
*int SpawnSpotFacing (str classname, int spottid [, int tid])
*int SpawnSpotFacing (str classname, int spottid [, int tid])
*int SpawnSpotFacingForced (str classname, int spottid [, int tid])
*[[SpawnSpotFacingForced]]
*[[SpawnSpotForced]]
*int ThingCount (int type, int tid)
*int ThingCount (int type, int tid)
*int ThingCountName (str classname, int tid)
*int ThingCountName (str classname, int tid)
Line 94: Line 106:
*int UniqueTID ([int tid[, int limit]])
*int UniqueTID ([int tid[, int limit]])


==Linedefs and sidedefs==
===Player===
*void ReplaceTextures (str oldtexturename, str newtexturename [, int flags])
*[[CheckInventory]]
*void SetLineSpecial (int lineid, int special [, int arg0 [, int arg1 [, int arg2 [, int arg3 [, int arg4]]]]])
*[[CheckWeapon]]
*void SetLineTexture(int lineid, int line_side, int sidedef_texture, str texturename);
*[[GetWeapon]]
*[[GetSigilPieces]]
*[[PlayerArmorPoints]]
*[[PlayerCount]]
*[[PlayerFrags]]
*[[PlayerHealth]]
*[[PlayerNumber]]
*[[SetWeapon]]
*[[TakeInventory]]


*fixed GetLineX(int lineId, fixed ratioAlongLine, fixed distanceFromLine);
===Linedefs and sidedefs===
*fixed GetLineY(int lineId, fixed ratioAlongLine, fixed distanceFromLine);
{|class="wikitable sortable"
:These two functions return the coordinates on top of a linedef tagged as ''lineId''. Other parameters are:
! zspecial.acs index
:*''ratioAlongLine'': 0 means that you get the position of first vertex; 1.0 (65536) means the position of the second vertex. Any value between them is partly between them. Negative values are before the first vertex and values over 1.0 (65536) are beyond the second one.
! Name
:*''distanceFromLine'': the distance in map units perpendicular from the line. 0 means that you get a coordinate exactly on the linedef. Positive values put it in front of the first sidedef. Negative values put it behind.
! Return type
! Parameters
! Description
|-
||internal|| [[ClearLineSpecial]] || nothing || nothing || Clears the trigger linedef's special.
|-
|| || [[GetLineRowOffset]] || || ||
|-
|| || [[GetLineX]] || || ||
|-
|| || [[GetLineY]] || || ||
|-
|| || [[LineSide]] || || ||
|-
|| || [[ReplaceTextures]] || nothing || str old_texture_name, str new_texture_name[, int flags] ||
|-
|| || [[SetLineBlocking]] || || ||
|-
||internal|| [[SetLineMonsterBlocking]] || || || Makes a linedef block or not block monsters.
|-
|| || [[SetLineSpecial]] || || ||
|-
|| || [[SetLineTexture]] || nothing || int line_id, int line_side, int sidedef_texture, str texture_name ||
|}


==Sky==
===Sky===
*void SetSkyScrollSpeed (int sky, fixed skyspeed);
*[[SetSkyScrollSpeed]]


==Scripts==
===Scripts===
*bool ACS_NamedExecuteAlways(str script, int map, int arg1, int arg2, int arg3)
*bool ACS_NamedExecuteAlways(str script, int map, int arg1, int arg2, int arg3)
:*Executes a named script, starting a new instance if one already exists. Returns true if successfully started.
:*Executes a named script, starting a new instance if one already exists. Returns true if successfully started.
Line 117: Line 160:
*bool ACS_NamedTerminate (string script, int map)
*bool ACS_NamedTerminate (string script, int map)


==Console==
===Console===
*int GetCVar (str cvar)
*int [[GetCVar]] (str cvar)
*string GetCVarString (str cvar)
*string [[GetCVarString]] (str cvar)
*int GetPlayerInput (int player, int input)
*int GetPlayerInput (int player, int input)
==Polyobjects==
*fixed GetPolyobjX (int po)
*fixed GetPolyobjY (int po)
==Quake==
*void Radius_Quake2 (int tid, int intensity, int duration, int damrad, int tremrad, str sound)
==Math==
*int Random (int min, int max)
*int Sqrt (int number)
*fixed FixedSqrt (fixed number)
*int VectorLength (int x, int y)


==Strings==
===Polyobjects===
*[[GetPolyobjX]]
*[[GetPolyobjY]]
*[[PolyWait]]
 
===Quake===
*[[Radius_Quake2]]
 
===Math===
*[[Cos]]
*fixed [[FixedSqrt]] (fixed number)
*int [[Random]] (int min, int max)
*int [[Sqrt]] (int number)
*[[Sin]]
*[[VectorAngle]]
*int [[VectorLength]] (int x, int y)
 
===Strings===
*str StrLeft (str string, int length)
*str StrLeft (str string, int length)
*str StrMid (str string, int start, int length)
*str StrMid (str string, int start, int length)
*str StrRight (str string, int length)
*str StrRight (str string, int length)
===Level state===
*[[GameSkill]]
*[[GameType]]
*[[GetLevelInfo]]
*[[SetAirControl]]
*[[SetAirFriction]]
*[[SetGravity]]
*[[SinglePlayer]]
*[[Timer]]
==See also==
*[[Parameterized linedef specials]]
[[Category:ACS]]
[[Category:Editing reference]]

Latest revision as of 11:16, 2 January 2022

These are predefined ACS functions with no parameterized linedef special equivalents, accessible only through ACS scripts.

NOTE: most of these functions are meant to be compatible with those from ZDoom. For any ones not yet documented on this wiki, you can check the ZDoom wiki. A few of them may be incompletely implemented in Eternity. Don't hesitate to update the wiki in case of any mistakes.

Special TID info[edit]

For functions affecting things, some TIDs (thing tags) carry special meaning. TID 0 means the activator, and TIDs -1 ... -4 mean each of the four players in the game -- this is an Eternity extension

Data type info[edit]

You may see specifiers such as void, str, int and others in ACS function signatures. They act as a guide on what kinds of values are expected, but in ACS there really are only two types: str and int (and str internally is merely a string ID number). Most importantly:

  • void means that a function should be used as a procedure (command) without returning anything,
  • fixed means you can use the decimal point notation: 1.0 is equivalent to 65536, 1.5 to 98304 etc. In ACS, such values are still of int type, but whether you use the decimal point or not is quite relevant. A value such as 128.0 is not the same as 128: it's actually equal to 8388608 (no decimal point).

Function list[edit]

Sound and music[edit]

Sectors[edit]

Name Description
ChangeCeiling Changes the ceiling texture.
ChangeFloor Changes the floor texture.
GetSectorCeilingZ Gets the ceiling height.
GetSectorFloorZ Gets the floor height.
GetSectorLightLevel Gets the light level.
SectorDamage Damages things in sector.
SetSectorDamage Modifies the damaging floor status.
TagWait Waits for sectors to stop movement.

Things[edit]

Returns true if the first thing with the given tid has the given flag enabled.
Returns true if there's a line of sight between at least one thing tagged as source and one thing tagged as dest. Currently flags is reserved and must be 0.
Checks the kind of thing tagged tid. It returns a set of flags, possibly combined:
  • ACTOR_PLAYER (2): it's player-controlled
  • ACTOR_VOODOODOLL (8): it's a duplicate player start, not controlled by the player but still linked to it. Used in Boom maps for advanced mapping tricks
  • ACTOR_MONSTER (16): it's a monster (has COUNTKILL or KILLABLE thing type flag set)
  • ACTOR_MISSILE (128): it's a projectile in flight (has MISSILE thing type flag set)
  • ACTOR_GENERIC (256): neither a monster, nor a projectile
  • ACTOR_ALIVE (32): has positive health
  • ACTOR_DEAD (64): has health <= 0
  • ACTOR_NONE (0): no thing found with this TID
  • ACTOR_WORLD (1): TID is 0 but activator isn't a thing

Player[edit]

Linedefs and sidedefs[edit]

zspecial.acs index Name Return type Parameters Description
internal ClearLineSpecial nothing nothing Clears the trigger linedef's special.
GetLineRowOffset
GetLineX
GetLineY
LineSide
ReplaceTextures nothing str old_texture_name, str new_texture_name[, int flags]
SetLineBlocking
internal SetLineMonsterBlocking Makes a linedef block or not block monsters.
SetLineSpecial
SetLineTexture nothing int line_id, int line_side, int sidedef_texture, str texture_name

Sky[edit]

Scripts[edit]

  • bool ACS_NamedExecuteAlways(str script, int map, int arg1, int arg2, int arg3)
  • Executes a named script, starting a new instance if one already exists. Returns true if successfully started.
  • bool ACS_NamedExecute(str script, int map, int arg1, int arg2, int arg3)
  • Executes a named script. Returns true if successfully started.
  • int ACS_NamedExecuteWithResult (string script, int s_arg1, int s_arg2, int s_arg3, int s_arg4)
  • bool ACS_NamedSuspend (string script, int map)
  • bool ACS_NamedTerminate (string script, int map)

Console[edit]

Polyobjects[edit]

Quake[edit]

Math[edit]

Strings[edit]

  • str StrLeft (str string, int length)
  • str StrMid (str string, int start, int length)
  • str StrRight (str string, int length)

Level state[edit]

See also[edit]

Retrieved from "http://eternity.youfailit.net/index.php?title=ACS_built-in_functions&oldid=5422"