./game_lib.lua

  1. -- Exclude the following functions from automatic documentation generation 
  2. --[[DocGenExclude: 
  3. character_is_ready_to_speak 
  4. group_create_check_done_loop 
  5. helicopter_fly_to_internal 
  6. ]] 
  7.  
  8. -------------------- 
  9. -- Script Globals -- 
  10. -------------------- 
  11.  
  12. MINIMAP_ICON_KILL								= "icon_class_kill" 
  13. MINIMAP_ICON_PROTECT_ACQUIRE				= "icon_class_protectacquire" 
  14. MINIMAP_ICON_LOCATION						= "icon_class_location" 
  15. MINIMAP_ICON_USE								= "icon_class_use" 
  16. MINIMAP_ICON_SAINTS							= "icon_class_saints" 
  17. MINIMAP_ICON_SYNDICATE						= "icon_class_syndicate" 
  18.  
  19. INGAME_EFFECT_LOCATION						= "vfx_missioncheckPointicon" 
  20. INGAME_EFFECT_CUTSCENE						= "mission_purchase" 
  21. INGAME_EFFECT_MP_TUTORIAL					= "mission_complete_mp" 
  22.  
  23. INGAME_EFFECT_VEHICLE_INTERACT			= "Icon_lg_b" 
  24. INGAME_EFFECT_VEHICLE_PROTECT_ACQUIRE	= "Icon_lg_c" 
  25. INGAME_EFFECT_VEHICLE_KILL					= "Icon_lg_d" 
  26.  
  27. INGAME_EFFECT_VEHICLE_LOCATION			= "vfx_missioncheckPointCar" 
  28. INGAME_EFFECT_VEHICLE_CUTSCENE			= "vfx_missioncheckPointCar" 
  29.  
  30. INGAME_EFFECT_CHECKPOINT					= "vfx_missioncheckPointicon" 
  31.  
  32. -- Object Indicator Assets 
  33. OI_ASSET_INVALID	  = -1 
  34. OI_ASSET_KILL		  = 0 
  35. OI_ASSET_DEFEND	  = 1 
  36. OI_ASSET_USE		  = 2 
  37. OI_ASSET_REVIVE	  = 3 
  38. OI_ASSET_LOCATION	  = 4 
  39. OI_ASSET_COOP		  = 5 
  40. OI_ASSET_KILL_FULL  = 6 
  41. OI_ASSET_FINSHER    = 7 -- Not used in lua, just here so we stay in sync with C. 
  42. OI_ASSET_KILL_TIRES = 8 
  43. OI_ASSET_HITMAN     = 9 
  44. OI_ASSET_CHOP_SHOP  = 10 
  45. OI_ASSET_ALL        = 11 -- Not used in lua, just here so we stay in sync with C. 
  46. OI_ASSET_SYNDICATE  = 12 
  47. OI_ASSET_GRENADE 		= 13 
  48.  
  49.  
  50.  
  51. -- This must match the flags defined in object_indicators.h 
  52. OI_FLAG_NONE					= 0x00 
  53. OI_FLAG_STICKY					= 0x01 
  54. OI_FLAG_DISPLAY_DISTANCE	= 0x02 
  55. OI_FLAG_PULSE					= 0x04 
  56. OI_FLAG_FADE					= 0x08 
  57. OI_FLAG_PARTIAL_HIDE			= 0x10 
  58. OI_FLAGS_DEFAULT				= OI_FLAG_STICKY + OI_FLAG_DISPLAY_DISTANCE + OI_FLAG_PARTIAL_HIDE 
  59. OI_FLAGS_LOCATION				= OI_FLAG_STICKY + OI_FLAG_DISPLAY_DISTANCE + OI_FLAG_PULSE 
  60. OI_FLAGS_FULL					= OI_FLAG_STICKY + OI_FLAG_DISPLAY_DISTANCE 
  61.  
  62. SYNC_LOCAL	= 1 
  63. SYNC_REMOTE = 2 
  64. SYNC_ALL		= 3 
  65.  
  66. VAULT_SEQUENCE = 0 
  67. BALL_SEQUENCE = 1 
  68.  
  69. MAX_NOTORIETY_LEVEL		= 5 
  70. INVALID_THREAD_HANDLE	= -1 
  71. INVALID_CONVERSATION_HANDLE = -1 
  72. INVALID_PERSONA_HANDLE = 0 
  73. INVALID_MESSAGE_HANDLE = -1  
  74.  
  75. MISSION_START_CHECKPOINT = "mission start" 
  76.  
  77. LOCAL_PLAYER	= "#PLAYER1#" 
  78. REMOTE_PLAYER	= "#PLAYER2#" 
  79. CLOSEST_PLAYER = "#CLOSEST_PLAYER#" 
  80. CLOSEST_TEAM1	= "#CLOSEST_TEAM1#" 
  81. CLOSEST_TEAM2	= "#CLOSEST_TEAM2#" 
  82.  
  83. PLAYER_TAG_LIST = { 
  84. 	"#PLAYER1#", 
  85. 	"#PLAYER2#", 
  86. 	"#PLAYER3#", 
  87. 	"#PLAYER4#", 
  88. 	"#PLAYER5#", 
  89. 	"#PLAYER6#", 
  90. 	"#PLAYER7#", 
  91. 	"#PLAYER8#" 
  92. } 
  93.  
  94. WEAPON_SLOT_NONE			= -1 
  95. WEAPON_SLOT_UNARMED		= 0 
  96. WEAPON_SLOT_MELEE			= 1 
  97. WEAPON_SLOT_PISTOL		= 2 
  98. WEAPON_SLOT_SMG			= 3 
  99. WEAPON_SLOT_SHOTGUN		= 4 
  100. WEAPON_SLOT_RIFLE			= 5 
  101. WEAPON_SLOT_EXPLOSIVE	= 6 
  102. WEAPON_SLOT_SPECIAL		= 7 
  103.  
  104. Mission_waypoint		= -1 
  105.  
  106. VT_AUTOMOBILE	= 0 
  107. VT_MOTORCYCLE	= 1 
  108. VT_AIRPLANE		= 2 
  109. VT_HELICOPTER	= 3 
  110. VT_VTOL			= 4 
  111. VT_WATERCRAFT	= 5 
  112. -- This means the player isn't in a vehicle. 
  113. VT_NONE			= 6 
  114.  
  115. IS_MOVER		= 1 
  116. IS_ITEM			= 2 
  117. INDETERMINATE	= 3 
  118.  
  119. VST_AMBULANCE = 0 
  120. VST_BUS = 1 
  121. VST_FBI = 2 
  122. VST_FIRETRUCK = 3 
  123. VST_INDUSTRIAL = 4 
  124. VST_METER_MAID = 5 
  125. VST_NEWS_VAN = 6 
  126. VST_POLICE = 7 
  127. VST_SWAT_VAN = 8 
  128. VST_TAXI = 9 
  129. VST_TOW_TRUCK = 10 
  130. VST_LIMO = 11 
  131. VST_ATV = 12 
  132. VST_TANK = 14 
  133. -- This player's vehicle isn't special or 
  134. -- this player isn't in a vehicle. 
  135. VST_NONE = 13 
  136.  
  137. -- Gender types 
  138. GT_NONE = 0 
  139. GT_MALE = 1 
  140. GT_FEMALE = 2 
  141.  
  142. -- Enable/Disable 
  143. ENABLE = true 
  144. DISABLE = false 
  145.  
  146. -- Trigger event state tracker globals 
  147. UPDATE_DEACTIVATED = 1 
  148. ALL_PLAYERS_DEACTIVATED = 2 
  149. ANY_PLAYER_DEACTIVATED = 3 
  150. UPDATE_ACTIVATED = 4 
  151. ALL_PLAYERS_ACTIVATED = 5 
  152. ALL_PLAYERS_ACTIVATED_RESET = 6 
  153. TRIGGER_MULTIPLE_TIMES = 7 
  154. TRIGGER_ONCE_FIRST_TRIGGERER = 8 
  155. TRIGGER_ONCE_PER_PLAYER = 9 
  156.  
  157. -- Parameters for use with npc_set_boss_ai 
  158. AI_BOSS_JYUNICHI = "Jyunichi" 
  159. AI_BOSS_AKUJI = "Akuji" 
  160.  
  161. START_FADE_OUT_TIME = 1.0 
  162. START_FADE_IN_TIME = 2.0 
  163. DEFAULT_END_DELAY_TIME = 2.0 
  164. DEFAULT_END_FADE_OUT_TIME = 3.0 
  165.  
  166. -- Persona override types 
  167. POT_ATTACK				= 1 
  168. POT_TAKE_DAMAGE		= 2 
  169. -- POT_TAUNT_NEGATIVE	= 3 (PA 7-14-08. There is no longer code-side support for this override type.) 
  170. POT_CUSTOM_1			= 4 
  171. POT_CUSTOM_2			= 5 
  172. POT_PRAISED_BY_PC		= 6 
  173. POT_TAUNTED_BY_PC		= 7 
  174. POT_BARTER				= 8 
  175. POT_GRATS_PC			= 9 
  176. POT_GRATS_SELF			= 10 
  177. POT_HIT_CAR				= 11 
  178. POT_HIT_OBJ				= 12 
  179. POT_HIT_PED				= 13 
  180.  
  181. -- Build types 
  182. BUILD_TYPE_NORMAL			= 1 
  183. BUILD_TYPE_AUSTRALIAN	= 2 
  184. BUILD_TYPE_GERMAN			= 3 
  185. BUILD_TYPE_JAPANESE_360	= 4 
  186. BUILD_TYPE_JAPANESE_PS3	= 5 
  187.  
  188. -- Persona situations associated w/ each override type 
  189. POT_SITUATIONS = { 
  190. 	[POT_ATTACK]			=	{"threat - alert (group attack)", 
  191. 									 "threat - alert (solo attack)"}, 
  192. 	[POT_TAKE_DAMAGE]		=	{"take damage",  
  193. 									 "threat - damage received (firearm)", 
  194. 									 "threat - damage received (melee)", 
  195. 									 "threat - damage received (vehicle)"}, 
  196. 	[POT_CUSTOM_1]			=	{"custom line 1"}, 
  197. 	[POT_CUSTOM_2]			=	{"custom line 2"}, 
  198. 	[POT_PRAISED_BY_PC]	=	{"observe - praised by pc"}, 
  199. 	[POT_TAUNTED_BY_PC]	=	{"misc - respond to player taunt w/taunt"}, 
  200. 	[POT_BARTER]			=	{"hostage - barters"}, 
  201. 	[POT_GRATS_PC]			=	{"combat - congratulate player"}, 
  202. 	[POT_GRATS_SELF]		=	{"combat - congratulate self"}, 
  203. 	[POT_HIT_CAR]			=	{"observe - passenger when driver hits cars"}, 
  204. 	[POT_HIT_OBJ]			=	{"observe - passenger when driver hits object"}, 
  205. 	[POT_HIT_PED]			=	{"observe - passenger when driver hits peds"} 
  206. } 
  207.  
  208. -- Persona situation overrides, correlates to enum persona_situation_override 
  209. PS_OVERRIDE_MISSION01 = 1 
  210. PS_OVERRIDE_MISSION07 = 2 
  211. PS_OVERRIDE_MISSION17 = 3 
  212. PS_OVERRIDE_HELI_ACTIVITY = 4 
  213. PS_OVERRIDE_MISSION03 = 5 
  214. PS_OVERRIDE_SH02 = 6 
  215. PS_OVERRIDE_ESCORT = 7 
  216. PS_OVERRIDE_SH02_BRUTE = 8 
  217.  
  218. -- Constants use by the audio_play_conversation function. 
  219. -- These indices are the indices of each segment of a dialog stream 
  220. -- in the dialog stream table. 
  221. DIALOG_STREAM_AUDIO_NAME_INDEX = 1 
  222. DIALOG_STREAM_CHAR_NAME_INDEX = 2 
  223. DIALOG_STREAM_DELAY_SECONDS_INDEX = 3 
  224. DIALOG_STREAM_ANIM_ACTION_INDEX = 4 
  225.  
  226. -- Types of conversations 
  227. NOT_CALL = 1 
  228. OUTGOING_CALL = 2 
  229. INCOMING_CALL = 3 
  230.  
  231. -- Used in a dialog stream to denote that this is a character speaking through the cellphone 
  232. CELLPHONE_CHARACTER  = "cellphone character" 
  233.  
  234. -- Ring sounds 
  235. CELLPHONE_INCOMING = "SYS_CELL_RING_1" 
  236. CELLPHONE_OUTGOING = "SYS_CELL_RING_OTHER" 
  237.  
  238. -- Gang persona tables 
  239. -- 
  240. --	The key of each entry is the persona, and the value is the tag prfix of its situation triggers. 
  241. -- 
  242. -- These tables are used in conjunction with persona_override_group_start and persona_override_group_stop. 
  243.  
  244. BROTHERHOOD_PERSONAS = { 
  245. 	["HM_Bro1"]	=	"HMBRO1", 
  246. 	["HM_Bro2"]	=	"HMBRO2", 
  247. 	["HM_Bro3"]	=	"HMBRO3", 
  248.  
  249. 	["HF_Bro1"]	=	"HFBRO1", 
  250. 	["HF_Bro2"]	=	"HFBRO2", 
  251.  
  252. 	["WM_Bro1"]	=	"WMBRO1", 
  253. 	["WM_Bro2"]	=	"WMBRO2", 
  254. 	["WM_Bro3"]	=	"WMBRO3", 
  255.  
  256. 	["WF_Bro1"]	=	"WFBRO1", 
  257. 	["WF_Bro2"]	=	"WFBRO2", 
  258. } 
  259.  
  260. RONIN_PERSONAS	= { 
  261. 	["AM_Ron1"]	=	"AMRON1", 
  262. 	["AM_Ron2"]	=	"AMRON2", 
  263. 	["AM_Ron3"]	=	"AMRON3", 
  264.  
  265. 	["AF_Ron1"]	=	"AFRON1", 
  266. 	["AF_Ron2"]	=	"AFRON2", 
  267. 	["AF_Ron3"]	=	"AFRON3", 
  268.  
  269. 	["WM_Ron1"]	=	"WMRON1", 
  270. 	["WM_Ron2"]	=	"WMRON2", 
  271.  
  272. 	["WF_Ron1"]	=	"WFRON1", 
  273. 	["WF_Ron2"]	=	"WFRON2", 
  274. } 
  275.  
  276. SAINTS_PERSONAS = { 
  277. 	["AM_TSS1"]	=	"AMTSS1", 
  278. 	["AM_TSS2"]	=	"AMTSS2", 
  279. 	["AM_TSS3"]	=	"AMTSS3", 
  280.  
  281. 	["AF_TSS1"]	=	"AFTSS1", 
  282. 	["AF_TSS2"]	=	"AFTSS2", 
  283. 	["AF_TSS3"]	=	"AFTSS3", 
  284.  
  285. 	["BM_TSS1"]	=	"BMTSS1", 
  286. 	["BM_TSS2"]	=	"BMTSS2", 
  287. 	["BM_TSS3"]	=	"BMTSS3", 
  288.  
  289. 	["BF_TSS1"]	=	"BFTSS1", 
  290. 	["BF_TSS2"]	=	"BFTSS2", 
  291. 	["BF_TSS3"]	=	"BFTSS3", 
  292.  
  293. 	["HM_TSS1"]	=	"HMTSS1", 
  294. 	["HM_TSS2"]	=	"HMTSS2", 
  295. 	["HM_TSS3"]	=	"HMTSS3", 
  296.  
  297. 	["HF_TSS1"]	=	"HFTSS1", 
  298. 	["HF_TSS2"]	=	"HFTSS2", 
  299. 	["HF_TSS3"]	=	"HFTSS3", 
  300.  
  301. 	["WM_TSS1"]	=	"WMTSS1", 
  302. 	["WM_TSS2"]	=	"WMTSS2", 
  303. 	["WM_TSS3"]	=	"WMTSS3", 
  304.  
  305. 	["WF_TSS1"]	=	"WFTSS1", 
  306. 	["WF_TSS2"]	=	"WFTSS2", 
  307. 	["WF_TSS3"]	=	"WFTSS3", 
  308. } 
  309.  
  310. SAMEDI_PERSONAS = { 
  311. 	["BM_SoS2"]	=	"BMSOS2", 
  312.  
  313. 	["BF_SoS1"]	=	"BFSOS1", 
  314. 	["BF_SoS2"]	=	"BFSOS2", 
  315. 	["BF_SoS3"]	=	"BFSOS3", 
  316.  
  317. 	["WM_SoS2"]	=	"WMSOS2", 
  318.  
  319. 	["WF_SoS1"]	=	"WFSOS1", 
  320. } 
  321.  
  322. COP_PERSONAS = { 
  323. --	["AM_Cop"]	=	"AMCOP",		Currently has no mission specific lines 
  324. 	["AF_Cop"]	=	"AFCOP", 
  325. 	 
  326. 	["BM_Cop"]	=	"BMCOP", 
  327. 	["BF_Cop"]	=	"BFCOP", 
  328. 	 
  329. 	["HM_Cop"]	=	"HMCOP", 
  330. 	["HF_Cop"]	=	"HFCOP", 
  331. 	 
  332. 	["WM_Cop"]	=	"WMCOP", 
  333. 	["WF_Cop"]	=	"WFCOP", 
  334. } 
  335.  
  336. BUM_PERSONAS = { 
  337. 	["BM_Hobo"]		=	"BMHOBO1", 
  338. 	["BF_Hobo"]		=	"BFHOBO1", 
  339. 	 
  340. 	["HM_Hobo"]		=	"HMHOBO1", 
  341. 	["HF_Hobo"]		=	"HFHOBO1", 
  342. 	 
  343. 	["WM_Hobo1"]	=	"WMHOBO1", 
  344. 	["WM_Hobo2"]	=	"WMHOBO2", 
  345. 	 
  346. 	["WF_Hobo1"]	=	"WFHOBO1", 
  347. 	["WF_Hobo2"]	=	"WFHOBO2", 
  348. } 
  349.  
  350. -- Human teams ( gangs ) 
  351. HUMAN_TEAM_BROTHERHOOD		= 1 
  352. HUMAN_TEAM_RONIN				= 2 
  353. HUMAN_TEAM_SAMEDI				= 3 
  354.  
  355. -- AI Atttack modes 
  356. ATTACK_ON_SIGHT = 0 
  357. ATTACK_NOW = 1 
  358. ATTACK_NOW_NEVER_LOSE = 2 
  359.  
  360. -- Level light toggle styles 
  361. LEVEL_LIGHT_TOGGLE_STYLE_POP = 0 
  362. LEVEL_LIGHT_TOGGLE_STYLE_FADE = 1 
  363. LEVEL_LIGHT_TOGGLE_STYLE_FLICKER = 2 
  364.  
  365. -- Spawn Region Filters 
  366. SRF_DEFAULT = 1 
  367. SRF_1 = 2 
  368. SRF_2 = 4 
  369. SRF_3 = 8 
  370. SRF_4 = 16 
  371. SRF_5 = 32 
  372. SRF_6 = 64 
  373. SRF_7 = 128 
  374. SRF_ALL = 255 
  375.  
  376. -- Global Variables -- 
  377. Player_controls_disabled_by_mission_start_fadeout = false 
  378.  
  379. -- HUD Elements -- 
  380. HUD_ELEM_GSI 						= 0 
  381. HUD_ELEM_MINIMAP 					= 1 
  382. HUD_ELEM_RETICLE 					= 2 
  383. HUD_ELEM_HIT_INDICATORS 		= 3 
  384. HUD_ELEM_WEAPONS 					= 4 
  385. HUD_ELEM_CASH_RESPECT_HOMEY 	= 5 
  386. HUD_ELEM_WEAPON_SWAP_MESSAGE 	= 6 
  387. HUD_ELEM_RADIO_STATION 			= 7 
  388. HUD_ELEM_VEHICLE_NAME 			= 8 
  389. HUD_ELEM_DIVERSIONS 				= 9 
  390. HUD_ELEM_MESSAGES 				= 10 
  391. HUD_ELEM_TUTORIAL_HELP 			= 11 
  392. HUD_ELEM_SCREEN_FX 				= 12	-- Must be explicitly hidden 
  393. HUD_ELEM_SUBTITLES 				= 13	-- Must be explicitly hidden 
  394. HUD_ELEM_OI 						= 14 -- Must be explicitly hidden 
  395. HUD_ALL_ELEM 						= 15 
  396.  
  397. -- HUD Fade Levels -- 
  398. HUD_FADE_HIDDEN = 0 
  399. HUD_FADE_TRANSPARENT = 1 
  400. HUD_FADE_VISIBLE = 2 
  401. HUD_FADE_NO_CHANGE = 3 
  402.  
  403. -- Helicopter pathfinding orientations 
  404. HELI_PF_FACE_ALONG_PATH = 0 
  405. HELI_PF_FACE_TARGET = 1 
  406. HELI_PF_LEFT_SIDE_FACE_TARGET = 2 
  407. HELI_PF_RIGHT_SIDE_FACE_TARGT = 3 
  408. HELI_PF_FACE_DOWN_AT_TARGET = 4 
  409. HELI_PF_PATH_PITCH = 5 
  410. HELI_PF_LEFT_WING_UP = 6 
  411.  
  412. -- Upgraded weapon levels 
  413. WEAPON_LEVEL1 = 0x0		-- no upgrades 
  414. WEAPON_LEVEL2 = 0x1		-- first upgrade 
  415. WEAPON_LEVEL3 = 0x3		-- first and second upgrades 
  416. WEAPON_LEVEL4 = 0x7		-- first second and third upgrades 
  417.  
  418. -- Character Gender Types 
  419. GENDER_TYPE_MALE = 0 
  420. GENDER_TYPE_FEMALE = 1 
  421.  
  422. ------------------------ 
  423. -- Internal functions -- 
  424. ------------------------ 
  425.  
  426. function character_is_ready_to_speak( speaking_character ) 
  427.    -- Check for a character that does not exist first 
  428.    if (not character_exists(speaking_character)) then 
  429. 		return false 
  430. 	end 
  431.  
  432. 	if (character_is_dead(speaking_character)) then 
  433. 		return false 
  434. 	end 
  435.  
  436. 	if (character_is_ragdolled(speaking_character)) then 
  437. 		return false 
  438. 	end 
  439. 	 
  440. 	if (character_is_on_fire(speaking_character)) then 
  441.       return false 
  442.    end 
  443.  
  444. 	-- The character can speak 
  445.    return true 
  446. end 
  447.  
  448. function group_create_check_done_loop(group) 
  449. 	local group_name = group 
  450.  
  451. 	if (type(group) == "table" and type(group.name) == "string") then 
  452. 		group_name = group.name 
  453. 	end 
  454.  
  455. 	while (not(group_create_check_done(group_name))) do 
  456. 		thread_yield() 
  457. 	end 
  458. end 
  459.  
  460. -- Internal use: generalized helicopter_fly_to function 
  461. -- 
  462. -- name:				name of the helicopter 
  463. -- speed:				speed at which the helicopter will fly 
  464. -- direct:				if true, move directly, ignoring heightmap 
  465. -- follow:				if non-empty, target vehicle to follow 
  466. -- continue_at_goal:	if true, continue forward at goal 
  467. -- path:				name of scripted_path or single navpoint 
  468. -- follow_dist:			distance at which to follow 
  469. -- directly_above:		whether the helicopter should be directly above the target vehicle 
  470. -- loop_path:			If true, the path should loop back on itself 
  471. -- start_full_speed:	if true, the helicopter will start the path at the full speed specified 
  472. -- 
  473. function helicopter_fly_to_internal(name, speed, direct, follow, continue_at_goal, path, follow_dist, directly_above, loop_path, start_full_speed, reverse_sp) 
  474. 	if (helicopter_fly_to_do(name, speed, direct, follow, continue_at_goal, path, follow_dist, directly_above, loop_path, start_full_speed, reverse_sp)) then 
  475. 		local check_done = vehicle_pathfind_check_done(name) 
  476. 		 
  477. 		while ( check_done == 0) do 
  478. 			thread_yield() 
  479. 			check_done = vehicle_pathfind_check_done(name) 
  480. 		end 
  481. 		 
  482. 		return check_done == 1 
  483. 	else 
  484. 		return false 
  485. 	end 
  486. end 
  487.  
  488. -------------------- 
  489. -- Script Actions -- 
  490. -------------------- 
  491.  
  492. -- Make a human play an animation and optional morph, blocking until the animation is done. 
  493. -- 
  494. -- name:			(string) name of character 
  495. -- anim_name:		(string) name of animation to play (valid action names can be found in anim_actions.xtbl, in data/tables) 
  496. -- morph_name:		(string, optional) name of morph to use (defaults to the animation name) 
  497. -- force_play:		(boolean, optional) if true, forces the animation to play on the character, even if dead (defaults to false) 
  498. -- percentage:		(float, optional) percentage done to check for (defaults to 0.8) 
  499. -- stand_still:		(boolean, optional) if true, the character is reset to a standing state before the animation is played (defaults to false) 
  500. -- zero_movement:	(boolean, optional) if ture, the charaters movement speed it set to zero (defaults to false) 
  501. -- navpoint:		(string, optional) slide into navpoint if provided 
  502. -- dest_nav:		(string, optional) destination navpoint to slide into if provided 
  503. -- 
  504. function action_play(name, anim_name, morph_name, force_play, percentage, stand_still, zero_movement, navpoint, dest_nav) 
  505. 	action_play_non_blocking(name, anim_name, morph_name, force_play, stand_still, zero_movement, navpoint, dest_nav) 
  506. 	repeat 
  507. 		thread_yield() 
  508. 	until action_play_is_finished(name, percentage) 
  509. end 
  510.  
  511. -- Make a human play a custom animation, blocking until the animation is done. 
  512. -- 
  513. -- name:				(string) name of character 
  514. -- anim_name:		(string) name of animation to play (valid action names can be found in anim_actions.xtbl, in data/tables) 
  515. -- percentage:		(float, optional) percentage done to check for (defaults to 0.8) 
  516. -- 
  517. -- If possible, the action_play script action should be used instead where possible. 
  518. -- 
  519. function action_play_custom(name, anim_name, percentage) 
  520. 	while not action_play_custom_do(name, anim_name) do 
  521. 		thread_yield() 
  522. 	end 
  523.  
  524. 	repeat 
  525. 		thread_yield() 
  526. 	until action_play_is_finished(name, percentage) 
  527. end 
  528.  
  529. -- Make a human play a direction stumble, blocking until the animation is done 
  530. -- 
  531. -- name:			(string) name of character 
  532. -- nav_name:		(string) name of navpoint indicating the direction to stumble 
  533. -- percentage:		(float, optional) percentage done to check for (defaults to 0.8) 
  534. -- do_flinch:		(boolean, optional) true if a flinch should be in place of the stumble animations 
  535. -- 
  536. -- If possible, the action_play script action should be used instead where possible. 
  537. -- 
  538. function action_play_directional_stumble(name, nav_name, percentage, do_flinch) 
  539. 	while not action_play_directional_stumble_do(name, nav_name, do_flinch) do 
  540. 		thread_yield() 
  541. 	end 
  542. 	 
  543. 	repeat 
  544. 		thread_yield() 
  545. 	until action_play_is_finished(name, percentage) 
  546. end 
  547.  
  548. -- Make a human play an animation without blocking. 
  549. -- 
  550. -- name:				(string) name of character 
  551. -- anim_name:		(string) name of animation to play (valid action names can be found in anim_actions.xtbl, in data/tables) 
  552. -- morph_name:		(string, optional) name of morph to use (defaults to the animation name) 
  553. -- force_play:		(boolean, optional) if true, forces the animation to play on the character, even if dead (defaults to false) 
  554. -- stand_still:	(boolean, optional) if true, the character is reset to a standing state before the animation is played (defaults to false) 
  555. -- zero_movement:	(boolean, optional) if ture, the charaters movement speed it set to zero (defaults to false)	 
  556. -- navpoint:		(string, optional) slide into navpoint if provided 
  557. -- dest_nav:		(string, optional) slide into destination navpoint if provided 
  558. -- 
  559. -- NB: This function will still block until the animation actually starts playing. 
  560. -- 
  561. function action_play_non_blocking(name, anim_name, morph_name, force_play, stand_still, zero_movement, navpoint, dest_nav) 
  562. 	while not action_play_do(name, anim_name, morph_name, force_play, stand_still, zero_movement, navpoint, dest_nav) do 
  563. 		thread_yield() 
  564. 	end 
  565. end 
  566.  
  567. -- Make a pair of humans play an animation.  This function blocks 
  568. -- 
  569. -- attacker:			(string) name of attacker 
  570. -- victim: 				(string) name of victim 
  571. -- anim_name:			(string) name of synced animation 
  572. -- start_nav_name:      (string, optional) name of the nav point with which to orient the synced animation 
  573. -- 
  574. function action_play_synced(attacker, victim, anim_name, start_nav) 
  575. 	while not action_play_synced_do(attacker, victim, anim_name, start_nav) do 
  576. 		thread_yield() 
  577. 	end 
  578. 	 
  579. 	repeat 
  580. 		thread_yield() 
  581. 	until action_play_synced_is_finished(attacker, victim) 
  582. end 
  583.  
  584. -- Make a pair of humans play an animation.  This function blocks 
  585. -- 
  586. -- attacker:			(string) name of attacker 
  587. -- victim: 				(string) name of victim 
  588. -- anim_name:			(string) name of synced animation 
  589. -- start_nav_name:      (string, optional) name of the nav point with which to orient the synced animation 
  590. -- 
  591. -- NB: This function will still block until the animation actually starts playing. 
  592. -- 
  593. function action_play_synced_non_blocking(attacker, victim, anim_name, start_nav) 
  594. 	while not action_play_synced_do(attacker, victim, anim_name, start_nav) do 
  595. 		thread_yield() 
  596. 	end 
  597. end 
  598.  
  599. -- Make an airplane fly through a series of navpoints 
  600. --  
  601. -- name:		(string) name of the airplane 
  602. -- speed:		(float) speed in m/s 
  603. -- path:		(string) name of a scripted_path, or single navpoint  
  604. -- 
  605. function airplane_fly_to(name, speed, path) 
  606. 	-- Wait until the resource is loaded. 
  607. 	-- character_wait_for_loaded_resource(name) 
  608. 			 
  609. 	if (airplane_fly_to_do(name, speed, path)) then 
  610. 		local check_done = vehicle_pathfind_check_done(name) 
  611. 		 
  612. 		while ( check_done == 0) do 
  613. 			thread_yield() 
  614. 			check_done = vehicle_pathfind_check_done(name) 
  615. 		end 
  616. 		 
  617. 		return check_done == 1 
  618. 	else 
  619. 		return false 
  620. 	end 
  621. end 
  622.  
  623.  
  624. -- Make an airplane land on a runway. 
  625. -- 
  626. -- name:				(string) name of the airplane 
  627. -- runway_start:	(string) name of the navpoint for the start of the runway (must be oriented in the direction of the runway) 
  628. -- 
  629. -- Note that the plane must already be heading in approximately the correct direction of the runway. 
  630. -- The plane will land after the runway_start position. 
  631. -- 
  632. function airplane_land(name, runway_start) 
  633. 	if (not airplane_land_do( name, runway_start )) then 
  634. 		return 
  635. 	end 
  636. 	 
  637. 	while( vehicle_pathfind_check_done(name) == 0) do 
  638. 		thread_yield() 
  639. 	end 
  640.  
  641. end 
  642.  
  643. -- Make an airplane take off straight in the direction they are currently facing. 
  644. -- 
  645. -- name:	(string) name of the airplane 
  646. -- 
  647. function airplane_takeoff(name) 
  648. 	if (not airplane_takeoff_do( name )) then 
  649. 		return 
  650. 	end 
  651. 	 
  652. 	while( vehicle_pathfind_check_done(name) == 0) do 
  653. 		thread_yield() 
  654. 	end 
  655.  
  656. end 
  657.  
  658. -- Make an NPC attack the closest player. 
  659. -- 
  660. -- name:		(string) name of the NPC 
  661. -- 
  662. -- This script action will silently fail if the NPC is dead. 
  663. -- 
  664. function attack_closest_player( npc_name ) 
  665.    local distance, closest_player = get_dist_closest_player_to_object( npc_name ) 
  666.    attack_safe( npc_name, closest_player ) 
  667. end 
  668.  
  669. -- Make a character attack another character, but checks to see if either character is dead first. 
  670. -- 
  671. -- attacker:	(string) name of the attacker 
  672. -- target:		(string, optional) name of the target (defaults to the player) 
  673. -- 
  674. -- If either the attacker of target is dead, the attack command is ignored. 
  675. -- 
  676. function attack_safe( npc_name, target ) 
  677. 	if target == nil then 
  678. 		target = CLOSEST_PLAYER 
  679. 	end 
  680.  
  681. 	if ( ( not character_is_dead( npc_name ) ) and ( ( not character_is_dead( target ) ) ) ) then 
  682. 		attack( npc_name, target )  
  683. 	end 
  684. end 
  685.  
  686. -- Play a 2D sound (by name). 
  687. -- 
  688. -- audio_name:		(string) name of sound to play 
  689. -- type_name:		(string, optional) name of audio source (can be "foley", "voice", "music", or "ambient"; defaults to "foley") 
  690. -- blocking:		(boolean, optional) set to true to block until the sound starts playing, else set to false to return immediately (defaults to false) 
  691. -- ignore_fade:	(boolean, optional) set to true to ignore the volume throttling that occurs with screen fades (defaults to false) 
  692. -- 
  693. -- returns:			(integer) audio instance handle, or -1 on error 
  694. -- 
  695. -- Example: 
  696. -- 
  697. --		audio_play("Some Foley Sound", "foley") 
  698. -- 
  699. -- Plays the foley sound, "Some Foley Sound", in 2D. 
  700. -- 
  701. function audio_play(audio_name, type_name, blocking, ignore_fade) 
  702. 	local handle = audio_play_do(audio_name, type_name, ignore_fade) 
  703. 	 
  704. 	if (not blocking) then 
  705. 		return handle; 
  706. 	end 
  707. 	 
  708. 	while (audio_is_playing(handle)) do 
  709. 		thread_yield() 
  710. 	end 
  711. 	 
  712. 	return -1; 
  713. end 
  714.  
  715. function audio_conversation_load(conversation_name) 
  716. 	local handle = audio_conversation_load_direct(conversation_name .. "_" .. persona_trigger_get_player_prefix(LOCAL_PLAYER)) 
  717. 	return handle 
  718. end 
  719.  
  720. function audio_conversation_load_player(conversation_name, player) 
  721. 	local handle = audio_conversation_load_direct(conversation_name .. "_" .. persona_trigger_get_player_prefix(player)) 
  722. 	return handle 
  723. end 
  724.  
  725. function audio_conversation_wait_for_end(handle) 
  726. 	while audio_conversation_playing(handle) do 
  727. 		thread_yield() 
  728. 	end 
  729. 	audio_conversation_end(handle) 
  730. end 
  731.  
  732. -- Play a conversation, which consists of a series of lines played by characters. 
  733. -- 
  734. -- dialog_stream:		(table) dialog stream segments that consist of a speaking character name, the name of the audio to play, and a delay in seconds between each dialog segment (character name is not necessary for cellphone calls) 
  735. -- cellphone_call:	(enumeration, optional) type of cellphone call (can be NOT_CALL, OUTGOING_CALL, or INCOMING_CALL; defaults to NOT_CALL) 
  736. -- 
  737. -- For cellphone calls, this function also takes care of cellphone animations. 
  738. -- 
  739. -- Example: 
  740. -- 
  741. --		FLEEING_LIEUTENANTS_DIALOG_STREAM = { 
  742. --			{ "SOS3_FLEE_L1", TOBIAS_NAME, 0 }, 
  743. --			{ "SOS3_FLEE_L2", LOCAL_PLAYER, 0 } 
  744. --		} 
  745. --		audio_play_conversation( FLEEING_LIEUTENANTS_DIALOG_STREAM, NOT_CALL ) 
  746. -- 
  747. -- Plays "SOS3_FLEE_L1" from Tobias and then "SOS3_FLEE_L2" from the local player. 
  748. -- 
  749. function audio_play_conversation( dialog_stream, cellphone_call ) 
  750.    if ( cellphone_call == nil ) then 
  751.       cellphone_call = NOT_CALL 
  752.    end 
  753.  
  754.    -- Open with the cellphone, if this is a cellphone 
  755.    -- conversation 
  756.    if ( cellphone_call == INCOMING_CALL ) then 
  757.       cellphone_animate_start_do() 
  758.       delay(0.5) 
  759.    elseif ( cellphone_call == OUTGOING_CALL ) then 
  760.       cellphone_animate_start_do() 
  761.       audio_play( CELLPHONE_OUTGOING, "foley", true ) 
  762.       delay(0.5) 
  763.    end 
  764.  
  765. 	-- Build a list of characters that will be tested for readyness before any line in the 
  766. 	-- conversation is played. We only use this list for NOT_CALL conversations. 
  767. 	local character_list = {} 
  768. 	if (cellphone_call == NOT_CALL) then 
  769. 		for segment_index, dialog_segment in pairs( dialog_stream ) do 
  770. 			local speaking_character = dialog_segment[DIALOG_STREAM_CHAR_NAME_INDEX] 
  771. 			character_list[speaking_character] = speaking_character 
  772. 		end 
  773. 	end 
  774.  
  775. 	local function dialog_characters_ready() 
  776. 		for i,character in pairs(character_list) do 
  777. 			if (not character_is_ready_to_speak(character)) then 
  778. 				return false 
  779. 			end 
  780. 		end 
  781. 		return true 
  782. 	end 
  783.  
  784.    for segment_index, dialog_segment in pairs( dialog_stream ) do 
  785.       local audio_name = dialog_segment[DIALOG_STREAM_AUDIO_NAME_INDEX] 
  786.       local speaking_character = dialog_segment[DIALOG_STREAM_CHAR_NAME_INDEX] 
  787.       local delay_seconds = dialog_segment[DIALOG_STREAM_DELAY_SECONDS_INDEX] 
  788. 		local anim_action = dialog_segment[DIALOG_STREAM_ANIM_ACTION_INDEX] 
  789.  
  790.       -- Play the dialog stream for each character 
  791.       if ( cellphone_call == NOT_CALL ) then 
  792.          repeat 
  793.             thread_yield() 
  794.          until ( dialog_characters_ready() ) 
  795.  
  796. 			local playing_action = (	(anim_action ~= nil) 
  797. 												and (not character_is_in_vehicle(speaking_character))  
  798. 												and (not character_is_combat_ready(speaking_character)) 
  799. 												and (not mesh_mover_wielding(speaking_character)) 
  800. 												and (vehicle_exit_check_done(speaking_character)) 
  801. 												and (vehicle_enter_check_done(speaking_character)) 
  802. 											) 
  803.  
  804. 			if (playing_action ) then	 
  805. 				inv_item_equip(nil,speaking_character) 
  806. 				action_play(speaking_character, anim_action, anim_action, true, 0.0, true) 
  807. 			end 
  808.          audio_play_for_character( audio_name, speaking_character, "voice", false, true) 
  809.          delay( delay_seconds ) 
  810.       -- Cellphone calls are different - just play the audio, don't use the character function unless 
  811.       -- it's the player. 
  812.       else 
  813.          -- For players, use audio_play_for_character so that the tag can be correctly translated 
  814.          if (	speaking_character ~= nil and character_is_player( speaking_character ) ) then 
  815.             -- Don't play lines unless and until the player is alive and in a state to deliver them 
  816.             repeat 
  817.                thread_yield() 
  818.             until ( character_is_ready_to_speak( speaking_character ) ) 
  819.             audio_play_for_character( audio_name, speaking_character, "voice", false, true) 
  820.          elseif ( speaking_character == CELLPHONE_CHARACTER or speaking_character == nil ) then 
  821.             -- for_cutscene = false, blocking = true, variant = nil, voice_distance = nil, cellphone_line = true 
  822.             audio_play_for_character( audio_name, LOCAL_PLAYER, "voice", false, true, nil, nil, true ) 
  823.          else 
  824.             script_assert( false, "You must specify CELLPHONE_CHARACTER as the speaking character ( or leave it at nil ) for the other side of a cellphone conversation." ) 
  825.          	audio_play( audio_name, "voice", true ) 
  826.          end 
  827.          delay( delay_seconds ) 
  828.       end 
  829.    end 
  830.  
  831.    -- Close the cellphone, if this was a cellphone 
  832.    -- conversation 
  833.    if ( cellphone_call ~= NOT_CALL ) then 
  834.       cellphone_animate_stop_do() 
  835.    end 
  836. end 
  837.  
  838. -- Play a conversation while the speaker is in a vehicle. 
  839. -- 
  840. -- dialog_stream:		(table) dialog stream segments that consist of a speaking character name, the name of the audio to play, and a delay in seconds between each dialog segment (character name is not necessary for cellphone calls) 
  841. -- 
  842. -- Behaves in much the same way as audio_play_conversation, but blocks while the speaking character is not in a vehicle. 
  843. -- 
  844. function audio_play_conversation_in_vehicle(dialog_stream) 
  845. 	-- Loop through the table conversation... 
  846.    for segment_index, dialog_segment in pairs( dialog_stream ) do 
  847.       local audio_name = dialog_segment[DIALOG_STREAM_AUDIO_NAME_INDEX] 
  848.       local speaking_character = dialog_segment[DIALOG_STREAM_CHAR_NAME_INDEX] 
  849.       local delay_seconds = dialog_segment[DIALOG_STREAM_DELAY_SECONDS_INDEX] 
  850.  
  851. 		-- Conversation requires them to be in a vehicle 
  852. 		while (not character_is_in_vehicle(speaking_character)) do 
  853. 			thread_yield() 
  854. 		end 
  855.  
  856.       -- Play the dialog stream for each character 
  857. 		audio_play_for_character(audio_name, speaking_character, "voice", false, true) 
  858. 		delay(delay_seconds) 
  859.    end 
  860. end 
  861.  
  862. -- Play a cellphone ring and then a conversation. 
  863. -- 
  864. -- ring_name:	(string) name of the ring sound (from foley.xtbl) 
  865. -- conv_name:	(string) name of the conversation (from voice.xtbl) 
  866. -- 
  867. -- The ring sound plays twice before the conversation occurs. This function also player cellphone animations. 
  868. -- 
  869. -- Note: this function does not display a "Press Y to ..." message on the screen. 
  870. -- 
  871. function audio_play_for_cellphone_force(ring_name, conv_name ) 
  872.  
  873. 	audio_play(ring_name, "foley", false, true) 
  874. 	delay(0.5) 
  875. 	audio_play(ring_name, "foley", false, true) 
  876. 	delay(0.5) 
  877. 	cellphone_animate_start_do() 
  878.  
  879. 	-- RCS: I think these should probably play in 2D...so audio_play would be more appropriate... 
  880. 	audio_play_for_character(conv_name, LOCAL_PLAYER, "voice", false, true) 
  881. 	cellphone_animate_stop_do() 
  882.  
  883. end 
  884.  
  885. -- Play a 3D sound (by name) on a character. 
  886. -- 
  887. -- audio_name:			(string) name of sound 
  888. -- human_name:			(string) name of character 
  889. -- type_name:			(string, optional) name of audio source (can be "foley", "voice", "music", or "ambient"; defaults to "foley") 
  890. -- for_cutscene:		(boolean, optional) no longer used (NIQ 4/2/09: this parameter needs to be removed) 
  891. -- blocking:			(boolean, optional) set to true if the function should block until the sound has finished playing (defaults to false) 
  892. -- variant:				(integer, optional) index of the specific variant of the voice line to play (or -1 for a random selection; defaults to -1) 
  893. -- voice_distance:	(integer, optional) distance that the foley can be heard from; only used for voices (0 = short, 1 = normal, 2 = long, 3 = extreme; defaults to -1, which is normal distance for peds, and extreme distance for passengers in cars) 
  894. -- cellphone_line:	(boolean, optional) set to true if the audio is for a cellphone line (defaults to false) 
  895. -- ignore_fade:		(boolean, optional) set to true to ignore the volume throttling that occurs with screen fades (defaults to false) 
  896. -- 
  897. -- returns:				(integer) audio instance handle, or -1 on error 
  898. -- 
  899. -- Example: 
  900. -- 
  901. --		audio_play_for_character("Woot", "#PLAYER1#", "foley") 
  902. -- 
  903. -- Plays the sound "Woot" on the local player. 
  904. --  
  905. function audio_play_for_character(audio_name, human_name, type_name, for_cutscene, blocking, variant, voice_distance, cellphone_line, ignore_fade)	 
  906. 	if (character_is_dead(human_name)) then 
  907. 		return -1, 0 
  908. 	end 
  909.    if ( cellphone_line == nil ) then 
  910.       cellphone_line = false 
  911.    end 
  912.  
  913. 	-- If we're playing a voice line, update the audio name to reflect the player's persona. 
  914. 	local new_audio_name = audio_name 
  915. 	if ( (type_name == "voice") and (character_is_player(human_name)) and cellphone_line == false ) then 
  916. 		new_audio_name = persona_trigger_get_player_prefix(human_name) .. audio_name 
  917. 	end 
  918.  
  919. 	local handle, play_time = audio_play_for_character_do(new_audio_name, human_name, type_name, blocking, variant, voice_distance, cellphone_line, ignore_fade) 
  920.  
  921. 	if (not(blocking)) then 
  922. 		return handle, play_time; 
  923. 	end 
  924.  
  925. 	-- While playing blocking audio, prevent random persona lines from playing 
  926. 	if (character_is_player(human_name)) then 
  927. 		audio_suppress_ambient_player_lines(true) 
  928. 	else 
  929. 		npc_suppress_persona(human_name, true) 
  930. 	end 
  931. 	 
  932. 	if (handle > 0) then 
  933. 		while (audio_is_playing(handle)) do 
  934. 			thread_yield() 
  935. 		end 
  936. 	else 
  937. 		delay( play_time ) 
  938. 	end 
  939.  
  940. 	-- Allow random persona lines to play again 
  941. 	if (character_is_player(human_name)) then 
  942. 		audio_suppress_ambient_player_lines(false) 
  943. 	else 
  944. 		npc_suppress_persona(human_name, true) 
  945. 	end	 
  946.  
  947. 	return -1, 0 
  948. end 
  949.  
  950. -- Play a 3D sound (by name) on a character's weapon. 
  951. -- 
  952. -- audio_name:	(string) name of sound 
  953. -- human_name:	(string) name of character 
  954. -- type_name:	(string, optional) name of audio source (can be "foley", "voice", "music", or "ambient"; defaults to "foley") 
  955. -- blocking:	(boolean, optional) set to true if the function should block until the sound has finished playing (defaults to false) 
  956. -- 
  957. -- returns:		(integer) audio instance handle, or -1 on error 
  958. -- 
  959. function audio_play_for_character_weapon( audio_name, character, type_name, blocking)	 
  960. 	local handle = audio_play_for_character_weapon_do( audio_name, character, type_name) 
  961. 	 
  962. 	if not blocking then 
  963. 		return handle 
  964. 	end 
  965. 	 
  966. 	if handle >= 0 then 
  967. 		repeat  
  968. 			thread_yield() 
  969. 		until not audio_is_playing(handle) 
  970. 		return 0 
  971. 	end 
  972.  
  973. 	return -1 
  974. end 
  975.  
  976. -- Play a 3D sound (by name) on a mover. 
  977. -- 
  978. -- audio_name:		(string) name of sound 
  979. -- script_mover:	(string) name of mover 
  980. -- type_name:		(string, optional) name of audio source (can be "foley", "voice", "music", or "ambient"; defaults to "foley") 
  981. -- blocking:		(boolean, optional) set to true if the function should block until the sound has finished playing (defaults to false) 
  982. -- 
  983. -- returns:			(integer) audio instance handle, or -1 on error 
  984. -- 
  985. function audio_play_for_mover( audio_name, script_mover, type_name, blocking ) 
  986.  
  987. 	local handle = audio_play_for_mover_do( audio_name, script_mover, type_name ) 
  988. 	 
  989. 	if (not blocking) then 
  990. 		return handle 
  991. 	end 
  992. 	 
  993. 	if (handle > 0) then 
  994. 		while (audio_is_playing(handle)) do 
  995. 			thread_yield() 
  996. 		end 
  997. 	end 
  998. 	 
  999. 	return -1 
  1000. end 
  1001.  
  1002. -- Play a 2D sound (by ID). 
  1003. -- 
  1004. -- audio_id:	(integer) ID of sound to play 
  1005. -- type_name:	(string, optional) name of audio source (can be "foley", "voice", "music", or "ambient"; defaults to "foley") 
  1006. -- blocking:	(boolean, optional) set to true if the function should block until the sound has finished playing (defaults to false) 
  1007. -- 
  1008. -- returns:		(integer) audio instance handle, or -1 on error 
  1009. -- 
  1010. function audio_play_id(audio_id, type, blocking) 
  1011. 	local handle = audio_play_id_do(audio_id, type) 
  1012. 	 
  1013. 	if (not blocking) then 
  1014. 		return handle; 
  1015. 	end 
  1016. 	 
  1017. 	while (audio_is_playing(handle)) do 
  1018. 		thread_yield() 
  1019. 	end 
  1020. 	 
  1021. 	return -1; 
  1022. end 
  1023.  
  1024. -- Play a 3D sound (by ID) on a character. 
  1025. -- 
  1026. -- human_name:			(string) name of character 
  1027. -- audio_id:			(integer) ID of sound to play 
  1028. -- type_name:			(string, optional) name of audio source (can be "foley", "voice", "music", or "ambient"; defaults to "foley") 
  1029. -- blocking:			(boolean, optional) set to true if the function should block until the sound has finished playing (defaults to false) 
  1030. -- variant:				(integer, optional) index of the specific variant of the voice line to play (or -1 for a random selection; defaults to -1) 
  1031. -- voice_distance:	(integer, optional) distance that the foley can be heard from; only used for voices (0 = short, 1 = normal, 2 = long, 3 = extreme; defaults to -1, which is normal distance for peds, and extreme distance for passengers in cars) 
  1032. -- 
  1033. -- returns:				(integer) audio instance handle, or -1 on error 
  1034. -- 
  1035. function audio_play_id_for_character(human_name, audio_id, type, blocking, variant, voice_distance) 
  1036. 	if (character_is_dead(human_name)) then 
  1037. 		return -1 
  1038. 	end 
  1039. 	 
  1040. 	local	handle = audio_play_id_for_character_do(human_name, audio_id, type, blocking, variant, voice_distance) 
  1041.  
  1042. 	if (not blocking) then 
  1043. 		return handle 
  1044. 	end 
  1045. 	 
  1046. 	while (audio_is_playing(handle)) do 
  1047. 		thread_yield() 
  1048. 	end 
  1049. 	 
  1050. 	return -1 
  1051. end 
  1052.  
  1053. -- Play a 3D sound (by ID) on a navpoint. 
  1054. -- 
  1055. -- navpoint_name:		(string) name of the navpoint 
  1056. -- audio_id:			(integer) ID of sound to play 
  1057. -- type_name:			(string, optional) name of audio source (can be "foley", "voice", "music", or "ambient"; defaults to "foley") 
  1058. -- blocking:			(boolean, optional) set to true if the function should block until the sound has finished playing (defaults to false) 
  1059. -- 
  1060. -- returns:				(integer) audio instance handle, or -1 on error 
  1061. --  
  1062. function audio_play_id_for_navpoint(navpoint_name, audio_id, type, blocking) 
  1063. 	local handle = audio_play_id_for_navpoint_do(navpoint_name, audio_id, type) 
  1064.  
  1065. 	if (not blocking) then 
  1066. 		return handle 
  1067. 	end 
  1068.  
  1069. 	while (audio_is_playing(handle)) do 
  1070. 		thread_yield() 
  1071. 	end 
  1072.  
  1073. 	return -1 
  1074. end 
  1075.  
  1076. -- Call the given function on each member of the given table 
  1077. -- 
  1078. -- function_ref:	(function reference - NOT a string) the function to call for each member of the table 
  1079. -- table:			(table) the table whose members the function should be called on 
  1080. -- ...:				(list) list of arguments to send to the function 
  1081. -- 
  1082. function call_function_on_each_member(function_ref, table, ...) 
  1083. 	if (type(function_ref) ~= "function") then 
  1084. 		return 
  1085. 	end 
  1086.  
  1087. 	if (type(table) ~= "table") then 
  1088. 		function_ref(table, unpack(arg)) 
  1089. 	else 
  1090. 		for i,member in pairs(table) do 
  1091. 			call_function_on_each_member(function_ref, member, unpack(arg)) 
  1092. 		end 
  1093. 	end 
  1094. end 
  1095.  
  1096. -- Moves the camera from its current position and orientation to the specified navpoint's position and orientation. 
  1097. -- 
  1098. -- navpoint_name:		(string) navpoint to look through 
  1099. -- duration:			(float, optional) duration of movement, in seconds; if set to 0, camera will instantly jump to the end position and orientation (defaults to 0) 
  1100. -- yield:				(boolean, optional) set to true to block until the camera movement is complete (defaults to false) 
  1101. -- hide_hud:			(boolean, option) set to false to not disable the hud when using this camera (defaults to true) 
  1102. -- 
  1103. -- NB: the camera will not return to its default behavior unless a camera_end_script() action is issued. If the camera script finishes execution before the 
  1104. -- camera_end_script() action is issued, the camera will hold the last position of the camera script. 
  1105. -- 
  1106. -- Example: 
  1107. -- 
  1108. --		camera_look_through("$npc000", 5.0, true) 
  1109. --		camera_end_script() 
  1110. -- 
  1111. -- Move the camera over a period of five seconds so that it is looking through navpoint "$npc000".  
  1112. -- 
  1113. function camera_look_through(navp, duration, yield, hide_hud) 
  1114. 	camera_look_through_do(navp, duration, hide_hud) 
  1115.  
  1116. 	if (yield) then	 
  1117. 		while (not(camera_script_is_finished())) do 
  1118. 			thread_yield() 
  1119. 		end 
  1120. 	end 
  1121. end 
  1122.  
  1123. -- Make a character take another character as a human shield. 
  1124. -- 
  1125. -- attacker:	(string) name of attacker 
  1126. -- victim:		(string) name of target 
  1127. -- bypass_ai:	(bool, optional) bypass AI and take shield immediately 
  1128. -- 
  1129. function character_take_human_shield( character, victim, ... ) 
  1130. 	local bypass_ai = false 
  1131. 	if (arg.n > 0) then 
  1132. 		bypass_ai = arg[1] 
  1133. 	end 
  1134. 	 
  1135.    character_take_human_shield_do( character, victim, bypass_ai ) 
  1136.  
  1137.    -- loop as long as grabber and grabee are alive until we've succeeded 
  1138.    while ( character_is_dead( character ) == false and 
  1139.            character_is_dead( victim ) == false and 
  1140. 	   character_take_human_shield_check_done( character, victim) == false) do 
  1141.       thread_yield(); 
  1142.    end 
  1143. end 
  1144.  
  1145. -- Blocks until the specified character's resources have loaded. 
  1146. -- 
  1147. -- name:	(string) name of the character to wait on 
  1148. -- 
  1149. function character_wait_for_loaded_resource(name) 
  1150. 	while (not(character_check_resource_loaded(name))) do 
  1151. 		thread_yield() 
  1152. 	end 
  1153. end 
  1154.  
  1155. -- Recursively cleanup all the callbacks for an object or table of objects. 
  1156. -- 
  1157. -- objects:	(string or table) object, table of objects, table of tables of objects, etc. 
  1158. -- 
  1159. function cleanup_callbacks(objects) 
  1160. 	if (type(objects) == "string") then 
  1161. 		clear_callbacks_for_obj(objects) 
  1162. 	elseif (type(objects) == "table") then 
  1163. 		for i,obj in pairs(objects) do 
  1164. 			cleanup_callbacks(obj) 
  1165. 		end 
  1166. 	end 
  1167. end 
  1168.  
  1169. -- Recursively cleanup all the audio conversations that may still be playing 
  1170. -- 
  1171. -- convos:	(table) conversation, table of conversations, table of tables of conversations, etc. 
  1172. -- 
  1173. function cleanup_conversations(convos) 
  1174. 	local ret_val = convos 
  1175.  
  1176. 	-- An audio conversation is a table, so if we've come to something that's not a table, there is no conversation here 
  1177. 	if (type(convos) ~= "table") then 
  1178. 		return ret_val 
  1179. 	end 
  1180.  
  1181. 	-- Conversations must have a name and a handle to the conversation as it plays, so having both should be a good sign that this is a conversation 
  1182. 	if (convos.name ~= nil and convos.handle ~= nil) then 
  1183. 		if (convos.handle ~= INVALID_CONVERSATION_HANDLE) then 
  1184. 			audio_conversation_end(convos.handle) 
  1185. 			ret_val.handle = INVALID_CONVERSATION_HANDLE 
  1186. 		end 
  1187. 	else 
  1188. 		-- The table didn't have a member called "handle", so this table isn't a conversation (though could be a table of conversations) 
  1189. 		for i,convo in pairs(convos) do 
  1190. 			ret_val[i] = cleanup_conversations(convo) 
  1191. 		end 
  1192. 	end 
  1193.  
  1194. 	-- Return a copy with the ended conversation handles set to INVALID_CONVERSATION_HANDLE 
  1195. 	return ret_val 
  1196. end 
  1197.  
  1198. -- Recursively clean up a script group or table of script groups. 
  1199. -- 
  1200. -- group:	(string or table) a group, table of groups, table of tables of groups, etc. 
  1201. -- 
  1202. function cleanup_groups(group) 
  1203. 	if (type(group) == "string") then 
  1204. 		if (group_is_loaded(group)) then 
  1205. 			group_destroy_do(group) 
  1206. 		end 
  1207. 	elseif (type(group) == "table") then 
  1208. 		if (type(group.name) == "string") then 
  1209. 			if (group_is_loaded(group.name)) then 
  1210. 				group_destroy_do(group.name) 
  1211. 			end 
  1212. 		else 
  1213. 			for i,group_member in pairs(group) do 
  1214. 				cleanup_groups(group_member) 
  1215. 			end 
  1216. 		end 
  1217. 	end 
  1218. end 
  1219.  
  1220. -- Recursively cleanup all the spawn groups (i.e. stop their spawning) 
  1221. -- 
  1222. -- group:	(string or table) a spawn group, table of spawn groups, table of tables of spawn groups, etc. 
  1223. -- 
  1224. function cleanup_spawn_groups(group) 
  1225. 	if (type(group) == "string") then 
  1226. 		continuous_spawn_stop(group, true) 
  1227. 	elseif (type(group) == "table") then 
  1228. 		-- See if the spawn group is within the regular group table 
  1229. 		if (type(group.name) == "string") then 
  1230. 			continuous_spawn_stop(group.name, true) 
  1231. 		else 
  1232. 			for i, member in pairs(group) do 
  1233. 				cleanup_spawn_groups(member) 
  1234. 			end 
  1235. 		end 
  1236. 	end 
  1237. end 
  1238.  
  1239. -- Recursively disable all spawn regions in a table 
  1240. -- 
  1241. -- regions:	(string or table) spawn region, table of spawn regions, table of tables of spawn regions, etc. 
  1242. -- 
  1243. function cleanup_spawn_regions(regions) 
  1244. 	continuous_spawn_regions_enable(regions, false) 
  1245. end 
  1246.  
  1247. -- Recursively remove temporary weapons from player inventory 
  1248. -- 
  1249. -- weapons:		(string or table) weapon, table of weapons, table of tables of weapons, etc. 
  1250. -- sync_type:	(enum, optional) SYNC_LOCAL, SYNC_REMOTE, SYNC_ALL (defaults to SYNC_ALL) 
  1251. -- 
  1252. function cleanup_temporary_weapons(weapons, sync_type) 
  1253. 	if (sync_type == nil) then 
  1254. 		sync_type = SYNC_ALL 
  1255. 	end 
  1256.  
  1257. 	if (type(weapons) == "string") then 
  1258. 		if (SYNC_LOCAL or SYNC_ALL) then 
  1259. 			inv_weapon_remove_temporary(LOCAL_PLAYER, weapons) 
  1260. 		end 
  1261. 		if (coop_is_active()) then 
  1262. 			if (SYNC_REMOTE or SYNC_ALL) then 
  1263. 				inv_weapon_remove_temporary(REMOTE_PLAYER, weapons) 
  1264. 			end 
  1265. 		end 
  1266. 	elseif (type(weapons) == "table") then 
  1267. 		for i,weapon in pairs(weapons) do 
  1268. 			cleanup_temporary_weapons(weapon, sync_type) 
  1269. 		end 
  1270. 	end 
  1271. end 
  1272.  
  1273. -- Iterates recursively through a table of threads, cleaning up any thread it finds. 
  1274. -- 
  1275. -- threads:	(string or table) a single thread, table of threads, table of tables of threads, etc. 
  1276. -- 
  1277. function cleanup_threads(threads) 
  1278. 	local ret_val = threads 
  1279.  
  1280. 	if (type(threads) == "number") then 
  1281. 		if (threads ~= INVALID_THREAD_HANDLE) then 
  1282. 			thread_kill(threads) 
  1283. 			ret_val = INVALID_THREAD_HANDLE 
  1284. 		end 
  1285. 	elseif (type(threads) == "table") then 
  1286. 		for i,thread in pairs(threads) do 
  1287. 			ret_val[i] = cleanup_threads(thread) 
  1288. 		end 
  1289. 	end 
  1290.  
  1291. 	-- Returns a copy with killed threads set to INVALID_THREAD_HANDLE 
  1292. 	return ret_val 
  1293. end 
  1294.  
  1295. -- Debug function for making a Lua function executable through the console. 
  1296. -- 
  1297. -- function_name:	(string) name of function 
  1298. -- 
  1299. function console_wrapper( function_name ) 
  1300. 	_UGGlobals[function_name]() 
  1301. end 
  1302.  
  1303. -- Recursively dig down into a spawn region table and enable/disable each region found 
  1304. -- 
  1305. -- regions:	(table or string) spawn region, table of spawn regions, table of tables of spawn regions, etc. 
  1306. -- enable:	(bool) whether to enable or disable these regions 
  1307. -- 
  1308. function continuous_spawn_regions_enable(regions, enable) 
  1309. 	if (type(regions) == "string") then 
  1310. 		spawn_region_enable(regions, enable) 
  1311. 	elseif (type(regions) == "table") then 
  1312. 		for i,region in pairs(regions) do 
  1313. 			continuous_spawn_regions_enable(region, enable) 
  1314. 		end 
  1315. 	end 
  1316. end 
  1317.  
  1318. -- Applies uniform fade-out and letterboxing that should be called before any cutscene (both scripted and artist created). 
  1319. -- 
  1320. function cutscene_in() 
  1321. 	if ( character_is_dead(LOCAL_PLAYER) ) then 
  1322. 		return 
  1323. 	end 
  1324. end 
  1325.  
  1326. -- Applies uniform fade-in and removal of letterboxing that should be called before any cutscene (both script and artist created). 
  1327. -- 
  1328. function cutscene_out() 
  1329. end 
  1330.  
  1331. -- Play a cutscene. 
  1332. -- 
  1333. -- name:				(string) name of cutscene to play 
  1334. -- group_name:		(string, or table of strings; optional) group(s) for the cutscene to load before returning (defaults to nil) 
  1335. -- teleport_name:	(table of strings, optional) names of navpoints to teleport the local and remote players to after the cutscene (defaults to nil) 
  1336. -- fade_in_after:	(boolean, optional) set to true to automatically fade in after the cutscene is finished (defaults to true) 
  1337. -- wait_for_spawning:   (boolean, optional) set to false to have the cutscene drop immediately into the world without waiting for spawning to finish up (defaults to true) 
  1338. -- 
  1339. -- This function blocks until the cutscene has finished playing. 
  1340. -- 
  1341. function cutscene_play(name, group_name, teleport_name, fade_in_after, wait_for_spawning) 
  1342. 	while (not zscene_is_loaded(name)) do 
  1343. 		thread_yield() 
  1344. 	end 
  1345.  
  1346. 	cutscene_in() -- ScottP wants all cutscenes to fade in. 
  1347. 	 
  1348. 	local function convert_to_table( var ) 
  1349. 		if (var == "" or var == nil) then 
  1350. 			return nil 
  1351. 		elseif (type(var) == "table") then		 
  1352. 			return var 
  1353. 		else 
  1354. 			return { var, n = 1 } 
  1355. 		end 
  1356. 	end 
  1357. 	 
  1358. 	local converted_group = convert_to_table( group_name ) 
  1359. 	local converted_teleports = convert_to_table( teleport_name ) 
  1360. 	 
  1361. 	cutscene_play_do(name, converted_group, converted_teleports, fade_in_after, wait_for_spawning) 
  1362.  
  1363. 	while (not(cutscene_play_check_done())) do 
  1364. 		thread_yield() 
  1365. 	end 
  1366. end 
  1367.  
  1368. -- Play a fake conversation by displaying consecutive lines of text on the screen 
  1369. -- 
  1370. -- conversation:	(table) character name, audio tag, delay between lines  
  1371. -- 
  1372. -- NOTE: conversation should be formatted the way it is for audio_play_conversation { "text", "name", duration } 
  1373. -- 
  1374. -- convo = { 
  1375. --		{ "This is the first line of the convo", "Speaker's Name", 3 }, 
  1376. --		{ "This is the second line of the convo", "Other Speaker's Name", 2 }, 
  1377. -- } 
  1378. -- 
  1379. -- This will display on the screen for 3 seconds: "Speaker's Name: This is the first line of the convo" 
  1380. -- This will display on the screen for 2 seconds: "Other Speaker's Name: This is the second line of the convo" 
  1381. -- 
  1382. function debug_conversation(conversation) 
  1383. 	if (conversation == nil) then 
  1384. 		return 
  1385. 	end 
  1386.  
  1387. 	for i,line in pairs(conversation) do 
  1388. 		local current_handle = message(line[DIALOG_STREAM_CHAR_NAME_INDEX] .. ": " .. line[DIALOG_STREAM_AUDIO_NAME_INDEX], line[DIALOG_STREAM_DELAY_SECONDS_INDEX]) 
  1389. 		delay(line[DIALOG_STREAM_DELAY_SECONDS_INDEX]) 
  1390. 		message_remove(current_handle) 
  1391. 		current_handle = INVALID_MESSAGE_HANDLE 
  1392. 	end 
  1393. end 
  1394.  
  1395. -- Block until the screen is completely faded in. 
  1396. -- 
  1397. function fade_in_block() 
  1398. 	while( not fade_is_fully_faded_in() ) do 
  1399. 		thread_yield() 
  1400. 	end 
  1401. 	 
  1402. 	thread_yield() 
  1403. end 
  1404.  
  1405. -- Block until the screen is completely faded out. 
  1406. -- 
  1407. function fade_out_block() 
  1408. 	while( not fade_is_fully_faded_out() ) do 
  1409. 		thread_yield() 
  1410. 	end 
  1411. 	 
  1412. 	thread_yield() 
  1413. end 
  1414.  
  1415. -- Force an NPC to fire at a navpoint. 
  1416. -- 
  1417. -- name:					(string) name of the NPC 
  1418. -- fire_at_navpoint:	(string) name of navpoitn to fire at 
  1419. -- fire_once:			(boolean, optional) set to true to only fire once, or false to fire continuously (defaults to false) 
  1420. -- 
  1421. function force_fire(name, fire_at_navpoint, fire_once) 
  1422. 	if (force_fire_do(name, fire_at_navpoint, fire_once)) then 
  1423. 		while (not(force_ai_mode_check_done(name))) do 
  1424. 			thread_yield() 
  1425. 		end 
  1426. 	end 
  1427. end 
  1428.  
  1429. -- Force an NPC to fire at a character. 
  1430. -- 
  1431. -- name:					(string) name of the NPC 
  1432. -- fire_at_target:	(string) name of the target character 
  1433. -- fire_once:			(boolean, optional) set to true to only fire once, or false to fire continuously (defaults to false) 
  1434. -- 
  1435. function force_fire_target(name, fire_at_target, fire_once) 
  1436. 	if (force_fire_target_do(name, fire_at_target, fire_once)) then 
  1437. 		while (not(force_ai_mode_check_done(name))) do 
  1438. 			thread_yield() 
  1439. 		end 
  1440. 	end 
  1441. end 
  1442.  
  1443. -- Force an NPC to toss a thrown weapon at a navpoint. 
  1444. -- 
  1445. -- name:				(string) name of the NPC 
  1446. -- target_navp:	(string) name of the target navpoint 
  1447. -- throw_pitch:	(float, optional) angle of elevation to throw at, in degrees (defaults to 45 degrees) 
  1448. -- throw_speed:	(float, optional) speed to throw at, in m/s (defaults to -1, which means use the default throw speed of the weapon) 
  1449. -- 
  1450. function force_throw(name, target_navp, throw_pitch, throw_speed) 
  1451. 	if (force_throw_do(name, target_navp, throw_pitch, throw_speed)) then 
  1452. 		while (not(force_ai_mode_check_done(name))) do 
  1453. 			thread_yield() 
  1454. 		end 
  1455. 	end 
  1456. end 
  1457.  
  1458. -- Force an NPC to toss a thrown weapon at a character. 
  1459. -- 
  1460. -- name:		(string) name of the NPC 
  1461. -- target:	(string) name of the target character 
  1462. -- 
  1463. function force_throw_char(name, target) 
  1464. 	if (force_throw_char_do(name, target)) then 
  1465. 		while (not(force_ai_mode_check_done(name))) do 
  1466. 			thread_yield() 
  1467. 		end 
  1468. 	end 
  1469. end 
  1470.  
  1471. -- Get the distance from an object to the closest player, and also returns the closest player. 
  1472. -- 
  1473. -- object:			(string) name of the object 
  1474. -- player_list:	(table of strings, optional) list of players to test against, or nil to test against all players (defaults to nil) 
  1475. -- 
  1476. -- returns:			(float) distance from the object to the closest player 
  1477. -- returns:			(string) name of closest player 
  1478. -- 
  1479. function get_dist_closest_player_to_object(object, player_list) 
  1480. 	if player_list == nil then 
  1481. 		player_list = player_names_get_all() 
  1482. 	end 
  1483. 	 
  1484. 	if sizeof_table( player_list ) == 0 then 
  1485. 		return 
  1486. 	end 
  1487. 	 
  1488. 	local closest_dist = get_dist(player_list[1], object) 
  1489. 	local closest_player = player_list[1] 
  1490. 	 
  1491. 	-- Spin through the available players 
  1492. 	for i, p in pairs(player_list) do 
  1493. 		local current_dist = get_dist(p, object) 
  1494. 		if current_dist < closest_dist then 
  1495. 			closest_dist = current_dist 
  1496. 			closest_player = p 
  1497. 		end 
  1498. 	end 
  1499. 	 
  1500. 	return closest_dist, closest_player 
  1501. end 
  1502.  
  1503. -- Get a random entry from a lua table. 
  1504. -- 
  1505. -- returns:		(any type) a random entry from the table passed in (can be any type) 
  1506. -- returns:		(nil) if the table passed in is not a table or has no entries, returns nil 
  1507. -- 
  1508. function get_random_table_entry(input_table) 
  1509. 	if (type(input_table) ~= "table") then 
  1510. 		return nil 
  1511. 	end 
  1512.  
  1513. 	if (sizeof_table(input_table) == 0) then 
  1514. 		return nil 
  1515. 	end 
  1516.  
  1517. 	return input_table[rand_int(1, sizeof_table(input_table))] 
  1518. end 
  1519.  
  1520. -- Gets a random player. If the game's not in coop, always returns the local player. 
  1521. -- Created this to select a random player for the AI to target. 
  1522. -- 
  1523. -- returns: LOCAL_PLAYER or REMOTE_PLAYER. In non-coop games, returns LOCAL_PLAYER. 
  1524. -- 
  1525. function get_random_target_player() 
  1526. 	if ( coop_is_active() == false ) then 
  1527. 		return LOCAL_PLAYER 
  1528. 	end 
  1529.  
  1530. 	local players_table = { LOCAL_PLAYER, REMOTE_PLAYER } 
  1531.  
  1532. 	return get_random_table_entry( players_table ) 
  1533. end 
  1534.  
  1535. -- Creates all script objects belonging to the specified script group. 
  1536. -- 
  1537. -- group:	(string or table) name of the script group, or a group table (should have a "name" field that contains the name of the group) 
  1538. -- block:	(boolean, optional) set to true to block until everything in the group has finished streaming in (defaults to false) 
  1539. -- 
  1540. -- If the script object is already created, it will reset the script object to initial position and state. The objects will be unhidden by default. 
  1541. -- 
  1542. -- Example: 
  1543. -- 
  1544. --		group_create("mission 1 characters", true) 
  1545. -- 
  1546. -- Creates all objects in the "mission 1 characters" group and waits for them to stream in. 
  1547. -- 
  1548. -- Notes: 
  1549. --  - before group_create() is called, script objects in the group donít exist, so they donít need to be hidden 
  1550. --  - also, this means that any script commands using those script objects must come AFTER the group_create() call; otherwise those commands will do nothing 
  1551. --  - group_create() call should probably go in mission_start() rather than mission_setup(), as in the final game, the player might have several missions open at once 
  1552. -- 
  1553. function group_create(group, block) 
  1554. 	local group_name = group 
  1555.  
  1556. 	-- With the new setup of groups in mission scripts, each group should have a "name" field that contains the name of the group 
  1557. 	if (type(group) == "table" and type(group.name) == "string") then 
  1558. 		group_name = group.name 
  1559. 	end 
  1560.  
  1561. 	-- pause npc spawning. we are starting in an area where we can't see peds and cars. so don't bother waiting for them 
  1562. 	-- object_spawn_pause(true, "group_create") 
  1563. 	 
  1564. 	group_create_do(group_name) 
  1565.  
  1566. 	local handle = thread_new("group_create_check_done_loop", group_name) 
  1567.  
  1568. 	if (block == true) then 
  1569. 		while (not thread_check_done(handle)) do 
  1570. 			thread_yield() 
  1571. 		end 
  1572. 		thread_yield() 
  1573. 	end 
  1574.  
  1575. 	-- pause npc spawning. we are starting in an area where we can't see peds and cars. so don't bother waiting for them 
  1576. 	-- object_spawn_pause(false, "group_create") 
  1577. end 
  1578.  
  1579. -- Creates all script objects belonging to the specified script group, and makes them all hidden. 
  1580. -- 
  1581. -- group:	(string or table) name of the script group, or a group table (should have a "name" field that contains the name of the group) 
  1582. -- block:	(boolean, optional) set to true to block until everything in the group has finished streaming in (defaults to false) 
  1583. -- 
  1584. -- If the script object is already created, it will reset the script object to initial position and state. 
  1585. -- 
  1586. -- This function behaves the same as the group_create script action, except that all members of the group remain hidden until manually made visible. 
  1587. -- 
  1588. function group_create_hidden(group, block) 
  1589. 	local group_name = group 
  1590.  
  1591. 	-- With the new setup of groups in mission scripts, each group should have a "name" field that contains the name of the group 
  1592. 	if (type(group) == "table" and type(group.name) == "string") then 
  1593. 		group_name = group.name 
  1594. 	end 
  1595. 	 
  1596. 	group_create_hidden_do(group_name) 
  1597.  
  1598. 	local handle = thread_new("group_create_check_done_loop", group_name) 
  1599.  
  1600. 	if (block == true) then 
  1601. 		while (not thread_check_done(handle)) do 
  1602. 			thread_yield() 
  1603. 		end 
  1604. 		thread_yield() 
  1605. 	end 
  1606. end 
  1607.  
  1608. -- Destroys all objects belonging to the specified script group 
  1609. -- 
  1610. -- group:	(string or table) name of a script group, or a script group table with a "name" field 
  1611. -- 
  1612. function group_destroy(group) 
  1613. 	if (type(group) == "table" and type(group.name) == "string") then 
  1614. 		group_destroy_do(group.name) 
  1615. 	else 
  1616. 		group_destroy_do(group) 
  1617. 	end 
  1618. end 
  1619.  
  1620. -- Hide a group of script objects 
  1621. -- 
  1622. -- group:	(string or table) name of a script group, or a script group table with a "name" field 
  1623. -- 
  1624. function group_hide(group) 
  1625. 	if (type(group) == "table" and type(group.name) == "string") then 
  1626. 		group_hide_do(group.name) 
  1627. 	else 
  1628. 		group_hide_do(group) 
  1629. 	end 
  1630. end 
  1631.  
  1632. -- Check if a group is loaded 
  1633. -- 
  1634. -- group:	(string or table) name of a script group, or a script group table with a "name" field 
  1635. -- 
  1636. -- returns:	(boolean) true if the group is loaded, false otherwise 
  1637. -- 
  1638. function group_is_loaded(group) 
  1639. 	if (type(group) == "table" and type(group.name) == "string") then 
  1640. 		return group_is_loaded_internal(group.name) 
  1641. 	else 
  1642. 		return group_is_loaded_internal(group) 
  1643. 	end 
  1644. end 
  1645.  
  1646. -- run a function on each NPC in a provided group. 
  1647. -- 
  1648. -- group: (string or table) the name of the script group or a script group table with a "name" field. 
  1649. -- fn: (function reference) the funciton you wish to execute on each NPC.  Should be protoyped like so - my_func(npc_name) 
  1650. -- 
  1651. function group_foreach_npc(group, fn) 
  1652. 	if (type(group) == "table" and type(group.name) == "string") then 
  1653. 		group = group.name 
  1654. 	end 
  1655. 	 
  1656. 	-- If it's not a function, that's no good. 
  1657. 	if (type(fn) == "function") then 
  1658. 		local np = group_get_first_npc(group) 
  1659. 		while (np) do 
  1660. 			fn(np) 
  1661. 			np = group_get_next_npc(group, np) 
  1662. 		end 
  1663. 	end 
  1664. end 
  1665.  
  1666. -- Unhide a group of script objects 
  1667. -- 
  1668. -- group:	(string or table) name of a script group, or a script group table with a "name" field 
  1669. -- 
  1670. function group_show(group) 
  1671. 	if (type(group) == "table" and type(group.name) == "string") then 
  1672. 		group_show_do(group.name) 
  1673. 	else 
  1674. 		group_show_do(group) 
  1675. 	end 
  1676. end 
  1677.  
  1678. -- Make a helicopter fly through one or more navpoints. 
  1679. -- 
  1680. -- name:		(string) name of the helicopter 
  1681. -- speed:		(float) spead to fly at, in m/s (-1 to use default movement speed) 
  1682. -- path:		(string) name of a scripted_path, or single navpoint  
  1683. -- 
  1684. -- The helicopter will pathfind through the specified path or to the specified point, 
  1685. -- avoiding buildings and other obstacles along the way. 
  1686. -- 
  1687. function helicopter_fly_to(name, speed, path, reverse_sp) 
  1688. 	local direct = false 
  1689. 	local follow = "" 
  1690. 	local continue_at_goal = false 
  1691. 	local follow_dist = 0.0 
  1692. 	local directly_above = false 
  1693. 	local loop_path = false 
  1694. 	local start_full_speed = false 
  1695. 	return helicopter_fly_to_internal(name, speed, direct, follow, continue_at_goal, path, follow_dist, directly_above, loop_path, start_full_speed, reverse_sp) 
  1696. end 
  1697.  
  1698. -- Make a helicopter fly through one or more navpoints, ignoring any obstacles along the way. 
  1699. -- 
  1700. -- name:		(string) name of the helicopter 
  1701. -- speed:		(float) spead to fly at, in m/s (-1 to use default movement speed) 
  1702. -- path:		(string) name of a scripted_path, or single navpoint  
  1703. -- 
  1704. -- Use the function only when you are absolutely sure there are no obstacles between waypoints. The helicopter will not move around them when using this function. 
  1705. -- 
  1706. function helicopter_fly_to_direct(name, speed, path,reverse_sp) 
  1707. 	local direct = true 
  1708. 	local follow = "" 
  1709. 	local continue_at_goal = false 
  1710. 	local follow_dist = 0.0 
  1711. 	local directly_above = false 
  1712. 	local loop_path = false 
  1713. 	return helicopter_fly_to_internal(name, speed, direct, follow, continue_at_goal, path, follow_dist, directly_above, loop_path,reverse_sp) 
  1714. end 
  1715.  
  1716. -- Make a helicopter fly through one or more navpoints, ignoring any obstacles along the way. 
  1717. -- 
  1718. -- name:		(string) name of the helicopter 
  1719. -- speed:		(float) spead to fly at, in m/s (-1 to use default movement speed) 
  1720. -- path:		(string) name of a scripted_path NOTE:  SHOULD BE A PATH!!! 
  1721. -- 
  1722. -- Use the function only when you are absolutely sure there are no obstacles between waypoints. 
  1723. --	The helicopter will not move around them when using this function. 
  1724. --	WARNING:  This function will return immediately unlike other similar functions. (when do you end running in a loop?) 
  1725. -- 
  1726. function helicopter_fly_to_direct_loop(name, speed, path) 
  1727. 	local direct = true 
  1728. 	local follow = "" 
  1729. 	local continue_at_goal = false 
  1730. 	local follow_dist = 0.0 
  1731. 	local directly_above = false 
  1732. 	local loop_path = true 
  1733.  
  1734. 	-- direct call to helicopter_fly_to_do because we don't want to wait for completion 
  1735. 	if (helicopter_fly_to_do(name, speed, direct, follow, continue_at_goal, path, follow_dist, directly_above, loop_path)) then 
  1736. 		-- immediate return 
  1737. 		return true 
  1738. 	else 
  1739. 		return false 
  1740. 	end 
  1741. end 
  1742.  
  1743. -- Make a helicopter fly through one or more navpoints, ignoring any obstacles along the way and without stopping. 
  1744. -- 
  1745. -- name:			(string) name of the helicopter 
  1746. -- speed:		(float) spead to fly at, in m/s (-1 to use default movement speed) 
  1747. -- path:		(string) name of a scripted_path, or single navpoint  
  1748. -- 
  1749. -- Use the function only when you are absolutely sure there are no obstacles between waypoints. The helicopter will not move around them when using this function. 
  1750. -- 
  1751. function helicopter_fly_to_direct_dont_stop(name, speed, path) 
  1752. 	local direct = true 
  1753. 	local follow = "" 
  1754. 	local continue_at_goal = true 
  1755. 	local follow_dist = 0.0 
  1756. 	local directly_above = false 
  1757. 	local loop_path = false 
  1758. 	return helicopter_fly_to_internal(name, speed, direct, follow, continue_at_goal, path, follow_dist, directly_above, loop_path) 
  1759. end 
  1760.  
  1761. -- Make a helicopter fly through one or more navpoints while following a target, ignoring obstacles along the way. 
  1762. -- 
  1763. -- name:				(string) name of the helicopter 
  1764. -- speed:			(float) spead to fly at, in m/s (-1 to use default movement speed) 
  1765. -- target:			(string) name of target to follow 
  1766. -- path:				(string) name of a scripted_path, or single navpoint 
  1767. -- follow_dist:	(number) distance at which to follow 
  1768. -- directly_above:(bool) whether the helicopter should be directly above the target vehicle 
  1769. -- 
  1770. -- Use the function only when you are absolutely sure there are no obstacles between waypoints. The helicopter will not move around them when using this function. 
  1771. -- 
  1772. function helicopter_fly_to_direct_follow(name, speed, target, path, follow_dist, directly_above) 
  1773. 	local direct = true 
  1774. 	local follow = target 
  1775. 	local continue_at_goal = false 
  1776. 	local loop_path = false 
  1777. 	return helicopter_fly_to_internal(name, speed, direct, follow, continue_at_goal, path, follow_dist, directly_above, loop_path) 
  1778. end 
  1779.  
  1780. -- Make a helicopter fly through one or more navpoints while following a target, ignoring obstacles along the way and without stopping. 
  1781. -- 
  1782. -- name:				(string) name of the helicopter 
  1783. -- speed:			(float) spead to fly at, in m/s (-1 to use default movement speed) 
  1784. -- target:			(string) name of target to follow 
  1785. -- path:				(string) name of a scripted_path, or single navpoint  
  1786. -- follow_dist:	(number) distance at which to follow 
  1787. -- directly_above:(bool) whether the helicopter should be directly above the target vehicle 
  1788. -- 
  1789. -- Use the function only when you are absolutely sure there are no obstacles between waypoints. The helicopter will not move around them when using this function. 
  1790. -- 
  1791. function helicopter_fly_to_direct_follow_dont_stop(name, speed, target, path, follow_dist, directly_above) 
  1792. 	local direct = true 
  1793. 	local follow = target 
  1794. 	local continue_at_goal = true 
  1795. 	local loop_path = false 
  1796. 	return helicopter_fly_to_internal(name, speed, direct, follow, continue_at_goal, path, follow_dist, directly_above, loop_path) 
  1797. end 
  1798.  
  1799. -- Make a helicopter fly through one or more navpoints without stopping 
  1800. -- 
  1801. -- name:			(string) name of the helicopter 
  1802. -- speed:		(float) spead to fly at, in m/s (-1 to use default movement speed) 
  1803. -- path:		(string) name of a scripted_path, or single navpoint  
  1804. -- 
  1805. -- The helicopter will pathfind through the specified points, avoiding buildings and other obstacles along the way. 
  1806. -- 
  1807. function helicopter_fly_to_dont_stop(name, speed, path) 
  1808. 	local direct = false 
  1809. 	local follow = "" 
  1810. 	local continue_at_goal = true 
  1811. 	local follow_dist = 0.0 
  1812. 	local directly_above = false 
  1813. 	local loop_path = false 
  1814. 	return helicopter_fly_to_internal(name, speed, direct, follow, continue_at_goal, path, follow_dist, directly_above, loop_path) 
  1815. end 
  1816.  
  1817. -- Add an item to a character's inventory. 
  1818. -- 
  1819. -- item_name:	(string) name of the item 
  1820. -- count:		(integer, optional) number of the item to give, or ammount of reserve ammo to give in the case of weapons (default = 1) 
  1821. -- character:	(string, optional) character to add item to (defaults to the local player) 
  1822. -- equip_now:	(boolean, optional) set to true to force the item to be immediately equipped (defaults to false) 
  1823. -- 
  1824. function inv_item_add(item_name, count, character, equip_now)	 
  1825. 	if (type(item_name) == "table" ) then 
  1826. 		local size = sizeof_table(item_name) 
  1827. 		 
  1828. 		for x=1, size, 1 do 
  1829. 			inv_item_add_do(item_name[x], count[x], character, equip_now) 
  1830. 		end	 
  1831. 	else 
  1832. 		inv_item_add_do(item_name, count, character, equip_now) 
  1833. 	end 
  1834. end 
  1835.  
  1836. -- Check if a script tag refers to a player. 
  1837. -- 
  1838. -- tag:		(string) tag to check 
  1839. -- 
  1840. -- returns:	(boolean) true if the tag refers to a player, else false 
  1841. -- 
  1842. function is_player_tag(tag) 
  1843. 	-- Search the "closest" tags 
  1844. 	if tag == CLOSEST_PLAYER or tag == CLOSEST_TEAM1 or tag == CLOSEST_TEAM2 then 
  1845. 		return true 
  1846. 	end 
  1847. 	 
  1848. 	-- Loop through the player tags 
  1849. 	for i, player in pairs(PLAYER_TAG_LIST) do 
  1850. 		if tag == player then 
  1851. 			return true 
  1852. 		end 
  1853. 	end 
  1854. 	 
  1855. 	return false 
  1856. end 
  1857.  
  1858. -- Toggle level lights on or off 
  1859. -- 
  1860. -- enable:			(bool) whether to enable or disable all level lights 
  1861. -- toggle_style:	(enumeration, optional) method by which to toggle the level lights 
  1862. -- 
  1863. function level_lights_toggle_all(enable, toggle_style) 
  1864. 	if (toggle_style == nil) then 
  1865. 		toggle_style = LEVEL_LIGHT_TOGGLE_STYLE_FADE 
  1866. 	end 
  1867.  
  1868. 	level_light_enable_all_do(enable, toggle_style) 
  1869. end 
  1870.  
  1871. -- Check line of sight between two human-types 
  1872. -- 
  1873. -- name_one, name_two:  Names of the people to check los between 
  1874. -- 
  1875.  
  1876. -- Check for line-of-sight between two characters. 
  1877. -- 
  1878. -- name_one:	(string) name of the first character 
  1879. -- name_two:	(string) name of the second character 
  1880. -- 
  1881. -- returns:		(boolean) true if there is line-of-sight between the characters, or false if there is not 
  1882. -- 
  1883. -- Note that this function may take up to a 100 frames before returning a result and will block in the meantime. 
  1884. -- 
  1885. function los_check(name_one, name_two) 
  1886. 	local retval = false 
  1887. 	local current_los_result = -1 
  1888. 	local num_retries = 0 
  1889. 	-- It's possible for the los check to continually get deleted intead of processed 
  1890. 	-- For example, if one of the humans is hidden.  So only try re-issuing 100 times. 
  1891. 	while (current_los_result == -1 and num_retries < 100) do 
  1892. 		current_los_result = los_check_do(name_one, name_two) 
  1893. 		thread_yield() 
  1894. 		num_retries = num_retries + 1 
  1895. 	end 
  1896. 	if (current_los_result == 0) then 
  1897. 		return false 
  1898. 	end 
  1899. 	if (current_los_result == 1) then 
  1900. 		return true 
  1901. 	end 
  1902. 	return false 
  1903. end 
  1904.  
  1905. -- Add a minimap marker and object indicator to a table (or single object) of navpoints, players, or script objects. 
  1906. -- 
  1907. -- object_name:				(table or string) table of objects (or a single object) to add object indicators to 
  1908. -- minimap_icon_name:		(string) name of the minimap icon 
  1909. -- object_indicator_id:		(integer) ID of the object indicator asset to use 
  1910. -- object_indicator_flags:	(integer, optional) flags for the object indicator (defaults to OI_FLAGS_DEFAULT) 
  1911. -- sync_type:					(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  1912. -- fade_dist:					(float, optional) distance to start fading if the OI_FLAG_FADE flag is specified (default, 100.0) 
  1913. -- 
  1914. -- Returns the number of objects that were found (markers successfully added) 
  1915. -- 
  1916. function marker_add(object_name, minimap_icon_name, object_indicator_id, object_indicator_flags, sync_type, fade_dist) 
  1917. 	local num_added = 0 
  1918.  
  1919. 	if (type(object_name) == "table") then 
  1920. 		for i,obj in pairs(object_name) do 
  1921. 			num_added = num_added + marker_add(obj, minimap_icon_name, object_indicator_id, object_indicator_flags, sync_type) 
  1922. 		end 
  1923. 	elseif (type(object_name) == "string") then 
  1924. 		if (object_indicator_flags == nil) then 
  1925. 			object_indicator_flags = OI_FLAGS_DEFAULT 
  1926. 		end 
  1927.  
  1928. 		if (sync_type == nil) then 
  1929. 			sync_type = SYNC_ALL 
  1930. 		end 
  1931. 		 
  1932. 		if (fade_dist == nil) then 
  1933. 			fade_dist = 100.0 
  1934. 		end 
  1935.  
  1936. 		minimap_icon_add_do( object_name, minimap_icon_name, "", 0, sync_type ) 
  1937. 		-- If the object was found and the object indicator was added, increase the number by 1 
  1938. 		if (object_indicator_add_do( object_name, object_indicator_id, object_indicator_flags, sync_type, fade_dist ) == true) then 
  1939. 			num_added = num_added + 1 
  1940. 		end 
  1941. 	end 
  1942.  
  1943. 	return num_added 
  1944. end 
  1945.  
  1946. -- Add a minimap marker and ingame effect to all objects in a script group. 
  1947. -- 
  1948. -- group:						(string or table) name of a script group, or a script group table with a "name" field 
  1949. -- minimap_icon_name:		(string) name of the minimap icon 
  1950. -- object_indicator_id:		(integer) ID of the object indicator asset to use 
  1951. -- object_indicator_flags:	(integer, optional) flags for the object indicator (defaults to OI_FLAGS_DEFAULT) 
  1952. -- sync_type:					(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  1953. -- 
  1954. function marker_add_script_group( group, minimap_icon_name, object_indicator_id, object_indicator_flags, sync_type ) 
  1955. 	if (object_indicator_flags == nil) then 
  1956. 		object_indicator_flags = OI_FLAGS_DEFAULT 
  1957. 	end 
  1958.  
  1959. 	if (sync_type == nil) then 
  1960. 		sync_type = SYNC_ALL 
  1961. 	end 
  1962.  
  1963. 	local group_name = group 
  1964.  
  1965. 	if (type(group) == "table" and type(group.name) == "string") then 
  1966. 		group_name = group.name 
  1967. 	end 
  1968.  
  1969. 	minimap_icon_add_script_group_do( group_name, minimap_icon_name, "", 0, sync_type ) 
  1970. 	object_indicator_add_script_group_do( group_name, object_indicator_id, object_indicator_flags, sync_type ) 
  1971. end 
  1972.  
  1973. -- Add an object indicator to the npc in the script group closest to the target. 
  1974. -- 
  1975. -- target_name:				(string) name of the target to find the npc closest to 
  1976. -- group:						(string or table) name of a script group, or a script group table with a "name" field 
  1977. -- object_indicator_id:		(integer) ID of the object indicator asset to use 
  1978. -- object_indicator_flags:	(integer, optional) flags for the object indicator (defaults to OI_FLAGS_DEFAULT) 
  1979. -- sync_type:					(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  1980. -- 
  1981. -- returns:						(string) the name of the npc that got the marker, or "" if none. 
  1982. -- 
  1983. function marker_add_closest_to_target( target_name, group, object_indicator_id, object_indicator_flags, sync_type ) 
  1984. 	if (object_indicator_flags == nil) then 
  1985. 		object_indicator_flags = OI_FLAGS_DEFAULT 
  1986. 	end 
  1987.  
  1988. 	if (sync_type == nil) then 
  1989. 		sync_type = SYNC_ALL 
  1990. 	end 
  1991.  
  1992. 	local group_name = group 
  1993.  
  1994. 	if (type(group) == "table" and type(group.name) == "string") then 
  1995. 		group_name = group.name 
  1996. 	end 
  1997. 	 
  1998. 	return add_object_indicator_to_closest_npc( target_name, group_name, object_indicator_id, object_indicator_flags, sync_type ) 
  1999. end 
  2000.  
  2001. -- Add a minimap marker and ingame effect to a script trigger. 
  2002. -- 
  2003. -- trigger_name:				(string) name of the script trigger 
  2004. -- minimap_icon_name:		(string) name of the minimap icon 
  2005. -- ingame_effect_name:		(string, optional) name of ingame effect (defaults to nil) 
  2006. -- object_indicator_id:		(integer, optional) ID of the object indicator asset to use (defaults to nil) 
  2007. -- object_indicator_flags:	(integer, optional) flags for the object indicator (defaults to OI_FLAGS_LOCATION) 
  2008. -- sync_type:					(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2009. -- fade_dist:					(float, optional) distance to start fading if the OI_FLAG_FADE flag is specified (default, 100.0) 
  2010. -- 
  2011. function marker_add_trigger( trigger_name, minimap_icon_name, ingame_effect_name, object_indicator_id, object_indicator_flags, sync_type, fade_dist ) 
  2012. 	if (sync_type == nil) then 
  2013. 		sync_type = SYNC_ALL 
  2014. 	end 
  2015. 	 
  2016. 	if (fade_dist == nil) then 
  2017. 		fade_dist = 100.0 
  2018. 	end 
  2019.  
  2020. 	minimap_icon_add_do(trigger_name, minimap_icon_name, "", 0, sync_type) 
  2021.  
  2022. 	if (ingame_effect_name ~= nil) then 
  2023. 		ingame_effect_add_trigger(trigger_name, ingame_effect_name, sync_type) 
  2024. 	end 
  2025.  
  2026. 	if (object_indicator_id ~= nil) then 
  2027. 		if (object_indicator_flags == nil) then 
  2028. 			object_indicator_flags = OI_FLAGS_LOCATION 
  2029. 		end 
  2030. 		object_indicator_add_do(trigger_name, object_indicator_id, object_indicator_flags, sync_type, fade_dist) 
  2031. 	end 
  2032. end 
  2033.  
  2034. -- Remove a minimap marker and ingame effect from a table of objects or a single object 
  2035. -- 
  2036. -- object_name:(table or string) table of objects (or a single object) to remove markers and effects from 
  2037. -- sync_type:	(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2038. -- 
  2039. function marker_remove(object_name, sync_type) 
  2040. 	if (type(object_name) == "table") then 
  2041. 		for i,obj in pairs(object_name) do 
  2042. 			marker_remove(obj, sync_type) 
  2043. 		end 
  2044. 	elseif (type(object_name) == "string") then 
  2045. 		if (sync_type == nil) then 
  2046. 			sync_type = SYNC_ALL 
  2047. 		end 
  2048.  
  2049. 		minimap_icon_remove_do( object_name, sync_type ) 
  2050. 		object_indicator_remove_do( object_name, sync_type ) 
  2051. 	end 
  2052. end 
  2053.  
  2054. -- Remove a minimap marker and ingame effect from a script group. 
  2055. -- 
  2056. -- group:		(string or table) name of a script group, or a script group table with a "name" field 
  2057. -- sync_type:	(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2058. -- 
  2059. function marker_remove_script_group( group, sync_type ) 
  2060. 	if (sync_type == nil) then 
  2061. 		sync_type = SYNC_ALL 
  2062. 	end 
  2063.  
  2064. 	local group_name = group 
  2065.  
  2066. 	if (type(group) == "table" and type(group.name) == "string") then 
  2067. 		group_name = group.name 
  2068. 	end 
  2069. 	 
  2070. 	minimap_icon_remove_script_group_do( group_name, sync_type ) 
  2071. 	object_indicator_remove_script_group_do( group_name, sync_type ) 
  2072. end 
  2073.  
  2074. -- Remove a minimap marker and ingame effect from a script trigger. 
  2075. -- 
  2076. -- trigger_name:	(string) name of the script trigger 
  2077. -- sync_type:		(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2078. -- 
  2079. function marker_remove_trigger( trigger_name, sync_type ) 
  2080. 	if (sync_type == nil) then 
  2081. 		sync_type = SYNC_ALL 
  2082. 	end 
  2083. 	 
  2084. 	minimap_icon_remove_do(trigger_name, sync_type) 
  2085. 	ingame_effect_remove_trigger(trigger_name, sync_type) 
  2086. 	object_indicator_remove_do(trigger_name, sync_type) 
  2087. end 
  2088.  
  2089. -- Add a minimap marker to a trigger, navpoint, player, or script object, with an optional radius around the marker. 
  2090. -- 
  2091. -- object_name:			(string or table) name of the object or a nested table of names 
  2092. -- minimap_icon_name:	(string) name of the minimap icon 
  2093. -- bitmap_glow_name:		(string, optional) name of minimap icon glow (defaults to nil) 
  2094. -- radius:					(float, optional) radius of the minimap marker, in meters (defaults to 0.0) 
  2095. -- sync_type:				(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2096. -- 
  2097. function minimap_icon_add(object_name, minimap_icon_name, bitmap_glow_name, radius, sync_type) 
  2098. 	if (type(object_name) == "string") then 
  2099. 		minimap_icon_add_do( object_name, minimap_icon_name, bitmap_glow_name, radius, sync_type ) 
  2100. 	elseif (type(object_name) == "table") then 
  2101. 		for i,obj in pairs(object_name) do 
  2102. 			minimap_icon_add(obj, minimap_icon_name, bitmap_glow_name, radius, sync_type) 
  2103. 		end 
  2104. 	end 
  2105. end 
  2106.  
  2107. -- Add a minimap radius around an object. 
  2108. -- 
  2109. -- object_name:(string or table) name of the object (can be a navpoint, trigger, or mover) or a nested table of names 
  2110. -- radius:		(float, optional) radius of the minimap marker, in meters (defaults to 0.0) 
  2111. -- sync_type:	(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2112. -- 
  2113. function minimap_icon_add_radius(object_name, radius, sync_type) 
  2114. 	if (type(object_name) == "string") then 
  2115. 		minimap_icon_add_radius_do( object_name, radius, sync_type ) 
  2116. 	elseif (type(object_name) == "table") then 
  2117. 		for i,obj in pairs(object_name) do 
  2118. 			minimap_icon_add_radius(obj, radius, sync_type) 
  2119. 		end 
  2120. 	end 
  2121. end 
  2122.  
  2123. -- Add a minimap marker to all objects in a script group, with an optional radius around the marker. 
  2124. -- 
  2125. -- group:					(string or table) name of a script group, or a script group table with a "name" field 
  2126. -- minimap_icon_name:	(string) name of the minimap icon 
  2127. -- bitmap_glow_name:		(string, optional) name of minimap icon glow (defaults to nil) 
  2128. -- radius:					(float, optional) radius of the minimap marker, in meters (defaults to 0.0) 
  2129. -- sync_type:				(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2130. -- 
  2131. function minimap_icon_add_script_group(group, minimap_icon_name, bitmap_glow_name, radius, sync_type) 
  2132. 	local group_name = group 
  2133.  
  2134. 	if (type(group) == "table" and type(group.name) == "string") then 
  2135. 		group_name = group.name 
  2136. 	end 
  2137.  
  2138. 	minimap_icon_add_script_group_do(group_name, minimap_icon_name, bitmap_glow_name, radius, sync_type) 
  2139. end 
  2140.  
  2141. -- Remove the minimap marker from a trigger, navpoint, player, or script object. 
  2142. -- 
  2143. -- object_name:	(string or table) name of the object or a nested table of names 
  2144. -- sync_type:		(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2145. -- 
  2146. function minimap_icon_remove(object_name, sync_type) 
  2147. 	if (type(object_name) == "string") then 
  2148. 		minimap_icon_remove_do(object_name, sync_type) 
  2149. 	elseif (type(object_name) == "table") then 
  2150. 		for i,obj in pairs(object_name) do 
  2151. 			minimap_icon_remove(obj, sync_type) 
  2152. 		end 
  2153. 	end 
  2154. end 
  2155.  
  2156. -- Remove a minimap radius from an object. 
  2157. -- 
  2158. -- object_name:	(string or table) name of the object (can be a navpoint, trigger, or mover) or a nested table of names 
  2159. -- sync_type:		(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2160. -- 
  2161. function minimap_icon_remove_radius(object_name, sync_type) 
  2162. 	if (type(object_name) == "string") then 
  2163. 		minimap_icon_remove_radius_do( object_name, sync_type ) 
  2164. 	elseif (type(object_name) == "table") then 
  2165. 		for i,obj in pairs(object_name) do 
  2166. 			minimap_icon_remove_radius(obj, sync_type) 
  2167. 		end 
  2168. 	end 
  2169. end 
  2170.  
  2171. -- Remove a minimap marker from all objects in a script group. 
  2172. -- 
  2173. -- group:		(string or table) name of a script group, or a script group table with a "name" field 
  2174. -- sync_type:	(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2175. -- 
  2176. function minimap_icon_remove_script_group(group, sync_type) 
  2177. 	local group_name = group 
  2178.  
  2179. 	if (type(group) == "table" and type(group.name) == "string") then 
  2180. 		group_name = group.name 
  2181. 	end 
  2182.  
  2183. 	minimap_icon_remove_script_group_do(group_name, sync_type) 
  2184. end 
  2185.  
  2186. -- Re-enable player controls if they have been disabled by a mission start fade-in. 
  2187. -- 
  2188. -- Should be called in mission cleanup by all missions that use mission_start_fade_in / mission_start_fade_out. 
  2189. -- 
  2190. function mission_cleanup_maybe_reenable_player_controls() 
  2191.    if ( Player_controls_disabled_by_mission_start_fadeout ) then 
  2192.       player_controls_enable( LOCAL_PLAYER ) 
  2193.       if ( coop_is_active() ) then 
  2194.          player_controls_enable( REMOTE_PLAYER ) 
  2195.       end 
  2196.       Player_controls_disabled_by_mission_start_fadeout = false 
  2197.    end 
  2198. end 
  2199.  
  2200. -- Generates a mission help message and updates the Objectives screen. 
  2201. -- 
  2202. -- tag:		(string) name of help text to display (from mission_help.xtbl) 
  2203. -- string1:	(string, optional) first replacement string 
  2204. -- string2:	(string, optional) second replacement string 
  2205. -- sync:		(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2206. -- 
  2207. -- Displays a localized help string in the help text area of the HUD. 
  2208. -- There are two replacement strings available which will replace up to 
  2209. -- instances of %s in the table text. 
  2210. -- 
  2211. -- The duration of the text is specified in the mission_help.xtbl file.  If 
  2212. -- a value of 0.0 is specified, the default duration is 5 seconds. 
  2213. -- 
  2214. -- Example: 
  2215. -- 
  2216. -- Entry in the mission_help.xtbl file has name of "KillGangsta" and text of 
  2217. -- "Kill %s more %s members!" 
  2218. -- 
  2219. -- Executing the lua statement 'mission_help_table("KillGangsta", 5, "Vice King")' 
  2220. -- results in the help output "Kill 5 more Vice King members!"  
  2221. -- 
  2222. function mission_help_table(tag, string1, string2, sync) 
  2223. 	mission_help_table_do(tag, true, false, string1, string2, sync, 0) 
  2224. end 
  2225.  
  2226. -- Generates a mission help nag message, but does not update the Objectives screen. 
  2227. -- 
  2228. -- tag:		(string) name of help text to display (from mission_help.xtbl) 
  2229. -- string1:	(string, optional) first replacement string 
  2230. -- string2:	(string, optional) second replacement string 
  2231. -- sync:		(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2232. -- 
  2233. function mission_help_table_nag(tag, string1, string2, sync) 
  2234. 	mission_help_table_do(tag, false, false, string1, string2, sync, 0) 
  2235. end 
  2236.  
  2237. -- Enables player controls and fades in the screen. 
  2238. -- 
  2239. -- Should be used when the mission is loading groups at start. Prevents the player from moving or seeing anything happening. Use in conjunction with mission_start_fade_out. 
  2240. -- 
  2241. function mission_start_fade_in() 
  2242.    mip_streaming_pause(false, "mission_start_fade_in") 
  2243.    object_spawn_pause(false, "mission_start_fade_in") 
  2244.  
  2245.    fade_in( START_FADE_IN_TIME ) 
  2246. 	fade_in_block() 
  2247.    player_controls_enable( LOCAL_PLAYER ) 
  2248.    if ( coop_is_active() ) then 
  2249.       player_controls_enable( REMOTE_PLAYER ) 
  2250.    end 
  2251.    Player_controls_disabled_by_mission_start_fadeout = false 
  2252. end 
  2253.  
  2254. -- Disables player controls and instantly fades out the screen. 
  2255. -- 
  2256. -- Should be used when the mission is loading groups at start. Prevents the player from moving or seeing anything happening. Use in conjunction with mission_start_fade_in. 
  2257. -- 
  2258. function mission_start_fade_out(fade_time) 
  2259. 	if (fade_time == nil) then 
  2260. 		fade_time = START_FADE_OUT_TIME 
  2261. 	end 
  2262. 	 
  2263. 	fade_out( fade_time ) 
  2264. 	player_controls_disable( LOCAL_PLAYER ) 
  2265. 	if ( coop_is_active() ) then 
  2266. 		player_controls_disable( REMOTE_PLAYER ) 
  2267. 	end 
  2268. 	Player_controls_disabled_by_mission_start_fadeout = true 
  2269. 	fade_out_block() 
  2270.  
  2271. 	mip_streaming_pause(true, "mission_start_fade_out") 
  2272. 	object_spawn_pause(true, "mission_start_fade_out") 
  2273. end 
  2274.  
  2275. -- Add a mission waypoint at a navpoint. 
  2276. -- 
  2277. -- navpoint:	(string) name of navpoint, NPC, vehicle, or trigger 
  2278. -- sync_type:	(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2279. -- 
  2280. -- If a mission waypoint currently exists, it will be removed and replaced by this call. 
  2281. -- 
  2282. function mission_waypoint_add(navpoint, sync_type) 
  2283. 	mission_waypoint_remove(sync_type) 
  2284. 	Mission_waypoint = waypoint_add(navpoint, sync_type) 
  2285. end 
  2286.  
  2287. -- Remove the current mission waypoint. 
  2288. -- 
  2289. -- sync_type:	(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2290. -- 
  2291. function mission_waypoint_remove(sync_type) 
  2292. 	if (Mission_waypoint ~= -1) then	 
  2293. 		waypoint_remove(sync_type) 
  2294. 		Mission_waypoint = -1 
  2295. 	end 
  2296. end 
  2297.  
  2298. -- move_to speed defines 
  2299. MOVE_TO_WALK = 1 
  2300. MOVE_TO_RUN = 2 
  2301. MOVE_TO_SPRINT = 3 
  2302.  
  2303. -- Make a character pathfind through one or more navpoints. 
  2304. --  
  2305. -- name:					(string) name of the character 
  2306. -- dest:					(string) name of the scripted_path spline to follow, or navpoint to go to 
  2307. -- speed:				(integer, optional) movement speed (1 = walk, 2 = run, 3 = sprint; defaults to 1) 
  2308. -- retry_on_failure:	(boolean, optional) set to true to keep retrying if path calculation fails (defaults to false) 
  2309. -- move_and_fire:		(boolean, optional) set to true to allow the NPC to fire on the move (defaults to false) 
  2310. -- 
  2311. -- This function blocks until the character has finished pathfinding. 
  2312.  
  2313. -- 
  2314. function move_to(name, dest, ...) 
  2315. 	local num_args, speed, retry_on_failure, move_and_fire, path_index 
  2316.  
  2317. 	-- Wait until the resource is loaded. 
  2318. 	character_wait_for_loaded_resource(name) 
  2319. 			 
  2320. 	num_args = arg.n 
  2321.  
  2322. 	-- get move and fire 
  2323. 	if ( (num_args >= 3) and (type(arg[num_args]) == "boolean") ) then 
  2324. 		move_and_fire = arg[num_args] 
  2325. 		num_args = num_args - 1 
  2326. 	else 
  2327. 		move_and_fire = false 
  2328. 	end 
  2329.  
  2330. 	-- get retry 
  2331. 	if ( (num_args >= 2) and (type(arg[num_args]) == "boolean") ) then 
  2332. 		retry_on_failure = arg[num_args] 
  2333. 		num_args = num_args - 1 
  2334. 	else 
  2335. 		retry_on_failure = false 
  2336. 	end 
  2337. 	 
  2338. 	-- get speed 
  2339. 	if ( (num_args >= 1) and (type(arg[num_args]) == "number") ) then 
  2340. 		speed = arg[num_args] 
  2341. 	else 
  2342. 		speed = 1 
  2343. 	end 
  2344. 	 
  2345. 	while( not character_is_ready( name ) ) do 
  2346. 		thread_yield() 
  2347. 	end 
  2348. 	 
  2349. 	if (type(dest) == "string") then 
  2350. 		-- Is it a scripted_path or a single navpoint? 
  2351. 		if ( path_name_is_path(dest)) then 
  2352. 			local	idx 
  2353.  
  2354. 			idx = 0 
  2355. 			while (1) do 
  2356. 				path_index = move_to_do(name, dest, speed, retry_on_failure, move_and_fire, true, idx) 
  2357. 				if (not (path_index == 0)) then 
  2358. 					-- Keep checking for done until the character dies or reaches the destination 
  2359. 					while ( character_is_dead( name ) == false and 
  2360. 						not( move_to_check_done(path_index,  name, dest, speed, retry_on_failure, move_and_fire, true, idx ) ) ) do 
  2361. 						thread_yield() 
  2362. 					end 
  2363.  
  2364. 					idx = idx + 1 
  2365. 				else 
  2366. 					return false 
  2367. 				end 
  2368. 			end 
  2369. 		else 
  2370. 			path_index = move_to_do(name, dest, speed, retry_on_failure, move_and_fire, false, 0) 
  2371. 			if (not (path_index == 0)) then 
  2372. 			-- Keep checking for done until the character dies or reaches the destination 
  2373. 				while ( character_is_dead( name ) == false and 
  2374. 					not( move_to_check_done(path_index,  name, dest, speed, retry_on_failure, move_and_fire, false, 0 ) ) ) do 
  2375. 					thread_yield() 
  2376. 				end 
  2377. 			else 
  2378. 				return false 
  2379. 			end 
  2380. 		end 
  2381. 	end 
  2382. 	 
  2383. 	return (not character_is_dead( name )) 
  2384. end 
  2385.  
  2386. -- Make a character pathfind through one or more navpoints. Returns if at any point the character dies. 
  2387. --  
  2388. -- name:				(string) name of the character 
  2389. -- dest:				(string) name of the scripted_path spline to follow, or navpoint to go to 
  2390. -- speed:				(integer, optional) movement speed (1 = walk, 2 = run, 3 = sprint; defaults to 1) 
  2391. -- retry_on_failure:	(boolean, optional) set to true to keep retrying if path calculation fails (defaults to false) 
  2392. -- move_and_fire:		(booelan, optional) set to true to allow the NPC to fire on the move (defaults to false) 
  2393. -- 
  2394. -- This function blocks until the character has finished pathfinding, or until the character dies. This function otherwise behaves exactly like move_to. 
  2395. -- 
  2396. function move_to_safe(name, dest, ...) 
  2397.  
  2398.    -- If the character is dead, then forget about pathfinding 
  2399.    if ( character_is_dead( name ) == true ) then 
  2400.       return false 
  2401.    end 
  2402.  
  2403. 	local num_args, speed, retry_on_failure, move_and_fire, path_index 
  2404.  
  2405. 	-- Wait until the resource is loaded. 
  2406. 	character_wait_for_loaded_resource(name) 
  2407. 			 
  2408. 	num_args = arg.n 
  2409.  
  2410. 	-- get move and fire 
  2411. 	if ( (num_args >= 3) and (type(arg[num_args]) == "boolean") ) then 
  2412. 		move_and_fire = arg[num_args] 
  2413. 		num_args = num_args - 1 
  2414. 	else 
  2415. 		move_and_fire = false 
  2416. 	end 
  2417.  
  2418. 	-- get retry 
  2419. 	if ( (num_args >= 2) and (type(arg[num_args]) == "boolean") ) then 
  2420. 		retry_on_failure = arg[num_args] 
  2421. 		num_args = num_args - 1 
  2422. 	else 
  2423. 		retry_on_failure = false 
  2424. 	end 
  2425. 	 
  2426. 	-- get speed 
  2427. 	if ( (num_args >= 1) and (type(arg[num_args]) == "number") ) then 
  2428. 		speed = arg[num_args] 
  2429. 	else 
  2430. 		speed = 1 
  2431. 	end 
  2432. 	 
  2433. 	while( not character_is_ready( name )) do 
  2434. 		thread_yield() 
  2435.  
  2436. 		-- Don't pathfind if character is dead or entered a vehicle 
  2437. 		if (character_is_dead(name) or character_is_in_vehicle( name )) then 
  2438. 			return false 
  2439. 		end 
  2440. 	end 
  2441.  
  2442. 	-- Character may have entered a vehicle in the same frame that it became ready. 
  2443. 		if (character_is_in_vehicle( name )) then 
  2444. 			return false 
  2445. 		end 
  2446.  
  2447. 	if (type(dest) == "string") then 
  2448. 		-- Is it a path list of navpoints are a single navpoint? 
  2449. 		if (path_name_is_path(dest)) then 
  2450. 			local	idx 
  2451.  
  2452. 			idx = 0 
  2453. 			while (1) do 
  2454. 				path_index = move_to_do(name, dest, speed, retry_on_failure, move_and_fire, true, idx) 
  2455. 				if (not (path_index == 0)) then 
  2456. 					while(not(move_to_check_done(path_index, name, dest, speed, retry_on_failure, move_and_fire, true, idx))) do 
  2457. 						thread_yield() 
  2458.  
  2459. 						-- Don't pathfind if character is dead or entered a vehicle 
  2460. 						if (character_is_dead(name) or character_is_in_vehicle( name )) then 
  2461. 							return false 
  2462. 						end 
  2463. 					end 
  2464.  
  2465. 					idx = idx + 1 
  2466. 				else 
  2467. 					return false 
  2468. 				end 
  2469. 			end 
  2470. 		else 
  2471. 			path_index = move_to_do(name, dest, speed, retry_on_failure, move_and_fire, false, 0) 
  2472. 			if (not (path_index == 0)) then 
  2473. 				while(not(move_to_check_done(path_index, name, dest, speed, retry_on_failure, move_and_fire, false, 0))) do 
  2474. 					thread_yield() 
  2475.  
  2476. 					-- Don't pathfind if character is dead or entered a vehicle 
  2477. 					if (character_is_dead(name) or character_is_in_vehicle( name )) then 
  2478. 						return false 
  2479. 					end 
  2480. 				end 
  2481. 			else 
  2482. 				return false 
  2483. 			end 
  2484. 		end 
  2485. 	end 
  2486. 	 
  2487. 	return true 
  2488. end 
  2489.  
  2490. -- Add object indicators to a table (or single object) of NPCs, vehicles, items, or anything else that's set up in object_indicator.h 
  2491. -- 
  2492. -- object_name:(table or string) table of names of the objects to add indicators to (or a single object, table of tables, etc.) 
  2493. -- asset_id:	(int) ID of the indicator asset to use 
  2494. -- flags:		(int, optional) flags for the object indicator (defaults to OI_FLAGS_DEFAULT) 
  2495. -- sync_type:	(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2496. -- fade_dist:					(float, optional) distance to start fading if the OI_FLAG_FADE flag is specified (default, 100.0) 
  2497. -- 
  2498. -- Returns the number of object indicators that were added 
  2499. -- 
  2500. function object_indicator_add(object_name, asset_id, flags, sync_type, fade_dist) 
  2501. 	local num_added = 0 
  2502. 	if (type(object_name) == "table") then 
  2503. 		for i,obj in pairs(object_name) do 
  2504. 			num_added = num_added + object_indicator_add(obj, asset_id, flags, sync_type) 
  2505. 		end 
  2506. 	elseif (type(object_name) == "string") then 
  2507. 		if (sync_type == nil) then 
  2508. 			sync_type = SYNC_ALL 
  2509. 		end 
  2510. 		 
  2511. 		if (fade_dist == nil) then 
  2512. 			fade_dist = 100.0 
  2513. 		end 
  2514.  
  2515. 		if (flags == nil) then 
  2516. 			flags = OI_FLAGS_DEFAULT 
  2517. 		end 
  2518.  
  2519. 		-- If the object was found, and the indicator was added, increase the number by 1 
  2520. 		if (object_indicator_add_do(object_name, asset_id, flags, sync_type, fade_dist) == true) then 
  2521. 			num_added = num_added + 1 
  2522. 		end 
  2523. 	end 
  2524.  
  2525. 	return num_added 
  2526. end 
  2527.  
  2528. -- Add an object indicator to each object in a group of script objects 
  2529. -- 
  2530. -- group:		(string or table) name of a script group, or a script group table with a "name" field 
  2531. -- asset_id:	(integer) ID of the object indicator asset to use 
  2532. -- flags:		(integer, optional) flags for the object indicator (defaults to OI_FLAGS_DEFAULT) 
  2533. -- sync_type:	(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2534. -- 
  2535. function object_indicator_add_script_group(group, asset_id, flags, sync_type) 
  2536. 	local group_name = group 
  2537.  
  2538. 	if (type(group) == "table" and type(group.name) == "string") then 
  2539. 		group_name = group.name 
  2540. 	end 
  2541.  
  2542. 	if (flags == nil) then 
  2543. 		flags = OI_FLAGS_DEFAULT 
  2544. 	end 
  2545.  
  2546. 	if (sync_type == nil) then 
  2547. 		sync_type = SYNC_ALL 
  2548. 	end 
  2549. 	 
  2550. 	object_indicator_add_script_group_do(group_name, asset_id, flags, sync_type) 
  2551. end 
  2552.  
  2553. -- Remove object indicators from a table (or single object) of NPCs, vehicles, items, or anything else that's set up in object_indicator.h 
  2554. -- 
  2555. -- object_name:(table or string) table of names of the objects to remove indicators from (or a single object, table of tables, etc.) 
  2556. -- sync_type:	(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2557. -- 
  2558. function object_indicator_remove(object_name, sync_type) 
  2559. 	if (type(object_name) == "table") then 
  2560. 		for i,obj in pairs(object_name) do 
  2561. 			object_indicator_remove(obj, sync_type) 
  2562. 		end 
  2563. 	elseif (type(object_name) == "string") then 
  2564. 		if (sync_type == nil) then 
  2565. 			sync_type = SYNC_ALL 
  2566. 		end 
  2567.  
  2568. 		object_indicator_remove_do(object_name, sync_type) 
  2569. 	end 
  2570. end 
  2571.  
  2572. -- Removes an object indicator from each object in a group of script objects 
  2573. -- 
  2574. -- group:		(string or table) name of a script group, or a script group table with a "name" field 
  2575. -- sync_type:	(enumeration, optional) synchronization type (SYNC_LOCAL = affects local player, SYNC_REMOTE = affects remote player, or SYNC_ALL = affects both players; defaults to SYNC_ALL) 
  2576. -- 
  2577. function object_indicator_remove_script_group(group, sync_type) 
  2578. 	local group_name = group 
  2579.  
  2580. 	if (type(group) == "table" and type(group.name) == "string") then 
  2581. 		group_name = group.name 
  2582. 	end 
  2583.  
  2584. 	if (sync_type == nil) then 
  2585. 		sync_type = SYNC_ALL 
  2586. 	end 
  2587. 	 
  2588. 	object_indicator_remove_script_group_do(group_name, sync_type) 
  2589. end 
  2590.  
  2591. -- Register a callback function for when any human is killed 
  2592. -- 
  2593. -- function_name:	(string) name of the function 
  2594. -- mission_name:	(string) name of the mission) 
  2595. -- 
  2596. -- When the callback is executed, the following parameters are passed to it: 
  2597. --  - (string) name of the attacker 
  2598. --  - (string) name of the team of the victim 
  2599. -- 
  2600. function on_random_human_killed( function_name, mission_name ) 
  2601. 	on_random_obj_killed_do( function_name, mission_name, 1 ) 
  2602. end 
  2603.  
  2604. -- Register a callback function for when any mover is killed 
  2605. -- 
  2606. -- function_name:	(string) name of the function 
  2607. -- mission_name:	(string) name of the mission 
  2608. -- 
  2609. -- When the callback is executed, the following parameters are passed to it: 
  2610. --  - (string) name of the attacker 
  2611. --  - (string) property name (from levels.xtbl) of the mover destroyed 
  2612. -- 
  2613. function on_random_mover_killed( function_name, mission_name ) 
  2614. 	on_random_obj_killed_do( function_name, mission_name, 2 ) 
  2615. end 
  2616.  
  2617. -- Register a callback function for when any object in an object destroyed script is destroyed during a mission. 
  2618. -- 
  2619. -- function_name:	(string) name of the function 
  2620. -- mission_name:	(string) name of the mission 
  2621. -- 
  2622. -- The object destroyed script is generated by Art. It contains the chunk number (all three digits, including leading zeroes) 
  2623. -- and the object name. The file is named exactly the same as the mission/stronghold/activity and has a ".ods" file extension. 
  2624. -- 
  2625. function on_random_ods_killed( function_name, mission_name ) 
  2626. 	on_random_obj_killed_do( function_name, mission_name, 4 ) 
  2627. end 
  2628.  
  2629. -- Register a callback function for when any vehicle is destroyed 
  2630. -- 
  2631. -- function_name:	(string) name of the function 
  2632. -- mission_name:	(string) name of the mission) 
  2633. -- 
  2634. -- When the callback is executed, the following parameters are passed to it: 
  2635. --  - (string) name of the attacker 
  2636. --  - (string) name of the team of the vehicle's driver 
  2637. -- 
  2638. function on_random_vehicle_killed( function_name, mission_name ) 
  2639. 	on_random_obj_killed_do( function_name, mission_name, 3 ) 
  2640. end 
  2641.  
  2642. -- Open an interface dialog box. 
  2643. -- 
  2644. -- title_tag:	(string) identifying tag for the title text 
  2645. -- body_tag:	(string) identifying tag for the body text 
  2646. -- tag1:			(string) identifying tag for selection 1 text 
  2647. -- tag2:			(string) identifying tag for selection 2 text 
  2648. -- 
  2649. -- returns:		(integer) index corresponding to which option was selected (0 corresponds to the first option, 1 corresponds to the second option, etc.) 
  2650. -- 
  2651. function open_vint_dialog(title_tag, body_tag, tag1, tag2) 
  2652. 	open_vint_dialog_do(title_tag, body_tag, tag1, tag2) 
  2653.  
  2654. 	local		check_value = open_vint_dialog_check_done() 
  2655.  
  2656. 	while (check_value == -1) do 
  2657. 		thread_yield() 
  2658. 		check_value = open_vint_dialog_check_done() 
  2659. 	end 
  2660.  
  2661. 	return check_value 
  2662. end 
  2663.  
  2664. -- Add members to the player's party. 
  2665. -- 
  2666. -- names:	(one or more strings) names of NPCs to add to the player's party 
  2667. -- player:	(string, optional) name of the player to add party members to (defaults to closest player) 
  2668. -- 
  2669. -- This function will automatically dismiss followers to make room for the specified NPCs. 
  2670. -- 
  2671. -- Example: 
  2672. -- 
  2673. --		party_add("NPC1", "NPC2", "NPC3") 
  2674. -- 
  2675. -- Adds three NPCs to the closeset playerís party, "NPC1", "NPC2", and "NPC3". 
  2676. -- 
  2677. function party_add(...) 
  2678. 	local player = CLOSEST_PLAYER 
  2679. 	 
  2680. 	if is_player_tag(arg[arg.n]) then 
  2681. 		player = arg[arg.n] 
  2682. 		arg.n = arg.n - 1 
  2683. 	end 
  2684. 		 
  2685. 	party_add_do(player, arg, false) 
  2686. end 
  2687.  
  2688. -- Add members to the player's party, but only if there is room. 
  2689. -- 
  2690. -- names:	(one or more strings) names of NPCs to add to the player's party 
  2691. -- player:	(string, optional) name of the player to add party members to (defaults to closest player) 
  2692. -- 
  2693. function party_add_optional(...) 
  2694. 	local player = CLOSEST_PLAYER 
  2695. 	 
  2696. 	if is_player_tag(arg[arg.n]) then 
  2697. 		player = arg[arg.n] 
  2698. 		arg.n = arg.n - 1 
  2699. 	end 
  2700. 		 
  2701. 	party_add_do(player, arg, true) 
  2702. end 
  2703.  
  2704. function party_add_ignore_limits(...) 
  2705. 	local player = CLOSEST_PLAYER 
  2706. 	 
  2707. 	if is_player_tag(arg[arg.n]) then 
  2708. 		player = arg[arg.n] 
  2709. 		arg.n = arg.n - 1 
  2710. 	end 
  2711. 		 
  2712. 	party_add_do(player, arg, false, true) 
  2713. end 
  2714.  
  2715.  
  2716. -- Dismiss members from the player's party 
  2717. -- 
  2718. -- names:	(one or more strings) names of NPCs to remove from the player's party 
  2719. -- 
  2720. -- Example: 
  2721. -- 
  2722. --		party_dismiss("NPC1", "NPC2", "NPC3") 
  2723. -- 
  2724. -- Dismisses three NPCs from the playerís party, "NPC1", "NPC2", and "NPC3". 
  2725. -- 
  2726. function party_dismiss(...) 
  2727. 	party_dismiss_do(arg) 
  2728. end 
  2729.  
  2730. -- Override an NPC's persona on a per-situation basis. 
  2731. -- 
  2732. -- name:			(string) name of the NPC 
  2733. -- situation:	(string, or table of strings) persona situation(s) to override (as defined in persona_situations.xtbl) 
  2734. -- audio:		(string, optional) audio file to force play, or "" to override with silence (defaults to "") 
  2735. -- count:		(integer, optional) number of times the override should occur, or -1 to override indefinitely (defaults to -1) 
  2736. -- 
  2737. -- The specified audio will play in the specified situation instead of the default voice line(s) defined in persona.xtbl. 
  2738. -- 
  2739. function persona_override_character_start(character, situation, audio, count) 
  2740.  
  2741. 	if type(situation) == "table" then 
  2742. 		for i, persona_situation in pairs(situation) do 
  2743. 			local trigger_prefix = persona_trigger_get_player_prefix(character) 
  2744. 			persona_override_character_start_do(character, persona_situation, trigger_prefix .. audio, count) 
  2745. 		end 
  2746. 	else 
  2747. 		local trigger_prefix = persona_trigger_get_player_prefix(character) 
  2748. 		persona_override_character_start_do(character, situation, trigger_prefix .. audio, count) 
  2749. 	end 
  2750.  
  2751. end 
  2752.  
  2753. -- Reset the situational persona overrides for an NPC. 
  2754. -- 
  2755. -- name:			(string) name of the NPC 
  2756. -- situation:	(string, or table of strings) persona situation(s) to reset back to normal (as defined in persona_situations.xtbl) 
  2757. -- 
  2758. function persona_override_character_stop(character, situation) 
  2759.  
  2760. 	if type(situation) == "table" then 
  2761. 		for i, persona_situation in pairs(situation) do 
  2762. 			persona_override_character_stop_do(character, persona_situation) 
  2763. 		end 
  2764. 	else 
  2765. 		persona_override_character_stop_do(character, situation) 
  2766. 	end 
  2767.  
  2768. end 
  2769.  
  2770. -- Override a group of personas for a single situation. 
  2771. -- 
  2772. -- persona_list:	(string, or table of strings) names of personas to override 
  2773. -- situation:		(string, or table of strings) persona situation(s) to override (as defined in persona_situations.xtbl) 
  2774. -- tag_suffix:		(string) common trigger suffix 
  2775. -- 
  2776. -- Example: 
  2777. -- 
  2778. --	The following 3 lines: 
  2779. -- 
  2780. --		EX_PERSONAS	=	{	["AM_Gang1"]	=	"AMGNG1"; 
  2781. --								["AM_Gang2"]	=	"AMGNG2"; 
  2782. --							} 
  2783. --		persona_override_group(EX_PERSONAS, POT_SITUATIONS[POT_ATTACK], "EX01_ATTACK") 
  2784. -- 
  2785. --	Are equivalent to: 
  2786. -- 
  2787. --		persona_override_persona_start("AM_Gang1", "threat - alert (group attack)",	"AMGNG1_EX01_ATTACK") 
  2788. --		persona_override_persona_start("AM_Gang1", "threat - alert (solo attack)",		"AFGNG1_EX01_ATTACK") 
  2789. --		persona_override_persona_start("AM_Gang2", "threat - alert (group attack)",	"AMGNG2_EX01_ATTACK") 
  2790. --		persona_override_persona_start("AM_Gang2", "threat - alert (solo attack)",		"AFGNG2_EX01_ATTACK") 
  2791. -- 
  2792. -- Generally this function will be used with one of 4 predefined gang persona tables: 
  2793. -- 
  2794. --		BROTHERHOOD_PERSONAS 
  2795. --		RONIN_PERSONAS 
  2796. --		SAINTS_PERSONAS 
  2797. --		SAMEDI_PERSONAS 
  2798. -- 
  2799. function persona_override_group_start(persona_list, situation, tag_suffix) 
  2800. 	for persona, tag_prefix in pairs(persona_list) do 
  2801. 		persona_override_persona_start(persona, situation, tag_prefix .. "_" .. tag_suffix) 
  2802. 	end 
  2803. end 
  2804.  
  2805. -- Reset the situational override for a group of personas. 
  2806. -- 
  2807. -- persona_list:	(string, or table of strings) names of personas to override 
  2808. -- situation:		(string, or table of strings) persona situation(s) to override (as defined in persona_situations.xtbl) 
  2809. -- 
  2810. function persona_override_group_stop(persona_list, situation) 
  2811. 	for persona, tag_prefix in pairs(persona_list) do 
  2812. 		persona_override_persona_stop(persona, situation) 
  2813. 	end 
  2814. end 
  2815.  
  2816. -- Override all script NPCs with a particular persona in a given situation (or situations). 
  2817. -- 
  2818. -- persona:		(string) name of the persona 
  2819. -- situation:	(string, or table of strings) persona situation(s) to override (as defined in persona_situations.xtbl) 
  2820. -- audio:		(string, optional) audio file to force play, or "" to override with silence (defaults to "") 
  2821. -- count:		(integer, optional) number of times the override should occur, or -1 to override indefinitely (defaults to -1) 
  2822. -- 
  2823. function persona_override_persona_start_old(persona, situation, audio, count) 
  2824.  
  2825. 	if type(situation) == "table" then 
  2826. 		for i, persona_situation in pairs(situation) do 
  2827. 			persona_override_persona_start_do(persona, persona_situation, audio, count) 
  2828. 		end 
  2829. 	else 
  2830. 		persona_override_persona_start_do(persona, situation) 
  2831. 	end 
  2832.  
  2833. end 
  2834.  
  2835. -- Reset all script NPCs with a particular persona in a given situation (or situations). 
  2836. -- 
  2837. -- persona:		(string) name of the persona 
  2838. -- situation:	(string, or table of strings) persona situation(s) to reset (as defined in persona_situations.xtbl) 
  2839. -- 
  2840. function persona_override_persona_stop_old(persona, situation) 
  2841.  
  2842. 	if type(situation) == "table" then 
  2843. 		for i, persona_situation in pairs(situation) do 
  2844. 			persona_override_persona_stop_do(persona, persona_situation) 
  2845. 		end 
  2846. 	else 
  2847. 		persona_override_persona_stop_do(persona, situation) 
  2848. 	end 
  2849.  
  2850. end 
  2851.  
  2852. -- Get the prefix that should be prepended to the character's persona triggers. 
  2853. -- 
  2854. -- name:		(string) name of the character 
  2855. -- 
  2856. --	returns:	(string) prefix to prepend to the trigger 
  2857. --  
  2858. function persona_trigger_get_player_prefix(name) 
  2859.  
  2860. 	local voice_prefixes = {[0] = "WM", [1] = "BM", [2] = "WMA", [3] = "WF", [4] = "BF", [5] = "HF", [6] = "Z"} 
  2861. 	local trigger_prefix = "" 
  2862.  
  2863. 	if(character_is_player(name)) then 
  2864. 		local player_voice_prefix = voice_prefixes[player_get_custom_voice(name)] 
  2865. 		if(player_voice_prefix ~= nil) then 
  2866. 			trigger_prefix = player_voice_prefix 
  2867. 		end 
  2868. 	end 
  2869.  
  2870. 	return trigger_prefix 
  2871.  
  2872. end 
  2873.  
  2874. -- Make a player take another character as a human shield. 
  2875. -- 
  2876. -- player:		(string) name of the player that will take a human shield 
  2877. -- victim:		(string) name of target 
  2878. -- tele_victim: (bool, optional) Teleport the victim in range if necessary? (default true) 
  2879. -- 
  2880. -- returns:		(bool) true if the grab worked, false if it failed. 
  2881. function player_take_human_shield( player, victim, tele_victim ) 
  2882. 	 
  2883. 	if (player == nil or player == "" or victim == nil or victim == "") then 
  2884. 		return false 
  2885. 	end 
  2886. 	 
  2887. 	if not player_take_human_shield_do( player, victim, tele_victim ) then 
  2888. 		return false 
  2889. 	end 
  2890.  
  2891.    -- loop as long as grabber and grabee are alive until we've succeeded 
  2892.    while ( character_is_dead( player ) == false and 
  2893.            character_is_dead( victim ) == false and 
  2894. 	   character_take_human_shield_check_done( player, victim) == false) do 
  2895.       thread_yield(); 
  2896.    end 
  2897.     
  2898.    return character_has_specific_human_shield( player, victim ) 
  2899. end 
  2900.  
  2901. -- Take a screenshot and stores the output file on the kit. 
  2902. -- 
  2903. -- filename:	(string, optional) filename to use for screenshot, excluding the file extension (default filename is MMDD_screenNNN, where MM is the month, DD is the date, and NNN is an incrementing count) 
  2904. -- 
  2905. function screenshot(...) 
  2906. 	if (arg.n > 0) then 
  2907. 		screenshot_do(arg[1]) 
  2908. 	else 
  2909. 		screenshot_do("") 
  2910. 	end 
  2911.  
  2912. 	while (not(screenshot_check_done())) do 
  2913. 		thread_yield() 
  2914. 	end 
  2915. end 
  2916.  
  2917. -- Determine the synchronization type from a player name. 
  2918. -- 
  2919. -- player_name:	(string) name of the player 
  2920. -- 
  2921. -- returns:			(enumeration) SYNC_REMOTE, if the player is REMOTE_PLAYER; SYNC_LOCAL, if the player is LOCAL_PLAYER; else SYNC_ALL 
  2922. -- 
  2923. function sync_from_player(player_name) 
  2924. 	if player_name == REMOTE_PLAYER then 
  2925. 		return SYNC_REMOTE 
  2926. 	end 
  2927. 	if player_name == LOCAL_PLAYER then 
  2928. 		return SYNC_LOCAL 
  2929. 	end 
  2930. 	 
  2931. 	return SYNC_ALL 
  2932. end 
  2933.  
  2934. -- Teleport both the local and remote players. 
  2935. -- 
  2936. -- local_player_nav:		(string) name of the navpoint to teleport the local player to 
  2937. -- remote_player_nav:	(string) name of the navpoint to teleport the remote player to 
  2938. -- exit_vehicles:			(boolean, optional) set to true to force the players to exit from whatever vehicle they are in (defaults to false) 
  2939. -- 
  2940. function teleport_coop( local_player_nav, remote_player_nav, exit_vehicles ) 
  2941.  
  2942. 	assert_screen_is_faded_out() -- Assert that the screen is completely faded out at this point - mission responsibility. 
  2943.  
  2944. 	if (coop_is_active()) then 
  2945. 		teleport( REMOTE_PLAYER, remote_player_nav, exit_vehicles ) 
  2946. 	end 
  2947.  
  2948. 	teleport( LOCAL_PLAYER, local_player_nav, exit_vehicles ) 
  2949.  
  2950. 	if (coop_is_active()) then 
  2951. 		waiting_for_player_dialog( true ) 
  2952. 		repeat thread_yield() until teleport_check_done(REMOTE_PLAYER) 
  2953. 		waiting_for_player_dialog( false ) 
  2954. 	end		 
  2955. 	 
  2956. 	repeat thread_yield() until teleport_check_done(LOCAL_PLAYER) 
  2957. end 
  2958.  
  2959. -- Block until a single thread or table of threads has completed processing 
  2960. -- 
  2961. -- thread_handle:	(number or table) handle to a thread, table of handles to a thread, table of tables, etc... 
  2962. -- 
  2963. function threads_wait_for_completion(thread_handle) 
  2964. 	local ret_val = thread_handle 
  2965.  
  2966. 	if (type(thread_handle) == "number") then 
  2967. 		while (not thread_check_done(thread_handle)) do 
  2968. 			thread_yield() 
  2969. 		end 
  2970. 		ret_val = INVALID_THREAD_HANDLE 
  2971. 	elseif (type(thread_handle) == "table") then 
  2972. 		for i,handle in pairs(thread_handle) do 
  2973. 			ret_val[i] = threads_wait_for_completion(handle) 
  2974. 		end 
  2975. 	end 
  2976.  
  2977. 	-- Returns a copy with the completed threads set to INVALID_THREAD_HANDLE 
  2978. 	return ret_val 
  2979. end 
  2980.  
  2981. -- Make a character turn to face an object (or turn to face the same direction as the object). 
  2982. -- 
  2983. -- name:		(string) name of the character 
  2984. -- target:	(string) name of the object (can be a navpoint, or character, or other scripted object) 
  2985. -- orient:	(boolean, optional) set to true to make the character face the same direction that the object is facing, or false to make the character face the object (defaults to false) 
  2986. -- 
  2987. -- This function blocks until the character has finished turning. 
  2988. -- 
  2989. function turn_to(name, target, orient) 
  2990. 	while (not(character_is_ready(name))) do 
  2991. 		thread_yield() 
  2992. 	end 
  2993. 	 
  2994. 	turn_to_do(name, target, orient) 
  2995.  
  2996. 	while (not(turn_to_check_done(name))) do 
  2997. 		thread_yield() 
  2998. 	end 
  2999. end 
  3000.  
  3001. -- Make a character enter vehicle. 
  3002. -- 
  3003. -- name:							(string) name of the character 
  3004. -- vehicle_name:				(string) name of the vehicle 
  3005. -- seat:							(integer, optional) index of the seat to enter (defaults to 0, the driver's seat) 
  3006. -- block:						(boolean, optional) set to true to block until vehicle entry is finished (defaults to true) 
  3007. -- force_hijack_success:	(boolean, optional) set to true to force any hijacks to automatically succeed (defaults to false) 
  3008. -- block_until_visual:		(boolean, optional) if blocking, only block until the human is visualy in vehicle instead of waiting until the enter is completely finished (defaults to false) 
  3009. -- override_action:			(string, optional) action to play instead of standard vehicle entry actions 
  3010. -- special_entry:				(boolean, optional) if this is set, the special_entry flag is required for the seat used.  This can be used to differentiate seats that should only be used in scripted situations. 
  3011. -- 
  3012. function vehicle_enter(name, vehicle_name, seat, block, force_hijack_success, block_until_visual, override_action, special_entry) 
  3013.    if ( force_hijack_success == nil ) then 
  3014.       force_hijack_success = false 
  3015.    end 
  3016. 	local s = vehicle_enter_do(name, vehicle_name, false, seat, force_hijack_success, override_action, special_entry) 
  3017. 	local r 
  3018. 	 
  3019. 	-- don't bother checking if it was successful unless the request was successful  
  3020. 	if (s and (block or (block == nil))) then 
  3021. 		repeat 
  3022. 			thread_yield() 
  3023. 			r = vehicle_enter_check_done(name, block_until_visual, vehicle_name) 
  3024. 		until r ~= 0 
  3025. 	else 
  3026. 		return s 
  3027. 	end 
  3028. 	 
  3029. 	if r == 2 then 
  3030. 		return false 
  3031. 	else 
  3032. 		return true 
  3033. 	end 
  3034. end 
  3035.  
  3036. -- Make a group of NPCs enter a vehicle. 
  3037. -- 
  3038. -- names:			(string, or table of strings) names of characters entering the vehicle 
  3039. -- vehicle_name:	(string) name of vehicle to enter 
  3040. --  
  3041. function vehicle_enter_group(...) 
  3042. 	local npcs = {} 
  3043. 	local vehicle_name 
  3044.  
  3045. 	if type(arg[1]) == "table" then 
  3046. 		npcs = { unpack(arg[1]) } 
  3047. 		npcs[ "n" ] = sizeof_table( npcs ) 
  3048. 		 
  3049. 		vehicle_name = arg[2] 
  3050. 	else		 
  3051. 		vehicle_name = arg[ arg.n ] 
  3052. 		 
  3053. 		npcs = arg; 
  3054. 		npcs.n = npcs.n - 1 
  3055. 	end 
  3056.  
  3057. 	if (vehicle_enter_group_do(vehicle_name, false, npcs)) then 
  3058. 		while (not(vehicle_enter_group_check_done(vehicle_name, false, npcs))) do 
  3059. 			thread_yield() 
  3060. 		end 
  3061. 	end 
  3062. end 
  3063.  
  3064. -- Teleport a group of NPCs directly into a vehicle 
  3065. -- 
  3066. -- names:			(string, or table of strings) names of characters to teleport 
  3067. -- vehicle_name:	(string) name of vehicle 
  3068. -- 
  3069. -- This function blocks until all the NPCs have finished teleporting. 
  3070. --  
  3071. function vehicle_enter_group_teleport(...) 
  3072. 	local npcs = {} 
  3073. 	local vehicle_name 
  3074.  
  3075. 	if type(arg[1]) == "table" then 
  3076. 		npcs = { unpack(arg[1]) } 
  3077. 		npcs[ "n" ] = sizeof_table( npcs ) 
  3078. 		 
  3079. 		vehicle_name = arg[2] 
  3080. 	else		 
  3081. 		vehicle_name = arg[ arg.n ] 
  3082. 		 
  3083. 		npcs = arg; 
  3084. 		npcs.n = npcs.n - 1 
  3085. 	end 
  3086. 	 
  3087. 	if (vehicle_enter_group_do(vehicle_name, true, npcs)) then 
  3088. 		while (not(vehicle_enter_group_check_done(vehicle_name, true, npcs))) do 
  3089. 			thread_yield() 
  3090. 		end 
  3091. 	end 
  3092. end 
  3093.  
  3094. -- Teleport a character directly into a vehicle. 
  3095. -- 
  3096. -- name:				(string) name of the character 
  3097. -- vehicle_name:	(string) name of the vehicle 
  3098. -- seat:				(integer, optional) index of the seat to enter (defaults to 0, the driver's seat) 
  3099. -- block:			(boolean, optional) set to true to block until vehicle entry is finished (defaults to true) 
  3100. -- exit_current:	(boolean, optional) set to true if the human should vacate their current vehicle (requires blocking) (defaults to true) 
  3101. -- special_entry:	(boolean, optional) if this is set, the special_entry flag is required for the seat used.  This can be used to differentiate seats that should only be used in scripted situations. 
  3102.  
  3103. -- 
  3104. function vehicle_enter_teleport(name, vehicle_name, seat, block, exit_current, special_entry) 
  3105. 	if (block == nil) then 
  3106. 		block = true 
  3107. 	end 
  3108.  
  3109. 	if (exit_current == nil) then 
  3110. 		exit_current = true 
  3111. 	end 
  3112.  
  3113. 	if (exit_current and block) then 
  3114. 		local current_name = get_char_vehicle_name(name) 
  3115. 		if (current_name ~= vehicle_name) then 
  3116. 			-- this blocks 
  3117. 			vehicle_exit_teleport(name, false) 
  3118. 		end 
  3119. 	end 
  3120.  
  3121. 	local s = vehicle_enter_do(name, vehicle_name, true, seat, false, nil, special_entry) 
  3122. 	local r 
  3123. 	 
  3124. 	-- don't bother checking if it was successful unless the request was successful 
  3125. 	if (s and block) then 
  3126. 		repeat 
  3127. 			thread_yield() 
  3128. 			r = vehicle_enter_check_done(name, false, vehicle_name) 
  3129. 		until r ~= 0 
  3130. 	else 
  3131. 		return s 
  3132. 	end 
  3133. 	 
  3134. 	if r == 2 then 
  3135. 		return false 
  3136. 	else 
  3137. 		return true 
  3138. 	end 
  3139. end 
  3140.  
  3141. -- Make a character exit a vehicle. 
  3142. -- 
  3143. -- name:				(string) name of the character 
  3144. -- not_enterable:		(boolean, optional) set to true to make the vehicle unenterable (defaults to false) 
  3145. -- override_action:		(string, optional) action to play instead of standard vehicle entry actions 
  3146. -- 
  3147. -- This function blocks until the character has exited the vehicle. 
  3148. -- 
  3149. function vehicle_exit(name, not_enterable, override_action) 
  3150. 	if (vehicle_exit_do(name, false, not_enterable, false, override_action)) then 
  3151. 		while (not(vehicle_exit_check_done(name))) do 
  3152. 			thread_yield() 
  3153. 		end 
  3154. 	end 
  3155. end 
  3156.  
  3157. -- Make a character exit a vehicle by diving. 
  3158. -- 
  3159. -- name:				(string) name of the character 
  3160. -- not_enterable:	(boolean, optional) set to true to make the vehicle unenterable (defaults to false) 
  3161. -- 
  3162. -- This function blocks until the character has exited the vehicle. 
  3163. -- 
  3164. function vehicle_exit_dive(name, not_enterable) 
  3165. 	if (vehicle_exit_do(name, false, not_enterable, true)) then 
  3166. 		while (not(vehicle_exit_check_done(name))) do 
  3167. 			thread_yield() 
  3168. 		end 
  3169. 	end 
  3170. end 
  3171.  
  3172. -- Make a character exit a vehicle by teleporting. 
  3173. -- 
  3174. -- name:				(string) name of the character 
  3175. -- not_enterable:	(boolean, optional) set to true to make the vehicle unenterable (defaults to false) 
  3176. -- 
  3177. -- This function blocks until the character has exited the vehicle. 
  3178. -- 
  3179. function vehicle_exit_teleport(name, not_enterable) 
  3180. 	if (vehicle_exit_do(name, true, not_enterable, false)) then 
  3181. 		while (not(vehicle_exit_check_done(name))) do 
  3182. 			thread_yield() 
  3183. 		end 
  3184. 	end 
  3185. end 
  3186.  
  3187. -- Make a group of NPCs exit a vehicle. 
  3188. -- 
  3189. -- npc_group:	(table of strings) names of characters exiting the vehicle 
  3190. --  
  3191. function vehicle_exit_group(npc_group, not_enterable) 
  3192. 	if (vehicle_exit_group_do(false, false, not_enterable, npc_group)) then 
  3193. 		while (not(vehicle_exit_group_check_done(npc_group))) do 
  3194. 			thread_yield() 
  3195. 		end 
  3196. 	end 
  3197. end 
  3198.  
  3199. -- Make a group of NPCs dive out of a vehicle. 
  3200. -- 
  3201. -- npc_group:	(table of strings) names of characters exiting the vehicle 
  3202. --  
  3203. function vehicle_exit_group_dive(npc_group, not_enterable) 
  3204. 	if (vehicle_exit_group_do(false, true, not_enterable, npc_group)) then 
  3205. 		while (not(vehicle_exit_group_check_done(npc_group))) do 
  3206. 			thread_yield() 
  3207. 		end 
  3208. 	end 
  3209. end 
  3210.  
  3211. -- Teleport a group of NPCs directly out of a vehicle 
  3212. -- 
  3213. -- npc_group:	(table of strings) names of characters to teleport 
  3214. --  
  3215. function vehicle_exit_group_teleport(npc_group, not_enterable) 
  3216. 	if (vehicle_exit_group_do(true, false, not_enterable, npc_group)) then 
  3217. 		while (not(vehicle_exit_group_check_done(npc_group))) do 
  3218. 			thread_yield() 
  3219. 		end 
  3220. 	end 
  3221. end 
  3222.  
  3223. -- Make a vehicle pathfind through a series of navpoints. 
  3224. -- 
  3225. -- name:					(string) name of the vehicle 
  3226. -- path:					(string) name of scripted path or navpoint to pathfind through 
  3227. -- use_navmesh:		(boolean, optional) set to true if the car should pathfind using the navmesh, or false if it should pathfind using traffic splines (defaults to false) 
  3228. -- stop_at_goal:		(boolean, optional) set to true if the vehicle should stop upon reaching the final destination (defaults to true) 
  3229. -- force_path:			(boolean, optional) set to true to ignore the current position to support looping (defaults to false) 
  3230. -- suppress_errors:	(boolean, optional) set to true to suppress errors (defaults to false) 
  3231. -- 
  3232. function vehicle_pathfind_to(name, path, use_navmesh, stop_at_goal, force_path, suppress_errors) 
  3233. 	if (use_navmesh == nil) then 
  3234. 		use_navmesh = false; 
  3235. 	end 
  3236.  
  3237. 	if (stop_at_goal == nil) then 
  3238. 		stop_at_goal = true 
  3239. 	end 
  3240. 	 
  3241. 	if (force_path == nil) then 
  3242. 		force_path = false 
  3243. 	end 
  3244. 	 
  3245. 	if (suppress_errors == nil) then 
  3246. 		suppress_errors = false; 
  3247. 	end 
  3248.  
  3249. 	if (use_navmesh) then 
  3250. 		if (not vehicle_pathfind_navmesh_do(name, path, force_path, stop_at_goal, suppress_errors, 0)) then 
  3251. 			return false 
  3252. 		end 
  3253. 	else 
  3254. 		if (not vehicle_pathfind_to_do(name, path, stop_at_goal, suppress_errors)) then 
  3255. 			return false 
  3256. 		end 
  3257. 	end 
  3258.  
  3259. 	local check_done = vehicle_pathfind_check_done(name) 
  3260.  
  3261. 	while ( check_done == 0) do 
  3262. 		thread_yield() 
  3263. 		check_done = vehicle_pathfind_check_done(name) 
  3264. 	end 
  3265.  
  3266. 	return check_done == 1 
  3267. end 
  3268.  
  3269. -- Make a vehicle pathfind through a series of navpoints (using the navmesh), starting from a specific point along the path. 
  3270. -- 
  3271. -- name:					(string) name of the vehicle 
  3272. -- start_index:		(integer) index into the path to start from 
  3273. -- path:					(string) name of scripted path or navpoint to pathfind through 
  3274. -- stop_at_goal:		(boolean, optional) set to true if the vehicle should stop upon reaching the final destination (defaults to true) 
  3275. -- force_path:			(boolean, optional) set to true to ignore the current position to support looping (defaults to false) 
  3276. -- suppress_errors:	(boolean, optional) set to true to suppress errors (defaults to false) 
  3277. -- 
  3278. function vehicle_navmesh_pathfind_to_starting_from(name, start_index, path, stop_at_goal, force_path, suppress_errors) 
  3279.  
  3280. 	if (stop_at_goal == nil) then 
  3281. 		stop_at_goal = true 
  3282. 	end 
  3283.  
  3284. 	if (force_path == nil) then 
  3285. 		force_path = false 
  3286. 	end 
  3287.  
  3288. 	if (suppress_errors == nil) then 
  3289. 		suppress_errors = false 
  3290. 	end 
  3291.  
  3292. 	if (not vehicle_pathfind_navmesh_do(name, path, force_path, stop_at_goal, suppress_errors, start_index)) then 
  3293. 		return false 
  3294. 	end 
  3295.  
  3296. 	local check_done = vehicle_pathfind_check_done(name) 
  3297.  
  3298. 	while ( check_done == 0) do 
  3299. 		thread_yield() 
  3300. 		check_done = vehicle_pathfind_check_done(name) 
  3301. 	end 
  3302.  
  3303. 	return check_done == 1 
  3304. end 
  3305.  
  3306. -- Make a vehicle come to a stop. 
  3307. -- 
  3308. -- name:			(string) name of the vehicle 
  3309. -- dont_block:	(boolean, optional) set to true if the function should not block while the vehicle is coming to a stop (defaults to false) 
  3310. -- 
  3311. function vehicle_stop( name, dont_block ) 
  3312.  
  3313. 	if( (name == nil) or (not vehicle_exists(name)) or  (vehicle_is_destroyed(name)) ) then 
  3314. 		return 
  3315. 	end 
  3316.  
  3317. 	vehicle_stop_do( name ) 
  3318. 	 
  3319. 	while( (not dont_block) and get_vehicle_speed(name) > 0 ) do 
  3320. 		thread_yield() 
  3321. 	end 
  3322. end 
  3323.  
  3324. -- Make a vehicle use turret mode to move along a path or to a navpoint. 
  3325. --  
  3326. -- name:			(string) name of the vehicle 
  3327. -- path:			(string) name of scripted_path to follow or navpoint to go to 
  3328. -- stop_at_goal:	(boolean, optional) set to true if the vehicle should stop upon reaching the final destination (defaults to true) 
  3329. -- 
  3330. -- A driver must be added to the car before calling vehicle_turret_base_to(). If the vehicle does not start on a rail, 
  3331. -- it will transition to rail and continue pathing from that position. 
  3332. -- 
  3333. -- Example: 
  3334. -- 
  3335. --		vehicle_turret_base_to("car", "heli_path 001", true) 
  3336. -- 
  3337. -- Sets "car" driving to navp1, and then on to navp2, stopping at goal. 
  3338. -- 
  3339. function vehicle_turret_base_to(name, path, stop_at_goal) 
  3340. 	 
  3341. 	-- Wait until the resource is loaded. 
  3342. 	-- character_wait_for_loaded_resource(name) 
  3343. 				 
  3344. 	if (vehicle_turret_base_to_do(name, path, stop_at_goal)) then 
  3345. 		local check_done = vehicle_pathfind_check_done(name) 
  3346. 		 
  3347. 		while ( check_done == 0) do 
  3348. 			thread_yield() 
  3349. 			check_done = vehicle_pathfind_check_done(name) 
  3350. 		end 
  3351. 		 
  3352. 		return check_done == 1 
  3353. 	else 
  3354. 		return false 
  3355. 	end 
  3356. end 
  3357.  
  3358. --[[ 
  3359. 	process enemy set 
  3360. 	Ver. 1.1 
  3361. 			- moved setup into its own function.  This can be called independently for greater flexability. 
  3362. 			- added cleanup call.  This will cleanup callbacks and kill markers.  This can stop calls in progress. 
  3363. 	Ver. 1.00 
  3364. 	 
  3365. 	Mark all enemies with target markers. (not yet implemented) 
  3366. 	Keep a count of total enemies and enemies killed. 
  3367. 	Continue when all enemies are killed. 
  3368. 	 
  3369. 	Setup: 
  3370. 	a list of all of the enemies that need to be killed 
  3371. 		_GROUP_TABLE	= {	"Script_NPC 001", "Script_NPC 002", "Script_NPC 003", 
  3372. 													"Script_NPC 004" } 
  3373. 	 
  3374. 	After the enemies are spawned, call the function (runs until all are killed) 
  3375. 		Process_enemy_set(_GROUP_TABLE) 
  3376. 	 
  3377. 	Cleanup enemies on your own 
  3378. ]]-- 
  3379.  
  3380. -- *** Defines 
  3381. 	Process_enemy_set_cleared		= false 
  3382. 	Num_enemies_alive					= 0 
  3383. 	Num_enemies_to_kill				= 0 
  3384. 	Process_enemy_set_objective_helptext	= "" 
  3385. 	 
  3386. -- *** Functions 
  3387.  
  3388. -- Wait until a group of enemies is killed before continuing 
  3389. -- 
  3390. -- enemy_table:			(strings, or table of strings) list of enemies to kill 
  3391. -- mission_helptext:		(string, optional) mission help to display 
  3392. -- objective_helptext:	(string, optional) X/Y helptext to display 
  3393. -- 
  3394. function process_enemy_set(enemy_table, mission_helptext, objective_helptext) 
  3395. 	 
  3396. 	enemy_set_setup(enemy_table, true) 
  3397.  
  3398. 	-- Display the help text 
  3399. 	if(mission_helptext) then 
  3400. 		mission_help_table(mission_helptext) 
  3401. 	end 
  3402. 	 
  3403. 	-- Display the objective text 
  3404. 	if(objective_helptext) then 
  3405. 		Process_enemy_set_objective_helptext = objective_helptext 
  3406. 		objective_text(0, Process_enemy_set_objective_helptext, Num_enemies_to_kill - Num_enemies_alive, Num_enemies_to_kill) 
  3407. 	end 
  3408. 	 
  3409. 	while (not Process_enemy_set_cleared) do 
  3410. 		thread_yield() 
  3411. 	end 
  3412. 	 
  3413. 	-- make sure everything is cleaned up 
  3414. 	enemy_set_cleanup(enemy_table) 
  3415.  
  3416. end 
  3417.  
  3418. -- Setup all of the enemies to be killed 
  3419. -- 
  3420. -- enemy_table:				(strings, or table of strings) list of enemies to kill 
  3421. -- target_closest_player	(bool)	if true, then every enemy in the set will target the closest player 
  3422. -- 
  3423. function enemy_set_setup(enemy_table, target_closest_player) 
  3424. 	Process_enemy_set_cleared = false 
  3425.  
  3426. 	-- Assign enemy callbacks 
  3427. 	Num_enemies_alive = 0 
  3428. 	for i, enemy in pairs(enemy_table) do 
  3429. 		if(not character_is_dead(enemy)) then 
  3430. 			-- set a callback to know when the enemy is killed 
  3431. 			on_death("process_enemy_set_killed", enemy) 
  3432. 			marker_add(enemy, MINIMAP_ICON_KILL, OI_ASSET_KILL, OI_FLAGS_DEFAULT, SYNC_ALL) 
  3433. 			if (target_closest_player) then 
  3434. 				ai_add_enemy_target(enemy, CLOSEST_PLAYER, 2) 
  3435. 			end 
  3436. 			Num_enemies_alive = Num_enemies_alive + 1 
  3437. 		end 
  3438. 	end 
  3439. 	 
  3440. 	-- Check the edge condition if all the enemies are already dead 
  3441. 	if (Num_enemies_alive == 0) then 
  3442. 		Process_enemy_set_cleared = true 
  3443. 	end 
  3444.  
  3445. 	-- Setup kill tracking numbers 
  3446. 	Num_enemies_to_kill = sizeof_table(enemy_table) 
  3447. end 
  3448.  
  3449. -- Remove callbacks and markers on the enemy set 
  3450. -- 
  3451. -- enemy_table:			(strings, or table of strings) list of enemies to kill 
  3452. -- 
  3453. function enemy_set_cleanup(enemy_table) 
  3454. 	-- Clear enemy callbacks 
  3455. 	for i, enemy in pairs(enemy_table) do 
  3456. 		-- cleanup the callback 
  3457. 		on_death("", enemy) 
  3458. 		marker_remove(enemy, SYNC_ALL) 
  3459. 	end 
  3460. 	Process_enemy_set_cleared = false 
  3461. end 
  3462.  
  3463. -- *** Callbacks 
  3464. -- Enemy killed callback (counts dead enemies) 
  3465. -- 
  3466. -- enemy:	(string) name of killed NPC 
  3467. -- 
  3468. function process_enemy_set_killed(enemy) 
  3469. 	marker_remove(enemy) 
  3470. 	on_death("",enemy) 
  3471. 	Num_enemies_alive = Num_enemies_alive - 1 
  3472. 	if (Num_enemies_alive < 1) then 
  3473. 		Process_enemy_set_cleared = true 
  3474. 		if (Process_enemy_set_objective_helptext ~= "") then 
  3475. 			objective_text_clear(0) 
  3476. 		end 
  3477. 		Process_enemy_set_objective_helptext = "" 
  3478. 	else 
  3479. 		if (Process_enemy_set_objective_helptext ~= "") then 
  3480. 			objective_text(0, Process_enemy_set_objective_helptext, Num_enemies_to_kill - Num_enemies_alive, Num_enemies_to_kill) 
  3481. 		end 
  3482. 	end 
  3483. end 
  3484.  
  3485. --[[ 
  3486. 	END process enemy set 
  3487. ]]-- 
  3488.  
  3489. --[[ 
  3490. 	temp weapon loadout 
  3491. 	Ver. 1.00 
  3492. 	 
  3493. 	Equip all players with temporary loadout 
  3494. 	Equip the last weapon provided 
  3495. 	 
  3496. 	Setup: 
  3497. 	a list of the weapons to equip the player with 
  3498. 		_PLAYER_LOADOUT	= {	"Gal43", "m16" } 
  3499. 	 
  3500. 	Equipment goes to the player and coop player 
  3501. 		inv_add_temp_loadout( _PLAYER_LOADOUT ) 
  3502. 		 
  3503. 	Make sure you cleanup (will only run if add was called) 
  3504. 		inv_remove_temp_loadout( _PLAYER_LOADOUT ) 
  3505. ]]-- 
  3506.  
  3507. -- *** Defines 
  3508. 	Players_have_temp_loadout		= false 
  3509. 	 
  3510. -- *** Functions 
  3511. -- Add temp weapons with unlimited ammo 
  3512. -- 
  3513. -- weapon_table:	(strings, or table of strings) list of weapons to equip 
  3514. -- restrict_to:	(string, optional) player to restrict loadout to (defaults to both players (if available)) 
  3515. -- 
  3516. function inv_add_temp_loadout(weapon_table, restrict_to) 
  3517. 	local equip_local = true 
  3518. 	local equip_remote = true 
  3519. 	if (restrict_to == LOCAL_PLAYER) then 
  3520. 		equip_remote = false 
  3521. 	end 
  3522. 	if (restrict_to == REMOTE_PLAYER) then 
  3523. 		equip_local = false 
  3524. 	end 
  3525. 		 
  3526. 	local last_weapon = "" 
  3527. 	local in_coop = equip_remote and coop_is_active() 
  3528. 	-- Assign weapons 
  3529. 	for i, weapon in pairs(weapon_table) do 
  3530. 		if (equip_local) then 
  3531. 			inv_weapon_add_temporary(LOCAL_PLAYER, weapon, 1, true) 
  3532. 		end 
  3533. 		if (in_coop) then 
  3534. 			inv_weapon_add_temporary(REMOTE_PLAYER, weapon, 1, true) 
  3535. 		end 
  3536. 		last_weapon = weapon 
  3537. 	end 
  3538. 	 
  3539. 	if (last_weapon ~= "") then 
  3540. 		if (equip_local) then 
  3541. 			inv_item_equip( last_weapon, LOCAL_PLAYER ) 
  3542. 		end 
  3543. 		if (in_coop) then 
  3544. 			inv_item_equip( last_weapon, REMOTE_PLAYER ) 
  3545. 		end 
  3546. 	end 
  3547. 	 
  3548. 	Players_have_temp_loadout = true 
  3549.  
  3550. end 
  3551.  
  3552.  
  3553. -- remove temp weapons 
  3554. -- 
  3555. -- weapon_table:		(strings, or table of strings) list of weapons to remove 
  3556. -- restrict_to:		(string, optional) player to restrict loadout to (defaults to both players (if available)) 
  3557. -- 
  3558. function inv_remove_temp_loadout(weapon_table, restrict_to) 
  3559. 	local equip_local = true 
  3560. 	local equip_remote = true 
  3561. 	if (restrict_to == LOCAL_PLAYER) then 
  3562. 		equip_remote = false 
  3563. 	end 
  3564. 	if (restrict_to == REMOTE_PLAYER) then 
  3565. 		equip_local = false 
  3566. 	end 
  3567. 	 
  3568. 	local in_coop = equip_remote and coop_is_active() 
  3569. 	if (Players_have_temp_loadout) then 
  3570. 		-- remove weapons 
  3571. 		for i, weapon in pairs(weapon_table) do 
  3572. 			if (equip_local) then 
  3573. 				inv_weapon_remove_temporary(LOCAL_PLAYER, weapon) 
  3574. 			end 
  3575. 			if (in_coop) then 
  3576. 				inv_weapon_remove_temporary(REMOTE_PLAYER, weapon) 
  3577. 			end 
  3578. 		end 
  3579. 	end 
  3580. 	 
  3581. 	Players_have_temp_loadout = false 
  3582. end 
  3583.  
  3584. --[[ 
  3585. 	END temp weapon loadout 
  3586. ]]-- 
  3587.  
  3588.  
  3589. --[[ 
  3590. 	Cutscene fade out/in hack 
  3591. ]]-- 
  3592.  
  3593. -- Enables player controls and fades in the screen. 
  3594. -- 
  3595. -- Temp function to fade in the screen, but still show messages 
  3596. -- 
  3597. function hack_cutscene_fade_in() 
  3598.    hack_fade_in() 
  3599.    player_controls_enable( LOCAL_PLAYER ) 
  3600.    if ( coop_is_active() ) then 
  3601.       player_controls_enable( REMOTE_PLAYER ) 
  3602.    end 
  3603. end 
  3604.  
  3605. -- Disables player controls and instantly fades out the screen. 
  3606. -- 
  3607. -- Temp function to fade out the screen, but still show messages 
  3608. -- 
  3609. function hack_cutscene_fade_out() 
  3610.    hack_fade_out() 
  3611.    player_controls_disable( LOCAL_PLAYER ) 
  3612.    if ( coop_is_active() ) then 
  3613.       player_controls_disable( REMOTE_PLAYER ) 
  3614.    end 
  3615. end 
  3616.  
  3617. --[[ 
  3618. 	END Cutscene fade hack 
  3619. ]]-- 
  3620.