Difference between revisions of "Lua:Interaction"

From Fortress Forever Wiki
Jump to navigationJump to search
m
 
(11 intermediate revisions by 5 users not shown)
Line 1: Line 1:
−
FryGuy needs to fill out this page.
+
{{Infobox mapping}}
 +
{{Infobox manual/Header}}
 +
== Introduction ==
 +
For all of the following events, the first parameter to the function will be the player that caused the event, where applicable. The '''entid''' global variable will be set which contains the entity that fired the event. Additionally, more global variables may be set and read by the engine depending on the event.
  
−
[[Category:LUA]]
+
Whenever an event is called, the engine will run the lua command '''<entity name>:<event name>()'''. This means that if you have an info_ff_script entity named '''red_flag''' and the event '''touch''' is being called, then '''red_flag:touch(12)''' may be called, if the player with id 12 touches the flag.
 +
 
 +
The following is a good way to define entities:
 +
<pre>
 +
red_flag = info_ff_script:new({})
 +
function red_flag:touch(player_id)
 +
  if GetPlayerTeam(player_id) == TEAM_BLUE then
 +
      Pickup( entid, player_id )
 +
  end
 +
end
 +
</pre>
 +
Note that the way objects are created in lua is slightly confusing, so reading [http://www.lua.org/pil Programming in Lua] may be helpful.
 +
 
 +
 
 +
== Global Events ==
 +
These are functions that are called by the engine that do not belong inside any class. Simply declare them as globals in the lua namespace by doing something like the following:
 +
<pre>
 +
function precache()
 +
  --stuff here
 +
end
 +
</pre>
 +
 
 +
=== tick() ===
 +
This function is called every second by the engine. Note that this function is in use by base.lua, so should not be declared again. To interface with this command, it must be [[hooked]]. A better method would be to use the scheduling interface may be found in the scheduling section of the API.
 +
 
 +
=== precache() ===
 +
This function is called when the map starts, before entities have been initialized. The main purpose of this is to precache all sound elements that
 +
 
 +
=== startup() ===
 +
This function is called when the map starts, after all the entities have been initialized. The main purpose of this function is to set properties of entities or teams, as well as initialize lua variables. Note that lua variables may be initialized outside this function however.
 +
 
 +
=== player_spawn() ===
 +
This function is called whenever a player spawns in this map.
 +
 
 +
Here is an example of giving the player full health, full armor, full rockets, full shells, and 1 grenade upon spawning (player_id is the player this event is called on and must be passed in to the functions used as shown in the example):
 +
<pre>
 +
function player_spawn( player_id )
 +
-- 400 for overkill. of course the values
 +
-- get clamped in game code
 +
AddHealth( player_id, 400 )
 +
AddArmor( player_id, 400 )
 +
 
 +
AddAmmo( player_id, "AMMO_NAILS", -400 )
 +
AddAmmo( player_id, "AMMO_SHELLS", 400 )
 +
AddAmmo( player_id, "AMMO_ROCKETS", 400 )
 +
AddAmmo( player_id, "AMMO_CELLS", -400 )
 +
AddAmmo( player_id, "AMMO_DETPACK", -1 )
 +
AddAmmo( player_id, "AMMO_RADIOTAG", -400 )
 +
AddAmmo( player_id, "AMMO_GREN1", -4 )
 +
AddAmmo( player_id, "AMMO_GREN2", -4 )
 +
 
 +
-- Players get 1 gren1
 +
AddAmmo( player_id, "AMMO_GREN1", 1 )
 +
end
 +
</pre>
 +
 
 +
=== player_killed() ===
 +
This function is called whenever a player dies. The global variable "killer" will be set, which contains the player that killed this player.
 +
 
 +
Here's an example if you wanted to give your team a point when you killed someone not on your team:
 +
<pre>
 +
function player_killed( player_id )
 +
-- If you kill someone, give your team a point
 +
if GetPlayerTeam( killer ) then
 +
if not ( GetPlayerTeam( player_id ) == GetPlayerTeam( killer ) ) then
 +
AddTeamScore( GetPlayerTeam( killer ), 1 )
 +
end
 +
end
 +
end
 +
</pre>
 +
 
 +
=== player_ondamage() ===
 +
This function is called whenever a player takes damage. The following variables are set in the global lua namespace before this function is called:
 +
*info_damage: The amount of damage that the player will recieve.
 +
*info_attacker: The player that fired the attack.
 +
*info_classname: The classname of the weapon that hit the player. Note that this may be the classname of the projectile for projectile weapons, or the classname of the weapon for non-projectile weapons.
 +
This function may modify the info_damage global variable in the global scope. If it does, the damage the player takes will be changed. This means that the script for a map can make players recieve more  or less damage through scripting. Here is an example script that makes the player take no damage from the super shotgun.
 +
<pre>
 +
function player_ondamage(player_id)
 +
ConsoleToAll(GetPlayerName(info_attacker).." shot "..GetPlayerName(player_id).." with a "..info_classname.." for "..info_damage.." damage")
 +
if info_classname == "ff_weapon_supershotgun" then
 +
ConsoleToAll("Take no damage from supershotty")
 +
info_damage = 0
 +
end
 +
end
 +
</pre>
 +
 
 +
Here's another example in case you wanted to not take damage from your own rockets:
 +
<pre>
 +
function player_ondamage( player_id )
 +
 
 +
-- Don't take rocket damage from ourselves
 +
if ( player_id == info_attacker ) then
 +
if ( info_classname == "rocket" ) then
 +
info_damage = 0
 +
end
 +
end
 +
end
 +
</pre>
 +
 
 +
TODO: Provide list of info_classname values
 +
 
 +
=== flaginfo() ===
 +
TODO: Add shit
 +
 
 +
== info_ff_script entity ==
 +
To create scripting for info_ff_script entities, simply extend the base info_ff_script class that is defined in base.lua and add functionality. Alternatively, you may extend the predefined classes [[#genericbackpack]] for respawning items or [[#baseflag]] for items the player may carry.
 +
 
 +
=== precache() ===
 +
This function is called when the entity has started to spawn and needs to precache any models that this entity needs.
 +
 
 +
=== spawn() ===
 +
This function is called when the entity has finished spawning so that the model for it can be set as well as initialize any variables for this script.
 +
 
 +
=== touch() ===
 +
This function is called when this entity is touched by a player.
 +
 
 +
=== ownerdie() ===
 +
This function is called when the player carrying this item (if it is attached to a player) dies.
 +
 
 +
=== materialize() ===
 +
This function is called when this item has finished waiting to respawn and has respawned.
 +
 
 +
=== ondrop() ===
 +
This function is called whenever the player dies or drops the item.
 +
 
 +
=== onloseitem() ===
 +
This function is called whenever the player loses this item for any reason (drops it, or is captured).
 +
 
 +
=== onreturn() ===
 +
This function is called when the item has been unattached to a player for the specified amount of time and it returns to its starting point.
 +
 
 +
=== dropitemcmd() ===
 +
This function is called when the player that has this item presses the [[Command:dropitems|dropitems command]].
 +
 
 +
== info_ff_teamspawn ==
 +
This entity is used to control where players spawn at. The engine will choose a spawn point where the player can spawn it and call the validspawn() function (see below). If it returns true then the player will spawn at this entity's location. Otherwise, the engine will attempt to spawn the player at the next spawn point. If no spawn points are valid, then it will pick a random one and spawn the player there.
 +
 
 +
=== validspawn() ===
 +
This function is called whenever a player attempts to spawn at this location. Return true if the player can spawn here, otherwise return false.
 +
 
 +
== func_button ==
 +
 
 +
=== ondamage() ===
 +
See [[#player_ondamage]] for parameter information. Additionally, if info_damage is set to 0 by the script, or the function returns false, the button will not be fired by this press. An example of allowing only spanners to hit a button:
 +
<pre>
 +
bob = func_button:new({})
 +
function bob:ondamage()
 +
ConsoleToAll(GetPlayerName(info_attacker).." shot button with a "..info_classname.." for "..info_damage.." damage")
 +
if info_classname == "ff_weapon_spanner" then
 +
PressButton(entname)
 +
end
 +
end
 +
</pre>
 +
 
 +
=== allowed() ===
 +
This function will be called whenever this button is attempted to be pressed. If it returns true, then the button will fire, otherwise it will not.
 +
 
 +
== trigger_ff_script and trigger_multiple ==
 +
These entities are exactly the same. Most of these functions will also work with the other trigger_* entities.
 +
 
 +
=== allowed() ===
 +
Called when the engine needs to know if the player in the first parameter of this function is allowed to trigger this entity. Return true from this function if the trigger is allowed, otherwise return false.
 +
 
 +
=== onfailtouch() ===
 +
Called when allowed() returns false.
 +
 
 +
=== ontouch() ===
 +
Called when a player starts touching this entity.
 +
 
 +
=== onendtouch() ===
 +
Called when a player stops touching this entity.
 +
 
 +
=== ontrigger() ===
 +
Called when this entity is triggered. Note that this takes into account the wait time of this trigger, whereas ontouch() does not.
 +
 
 +
{{Infobox manual/Footer}}

Latest revision as of 22:40, 20 July 2009

Mapping for FF
The Basics

Setting up Hammer
Getting Started With Lua
Releasing a map

FF-specific Entities

Lua location system

Map Templates
FF Lua Documentation

Entity Typing
Entity Collections

Commands
Callbacks


Introduction

For all of the following events, the first parameter to the function will be the player that caused the event, where applicable. The entid global variable will be set which contains the entity that fired the event. Additionally, more global variables may be set and read by the engine depending on the event.

Whenever an event is called, the engine will run the lua command <entity name>:<event name>(). This means that if you have an info_ff_script entity named red_flag and the event touch is being called, then red_flag:touch(12) may be called, if the player with id 12 touches the flag.

The following is a good way to define entities: 

red_flag = info_ff_script:new({})
function red_flag:touch(player_id)
   if GetPlayerTeam(player_id) == TEAM_BLUE then
      Pickup( entid, player_id )
   end
end

Note that the way objects are created in lua is slightly confusing, so reading Programming in Lua may be helpful.


Global Events

These are functions that are called by the engine that do not belong inside any class. Simply declare them as globals in the lua namespace by doing something like the following: 

function precache()
   --stuff here
end

tick()

This function is called every second by the engine. Note that this function is in use by base.lua, so should not be declared again. To interface with this command, it must be hooked. A better method would be to use the scheduling interface may be found in the scheduling section of the API.

precache()

This function is called when the map starts, before entities have been initialized. The main purpose of this is to precache all sound elements that

startup()

This function is called when the map starts, after all the entities have been initialized. The main purpose of this function is to set properties of entities or teams, as well as initialize lua variables. Note that lua variables may be initialized outside this function however.

player_spawn()

This function is called whenever a player spawns in this map.

Here is an example of giving the player full health, full armor, full rockets, full shells, and 1 grenade upon spawning (player_id is the player this event is called on and must be passed in to the functions used as shown in the example): 

function player_spawn( player_id )
	-- 400 for overkill. of course the values
	-- get clamped in game code
	AddHealth( player_id, 400 )
	AddArmor( player_id, 400 )

	AddAmmo( player_id, "AMMO_NAILS", -400 )
	AddAmmo( player_id, "AMMO_SHELLS", 400 )
	AddAmmo( player_id, "AMMO_ROCKETS", 400 )
	AddAmmo( player_id, "AMMO_CELLS", -400 )
	AddAmmo( player_id, "AMMO_DETPACK", -1 )
	AddAmmo( player_id, "AMMO_RADIOTAG", -400 )
	AddAmmo( player_id, "AMMO_GREN1", -4 )
	AddAmmo( player_id, "AMMO_GREN2", -4 )

	-- Players get 1 gren1
	AddAmmo( player_id, "AMMO_GREN1", 1 )
end

player_killed()

This function is called whenever a player dies. The global variable "killer" will be set, which contains the player that killed this player.

Here's an example if you wanted to give your team a point when you killed someone not on your team: 

function player_killed( player_id )
	-- If you kill someone, give your team a point
	if GetPlayerTeam( killer ) then
		if not ( GetPlayerTeam( player_id ) == GetPlayerTeam( killer ) ) then
			AddTeamScore( GetPlayerTeam( killer ), 1 )
		end
	end
end

player_ondamage()

This function is called whenever a player takes damage. The following variables are set in the global lua namespace before this function is called:

  • info_damage: The amount of damage that the player will recieve.
  • info_attacker: The player that fired the attack.
  • info_classname: The classname of the weapon that hit the player. Note that this may be the classname of the projectile for projectile weapons, or the classname of the weapon for non-projectile weapons.

This function may modify the info_damage global variable in the global scope. If it does, the damage the player takes will be changed. This means that the script for a map can make players recieve more or less damage through scripting. Here is an example script that makes the player take no damage from the super shotgun. 

function player_ondamage(player_id)
	ConsoleToAll(GetPlayerName(info_attacker).." shot "..GetPlayerName(player_id).." with a "..info_classname.." for "..info_damage.." damage")
	if info_classname == "ff_weapon_supershotgun" then
		ConsoleToAll("Take no damage from supershotty")
		info_damage = 0
	end
end

Here's another example in case you wanted to not take damage from your own rockets: 

function player_ondamage( player_id )

	-- Don't take rocket damage from ourselves
	if ( player_id == info_attacker ) then
		if ( info_classname == "rocket" ) then
			info_damage = 0
		end
	end
end

TODO: Provide list of info_classname values

flaginfo()

TODO: Add shit

info_ff_script entity

To create scripting for info_ff_script entities, simply extend the base info_ff_script class that is defined in base.lua and add functionality. Alternatively, you may extend the predefined classes #genericbackpack for respawning items or #baseflag for items the player may carry.

precache()

This function is called when the entity has started to spawn and needs to precache any models that this entity needs.

spawn()

This function is called when the entity has finished spawning so that the model for it can be set as well as initialize any variables for this script.

touch()

This function is called when this entity is touched by a player.

ownerdie()

This function is called when the player carrying this item (if it is attached to a player) dies.

materialize()

This function is called when this item has finished waiting to respawn and has respawned.

ondrop()

This function is called whenever the player dies or drops the item.

onloseitem()

This function is called whenever the player loses this item for any reason (drops it, or is captured).

onreturn()

This function is called when the item has been unattached to a player for the specified amount of time and it returns to its starting point.

dropitemcmd()

This function is called when the player that has this item presses the dropitems command.

info_ff_teamspawn

This entity is used to control where players spawn at. The engine will choose a spawn point where the player can spawn it and call the validspawn() function (see below). If it returns true then the player will spawn at this entity's location. Otherwise, the engine will attempt to spawn the player at the next spawn point. If no spawn points are valid, then it will pick a random one and spawn the player there.

validspawn()

This function is called whenever a player attempts to spawn at this location. Return true if the player can spawn here, otherwise return false.

func_button

ondamage()

See #player_ondamage for parameter information. Additionally, if info_damage is set to 0 by the script, or the function returns false, the button will not be fired by this press. An example of allowing only spanners to hit a button: 

bob = func_button:new({})
function bob:ondamage()
	ConsoleToAll(GetPlayerName(info_attacker).." shot button with a "..info_classname.." for "..info_damage.." damage")
	if info_classname == "ff_weapon_spanner" then
		PressButton(entname)
	end
end

allowed()

This function will be called whenever this button is attempted to be pressed. If it returns true, then the button will fire, otherwise it will not.

trigger_ff_script and trigger_multiple

These entities are exactly the same. Most of these functions will also work with the other trigger_* entities.

allowed()

Called when the engine needs to know if the player in the first parameter of this function is allowed to trigger this entity. Return true from this function if the trigger is allowed, otherwise return false.

onfailtouch()

Called when allowed() returns false.

ontouch()

Called when a player starts touching this entity.

onendtouch()

Called when a player stops touching this entity.

ontrigger()

Called when this entity is triggered. Note that this takes into account the wait time of this trigger, whereas ontouch() does not.


Retrieved from "https://www.fortress-forever.com/wiki/index.php?title=Lua:Interaction&oldid=9225"