Actor pointer: Difference between revisions

Jump to navigation Jump to search

Actor pointer (view source)

Revision as of 12:23, 5 December 2024

2,063 bytes added ,  5 December 2024
→‎DECORATE & ACS
== DECORATE & ACS ==
Several [[DECORATE]] and [[ACS]] functions support custom retrieval and assignment of pointer values. The data location or method of retrieval is specified using named pointer selectors.
 
In contrast to [[ZScript]], these pointers function as internal constants that can point to a specific actor.
 
All pointers are automatically supported by all implementing functions, unless the function documentation specifies otherwise.
 
{| class="wikitable"
'''Selectors'''
|- style="font-weight:bold; text-align:center;"
 
! [[ACS]] constant
The following set of named values all indicate ways of retrieving an actor pointer from a source actor or a static context. The values are divided into categories, and the first selector applicable to the source actor is used. Selectors from different categories may be combined using BITWISE OR. (SELECTOR_A | SELECTOR_B)
! [[DECORATE]] constant
 
! [[ZScript]] analog
 
! style="text-align:left;" | Static?
'''Selector category 1: Player-only selectors'''
! style="text-align:left;" | Modifiable?
 
! Explanation
Players will use a pointer in this category if one is specified. Otherwise, a pointer from another applicable category will be used.
|-
 
| AAPTR_NULL
* AAPTR_PLAYER_GETTARGET: Get the actor in the player's line of sight. Most target-specific functions use this approach to determining the player's target. This only works if the actor has the '''{{Flag|SHOOTABLE}}''' and '''{{Flag|SOLID}}''' flags, and also lacks the '''{{Flag|NOBLOCKMAP}}''' flag, much like [[A_JumpIfTargetInLOS]].
| AAPTR_NULL
* AAPTR_PLAYER_GETCONVERSATION: Get the actor currently talking to the player. Best used from a Strife dialogue that gives a custom inventory item, or starts a script with ACS_ExecuteWithResult (as it processes immediately).
| null
 
| style="background-color:#96fffb;" | Yes
 
| style="background-color:#FFCB2F;" | No
'''Selector category 2: Generic context selectors'''
| A null pointer. In ZScript this is not limited to actors.
 
|-
Any actor (non-null) will use a pointer in this category if one is specified. Otherwise, a pointer from another applicable category will be used.
| AAPTR_DEFAULT
 
| AAPTR_DEFAULT
* AAPTR_MASTER: Access the actor's MASTER pointer. (Players normally do not have masters.)
| self<br />Actor(self)
* AAPTR_TARGET: Access the actor's TARGET pointer. (Players normally do not use this.)
| style="background-color:#ffcb2f;" | No
* AAPTR_TRACER: Access the actor's TRACER pointer.
| style="background-color:#FFCB2F;" | No
* AAPTR_FRIENDPLAYER: Access the actor's FRIENDPLAYER pointer.
| Returns the source actor itself (null if there is no source actor).<br /><br />In ZScript, this is not limited to actors. If the context is ambiguous, ZScript may require using {{c|Actor(self)}} to explicitly<br />tell the code the pointer is an actor in this instance.
* AAPTR_GET_LINETARGET: Get the actor in the line of sight. This is similar to AAPTR_PLAYER_GETTARGET above, except it is used for non-player actors.
|-
 
| AAPTR_PLAYER#
Note that AAPTR_GET_LINETARGET is identified as AAPTR_LINETARGET in DECORATE.
| AAPTR_PLAYER#
 
| players[#].mo<br /><br />Note: In ZScript # would be 1 value smaller,<br />because player numbers in ZScript begin with 0
Note on retrieving TARGET information: Most functions use a special approach to find the target of a player; checking what they are aiming/looking at. This corresponds to AAPTR_PLAYER_GETTARGET. To make a single function that conforms to this standard, use the selector combination AAPTR_TARGET|AAPTR_PLAYER_GETTARGET. The most applicable method will be used (AAPTR_PLAYER_GETTARGET for any player).
| style="background-color:#96fffb;" | Yes
 
| style="background-color:#FFCB2F;" | No
 
| Pointers to the {{class|PlayerPawn}} of the specified player. Note, in DECORATE these pointers begin with 1, but in<br />ZScript player numbers begin with 0. In ZScript the global <code>players</code> array contains all players'<br />{{struct|PlayerInfo}} structs, and those structs have a <code>mo</code> pointer to their PlayerPawn actors.<br />So, DECORATE's {{c|AAPTR_PLAYER1}} is equal to {{c|players[0].mo}} in ZScript.<br /><br />For ZScript, see also '''[[PlayerNumber]]'''.<br /><br />''Scripting tip'': AAPTR_PLAYER1 points to player 1. AAPTR_PLAYER1<<X (shift bits X up) points to player (1 + X).<br />This fact can be applied in ACS loops if you need to reference each active player in sequence.
'''Selector category 3: Static context selectors'''
|-
 
| AAPTR_MASTER
Any specified pointer in this category will be used.
| AAPTR_MASTER
 
| master
* AAPTR_NULL: Return NULL.
| style="background-color:#FFCB2F;" | No
* AAPTR_PLAYER# (where # is a number in the range 1 - 8):
| style="background-color:#96fffb;" | Yes
** A static pointer to the player of that number. NULL if the player does not exist.
| The actor's [[Actor_pointer#Target,_master_and_tracer|master]] pointer. Players normally don't have masters.
 
|-
''Scripting tip:'' AAPTR_PLAYER1 points to player 1. AAPTR_PLAYER1<<X (shift bits X up) points to player (1 + X). This fact can be applied in ACS loops if you need to reference each active player in sequence.
| AAPTR_TARGET
 
| AAPTR_TARGET
 
| target
'''Selector category 4: Default'''
| style="background-color:#FFCB2F;" | No
 
| style="background-color:#96fffb;" | Yes
This selection is always implied, and applies if no other selection was made. To fully disable this, specify one static selection (as they always apply when specified), such as AAPTR_NULL.
| The actor's [[Actor_pointer#Target,_master_and_tracer|target]] pointer. Players normally don't have targets.<br /><br />Note: Most functions use a special approach to find the target of a player; checking what they are<br />aiming/looking at. This corresponds to AAPTR_PLAYER_GETTARGET. To make a single function that<br />conforms to this standard, use the selector combination AAPTR_TARGET|AAPTR_PLAYER_GETTARGET.<br />The most applicable method will be used (AAPTR_PLAYER_GETTARGET for any player).<br />
 
|-
* AAPTR_DEFAULT: Returns the source actor itself (null if there is no source actor).
| AAPTR_TRACER
 
| AAPTR_TRACER
| tracer
| style="background-color:#FFCB2F;" | No
| style="background-color:#96fffb;" | Yes
| The actor's [[Actor_pointer#Target,_master_and_tracer|target]] tracer. Players normally don't have tracers.
|-
| AAPTR_FRIENDPLAYER
| AAPTR_FRIENDPLAYER
| players[friendplayer].mo
| style="background-color:#FFCB2F;" | No
| style="background-color:#FFCB2F;" | No
| If it's a {{flag|FRIENDLY}} monster, this will be a pointer to the player they're friendly to. This is only relevant in<br />multiplayer, where friendly monsters may not be equally friendly to everyone.<br /><br />Note, in ZScript the <code>friendplayer</code> field is numeric field on an actor, so to get the actual {{class|PlayerPawn}}<br />of that player, checking the <code>players</code> global array is necessary. Also, if calling from a different actor/class,<br />{{c|friendplayer}} will have to be prefixed with a pointer to the actor whose friendplayer you want to get.<br /><br /><br />For more details on friendliness in ZScript, see '''[[IsFriend]]''' and '''[[IsHostile]]''' functions.
|-
| AAPTR_GET_LINETARGET
| AAPTR_LINETARGET
|
| style="background-color:#FFCB2F;" | No
| style="background-color:#FFCB2F;" | No
|
|-
| AAPTR_PLAYER_GETTARGET
| AAPTR_PLAYER_GETTARGET
| None. See '''[[BulletSlope]]''' and its wrapper '''[[AimTarget]]'''<br />actor functions for obtaining the same pointers in ZScript.
| style="background-color:#FFCB2F;" | No
| style="background-color:#FFCB2F;" | No
| Get the actor in the player's line of sight. Most target-specific functions use this approach to determining the player's target.<br />This only works if the actor has the '''{{Flag|SHOOTABLE}}''' and '''{{Flag|SOLID}}''' flags, and also lacks the <br />'''{{Flag|NOBLOCKMAP}}''' flag, much like [[A_JumpIfTargetInLOS]].
|-
| AAPTR_PLAYER_GETCONVERSATION
| AAPTR_PLAYER_GETCONVERSATION
| player.ConversationNPC
| style="background-color:#FFCB2F;" | No
| style="background-color:#FFCB2F;" | No
| Get the actor currently talking to the player. Best used from a Strife dialogue that gives a custom inventory item, or starts<br />a script with [[ACS_ExecuteWithResult]] (as it processes immediately).<br /><br />In ZScript this pointer is defined in the {{struct|PlayerInfo}} struct and is not available for the base Actor class.
|}
 
'''Assignment'''
Retrieved from "https://zdoom.org/wiki/Special:MobileDiff/54025"

Navigation menu