LibAction

Introduction

This is a module for npc program which is to be placed in the npcscripts/plugins folder.

Features

• Single command ShootPlayer( pid ) and npc starts shooting at the player.
• Aim Pos and Aim Dir for shooting are internally calculated and user has the option to correct it for more accuracy.
• Rich callbacks: just before shooting (for correction of aimpos/dir), target out of range or ran out of ammo/gun.
• No timers/loops.
• Internally calculate clipsize, firing rate of weapons and do the reloading animation too.

Callbacks

These callbacks are optional and are meant to add additional functionality to your scripts.

1. OnTargetCleared

OnTargetCleared([integer]targetpid, [integer]reason)

The value of reason can be:

Constant
AMMO_SHORTAGE
PLAYER_WASTED
PLAYER_STREAMEDOUT
INSTRUCTION_RECEIVED

2. OnTargetOutOfRange

OnTargetOutOfRange([integer]targetid)

Called when target is out of range of the weaponrange of the current weapon of npc. If target is not cleared, npc resumes shooting when target comes in range again.

3. OnPullTrigger

OnPullTrigger([integer] keys, [Vector]pos,  [float]angle, [integer]health, [integer]armour, [integer]weapon, [integer]ammo, [Vector]speed, [Vector]aimpos, [Vector]aimdir, [bool]isCrouching, [bool]isReloading )

This event is called just before sending the Aiming Packet( with decreased ammo) to server. The purpose is to manually change the aimpos/aimdir for accuracy.
0.4.7.1 servers need Bullet-fired packet also in order to actually fire bullets. If this packet is not send, then npc may animate shooting, but no bullets will be fired. The function FireBullet sends this packet. It need weapon id and source-pos from which bullet starts moving. Usually pos.x, pos.y, pos.z + 0.5 will work. The 0.5 is needed, otherwise it will appear that from a point approx. 0.5 below the gun of npc, bullets starts coming. If still, it is not correct, you can adjust it in the FireBullet function.
To manually change, Call SendOnFootSyncDataEx at this point and then call FireBullet as well and return false.

function OnPullTrigger(keys, pos, angle, health, armour, weapon, ammo, speed, aimpos, aimdir, isCrouching, isReloading)
{
    aimpos=...       //changing or correcting
    aimdir= ...

    ...

    SendOnFootSyncDataEx(keys, pos, angle, health, armour, weapon, ammo, speed, aimpos, aimdir, isCrouching, isReloading);
    FireBullet(weapon, pos.z+0.5, pos.y, pos.x ); //In 0.4.7.1, this is needed to fire bullets.
    return false;    //we send it and library need not send it again.
}

The automatic sending of aim packet depends on the return value of this function:

return value
false	will not send packet, assuming the user send it using SendOnFootSyncDataEx or similar functions
0	"
null (or no return value)	"

4. OnWeaponChange

OnWeaponChange(oldwepid, newwepid )

This function is called when npc changes it's weapon when shooting( ran out of ammo of one weapon, but has another weapon).

Functions

1. ShootPlayer

ShootPlayer([integer]playerid)

The npc pickup a gun from it's available weapons and starts shooting at the player. To shoot with a specific gun set the weapon of npc prior to the call. From npcscripts this can be done using SetLocalValue with field I_CURWEP
return value: true on success, false on failure (player not streamed in or no proper gun available)

2. ClearTarget

ClearTarget()

Clears the target and calls OnTargetCleared with reason as INSTRUCTION_RECEIVED
return vaue: true (if the npc had a target) or false( if the npc did not had a target)

3. GetTarget

GetTarget()

return value: The player ID of the target or -1 if there is no target.

Supported Guns

• The npc will shoot it's target if one or more of the weapons is available to it.

Weapons with ID: 17 - 27, 32, 33

• The npc will automatically change weapon, when it ran of out of ammo of one weapon.

Limitation

• This library can be used only to shoot other players, but npc cannot take damage. To give damage to npc, the proper way might be as follows:

1. Watch for damage using Client side function OnPlayerShoot
2. Some weapons will not trigger OnPlayerShoot properly, use RayTrace in client side at that point possibly using aimpos or aimdir. Some of this trick the author has done in the Attack_Script(Download it and see)
3. When you are sure that npc's health should be reduced from 100 to 75 for example, use SetLocalValue(I_HEALTH, 75). This will prevent sending packet as opposed to player.Health=75 and the heath will be reflected through the next aim packet.
4. Using LibRPC library, the step 3 ( of calling SetLocalValue ) can be done from server-side:

RFC(npcid, "SetLocalValue")(F(F("compilestring")("return I_HEALTH"))(), 75);

or simply:

RFC(npcid, "SetLocalValue")(5, 75); //since I_HEALTH = 5 in current version.

API Info

• Requires API 1.1

Example

server-side (scripts/main.nut):

ConnectNPC("bot","shoot.nut",false,"","rpclib actionlib");

The following script waits for a player to come near a distance of 40 units and it do nothing even if the player has gun. But as soon as the player starts shooting, the npc also starts shooting and at the player.
npc-script (npcscripts/shoot.nut):

function OnNPCScriptLoad( params )
{
	SetTimerEx("Check", 200, 0);
}

function Check()
{
	if(GetTarget()!=-1)
	return;
	
	for(local i=0;i<100;i++)
	{
		if(IsPlayerConnected(i)&&IsPlayerStreamedIn(i))
		{
			if(GetPlayerState(i)==PLAYER_STATE_AIM)
			{
				if(GetDistanceFromMeToPoint(GetPlayerPos(i))<40)
				{
					if( GetTarget()== -1 )
						ShootPlayer(i);
				}
			}
		}
	}
}

Availability

The module is available with NPC v.1.6 Beta3 (20.Feb.2023)