NPC functions - WoutProvost/FCNPC-AI GitHub Wiki

Home ▸ Functions ▸ NPC functions

FAI_Create(name[])
FAI_GetFullName(npcid, name[], len)
  • Description: Get an NPC's fullName.
  • Parameters:
    • npcid: The ID of the NPC to get the fullName of.
    • name[]: An array into which to store the fullName, passed by reference.
    • len: The length of the string that should be stored. Recommended to be FAI_MAX_FULL_NAME.
  • Return values:
    • FullName length: The function executed successfully.
    • -1: The function failed to execute. An invalid npcid was given.
FAI_SetFullName(npcid, name[])
  • Description: Set an NPC's fullName which is displayed in TextDraw 3.
  • Parameters:
    • npcid: The ID of the NPC to set the fullName of.
    • name[]: The name to set. Max length is FAI_MAX_FULL_NAME. If "" (an empty string) is given, this will be set to be the same as the playername.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
FAI_GetMapiconInfo(npcid, &iconid, &iconMarker, &iconColor, &iconStyle)
  • Description: Get an NPC's iconid, iconMarker, iconColor and iconStyle.
  • Parameters:
    • npcid: The ID of the NPC to get the mapiconInfo of.
    • &iconid: The variable into which to store the iconid, passed by reference.
    • &iconMarker: The variable into which to store the iconMarker, passed by reference.
    • &iconColor: The variable into which to store the iconColor, passed by reference.
    • &iconStyle: The variable into which to store the iconStyle, passed by reference.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
FAI_SetMapiconInfo(npcid, iconid, iconMarker, iconColor, iconStyle)
  • Description: Set an NPC's iconid, iconMarker, iconColor and iconStyle which will display on the map at the NPCs position. See SetPlayerMapIcon. If INVALID_ICON_ID is used, no mapicon will display and the other values will be ignored.
  • Parameters:
    • npcid: The ID of the NPC to set the mapiconInfo of.
    • iconid: The iconid to set. Defaults to INVALID_ICON_ID.
    • iconMarker: The iconMarker to set. Defaults to 23 which is the Skull/Loco markerid.
    • iconColor: The iconColor to set. Defaults to 0xff0000ff.
    • iconStyle: The iconStyle to set. Defaults to MAPICON_LOCAL.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
FAI_GetMaxHealth(npcid, &Float:health)
  • Description: Get an NPC's maxHealth.
  • Parameters:
    • npcid: The ID of the NPC to get the maxHealth of.
    • &Float:health: The variable into which to store the maxHealth, passed by reference.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
FAI_SetMaxHealth(npcid, Float:health)
  • Description: Set an NPC's maxHealth.
  • Parameters:
    • npcid: The ID of the NPC to set the maxHealth of.
    • Float:health: The maxHealth to set. If a value < 0.0 was given, it will be reset to 0.0. If the value is 0.0, the NPC will die immediately.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
  • Notes: When using very large values like >= 2 billion, bugs can occur due to overflow.
FAI_GetDisplayRange(npcid, &Float:range)
  • Description: Get an NPC's displayRange.
  • Parameters:
    • npcid: The ID of the NPC to get the displayRange of.
    • &Float:range: The variable into which to store the displayRange, passed by reference.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
FAI_SetDisplayRange(npcid, Float:range)
  • Description: Set the range at which the NPC's TextDraws should appear for a player.
  • Parameters:
    • npcid: The ID of the NPC to set the displayRange of.
    • Float:range: The displayRange to set. If a value < 0.0 was given, it will be reset to 0.0. If the value is 0.0, the NPC's TextDraws will never show.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
  • Notes:
    • The NPC's textdraws will show for a player if the NPC is valid for that player.
    • If the player is in the displayRange of more than 1 NPC, only the closest NPC will show for that player.
    • All NPC/spell textdraws are hidden for a player if that player dies.
    • If you don't want to show an NPC's textdraws at all, set that NPC's displayRange to 0.0.
FAI_GetAggroRange(npcid, &Float:range)
  • Description: Get an NPC's aggroRange.
  • Parameters:
    • npcid: The ID of the NPC to get the aggroRange of.
    • &Float:range: The variable into which to store the aggroRange, passed by reference.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
FAI_SetAggroRange(npcid, Float:range)
  • Description: Set the range at which a player aggros the NPC.
  • Parameters:
    • npcid: The ID of the NPC to set the aggroRange of.
    • Float:range: The aggroRange to set. If a value < 0.0 was given, it will be reset to 0.0. If the value is 0.0, no player will take aggro from the NPC by approaching him.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
  • Notes:
    • Setting the aggro has no effect if the NPC's behaviour is FRIENDLY, so if you don't want an NPC to aggro anyone at all, set that NPC's behaviour to FRIENDLY.
    • The aggroRange is different from the ranged and melee attack ranges.
FAI_GetDisplayIfDead(npcid)
  • Description: Get an NPC's displayIfDead.
  • Parameters:
    • npcid: The ID of the NPC to get the displayIfDead of.
  • Return values:
    • 1: The function executed successfully. DisplayIfDead is true.
    • 0: The function executed successfully. DisplayIfDead is false.
    • -1: The function failed to execute. An invalid npcid was given.
FAI_SetDisplayIfDead(npcid, bool:displayIfDead)
  • Description: Set wether the NPC's TextDraws and mapicon should keep being shown to players when the NPC is dead.
  • Parameters:
    • npcid: The ID of the NPC to set the displayIfDead of.
    • bool:displayIfDead: True to keep displaying the TextDraws, false to do not.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
  • Notes: Setting this option to true has no effect if the NPC's displayRange is 0.
FAI_GetCurrentHealth(npcid, &Float:health)
  • Description: Get an NPC's currentHealth.
  • Parameters:
    • npcid: The ID of the NPC to get the currentHealth of.
    • &Float:health: The variable into which to store the currentHealth, passed by reference.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
FAI_SetCurrentHealth(npcid, Float:health)
  • Description: Set an NPC's currentHealth which is displayed in TextDraw 2 and represented by the TextDraw 0 health bar.
  • Parameters:
    • npcid: The ID of the NPC to set the currentHealth of.
    • Float:health: The currentHealth to set. If a value < 0.0 was given, it will be reset to the NPC's maxHealth. If the value is 0.0, the NPC will die immediately.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
  • Notes: When using very large values like >= 2 billion, bugs can occur due to overflow.
FAI_GetTarget(npcid)
  • Description: Get an NPC's target.
  • Parameters:
    • npcid: The ID of the NPC to get the target of.
  • Return values:
    • Valid playerid: The function executed successfully. The NPC has a target.
    • INVALID_PLAYER_ID: The function executed successfully. The NPC has no target.
    • -1: The function failed to execute. An invalid npcid was given.
FAI_SetTarget(npcid, playerid)
  • Description: Set NPC's target which he will move to and attack.
  • Parameters:
    • npcid: The ID of the NPC to set the target of.
    • playerid: The target to set. Can be INVALID_PLAYER_ID.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given, or old target was equal to the new target, or the player was invalid for the NPC, or the player was not streamed in for the NPC.
FAI_GetMoveInfo(npcid, &type, &Float:speed, &bool:useMapAndreas, &Float:radius, &bool:setAngle)
  • Description: Get an NPC's moveType, moveSpeed, moveUseMapAndreas, moveRadius and moveSetAngle.
  • Parameters:
    • npcid: The ID of the NPC to get the moveInfo of.
    • &type: The variable into which to store the moveType, passed by reference.
    • &Float:speed: The variable into which to store the moveSpeed, passed by reference.
    • &bool:useMapAndreas: The variable into which to store the moveUseMapAndreas, passed by reference.
    • &Float:radius: The variable into which to store the moveRadius, passed by reference.
    • &bool:setAngle: The variable into which to store the moveSetAngle, passed by reference.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
FAI_SetMoveInfo(npcid, type, Float:speed, bool:useMapAndreas, Float:radius, bool:setAngle)
  • Description: Set an NPC's moveType, moveSpeed, moveUseMapAndreas, moveRadius and moveSetAngle which will determine his movement settings. See FCNPC_GoToPlayer.
  • Parameters:
    • npcid: The ID of the NPC to set the moveInfo of.
    • type: The moveType to set. Defaults to FCNPC_MOVE_TYPE_AUTO.
    • Float:speed: The moveSpeed to set. Defaults to FCNPC_MOVE_SPEED_AUTO.
    • bool:useMapAndreas: The moveUseMapAndreas to set. Defaults to false.
    • Float:radius: The moveRadius to set. Defaults to 0.0.
    • bool:setAngle: The moveSetAngle to set. Defaults to true.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
  • Notes: If useMapAndreas is true, MapAndreas must be initialized with MapAndreas_Init and the plugin address must be passed to FCNPC with FCNPC_InitMapAndreas to take effect.
FAI_GetRangedAttackInfo(npcid, &Float:range, &delay, &bool:setAngle)
  • Description: Get an NPC's rangedAttackRange, rangedAttackDelay and rangedAttackSetAngle.
  • Parameters:
    • npcid: The ID of the NPC to get the rangedAttackInfo of.
    • &Float:range: The variable into which to store the rangedAttackRange, passed by reference.
    • &delay: The variable into which to store the rangedAttackDelay, passed by reference.
    • &bool:setAngle: The variable into which to store the rangedAttackSetAngle, passed by reference.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
FAI_SetRangedAttackInfo(npcid, Float:range, delay, bool:setAngle)
  • Description: Set an NPC's rangedAttackRange, rangedAttackDelay and rangedAttackSetAngle which will determine his ranged attack settings. See FCNPC_AimAtPlayer.
  • Parameters:
    • npcid: The ID of the NPC to set the rangedAttackInfo of.
    • Float:range: The rangedAttackRange to set. Defaults to 20.0. If the value is -1, the NPC will never move while ranged attacking and will thus ranged attack from any distance.
    • delay: The rangedAttackDelay to set. Defaults to -1.
    • bool:setAngle: The rangedAttackSetAngle to set. Defaults to true.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
  • Notes: The rangedAttackRange is different from the aggro range.
FAI_GetMeleeAttackInfo(npcid, &Float:range, &delay, &bool:useFightStyle)
  • Description: Get an NPC's meleeAttackRange, meleeAttackDelay and useFightStyle.
  • Parameters:
    • npcid: The ID of the NPC to get the meleeAttackInfo of.
    • &Float:range: The variable into which to store the meleeAttackRange, passed by reference.
    • &delay: The variable into which to store the meleeAttackDelay, passed by reference.
    • &bool:useFightStyle: The variable into which to store the useFightStyle, passed by reference.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
FAI_SetMeleeAttackInfo(npcid, Float:range, delay, bool:useFightStyle)
  • Description: Set an NPC's meleeAttackRange, meleeAttackDelay and useFightStyle which will determine his melee attack settings. See FCNPC_MeleeAttack.
  • Parameters:
    • npcid: The ID of the NPC to set the meleeAttackInfo of.
    • Float:range: The meleeAttackRange to set. Defaults to 1.0. If the value is -1, the NPC will never move while melee attacking and will thus melee attack from any distance.
    • delay: The meleeAttackDelay to set. Defaults to -1.
    • bool:useFightStyle : The useFightStyle to set. Defaults to false.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
  • Notes:
    • If the NPC should attack with the equipped melee weapon instead of with his fists, set useFightStyle to false. If the NPC should attack with his fists, regardless if he has a melee weapon equipped, set useFightStyle to true.
    • The meleeAttackRange is different from the aggro range.
FAI_GetAllowNPCTargets(npcid)
  • Description: Get an NPC's allowNPCTargets.
  • Parameters:
    • npcid: The ID of the NPC to get the allowNPCTargets of.
  • Return values:
    • 1: The function executed successfully. AllowNPCTargets is true.
    • 0: The function executed successfully. AllowNPCTargets is false.
    • -1: The function failed to execute. An invalid npcid was given.
FAI_SetAllowNPCTargets(npcid, bool:allowNPCTargets)
  • Description: Set wether the NPC can target NPC's.
  • Parameters:
    • npcid: The ID of the NPC to set the allowNPCTargets of.
    • bool:allowNPCTargets: True to allow NPC targets, false to do not.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
FAI_GetBehaviour(npcid)
  • Description: Get an NPC's behaviour.
  • Parameters:
    • npcid: The ID of the NPC to get the behaviour of.
  • Return values:
    • Valid behaviour: The function executed successfully.
    • -1: The function failed to execute. An invalid npcid was given.
FAI_SetBehaviour(npcid, behaviour)
  • Description: Set wether the NPC will attack on sight, on damage or not at all.
  • Parameters:
    • npcid: The ID of the NPC to set the behaviour of.
    • behaviour: The behaviour to set.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given, or an invalid behaviour was given.
FAI_DestroyNPC(npcid)
  • Description: Destroys an NPC that was created using one of the FAI_Create functions.
  • Parameters:
    • npcid: The ID of the NPC to destroy.
  • Return values:
    • 1: The function executed successfully.
    • 0: The function failed to execute. An invalid npcid was given.
FAI_DestroyAll()
  • Description: Destroys all NPCs that were created using one of the FAI_Create functions. This function gets executed automatically when OnFilterScriptExit is called, if the include is included in a filterscript, or when OnGameModeExit is called, if the include is included in a gamemode.
  • Parameters: This function has no parameters.
  • Return values: This function always returns 1.
FAI_IsValidForPlayer(playerid, npcid)
  • Description: Checks if a player is valid for an NPC.
  • Parameters:
    • playerid: The ID of the player to check if he is valid for the NPC.
    • npcid: The ID of the NPC to check the player for.
  • Return values: (bool)
    • true: The player is connected, the NPC is valid, the player is not equal to the NPC's npcid, (the NPC is not dead or the NPC's displayIfDead is true), (the player is no npc and his interior equals the NPC's interior and his world equals the NPC's world and his state is not equal to PLAYER_STATE_NONE and his state is not equal to PLAYER_STATE_WASTED and his state is not equal to PLAYER_STATE_SPAWNED and his state is not equal to PLAYER_STATE_SPECTATING and he hasn't got his game paused) or (the player is an npc created with FCNPC and he is valid and he is spawned and he is not dead and his interior equals the NPC's interior and his world equals the NPC's world).
    • false: The player is not valid for the NPC.
FAI_IsPlayerInDisplayRange(playerid, npcid)
  • Description: Checks if a player is in the displayRange of an NPC.
  • Parameters:
    • playerid: The ID of the player to check.
    • npcid: The ID of the NPC to check.
  • Return values: (bool)
    • true: The player is in the displayRange.
    • false: The player is not in the displayRange, or the player is not connected or the NPC is not valid or the player is not valid for the NPC.
FAI_IsPlayerInAggroRange(playerid, npcid)
  • Description: Checks if a player is in the aggroRange of an NPC.
  • Parameters:
    • playerid: The ID of the player to check.
    • npcid: The ID of the NPC to check.
  • Return values: (bool)
    • true: The player is in the aggroRange .
    • false: The player is not in the aggroRange , or the player is not connected or the NPC is not valid or the player is not valid for the NPC.
FAI_HasMeleeWeapons(npcid)
  • Description: Checks if an NPC currently has a melee weapon equipped.
  • Parameters:
    • npcid: The ID of the NPC to check.
  • Return values: (bool)
    • true: The NPC has a melee weapon equipped.
    • false: The NPC has no melee weapon equipped. Or an invalid npcid was given.
FAI_GetTextDraw(npcid, textdraw)
  • Description: Get one of an NPC's TextDraw IDs.
  • Parameters:
    • npcid: The ID of the NPC to get the TextDraw of.
    • textdraw: The TextDraw of the NPC.
  • Return values: (Text)
    • Text:Valid TextDraw: The function executed successfully.
    • Text:INVALID_TEXT_DRAW: The function failed to execute. An invalid npcid was given, or a textdraw < 0 was given, or a textdraw > = FAI_MAX_TEXTDRAWS was given.
FAI_GetCurrentHealthPercent(npcid)
  • Description: Get an NPC's currentHealthPercent which is displayed in TextDraw 1. This will be different from just using currentHealth / maxHealth * 100, because floatround_ceil is used for various reasons.
  • Parameters:
    • npcid: The ID of the NPC to get the currentHealthPercent of.
  • Return values:
    • Valid percent: The function executed successfully.
    • -1: The function failed to execute. An invalid npcid was given.
FAI_Damage(npcid, damagerid, Float:amount)
  • Description: Damage an NPC.
  • Parameters:
    • npcid: The ID of the NPC to damage.
    • damagerid: The ID of the player that gets credit for the damage. Can be INVALID_PLAYER_ID.
    • Float:amount: The amount of damage to be afflicted.
  • Return values:
    • 1: The NPC died because of the damage.
    • 0: The NPC didn't die, or the NPC is not valid, or the damagerid is not connected, or the NPC is already dead, or the players's interior doesn't equal the NPC's interior.
  • Notes: Internally, there will be checked if the NPC's interior is equal to the players's interior, because the NPC is visible and thus damagable in other interiors.
FAI_Heal(npcid, healerid, Float:amount)
  • Description: Heal an NPC.
  • Parameters:
    • npcid: The ID of the NPC to heal.
    • healerid: The ID of the player that gets credit for the healing. Can be INVALID_PLAYER_ID.
    • Float:amount: The amount of healing to be afflicted.
  • Return values:
    • 1: The NPC healed fully because of the healing.
    • 0: The NPC didn't heal fully, or the NPC is not valid, or the healerid is not connected, or the NPC is dead.
FAI_IsEncounterStarted(npcid)
  • Description: Checks if an NPC encounter is started.
  • Parameters:
    • npcid: The ID of the NPC to check the encounter state of.
  • Return values: (bool)
    • true: The NPC's encounter has started.
    • false: The NPC's encounter has not been started. Or an invalid npcid was given.
FAI_StopEncounter(npcid)
  • Description: Stop an encounter of an NPC.
  • Parameters:
    • npcid: The ID of the NPC to stop the encounter of.
  • Return values:
    • 1: The function executed successfully, regardless if the NPC's encounter was started or not.
    • 0: An invalid npcid was given.