SA-MP Forums

Go Back   SA-MP Forums > SA-MP Scripting and Plugins > Filterscripts > Includes

Thread Tools Display Modes
Old 25/01/2018, 02:19 PM   #1
Dayrion's Avatar
Join Date: Jan 2016
Location: France
Posts: 1,917
Reputation: 258
Default actor_plus » Useful functions/callbacks for actors


This is a simple include which give you some functions to manipulate actors and interact with them more easily. This include differentiates dynamic actors from static actors. You must specify this when using the functions below. By the way, if you don't have streamer ; you doesn't have to specify if the actor is dynamic or not.
I recommed to have YSI (from ******) library for better performance (the include use y_iterate and y_timers when they are included before). Also using streamer and dynamic actors can improve performance too.

I'll copy/paste the «documentation» which already on GitHub. I recommend to read it, the presentation is more clear.

An include with a bunch of useful functions and callback for actors. Functions returning 1 on success, 2 for specific success, 0 on failure or cellmin for specific failure. Please, check the wiki for more specific informations.


Can not be redefined
  • MULTIPLE_TARGET_FOUND: Returned by GetNearestActorForPlayer or GetNearestActorByCoord when multiple actors are found and when return_multiple_target is set to true
  • DEFAULT_ACTOR_VALUE: Using this one instead of any other value result taking the value from the actor.
  • DEFAULT_CHECKING_TIME: Used to detect OnPlayerTargetActor.
  • ALL_VALUES_INCLUDED: If ALL_VALUES_INCLUDED is returned by a function, it means it will appear at every stage (like interior or virtual world).
  • DEFAULT_ACTOR_REPLACEMENT: Time before an actor is being re-placed at his old position.
  • AP_DEBUG_ENABLED: If some debugs printed messages are needed
  • MAX_ANIMATION_LIBRARY_LENGTH: Maximum animation library length name
  • MAX_ANIMATION_NAME_LENGTH: Maximum animation length name
  • DEFAULT_IS_DYNAMIC_PARAMETER: Set to true if streamer is included otherwise, it set to false

Can be redefined
  • DEFAULT_ACTOR_DRAW_DISTANCE: Distance that label is displayed | (type: float)
  • MAX_ACTOR_LABEL_LENGTH: Max length for a text in a label | (type: integer)
  • DEFAULT_ACTOR_COLOR: Default actor color text | (type: hexadecimal)
  • DEFAULT_ACTOR_COLOR_NAME: Default actor color name | (type: hexadecimal)
  • DONT_DETECT_OPTA: You can define it before the include to deactivated OnPlayerTargetActor detection (which using timer) | (type: N/A)
  • DEFAULT_TEXT_RANGE_DETECTION: This allows you to change the distance at which the actor (for OnPlayerTextNearActor only) is detected | (type: float)

General functions
PHP Code:
native RespawnActor(actoridbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native SetActorSkin(actoridskinidbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native IsActorDead(actoridbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native GetActorSkin(actoridbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native ActorPlaySound(actoridsoundidFloat:xFloat:yFloat:zFloat:max_rangebool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);

native SetActorName(actorid, const actor_name[], bool:displaybool:contain_id falsebool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native GetActorName(actoridactor_name[], length sizeof(actor_name), bool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native ToggleActorName(actoridbool:togglebool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);

native GetActorTextLabel(actoridtext[], length sizeof(text), bool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native GetActorLabelColor(actoridbool:ToRGB falsebool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER); // output -> RGBA
native GetActorNameColor(actoridbool:ToRGB falsebool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER); // output -> RGBA
native SetActorLabelColor(actoridcolorbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native SetActorNameColor(actoridcolorbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native ActorHasAttachedLabel(actorid, &bool:name_displayed false, &bool:text_displayed falsebool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native UpdateAttachedActor3DTextLabel(actorid, const text[], colorbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native DestroyActor3DTextLabel(actoridbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);

native SetActorChatBubble(actoridtext[], colorFloat:drawdistanceexpiretimebool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER); 

Functions - Streamer dependency
PHP Code:
native Attach3DTextLabelToActor(actorid, const text[], bool:isdynamiccolorFloat:OffsetXFloat:OffsetYFloat:OffsetZFloat:drawdistancetestlos 0worldid DEFAULT_ACTOR_VALUEinteriorid DEFAULT_ACTOR_VALUEplayerid DEFAULT_ACTOR_VALUEFloat:streamdistance STREAMER_3D_TEXT_LABEL_SDareaid DEFAULT_ACTOR_VALUEpriority 0bool:store_string true);

// Used to get the real internal actor id used by SA-MP
native GetInternalActorIDForPlayer(forplayeridactorid);

// In addition to the streamer
native GetDynamicActorInterior(actorid);
native SetDynamicActorInterior(actoridinteriorid);
native DestroyAllDynamicActors(serverwide);
native CountDynamicActors(serverwide);
native UpdateDynamicActorForPlayer(playerid);
native CountStreamedActorForPlayer(playeridserverwide);
native STREAMER_TAG_AREA GetDynamicActorArea(actorid);
native SetDynamicActorArea(actoridSTREAMER_TAG_AREA areaid);
native GetDynamicActorPriority(actorid);
native SetDynamicActorPriority(actoridpriority);
native GetInternalActorIdForPlayer(forplayeridactorid); 

Functions - Non-Streamer dependency
PHP Code:
native Attach3DTextLabelToActor(actoridtext[], colorFloat:OffsetXFloat:OffsetYFloat:OffsetZFloat:drawdistancevirtualworld DEFAULT_ACTOR_VALUEtestlos 0bool:store_string true);
native SetActorInvulnerable(actoridinvulnerable true); // Force actor re-stream
native SetActorVirtualWorld(actoridvworld); // Force actor re-stream
native SetActorFacingAngle(actoridFloat:ang); // Force actor re-stream
native CountStaticActors(); 

Useful functions (none include needed)
PHP Code:
native GetNearestActorForPlayer(playerid, &bool:isdynamic falsetype SEARCH_TYPE_ALLbool:return_multiple_target false);
native GetNearestActorByCoord(Float:xFloat:yFloat:z, &bool:isdynamic falsetype SEARCH_TYPE_ALLbool:return_multiple_target falseFloat:max_range INVALID_RANGE_ID);
native Float:GetActorDistanceFromPoint(actoridFloat:xFloat:yFloat:zbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native IsPlayerInRangeOfActor(playeridactoridFloat:range 2.0bool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native IsPlayerAimingActor(playeridactoridbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native IsActorInPlayerFacingAngle(playeridactoridFloat:max_angle 90.0bool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);

native GetActorSpawnInfo(actorid, &skinid, &Float:fX, &Float:fY, &Float:fZ, &Float:fAnglebool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native GetActorAnimationName(actoridanimlib[], size_animlib sizeof(animlib), animname[], size_animname sizeof(animname)); // Static actors only
native GetActorAnimation(actoridanimlib[], size_animlib sizeof(animlib), animname[], size_animname sizeof(animname), &Float:fDelta, &loop, &lockx, &locky, &freeze, &time); // Static actors only
native ToggleActorAnimationLoop(actoridbool:toggle); // Static actors only
native bool:IsActorPlayingAnimation(actoridbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);

native CountAllActors(); 
Type of research:
  • SEARCH_TYPE_DYNAMIC: Search only for dynamics actors
  • SEARCH_TYPE_STATIC: Search only for statics actors
  • SEARCH_TYPE_ALL: Search for dynamics and statics actors

Per-players functions (Pawn RakNet dependency)
PHP Code:
native HideActorForPlayer(forplayeridactoridhide_typebool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native BringBackActorForPlayer(forplayeridactoridbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native SetActorHideTypeForPlayer(forplayeridactoridhide_typebool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native RemoveAllHiddenActorForPlayer(playerid);

native ApplyActorAnimationForPlayer(forplayeridactoridrepeated_animationanimlib[], animname[], Float:fDeltalooplockxlockyfreezetimebool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native ClearActorAnimationsForPlayer(forplayeridactoridbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);

native SetActorPosForPlayer(forplayeridactoridfake_position_typeFloat:xFloat:yFloat:zFloat:anglebool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER);
native BringBackActorPosForPlayer(forplayeridactoridbool:isdynamic DEFAULT_IS_DYNAMIC_PARAMETER); 

Player Flags
Hide type
  • HIDE_TYPE_NONE: Default value
  • HIDE_TYPE_ONE_TIME: The actor will be hidden one time and reappear when it be streamed
  • HIDE_TYPE_PERMANENT: The actor will be hidden until the script make it come back even if the player re-stream the actor

Repeated animation type
  • ANIMATION_PLAY_NONE: Default value
  • ANIMATION_PLAY_ONE_TIME: The actor will play an animation one time and stop it when it be streamed even if the animation is looped
  • ANIMATION_PLAY_PERMANENT: The actor will permently play the same animation. Restream the actor doesn't stop the process

Per players positions type
  • FAKE_POSITION_NONE: Default value
  • FAKE_POSITION_ONE_TIME: The actor will be placed, one time, at the specified coordinates. Re-stream the actor will place him at server sided coordinates
  • FAKE_POSITION_PERMANENT: The actor will be placed at specified coordinates. Re-stream it won't change anything the coordinates.

PHP Code:
forward OnPlayerShotActor(playeridactoridweaponidbool:IsDynamicActor);
forward OnPlayerTargetActor(playeridactoridweaponid);
forward OnPlayerStopTargetActor(playeridactoridweaponid);
forward OnPlayerMakeDamageToActor(playeriddamaged_actoridFloat:amountweaponidbodypartbool:deathbool:IsDynamicActor);
forward OnActorDeath(actoridkilleridreasonbool:IsDynamicActor);
forward OnActorSpawn(actoridbool:IsDynamicActor);
forward OnPlayerStreamForActor(forplayeridactoridactor_flagsbool:IsDynamicActor); // Pawn RakNet dependency
forward OnActorVirtualWorldChange(actoridoldvwnewvwbool:IsDynamicActor);
forward OnPlayerTextNearActor(playeridactoridtext[], bool:IsDynamicActor);
forward OnDynamicActorInteriorChange(actoridoldinteriornewinteriorid); 
  • OnPlayerShotActor: Called when a player shot an actor even if the actor is invulnerable
  • OnPlayerTargetActor: Called when a player stop aiming an actor.
  • OnPlayerStopTargetActor: Called when a player aim an actor.
  • OnPlayerMakeDamageToActor: Called when a player damage an actor with a firearm. bool:death is set to true when the actor will die after processing damage.
    Returning 0 to this call prevent applying damage to the actor.
  • OnActorDeath: Called when a actor die. Set actor's HP to 0 trigger this callback too.
  • OnActorSpawn: Called when a player spawn (is created).
  • OnPlayerStreamForActor: Called when a player stream IN an actor even if the actor is hidden for the player.
    Important: actor_flags should be used with different flags type defined below
  • OnActorVirtualWorldChange: Called when a virtualworld is set to an actor.
  • OnPlayerTextNearActor: Called when a player chat near an actor
  • OnDynamicActorInteriorChange: Called when an interior is set to a dynamic actor.

You need to use the latest version of Zeex's compiler because of implicit 4D arrays. You can find the download here:
Zeex's compiler is an improved version of the actual compiler with a lot of bugfixs and new features (like 4D arrays).

My english is a mess, I apologize for that. Any tips, comments, whatever can make me go further will be appreciated.
actor_plus - v5.0.2
« I'm a goner, somebody catch my breath,
I'm a goner, somebody catch my breath »

Last edited by Dayrion; 30/08/2018 at 09:48 PM.
Dayrion is offline   Reply With Quote
Old 25/01/2018, 02:22 PM   #2
Join Date: Nov 2017
Posts: 228
Reputation: 43
Default Re: actor_plus » Useful functions/callbacks for actors

it's github not githud
rfr is offline   Reply With Quote
Old 25/01/2018, 02:26 PM   #3
Dayrion's Avatar
Join Date: Jan 2016
Location: France
Posts: 1,917
Reputation: 258
Default Re: actor_plus » Useful functions/callbacks for actors

Originally Posted by rfr View Post
it's github not githud
Every freaking time I do this mistake. -.-
actor_plus - v5.0.2
« I'm a goner, somebody catch my breath,
I'm a goner, somebody catch my breath »
Dayrion is offline   Reply With Quote
Old 25/01/2018, 04:41 PM   #4
Big Clucker
Join Date: Dec 2010
Posts: 151
Reputation: 6
Default Re: actor_plus » Useful functions/callbacks for actors

GuyYahood1 is offline   Reply With Quote
Old 25/01/2018, 08:05 PM   #5
Little Clucker
Join Date: May 2009
Posts: 47
Reputation: 0
Default Re: actor_plus » Useful functions/callbacks for actors

Great job, but why you didn't stream the name ?
chneubeul is offline   Reply With Quote
Old 25/01/2018, 10:10 PM   #6
Dayrion's Avatar
Join Date: Jan 2016
Location: France
Posts: 1,917
Reputation: 258
Default Re: actor_plus » Useful functions/callbacks for actors

Originally Posted by GuyYahood1 View Post
Originally Posted by chneubeul View Post
Great job, but why you didn't stream the name ?
Thanks you. What do you mean? Labels (text/name) are streamed if you use streamer.
actor_plus - v5.0.2
« I'm a goner, somebody catch my breath,
I'm a goner, somebody catch my breath »
Dayrion is offline   Reply With Quote
Old 26/01/2018, 04:13 PM   #7
ThePhenix's Avatar
Join Date: May 2012
Posts: 801
Reputation: 157
Default Re: actor_plus » Useful functions/callbacks for actors

I like the fact that you're using bit flags.
ThePhenix is offline   Reply With Quote
Old 26/01/2018, 10:00 PM   #8
Dayrion's Avatar
Join Date: Jan 2016
Location: France
Posts: 1,917
Reputation: 258
Default Re: actor_plus » Useful functions/callbacks for actors

Originally Posted by ThePhenix View Post
I like the fact that you're using bit flags.
Eheh, thanks!
actor_plus - v5.0.2
« I'm a goner, somebody catch my breath,
I'm a goner, somebody catch my breath »
Dayrion is offline   Reply With Quote
Old 26/01/2018, 10:29 PM   #9
Join Date: Jun 2015
Location: Romania
Posts: 486
Reputation: 131
Default Re: actor_plus » Useful functions/callbacks for actors
this will trigger an error while compiling with default pawncc since #warning is a zeex compiler directive
Spmn is offline   Reply With Quote
Old 26/01/2018, 11:58 PM   #10
Pottus's Avatar
Join Date: Jun 2012
Posts: 4,885
Reputation: 1321
Default Re: actor_plus » Useful functions/callbacks for actors

I didn't realize you could do this.

enum _:E_TYPE_SEARCH(<<= 1)
I was looking at a few things here and this doesn't make sense to me.

			if(type & SEARCH_TYPE_STATIC)
				foreach(new i : Static_Actors)
					if(!IsPlayerInRangeOfPoint(playerid, range, Static_Actors[i][eapPosX], Static_Actors[i][eapPosY], Static_Actors[i][eapPosZ]))
					if(actorid != INVALID_ACTOR_ID)
					actorid = i;
Why would you do that? That pretty much makes this function useless if there is two or more actors. It should at least have an optional parameter to do what you are doing otherwise update your code to find the closest actor and return it.
Pottus is offline   Reply With Quote

Thread Tools
Display Modes

Posting Rules
You may not post new threads
You may not post replies
You may not post attachments
You may not edit your posts

BB code is On
Smilies are On
[IMG] code is On
HTML code is Off

Similar Threads
Thread Thread Starter Forum Replies Last Post
[Tutorial] How to hook Functions and Callbacks. Lordzy Tutorials 20 11/11/2017 09:57 PM
[Include] [INC]Area functions and callbacks. Backwardsman97 Includes 8 04/11/2011 07:09 AM
[Tutorial] How to hook FUNCTIONS (not callbacks) Luka P. Tutorials 17 13/06/2011 05:35 PM
Useful Functions and Callbacks Re-release Larcius Filterscripts 12 24/06/2010 03:34 PM

All times are GMT. The time now is 07:53 PM.

Powered by vBulletin® Version 3.8.6
Copyright ©2000 - 2020, Jelsoft Enterprises Ltd.